VMware vRealize Orchestrator - 7.4 User’s Manual

Using VMware vRealize Orchestrator Plug-Ins

12 April 2018 vRealize Automation 7.4 vRealize Orchestrator 7.4

Using VMware vRealize Orchestrator Plug-Ins

You can find the most up-to-date technical documentation on the VMware website at:

https://docs.vmware.com/

If you have comments about this documentation, submit your feedback to

docfeedback@vmware.com

VMware, Inc.

3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

VMware, Inc. 2

Using VMware vRealize Orchestrator Plug-Ins 10

Introduction to Orchestrator Plug-Ins 11

Orchestrator Architecture 11

Plug-Ins Installed with the Orchestrator Server 12

Access the Orchestrator API Explorer 15

Configure the Orchestrator Plug-Ins 16

Manage the Orchestrator Plug-Ins 16

Uninstall a Plug-In 17

Using the vCenter Server Plug-In 19

Configuring the vCenter Server Plug-In 19

Configuration Workflows 20

Configure the Connection to a vCenter Server Instance 20

vCenter Server Plug-In Scripting API 22

Using the vCenter Server Plug-In Inventory 22

Performance Considerations for Querying 22

Using XPath Expressions with the vCenter Server Plug-In 23

Access the vCenter Server Plug-In Workflow Library 24

vCenter Server Plug-In Workflow Library 25

Batch Workflows 28

Cluster and Compute Resource Workflows 28

Configuration Workflows 29

Custom Attributes Workflows 29

Datacenter Workflows 29

Datastore and Files Workflows 30

Datacenter Folder Management Workflows 30

Host Folder Management Workflows 30

Virtual Machine Folder Management Workflows 31

Guest Operation Files Workflows 31

Guest Operation Processes Workflows 32

Power Host Management Workflows 32

Basic Host Management Workflows 32

Host Registration Management Workflows 33

Networking Workflows 33

Distributed Virtual Port Group Workflows 33

VMware, Inc.

Using VMware vRealize Orchestrator Plug-Ins

Distributed Virtual Switch Workflows 34

Standard Virtual Switch Workflows 34

Networking Virtual SAN Workflows 35

Resource Pool Workflows 35

Storage Workflows 35

Storage DRS Workflows 36

Storage VSAN Workflows 37

Basic Virtual Machine Management Workflows 37

Clone Workflows 38

Linked Clone Workflows 38

Linux Customization Clone Workflows 39

Tools Clone Workflows 39

Windows Customization Clone Workflows 40

Device Management Workflows 40

Move and Migrate Workflows 41

Other Workflows 41

Power Management Workflows 42

Snapshot Workflows 43

VMware Tools Workflows 43

Using the vRealize Automation Plug-In 44

Introduction to the VMware vRealize Orchestrator Plug-In for vRealize Automation 44

Role of vRealize Orchestrator with the vRealize Automation Plug-In 45

Configuring the vRealize Automation Plug-In 45

Configuration Workflows 45

Using the vRealize Automation Plug-In Workflows 48

Remove Operation Restrictions 48

Using the vRealize Automation Plug-In Inventory 50

Using the vRealize Automation Plug-In Administration Workflows 51

Using the vRealize Automation Plug-In Infrastructure Administration Workflows 57

Using the vRealize Automation Plug-In Requests Workflows 60

Using the vRealize Automation Plug-In Sample Workflows 61

Access the vRealize Automation Plug-In API 62

Example vRealize Automation Plug-In Scripts 62

CRUD Infrastructure Administration Tasks Example Scripts 62

Finding vRealize Automation Entities Example Scripts 67

Get a Resource Provisioned by vRealize Automation Example Script 68

Common Tasks Example Scripts 70

Using the Configuration Plug-In 73

Access the Configuration Plug-In Workflow Library 73

Configuration Plug-In Workflow Library 73

VMware, Inc. 4

Using VMware vRealize Orchestrator Plug-Ins

Using the Library Plug-In 75

Library Plug-In Workflows 75

Using the SQL Plug-In 77

Configuring the SQL Plug-In 77

SQL Plug-In Configuration Workflows 77

Add a Database 78

Add Tables to a Database 79

Update a Database 79

Running the SQL Sample Workflows 80

Generate a JDBC URL 80

Test a JDBC Connection 81

Create a Table by Using JDBC 81

Insert a Row into a JDBC Table 82

Select Rows from a JDBC Table 82

Delete an Entry from a JDBC Table 83

Delete All Entries from a JDBC Table 84

Drop a JDBC Table 84

Run a Complete JDBC Cycle 85

Using the SQL Plug-In Standard Workflows 85

SQL Plug-In Workflow Library 86

Generate CRUD Workflows for a Table 86

Using the SSH Plug-In 88

Configure the SSH Plug-In 88

Configuration Workflows 89

Running the SSH Plug-In Sample Workflows 89

Generate a Key Pair 90

Change the Key Pair Passphrase 90

Run an SSH Command 91

Copy a File from an SSH Host 92

Copy a File to an SSH Host 93

Using the XML Plug-In 94

Running the XML Plug-In Sample Workflows 94

Create a Simple XML Document 95

Find an Element in an XML Document 95

Modify an XML Document 96

Create an Example Address Book from XML 97

VMware, Inc. 5

Using VMware vRealize Orchestrator Plug-Ins

Access the Mail Plug-In Sample Workflows 98

Add a Database 99

Add a REST Host 101

Add a SOAP Host 103

Change the Key Pair Passphrase 105

Configure the Connection to a vCenter Server Instance 106

Configure the SSH Plug-In 108

Copy a File from an SSH Host 109

Copy a File to an SSH Host 110

Plug-Ins Installed with the Orchestrator Server 111

Define the Default SMTP Connection 115

Generate a Key Pair 116

Mail Plug-In Sample Workflows 117

Run an SSH Command 119

Using the Configuration Plug-In 120

Using the Mail Plug-In 121

Using the Mail Plug-In Sample Workflows 122

Using the Mail Plug-In 123

Define the Default SMTP Connection 123

Using the Mail Plug-In Sample Workflows 124

Access the Mail Plug-In Sample Workflows 124

Mail Plug-In Sample Workflows 124

VMware, Inc. 6

Using VMware vRealize Orchestrator Plug-Ins

Using the Net Plug-In 125

Using the Enumeration Plug-In 126

Time Zone Codes 126

Using the Workflow Documentation Plug-In 129

Workflow Library for the Workflow Documentation Plug-In 129

Generate Workflow Documentation 129

Using the HTTP-REST Plug-In 131

Configuring the HTTP-REST Plug-In 131

Configuration Workflows 131

Configure Kerberos Authentication 132

Add a REST Host 133

Add a REST Operation 135

Add a Schema to a REST Host 135

Generate a New Workflow from a REST Operation 136

Invoking a REST Operation 137

Invoke a REST Operation 137

Using the SOAP Plug-In 138

Configuring the SOAP Plug-In 138

Configuration Workflows 138

Add a SOAP Host 139

Configure Kerberos Authentication 140

Generate a New Workflow from a SOAP Operation 141

Test a Custom-Generated Workflow 142

Invoke a SOAP Operation 142

Using the AMQP Plug-In 144

Configuring the AMQP Plug-In 144

Configuration Workflows 144

Add a Broker 144

Subscribe to Queues 145

Update a Broker 146

Using the AMQP Plug-In Standard Workflows 146

Declare a Binding 147

Declare a Queue 147

Declare an Exchange 148

Send a Text Message 149

Delete a Binding 150

VMware, Inc. 7

Using VMware vRealize Orchestrator Plug-Ins

Using the SNMP Plug-In 151

Managing SNMP Devices 151

Device Management Workflows 151

Managing SNMP Queries 153

Query Management Workflows 153

Add a Query to an SNMP Device 153

Managing the SNMP Trap Host 154

Trap Host Management Workflows 154

Set the SNMP Trap Port 154

Receiving SNMP Traps 155

Wait for a Trap on an SNMP Device 155

Set an SNMP Trap Policy 156

Configure an SNMP Trap Host Policy 156

Edit a Trap Policy 157

Generic SNMP Request Workflows 158

Using the Active Directory Plug-In 159

Configuring the Active Directory Plug-In 159

Active Directory Configuration Workflows 159

Using the Active Directory Plug-In Workflow Library 160

Using the Active Directory Plug-In Inventory 160

Access the Active Directory Plug-In Workflow Library 160

Active Directory Plug-In Workflows 160

Using the Dynamic Types Plug-In 163

Dynamic Types Configuration Workflows 163

Using the PowerShell Plug-In 165

Introduction to the VMware vRealize Orchestrator PowerShell Plug-In 165

PowerShell Plug-In Components 165

Configuring WinRM 167

Configure Kerberos Authentication 170

Configuring the PowerShell Plug-In 172

Configuration Workflows 172

Add a PowerShell Host 172

Using the PowerShell Plug-In Inventory 173

Running PowerShell Scripts 173

Invoke a PowerShell Script 173

Invoke an External Script 174

VMware, Inc. 8

Using VMware vRealize Orchestrator Plug-Ins

Generating Actions 175

Generate an Action from a PowerShell Script 175

Generate an Action for a PowerShell Cmdlet 176

Passing Invocation Results Between Actions 177

PowerCLI Integration with the PowerShell Plug-In 177

Converter Workflows 178

Sample Workflows 178

Access the PowerShell Plug-In API 178

Working with PowerShell Results 179

Examples of Scripts for Common PowerShell Tasks 180

Troubleshooting 182

Enable Kerberos Event Logging 182

Servers Not Found in Kerberos Database 182

Unable to Obtain a Kerberos Ticket 183

Kerberos Authentication Fails Due to Different Time Settings 183

Kerberos Authentication Session Mode Fails 184

Unable to Reach a Key Distribution Center for a Realm 184

Unable to Locate the Default Realm 185

Using the Multi-Node Plug-In 186

Introduction to the vRealize Orchestrator Multi-Node Plug-In 186

Configuring the Multi-Node Plug-In 186

Servers Configuration Workflows 187

Add an Orchestrator Server 187

Using Proxy Workflows 187

Synchronous Proxy Workflows 188

Asynchronous Proxy Workflows 188

Remote Execution Workflows 189

Using the Multi-Node Plug-In Inventory 190

Remote Management Workflows 190

Access the Multi-Node Plug-In API 191

Multi-Node Plug-In Use Cases 191

Create a Multi-Proxy Action 192

Maintenance of Remote and Proxy Workflows 193

Deploy a Package from a Local Server 194

Using the vCloud Suite API (vAPI) Plug-In 195

Configuring the vCloud Suite API Plug-In 195

Import a vCloud Suite API Metamodel 195

Add a vCloud Suite API Endpoint 196

Access the vCloud Suite API Plug-In API 197

VMware, Inc. 9

Using VMware vRealize Orchestrator Plug-Ins

Using VMware vRealize Orchestrator Plug-Ins provides information and instructions about configuring

and using the standard set of plug-ins installed with VMware® vRealize Orchestrator.

Intended Audience

This information is intended for advanced vSphere administrators and experienced system administrators

who are familiar with virtual machine technology and datacenter operations.

VMware, Inc. 10

Introduction to Orchestrator

Plug-Ins 1

With the Orchestrator plug-ins, you can access and control external technologies and applications.

Exposing an external technology in an Orchestrator plug-in lets you incorporate objects and functions in

workflows and run workflows on the objects of that external technology.

The external technologies that you access by using plug-ins include virtualization management tools,

email systems, databases, directory services, and remote control interfaces.

Orchestrator provides a standard set of preinstalled plug-ins, which expose the VMware vCenter Server

API, email and authentication capabilities, and other technologies. In addition, the Orchestrator open

plug-in architecture lets you to develop plug-ins to access other applications. Orchestrator implements

open standards to simplify integration with external systems. For information about developing custom

content, see Developing with VMware vRealize Orchestrator.

The standard set of plug-ins is automatically installed with the Orchestrator server. You might need to

configure some of the plug-ins, for example the vCenter Server plug-in, before start using them.

Plug-ins extend the Orchestrator scripting engine with new object types and methods, and plug-ins

publish notification events from the external system that triggers events in Orchestrator and in the

plugged-in technology. Plug-ins provide an inventory of JavaScript objects that you can access on the

Inventory tab of the Orchestrator client. Each plug-in contains packages of workflows and actions that

you can run on the objects in the inventory to automate the typical use cases of the integrated product.

This chapter includes the following topics:

Orchestrator Architecture

Plug-Ins Installed with the Orchestrator Server

Access the Orchestrator API Explorer

Orchestrator Architecture

Orchestrator contains a workflow library and a workflow engine to allow you to create and run workflows

that automate orchestration processes. You run workflows on the objects of different technologies that

Orchestrator accesses through a series of plug-ins.

Orchestrator provides a standard set of plug-ins, including a plug-in for vCenter Server, to allow you to

orchestrate tasks in the different environments that the plug-ins expose.

VMware, Inc.

Authentication

Providers

vCenter

Server

Orchestrator

database

vRealize Orchestrator

Client application

Web services REST

workflow libraryworkflow engine

vCenter

Server

XML SSH SQL SMTP 3rd-party

plug-in

Using VMware vRealize Orchestrator Plug-Ins

Orchestrator also presents an open architecture to allow you to plug in external third-party applications to

the orchestration platform. You can run workflows on the objects of the plugged-in technologies that you

define yourself. Orchestrator connects to an authentication provider to manage user accounts, and to a

database to store information from the workflows that it runs. You can access Orchestrator, the

Orchestrator workflows, and the objects it exposes through the Orchestrator client interface, or through

Web services.

Figure 1‑1. VMware vRealize Orchestrator Architecture

Plug-Ins Installed with the Orchestrator Server

Orchestrator includes a collection of standard plug-ins. Each plug-in exposes an external product API to

the Orchestrator platform. Plug-ins provide inventory classes, additional object types for the scripting

engine, and publish notification events from the external system. Each plug-in also provides a library of

workflows for automating the typical use cases of the integrated external products.

You can see the list of the installed plug-ins on the Manage Plug-ins page in Control Center. For the

plug-ins that require configuration, there are separate tabs in the interface.

Table 1‑1. Plug-ins Installed With Orchestrator

Plug-In Purpose Configuration

vCenter Server Provides access to the vCenter Server API so that you can

Configuration Provides workflows for configuring the Orchestrator

incorporate all the vCenter Server objects and functions

into the management processes that you automate by

using Orchestrator.

authentication, database connection, SSL certificates, and

so on.

See Configuring the vCenter Server

Plug-In.

None

VMware, Inc. 12

Using VMware vRealize Orchestrator Plug-Ins

Table 1‑1. Plug-ins Installed With Orchestrator (Continued)

Plug-In Purpose Configuration

Library Provides workflows that act as basic building blocks for

customization and automation of client processes. The

workflow library includes templates for life cycle

management, provisioning, disaster recovery, hot backup,

and other standard system management processes. You

can copy and edit the templates to modify them according

to your needs.

SQL Provides the Java Database Connectivity (JDBC) API,

which is the industry standard for database-independent

connectivity between the Java programming language and

a wide range of databases. The databases include SQL

databases and other tabular data sources, such as

spreadsheets or flat files. The JDBC API provides a call-

level API for SQL-based database access from workflows.

SSH Provides an implementation of the Secure Shell v2

(SSH-2) protocol. Allows remote command and file transfer

sessions with password and public key-based

authentication in workflows. Supports keyboard-interactive

authentication. Optionally, the SSH plug-in can provide

remote file system browsing directly in the Orchestrator

client inventory.

XML A complete Document Object Model (DOM) XML parser

that you can implement in workflows. Alternatively, you can

use the ECMAScript for XML (E4X) implementation in the

Orchestrator JavaScript API.

None

See Configure the SSH Plug-In.

None

Mail Uses Simple Mail Transfer Protocol (SMTP) to send email

from workflows.

Net Uses the Jakarta Apache Commons Net Library. Provides

implementations of the Telnet, FTP, POP3, and IMAP

protocols. The POP3 and IMAP protocols is used for

reading email. In combination with the Mail plug-in, the Net

plug-in provides complete email sending and receiving

capabilities in workflows.

Workflow documentation Provides workflows that you can use to generate

information in PDF format about a workflow or a workflow

category.

Enumeration Provides common Enumerated Types that can be used in

workflows by other plug-ins.

HTTP-REST Enables management of REST Web services through an

interaction between vRealize Orchestrator and REST

hosts.

SOAP Lets you manage SOAP Web services by providing

interaction between vRealize Orchestrator and SOAP

hosts.

Set the default values for the

EmailMessage object to use.

See Chapter 20 Define the Default

SMTP Connection.

None

See Configuring the HTTP-REST

Plug-In.

See Configuring the SOAP Plug-In.

VMware, Inc. 13

Using VMware vRealize Orchestrator Plug-Ins

Table 1‑1. Plug-ins Installed With Orchestrator (Continued)

Plug-In Purpose Configuration

AMQP Lets you interact with Advanced Message Queuing

Protocol (AMQP) servers also known as brokers.

SNMP Enables vRealize Orchestrator to connect and receive

information from SNMP-enabled systems and devices.

Active Directory Provides interaction between vRealize Orchestrator and

Microsoft Active Directory.

Dynamic Types Lets you define dynamic types and create and use objects

of these dynamic types.

Multi-Node Contains workflows for hierarchical management,

management of Orchestrator instances, and scale-out of

Orchestrator activities.

PowerShell Lets you manage PowerShell hosts and run custom

PowerShell operations.

See Configuring the AMQP Plug-In.

None

See Configuring the Active Directory

Plug-In.

See Chapter 37 Using the Dynamic

Types Plug-In.

See Chapter 39 Using the Multi-

Node Plug-In.

See Chapter 38 Using the

PowerShell Plug-In.

Plug-In Components

Each plug-in is a DAR file package. The DAR files are stored in /var/lib/vco/app-server/plugins

on the Orchestrator Appliance. The components of each plug-in, such as workflow categories and API

modules, use different naming conventions.

Table 1‑2. Names of Plug-In Components

Plug-In Name in the

Configuration UI DAR File

vCenter Server

vRO Configuration

Library

SQL

SSH

XML

Mail

Net

Workflow

documentation

Common enumerated

types

Dynamic Types

o11nplugin-vsphere.dar

o11nplugin-configurator.dar

o11nplugin-library.dar

o11nplugin-database.dar

o11nplugin-ssh.dar

o11nplugin-xml.dar

o11nplugin-mail.dar

o11nplugin-jakartacommonsnet.dar

o11nplugin-wfdocs.dar

o11nplugin-enums.dar

o11n-plugin-dynamictypes.dar

Workflow

Categories API Module

vCenter

Configuration

Locking

Orchestrator

Troubleshooting

JDBC

SQL

SSH

XML

Mail

None

Workflow

documentation

None

Configuration

Configurator

Not applicable.

SQL

SSH

XML

Mail

Net

Workflow documentation

Enums

DynamicTypes

HTTP-REST

VMware, Inc. 14

o11nplugin-rest.dar

Configuration

REST

Using VMware vRealize Orchestrator Plug-Ins

Table 1‑2. Names of Plug-In Components (Continued)

Plug-In Name in the

Configuration UI DAR File

SOAP

AMQP

SNMP

Active Directory

Orchestrator

o11n-plugin-soap.dar

o11n-plugin-amqp.dar

o11n-plugin-snmp.dar

o11nplugin-ad.dar

o11nplugin-multi-node.dar

Workflow

Categories API Module

Configuration

Device Management

Query Management

Trap Host

Management

Computer

Configuration

Organizational Unit

User

User Group

Servers

Configuration

Remote Execution

Remote

Management

Tasks

Workflows

SOAP

AMQP

SNMP

VCO

PowerShell

o11nplugin-powershell.dar

Configuration

Generate

Templates

PowerShell

Access the Orchestrator API Explorer

Orchestrator provides an API Explorer that you can use to search the Orchestrator API and see the

documentation for JavaScript objects that you can use in scripted elements.

You can consult an online version of the Scripting API for the vCenter Server plug-in on the Orchestrator

documentation home page.

Procedure

1 Log in to the Orchestrator client.

2 Select Tools > API Explorer.

The API Explorer appears. You can use it to search all the objects and functions of the Orchestrator API.

What to do next

Use the API Explorer to write scripts for scriptable elements.

VMware, Inc. 15

Conﬁgure the Orchestrator

Plug-Ins 2

The default Orchestrator plug-ins are configured only through workflows.

If you want to configure any of the default Orchestrator plug-ins, you need to use the specific workflow

from the Orchestrator client.

This chapter includes the following topics:

Manage the Orchestrator Plug-Ins

Uninstall a Plug-In

Manage the Orchestrator Plug-Ins

In the Manage Plug-Ins page of Control Center, you can view a list of all plug-ins that are installed in

Orchestrator and perform basic management actions.

Change Plug-Ins Logging Level

Instead of changing the logging level for Orchestrator, you can change it only for specific plug-ins.

Install a New Plug-In

With the Orchestrator plug-ins, the Orchestrator server can integrate with other software products. The

Orchestrator Appliance includes a set of preinstalled plug-ins and you can also install custom plug-ins.

All Orchestrator plug-ins are installed from Control Center. The file extensions that can be used

are .vmoapp and .dar. A .vmoapp file can contain a collection of several .dar files and can be installed

as an application, while a .dar file contains all the resources associated with one plug-in.

Disable a Plug-In

You can disable a plug-in by deselecting the Enable check box next to the name of the plug-in.

This action does not remove the plug-in file. For more information on uninstalling a plug-in in

Orchestrator, see Uninstall a Plug-In.

VMware, Inc.

Using VMware vRealize Orchestrator Plug-Ins

Uninstall a Plug-In

You can use Control Center to disable a plug-in, but this action does not remove the plug-in file from the

Orchestrator Appliance file system. To remove the plug-in file, you must log in to the

Orchestrator Appliance and remove the plug-in file manually.

Procedure

1 Delete the plug-in from the Orchestrator Appliance.

a Log in to the Orchestrator Appliance over SSH as root.

b Open the /etc/vco/app-server/plugins/_VSOPluginInstallationVersion.xml file with a

text editor.

c Delete the line of code that corresponds to the plug-in that you want to remove.

d Navigate to the /var/lib/vco/app-server/plugins directory.

e Delete the .dar archives that contain the plug-in that you want to remove.

2 Restart the vRealize Orchestrator services.

service vco-configurator restart && service vco-server restart

3 Log in to Control Center as root.

4 In the Manage Plug-Ins page, verify that the plug-in is removed.

5 Through the Orchestrator client, delete the packages and folders that are related to the plug-in.

a Log in to the Orchestrator client.

b Select Design from the drop-down menu in the upper-left corner.

c Click the Packages view.

d Right-click the package that you want to delete, and select Delete element with content.

Note Orchestrator elements that are locked in the read-only state, for example, workflows in the

standard library, are not deleted.

e From the Tools menu in the upper-right corner, select User preferences.

The Preferences context menu opens.

f On the General page, select the Delete non empty folder permitted check box.

You can now delete an entire folder, including its subfolders and workflows, with a single click.

g Click the Workflow view.

h Delete the folder of the plug-in that you want to remove.

VMware, Inc. 17

Using VMware vRealize Orchestrator Plug-Ins

i Click the Actions view.

j Delete the action modules of the plug-in that you want to remove.

6 Restart the vRealize Orchestrator services.

You removed all custom workflows, actions, policies, configurations, settings, and resources related to the

plug-in.

VMware, Inc. 18

Using the vCenter Server Plug-

In 3

You can use the vCenter Server plug-in to manage multiple vCenter Server instances. You can create

workflows that use the vCenter Server plug-in API to automate tasks in your vCenter Server environment.

The vCenter Server plug-in maps the vCenter Server API to the JavaScript that you can use in workflows.

The plug-in also provides actions that perform individual vCenter Server tasks that you can include in

workflows.

The vCenter Server plug-in provides a library of standard workflows that automate vCenter Server

operations. For example, you can run workflows that create, clone, migrate, or delete virtual machines.

The vCenter Server plug-in includes the Policy-Based Management (PBM) and the Storage Montoring

Service (SMS) APIs as scripting objects in the Orchestrator scripting API. The Storage Policy-Based

Management policies and components appear in the Orchestrator Inventory tab.

This chapter includes the following topics:

Configuring the vCenter Server Plug-In

vCenter Server Plug-In Scripting API

Using the vCenter Server Plug-In Inventory

Performance Considerations for Querying

Using XPath Expressions with the vCenter Server Plug-In

Access the vCenter Server Plug-In Workflow Library

vCenter Server Plug-In Workflow Library

Conﬁguring the vCenter Server Plug-In

Before managing the objects in your vSphere inventory by using Orchestrator and to run workflows on the

objects, you must configure the vCenter Server plug-in and define the connection parameters between

Orchestrator and the vCenter Server instances you want to orchestrate.

You can configure the vCenter Server plug-in by running the vCenter Server configuration workflows from

the Orchestrator client.

VMware, Inc.

Using VMware vRealize Orchestrator Plug-Ins

To manage the objects in your vSphere inventory by using the vSphere Web Client, make sure that you

configure the Orchestrator server to work with the same vCenter Single Sign-On instance to which both

vCenter Server and vSphere Web Client are pointing. You must also ensure that Orchestrator is

registered as a vCenter Server extension. You register Orchestrator as a vCenter Server extension when

you specify a user (by providing the user name and password), who has the privileges to manage

vCenter Server extensions.

Conﬁguration Workﬂows

The Configuration workflow category of the vCenter Server plug-in contains workflows that let you

manage the connections to vCenter Server instances.

You can access these workflows from Library > vCenter > Configuration in the Workflows view of the

Orchestrator client.

Workflow Name Description

Add a vCenter Server instance Configures Orchestrator to connect to a new vCenter Server instance so that you can

run workflows over the objects in the vSphere infrastructure.

List the vRealize Orchestrator

extensions of vCenter Server

vCenter Server extension

Remove a vCenter Server instance Removes a vCenter Server instance from the Orchestrator inventory. You will no longer

Update a vCenter Server instance Updates the connection to a vCenter Server instance. For example, if the IP address of

Unregister a vCenter Server extension Unregisters a vSphere Web Client extension.

Lists all vRealize Orchestrator extensions of vCenter Server.

Registers the Orchestrator instance as a vCenter Server extension.

be able to orchestrate this vCenter Server instance.

your vCenter Server system changes, you must update the connection parameters to

the vCenter Server instance so that you can manage your vSphere inventory with

Orchestrator.

Conﬁgure the Connection to a vCenter Server Instance

You can configure the connections to vCenter Server instances by running the vCenter Server

configuration workflows in the Orchestrator client.

Procedure

1 Log in to the Orchestrator client as an administrator.

2 Click the Workflows view in the Orchestrator client.

3 In the workflows hierarchical list, expand Library > vCenter > Configuration and navigate to the

Add a vCenter Server instance workflow.

4 Right-click the Add a vCenter Server instance workflow and select Start workflow.

VMware, Inc. 20

Using VMware vRealize Orchestrator Plug-Ins

5 Enter the IP address or the DNS name of the machine on which the vCenter Server instance you

want to add is installed.

Note The hostname that you enter is case-sensitive.

6 Retain the default port value, 443.

7 Retain the default location of the SDK to use to connect to your vCenter Server instance.

8 Select whether you want to manage the vCenter Server instance through Orchestrator, and click

Next.

9 Select whether you want to ignore certificate warnings for the vCenter Server instances that you want

to add.

If you choose to ignore certificate warnings, the vCenter Server instance certificate is accepted

silently and the certificate is added to the trusted store.

10 Select the method that you want to use to manage user access on the vCenter Server system.

Option Description

Share a unique session Allows Orchestrator to create only one connection to vCenter Server.

In the User name and Password text boxes, enter the credentials for

Orchestrator to use to establish the connection to the vCenter Server host.

The user that you select must be a valid user with privileges to manage

vCenter Server extensions and a set of custom defined privileges. Orchestrator

uses these credentials to monitor the VirtualCenter Web service, typically to run

Orchestrator system workflows.

Session per user Creates a new session to vCenter Server. This action might rapidly use CPU,

memory, and bandwidth.

Select this option only if your vCenter Server is in an Active Directory domain or if

vCenter Server Single Sign-On is enabled.

The user that you select must be a valid user with privileges to manage

vCenter Server extensions.

The user account that you select is also used by the policy engine to collect statistical and other data.

If the user that you select does not have enough privileges, the policy engine cannot access the

necessary parts of the vCenter Server inventory and cannot collect the necessary data.

11 (Optional) Enter the user domain.

You must specify the user domain name only when you select to use a shared session.

Note Fill this text box if session per user is selected.

12 (Optional) Enter the URLs for the vSphere storage management endpoints.

You can configure the Policy-Based Management (PBM) endpoint, the Storage Monitoring Service

(SMS) endpoint, or both.

13 Click Submit to run the workflow.

VMware, Inc. 21

Using VMware vRealize Orchestrator Plug-Ins

After the workflow runs successfully, the vCenter Server instance and all vSphere objects that belong to it

appear in the Inventory view.

vCenter Server Plug-In Scripting API

The vCenter Server scripting API contains classes, with their respective attributes, methods, and

constructors that allow interaction between vRealize Orchestrator and vCenter Server. You can use the

API to develop custom workflows.

For a list of available API objects, see https://www.vmware.com/support/orchestrator/doc/vro-vsphere65-

api/index.html.

Using the vCenter Server Plug-In Inventory

The vCenter Server plug-in exposes all objects of the connected vCenter Server instances in the

Inventory view. You can use the Inventory tab to add authorization elements or to run workflows on

vCenter Server objects.

If you enable the Use contextual menu in inventory option from the Inventory tab of the User

preferences tool, all of the workflows that you can run on the selected inventory object appear in a pop-up

menu.

Performance Considerations for Querying

With the vCenter Server plug-in for vRealize Orchestrator, you can query the vCenter Server inventory for

specific objects.

Querying Methods

For querying, you can either use the vCSearchIndex managed object, or the object finder methods that

are included in the plug-in inventory, such as getAllDatastores(), getAllVirtualMachines(),

findAllForType(), and others.

Performance

By default, both methods return the queried objects without including any of their properties, unless you

specify a set of properties as an argument for the method parameters in the search query.

Note You must always use query expressions with the getAll...() and findAll...() finder objects

to prevent the Orchestrator client from filtering large sets of returned objects, which might affect the

overall performance of the Orchestrator server.

You can use two types of expressions for querying the vCenter Server inventory.

VMware, Inc. 22

Using VMware vRealize Orchestrator Plug-Ins

Type of Expression Description

Name expressions You can specify a name as an argument for a query parameter.

Note The objects are filtered by the specified name argument

according to the name of the plug-in object as it is appears in

the vCenter Server plug-in inventory.

XPath expressions You can use expressions based on the XPath query language.

For more information, see Using XPath Expressions with the

vCenter Server Plug-In.

When you invoke a vCenter Server inventory object with custom properties, each reference to this object,

in a workflow or an action, sends a query to the vCenter Server, which generates a noticeable

performance overhead. To optimize performance and avoid serializing and deserializing the object

multiple times within a workflow run, it is best to use a shared resource to store the object, instead of

storing it as a workflow attribute, an input, or an output parameter. Such shared resource can be a

configuration element or a resource element.

Using XPath Expressions with the vCenter Server Plug-In

You can use the finder methods in the vCenter Server plug-in to query for vCenter Server inventory

objects. You can use XPath expressions to define search parameters.

The vCenter Server plug-in includes a set of object finder methods such as getAllDatastores(),

getAllResourcePools(), findAllForType(). You can use these methods to access the inventories of

the vCenter Server instances that are connected to your Orchestrator server and search for objects by ID,

name, or other properties.

For performance reasons, the finder methods do not return any properties for the queried objects, unless

you specify a set of properties in the search query.

You can consult an online version of the Scripting API for the vCenter Server plug-in on the Orchestrator

documentation home page.

Important The queries based on XPath expressions might impact the Orchestrator performance

because the finder method returns all objects of a given type on the vCenter Server side and the query

filters are applied on the vCenter Server plug-in side.

Using XPath Expressions with the vCenter Server Plug-In

When you invoke a finder method, you can use expressions based on the XPath query language. The

search returns all the inventory objects that match the XPath expressions. If you want to query for any

properties, you can include them to the search script in the form of a string array.

VMware, Inc. 23

Using VMware vRealize Orchestrator Plug-Ins

The following JavaScript example uses the VcPlugin scripting object and an XPath expression to return

the names of all datastore objects that are part of the vCenter Server managed objects and contain the

string ds in their names.

var datastores = VcPlugin.getAllDatastores(null, "xpath:name[contains(.,'ds')]");

for each (datastore in datastores){

System.log(datastore.name);

}

The same XPath expression can be invoked by using the Server scripting object and the

findAllForType finder method.

var datastores = Server.findAllForType("VC:Datastore", "xpath:name[contains(.,'ds')]");

for each (datastore in datastores){

System.log(datastore.name);

}

The following script example returns the names of all host system objects whose ID starts with the digit 1.

var hosts = VcPlugin.getAllHostSystems(null, "xpath:id[starts-with(.,'1')]");

for each (host in hosts){

System.log(host.name);

}

The following script returns the names and IDs of all data center objects that contain the string DC, in

upper- or lower-case letters, in their names. The script also retrieves the tag property.

var datacenters = VcPlugin.getAllDatacenters(['tag'], "xpath:name[contains(translate(., 'DC', 'dc'),

'dc')]");

for each (datacenter in datacenters){

System.log(datacenter.name + “ ” + datacenter.id);

}

Access the vCenter Server Plug-In Workﬂow Library

You must use the Orchestrator client or the vSphere Web Client to access the elements from the

vCenter Server plug-in workflow library.

Prerequisites

Configure a connection to a vCenter Server instance.

Verify that the user account you are logged in with has the necessary permissions to run

vCenter Server workflows.

Procedure

1 In the Orchestrator client, select Design or Run from the drop-down menu in the left upper corner.

2 Click the Workflows view in the Orchestrator client left pane.

VMware, Inc. 24

Using VMware vRealize Orchestrator Plug-Ins

3 Expand the hierarchical list to Library > vCenter.

What to do next

Review the workflow library.

vCenter Server Plug-In Workﬂow Library

The vCenter Server plug-in workflow library contains workflows that you can use to run automated

processes related to the management of vCenter Server.

Batch Workflows

Batch workflows populate configuration elements or run workflows on a selected vCenter Server

object.

Cluster and Compute Resource Workflows

With the cluster and compute resource workflows, you can create, rename, or delete a cluster. You

can also enable or disable high availability, Distributed Resource Scheduler, and

vCloud Distributed Storage on a cluster.

Configuration Workflows

The Configuration workflow category of the vCenter Server plug-in contains workflows that let you

manage the connections to vCenter Server instances.

Custom Attributes Workflows

With custom attributes workflows, you can add custom attributes to virtual machines or get a custom

attribute for a virtual machine.

Datacenter Workflows

With datacenter workflows, you can create, delete, reload, rename, or rescan a datacenter.

Datastore and Files Workflows

With the datastore and files workflows, you can delete a list of files, find unused files in a datastore,

and so on.

Datacenter Folder Management Workflows

With datacenter folder management workflows, you can create, delete, or rename a datacenter

folder.

Host Folder Management Workflows

With host folder management workflows, you can create, delete, or rename a host folder.

Virtual Machine Folder Management Workflows

With virtual machine folder management workflows, you can create, delete, or rename a virtual

machine folder.

Guest Operation Files Workflows

With the guest operation files workflows, you can manage files in a guest operating system.

VMware, Inc. 25

Using VMware vRealize Orchestrator Plug-Ins

Guest Operation Processes Workflows

With guest operation processes workflows, you can get information and control the running

processes in a guest operating system.

Power Host Management Workflows

With power host management workflows you can reboot or shut down a host.

Basic Host Management Workflows

With the basic host management workflows, you can put a host into maintenance mode and make a

host exit maintenance mode. You can also move a host to a folder or a cluster, and reload data from

a host.

Host Registration Management Workflows

With the host registration management workflows, you can add a host to a cluster, disconnect, or

reconnect a host from a cluster, and so on.

Networking Workflows

With networking workflows you can add a port group to distributed virtual switch, create a distributed

virtual switch with a port group, and so on.

Distributed Virtual Port Group Workflows

With the distributed virtual port group workflows, you can update or delete a port group, and

reconfigure the port group.

Distributed Virtual Switch Workflows

With distributed virtual switch workflows, you can create, update or delete a distributed virtual switch,

and create, delete, or update a private VLAN.

Standard Virtual Switch Workflows

With the standard virtual switch workflows you can create, update, or delete a standard virtual

switch, and create, delete, or update port groups in standard virtual switches.

Networking Virtual SAN Workflows

With Virtual SAN workflows, you can configure Virtual SAN network traffic.

Resource Pool Workflows

With the resource pool workflows you can create, rename, reconfigure or delete a resource pool,

and get resource pool information.

Storage Workflows

With the storage workflows, you can perform storage-related operations.

Storage DRS Workflows

With the storage DRS workflows, you perform storage-related operations, such as creating and

configuring a datastore cluster, removing a datastore from cluster, adding storage to a cluster, and

others.

VMware, Inc. 26

Using VMware vRealize Orchestrator Plug-Ins

Storage VSAN Workflows

With the Virtual SAN workflows, you can manage non-SSD disks and disk groups in a Virtual SAN

cluster.

Basic Virtual Machine Management Workflows

With the basic virtual machine management workflows, you can perform basic operations on virtual

machines, for example, create, rename or delete a virtual machine, upgrade virtual hardware, and

others.

Clone Workflows

With clone workflows, you can clone virtual machines with or without customizing the virtual machine

properties.

Linked Clone Workflows

With the linked clone workflows, you can perform linked clone operations such as restoring a virtual

machine from a linked clone, creating a linked clone, or others.

Linux Customization Clone Workflows

With Linux customization workflows, you can clone a Linux virtual machine and customize the guest

operating system.

Tools Clone Workflows

With the tools clone workflows, you can obtain customization information about the operating system

of the virtual machine, information required to update a virtual device, and others.

Windows Customization Clone Workflows

With the Windows customization clone workflows, you can clone Windows virtual machines and

customize the guest operating system.

Device Management Workflows

With the device management workflows, you can manage the devices that are connected to a virtual

machine or to a host datastore.

Move and Migrate Workflows

With the move and migrate workflows, you can migrate virtual machines.

Other Workflows

With the workflows from the Others category, you can enable and disable Fault Tolerance (FT),

extract virtual machine information, and find orphaned virtual machines.

Power Management Workflows

With the power management workflows, you can power on and off virtual machines, reboot the

guest operating system of a virtual machine, suspend a virtual machine, and others.

Snapshot Workflows

With snapshot workflows, you can perform snapshot-related operations.

VMware Tools Workflows

With VMware Tools workflows, you can perform VMware Tools-related tasks on virtual machines.

VMware, Inc. 27

Using VMware vRealize Orchestrator Plug-Ins

Batch Workﬂows

Batch workflows populate configuration elements or run workflows on a selected vCenter Server object.

You can access the batch workflows from Library > vCenter > Batch in the Workflows view of the

Orchestrator client.

Workflow Name Description

Fill batch configuration

elements

Run a workflow on a

selection of objects

Populates the configuration elements that the Run a workflow on a selection of objects workflow uses.

Performs the following tasks:

Resets the BatchObject and BatchAction configuration elements.

Fills the BatchObject configuration element with all the workflows that have only one input

parameter.

Fills the BatchAction configuration element with all the actions that have no input parameters or one

input parameter and that have an array as the returnType.

Runs a workflow on a selection of vCenter Server objects, taking one action as input. This is the action

that retrieves the list of objects on which to run the workflow. To return the objects without running the

selected workflow, run the workflow in simulation mode.

Cluster and Compute Resource Workﬂows

With the cluster and compute resource workflows, you can create, rename, or delete a cluster. You can

also enable or disable high availability, Distributed Resource Scheduler, and vCloud Distributed Storage

on a cluster.

You can access the cluster and compute resource workflows from Library > vCenter > Cluster and

Compute Resource in the Workflows view of the Orchestrator client.

Workflow Name Description

Add DRS virtual machine group to cluster Adds a DRS virtual machine group to a cluster.

Add virtual machines to DRS group Adds a virtual machine list to an existing DRS virtual machine group.

Create cluster Creates a cluster in a host folder.

Delete cluster Deletes a cluster.

Disable DRS on cluster Disables DRS on a cluster.

Disable HA on cluster Disables high availability on a cluster.

Disable vCloud Distributed Storage on cluster Disables vCloud Distributed Storage on a cluster.

Enable DRS on cluster Enables DRS on a cluster.

Enable HA on cluster Enables high availability on a cluster.

Enable vCloud Distributed Storage on cluster Enables vCloud Distributed Storage on a cluster.

Remove virtual machine DRS group from cluster Removes a DRS virtual machine group from a cluster.

Remove virtual machines from DRS group Removes virtual machines from a cluster DRS group.

Rename cluster Renames a cluster.

VMware, Inc. 28

Using VMware vRealize Orchestrator Plug-Ins

Conﬁguration Workﬂows

The Configuration workflow category of the vCenter Server plug-in contains workflows that let you

manage the connections to vCenter Server instances.

You can access these workflows from Library > vCenter > Configuration in the Workflows view of the

Orchestrator client.

Workflow Name Description

Add a vCenter Server instance Configures Orchestrator to connect to a new vCenter Server instance so that you can

run workflows over the objects in the vSphere infrastructure.

List the Orchestrator extensions of

vCenter Server

vCenter Server extension

Remove a vCenter Server instance Removes a vCenter Server instance from the Orchestrator inventory. You cannot

Update a vCenter Server instance Updates the connection to a vCenter Server instance. For example, if the IP address of

Unregister a vCenter Server extension Unregisters a vCenter Server extension.

Lists all Orchestrator extensions of vCenter Server.

Registers the Orchestrator instance as a vCenter Server extension.

orchestrate this vCenter Server instance any longer.

your vCenter Server system changes, you must update the connection parameters to

the vCenter Server instance so that you can manage your vSphere inventory with

Orchestrator.

Custom Attributes Workﬂows

With custom attributes workflows, you can add custom attributes to virtual machines or get a custom

attribute for a virtual machine.

You can access the custom attributes workflows from Library > vCenter > Custom Attributes in the

Workflows view of the Orchestrator client.

Workflow Name Description

Add custom attribute to a virtual machine Adds a custom attribute to a virtual machine.

Add custom attribute to multiple virtual machines Adds a custom attribute to a selection of virtual machines.

Get custom attribute Gets a custom attribute for a virtual machine in vCenter Server.

Datacenter Workﬂows

With datacenter workflows, you can create, delete, reload, rename, or rescan a datacenter.

You can access the datacenter workflows from Library > vCenter > Datacenter in the Workflows view

of the Orchestrator client.

Workflow Name Description

Create datacenter Creates a data center in a data center folder.

Delete datacenter Deletes a data center.

VMware, Inc. 29

Using VMware vRealize Orchestrator Plug-Ins

Workflow Name Description

Reload datacenter Forces vCenter Server to reload data from a data center.

Rename datacenter Renames a data center and waits for the task to complete.

Rescan datacenter HBAs Scans the hosts in a data center and initiates a rescan on the host bus adapters to discover new

storage.

Datastore and Files Workﬂows

With the datastore and files workflows, you can delete a list of files, find unused files in a datastore, and

so on.

You can access the datastore and files workflows from Library > vCenter > Datastore and Files in the

Workflows view of the Orchestrator client.

Workflow Name Description

Delete all files Deletes a list of files.

Delete all unused datastore files Searches all datastores in the vCenter Server environment and deletes all unused files.

Export unused datastore files Searches all datastores and creates an XML descriptor file that lists all unused files.

Find unused files in datastores Searches the vCenter Server environment for all unused disks (*.vmdk), virtual machines

(*.vmx), and template (*.vmtx) files that are not associated with any

vCenter Serverinstances registered with Orchestrator.

Get all configuration, template, and

disk files from virtual machines

Log all datastore files Creates a log for every virtual machine configuration file and every virtual machine file found

Log unused datastore files Searches the vCenter Server environment for unused files that are registered on virtual

Upload file to datastore Uploads a file to an existing folder on a specific datastore. The uploaded file overwrites any

Creates a list of all virtual machine descriptor files and a list of all virtual machine disk files, for

all datastores.

in all datastores.

machines and exports a log of the files in a text file.

existing file with the same name in the same destination folder.

Datacenter Folder Management Workﬂows

With datacenter folder management workflows, you can create, delete, or rename a datacenter folder.

You can access the datacenter folder management workflows from Library > vCenter > Folder

management > Datacenter folder in the Workflows view of the Orchestrator client.

Workflow Name Description

Create datacenter folder Creates a data center folder.

Delete datacenter folder Deletes a data center folder and waits for the task to complete.

Rename datacenter folder Renames a data center folder and waits for the task to complete.

Host Folder Management Workﬂows

With host folder management workflows, you can create, delete, or rename a host folder.

VMware, Inc. 30

+ 167 hidden pages

VMware vRealize Orchestrator - 7.4 User’s Manual

Contents

Using VMware vRealize Orchestrator Plug-Ins

Orchestrator Architecture

Plug-Ins Installed with the Orchestrator Server

Access the Orchestrator API Explorer

Manage the Orchestrator Plug-Ins

Uninstall a Plug-In

Configuring the vCenter Server Plug-In

vCenter Server Plug-In Scripting API

Using the vCenter Server Plug-In Inventory

Performance Considerations for Querying

Using XPath Expressions with the vCenter Server Plug-In

Using XPath Expressions with the vCenter Server Plug-In