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 [e-mail]

VMware, Inc.

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

Copyright © 2008–2017 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware, Inc.

2

Contents

Using VMware vRealize Orchestrator Plug-Ins 10

1 Introduction to Orchestrator Plug-Ins 11

Orchestrator Architecture 11

Plug-Ins Installed with the Orchestrator Server 12 Access the Orchestrator API Explorer 15

2 Configure the Orchestrator Plug-Ins						16
Manage the Orchestrator Plug-Ins			16
Uninstall a Plug-In	17
3 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
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.

3

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

4 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

5 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

6 Using the Library Plug-In		75
Library Plug-In Workflows 75
7 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
8 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
Register an Orchestrator Public Key on an SSH Host 91
Run an SSH Command		91
Copy a File from an SSH Host				92
Copy a File to an SSH Host			93
9 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

10	Access the Mail Plug-In Sample Workflows							98
11	Add a Database	99
12	Add a REST Host	101
13	Add a SOAP Host	103
14	Change the Key Pair Passphrase					105
15	Configure the Connection to a vCenter Server Instance								106
16	Configure the SSH Plug-In			108
17	Copy a File from an SSH Host				109
18	Copy a File to an SSH Host			110
19	Plug-Ins Installed with the Orchestrator Server 111
20	Define the Default SMTP Connection						115
21	Generate a Key Pair 116
22	Mail Plug-In Sample Workflows					117
23	Register an Orchestrator Public Key on an SSH Host								118
24	Run an SSH Command		119
25	Using the Configuration Plug-In					120
26	Using the Mail Plug-In		121
27	Using the Mail Plug-In Sample Workflows							122
28	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

29 Using the Net Plug-In			125
30 Using the Enumeration Plug-In						126
Time Zone Codes	126
31 Using the Workflow Documentation Plug-In								129
Workflow Library for the Workflow Documentation Plug-In 129
Generate Workflow Documentation						129
32 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
33 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
34 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

35 Using the SNMP Plug-In	151
Managing SNMP Devices	151
Device Management Workflows		151
Register an SNMP Device 152
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

36 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
37 Using the Dynamic Types Plug-In				163
Dynamic Types Configuration Workflows 163
38 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

39 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

40 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	1
Plug-Ins

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:

nOrchestrator Architecture

nPlug-Ins Installed with the Orchestrator Server

nAccess 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.

11

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

	vRealize Orchestrator					Web services REST
	Client application
	workflow engine					workflow library
	vCenter XML SSH			SQL SMTP 3rd-party
	Server						plug-in

vCenter Server

Authentication	Orchestrator
Providers	database

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	See Configuring the vCenter Server
	incorporate all the vCenter Server objects and functions	Plug-In.
	into the management processes that you automate by
	using Orchestrator.
Configuration	Provides workflows for configuring the Orchestrator	None
	authentication, database connection, SSL certificates, and
	so on.

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	None
	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,	None
	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	See Configure the SSH Plug-In.
	(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	None
	that you can implement in workflows. Alternatively, you can
	use the ECMAScript for XML (E4X) implementation in the
	Orchestrator JavaScript API.
Mail	Uses Simple Mail Transfer Protocol (SMTP) to send email	Set the default values for the
	from workflows.	EmailMessage object to use.
		See Chapter 20 Define the Default
		SMTP Connection.
Net	Uses the Jakarta Apache Commons Net Library. Provides	None
	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	None
	information in PDF format about a workflow or a workflow
	category.
Enumeration	Provides common Enumerated Types that can be used in	None
	workflows by other plug-ins.
HTTP-REST	Enables management of REST Web services through an	See Configuring the HTTP-REST
	interaction between vRealize Orchestrator and REST	Plug-In.
	hosts.
SOAP	Lets you manage SOAP Web services by providing	See Configuring the SOAP Plug-In.
	interaction between vRealize Orchestrator and SOAP
	hosts.

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	See Configuring the AMQP Plug-In.
	Protocol (AMQP) servers also known as brokers.
SNMP	Enables vRealize Orchestrator to connect and receive	None
	information from SNMP-enabled systems and devices.
Active Directory	Provides interaction between vRealize Orchestrator and	See Configuring the Active Directory
	Microsoft Active Directory.	Plug-In.
Dynamic Types	Lets you define dynamic types and create and use objects	See Chapter 37 Using the Dynamic
	of these dynamic types.	Types Plug-In.
Multi-Node	Contains workflows for hierarchical management,	See Chapter 39 Using the Multi-
	management of Orchestrator instances, and scale-out of	Node Plug-In.
	Orchestrator activities.
PowerShell	Lets you manage PowerShell hosts and run custom	See Chapter 38 Using the
	PowerShell operations.	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		Workflow
Configuration UI	DAR File	Categories	API Module
vCenter Server	o11nplugin-vsphere.dar	vCenter	VC
vRO Configuration	o11nplugin-configurator.dar	Configuration	Configurator
Library	o11nplugin-library.dar	Locking	Not applicable.
		Orchestrator
		Troubleshooting
SQL	o11nplugin-database.dar	JDBC	SQL
		SQL
SSH	o11nplugin-ssh.dar	SSH	SSH
XML	o11nplugin-xml.dar	XML	XML
Mail	o11nplugin-mail.dar	Mail	Mail
Net	o11nplugin-jakartacommonsnet.dar	None	Net
Workflow	o11nplugin-wfdocs.dar	Workflow	Workflow documentation
documentation		documentation
Common enumerated	o11nplugin-enums.dar	None	Enums
types
Dynamic Types	o11n-plugin-dynamictypes.dar	Configuration	DynamicTypes
HTTP-REST	o11nplugin-rest.dar	Configuration	REST

VMware, Inc.

14

Using VMware vRealize Orchestrator Plug-Ins

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

Plug-In Name in the		Workflow
Configuration UI	DAR File	Categories	API Module
SOAP	o11n-plugin-soap.dar	Configuration	SOAP
AMQP	o11n-plugin-amqp.dar	Configuration	AMQP
SNMP	o11n-plugin-snmp.dar	Device Management	SNMP
		Query Management
		Trap Host
		Management
Active Directory	o11nplugin-ad.dar	Computer	AD
		Configuration
		Organizational Unit
		User
		User Group
Orchestrator	o11nplugin-multi-node.dar	Servers	VCO
		Configuration
		Remote Execution
		Remote
		Management
		Tasks
		Workflows
PowerShell	o11nplugin-powershell.dar	Configuration	PowerShell
		Generate
		Templates

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

1Log in to the Orchestrator client.

2Select 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

Configure the Orchestrator	2
Plug-Ins

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:

nManage the Orchestrator Plug-Ins

nUninstall 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.

16

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

1Delete 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.

2Restart the vRealize Orchestrator services.

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

3Log in to Control Center as root.

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

5Through 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.

eFrom the Tools menu in the upper-right corner, select User preferences. The Preferences context menu opens.

fOn 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.

gClick the Workflow view.

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

VMware, Inc.

17

Using VMware vRealize Orchestrator Plug-Ins

iClick the Actions view.

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

6Restart the vRealize Orchestrator services.

You removed all custom workflows, actions, policies, configurations, settings, and resources related to the plug-in.

VMware, Inc.

18

In	3
Using the vCenter Server Plug-

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:

nConfiguring the vCenter Server Plug-In

nvCenter Server Plug-In Scripting API

nUsing the vCenter Server Plug-In Inventory

nPerformance Considerations for Querying

nUsing XPath Expressions with the vCenter Server Plug-In

nAccess the vCenter Server Plug-In Workflow Library

nvCenter Server Plug-In Workflow Library

Configuring 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.

19

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.

Configuration Workflows

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	Lists all vRealize Orchestrator extensions of vCenter Server.
extensions of vCenter Server
Register Orchestrator as a	Registers the Orchestrator instance as a vCenter Server extension.
vCenter Server extension
Remove a vCenter Server instance	Removes a vCenter Server instance from the Orchestrator inventory. You will no longer
	be able to orchestrate this vCenter Server instance.
Update a vCenter Server instance	Updates the connection to a vCenter Server instance. For example, if the IP address of
	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.
Unregister a vCenter Server extension	Unregisters a vSphere Web Client extension.

Configure 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

1Log in to the Orchestrator client as an administrator.

2Click the Workflows view in the Orchestrator client.

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

Add a vCenter Server instance workflow.

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

VMware, Inc.

20

Using VMware vRealize Orchestrator Plug-Ins

5Enter 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.

6Retain the default port value, 443.

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

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

Next.

9Select 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.

13Click 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 upperor 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 Workflow 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

nConfigure a connection to a vCenter Server instance.

nVerify that the user account you are logged in with has the necessary permissions to run vCenter Server workflows.

Procedure

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

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

VMware, Inc.

24

Using VMware vRealize Orchestrator Plug-Ins

3Expand the hierarchical list to Library > vCenter.

What to do next

Review the workflow library.

vCenter Server Plug-In Workflow 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.

nBatch Workflows

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

nCluster 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.

nConfiguration Workflows

The Configuration workflow category of the vCenter Server plug-in contains workflows that let you manage the connections to vCenter Server instances.

nCustom Attributes Workflows

With custom attributes workflows, you can add custom attributes to virtual machines or get a custom attribute for a virtual machine.

nDatacenter Workflows

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

nDatastore 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.

nDatacenter Folder Management Workflows

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

nHost Folder Management Workflows

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

nVirtual Machine Folder Management Workflows

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

nGuest 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

nGuest Operation Processes Workflows

With guest operation processes workflows, you can get information and control the running processes in a guest operating system.

nPower Host Management Workflows

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

nBasic 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.

nHost 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.

nNetworking 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.

nDistributed Virtual Port Group Workflows

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

nDistributed 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.

nStandard 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.

nNetworking Virtual SAN Workflows

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

nResource Pool Workflows

With the resource pool workflows you can create, rename, reconfigure or delete a resource pool, and get resource pool information.

nStorage Workflows

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

nStorage 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

nStorage VSAN Workflows

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

nBasic 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.

nClone Workflows

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

nLinked 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.

nLinux Customization Clone Workflows

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

nTools 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.

nWindows Customization Clone Workflows

With the Windows customization clone workflows, you can clone Windows virtual machines and customize the guest operating system.

nDevice Management Workflows

With the device management workflows, you can manage the devices that are connected to a virtual machine or to a host datastore.

nMove and Migrate Workflows

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

nOther 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.

nPower 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.

nSnapshot Workflows

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

nVMware 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 Workflows

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	Populates the configuration elements that the Run a workflow on a selection of objects workflow uses.
elements	Performs the following tasks:
	n Resets the BatchObject and BatchAction configuration elements.
	n Fills the BatchObject configuration element with all the workflows that have only one input
	parameter.
	n 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.

Run a workflow on a selection of objects

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 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.

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

Configuration Workflows

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

Lists all Orchestrator extensions of vCenter Server.

Register Orchestrator as a	Registers the Orchestrator instance as a vCenter Server extension.
vCenter Server extension
Remove a vCenter Server instance	Removes a vCenter Server instance from the Orchestrator inventory. You cannot
	orchestrate this vCenter Server instance any longer.
Update a vCenter Server instance	Updates the connection to a vCenter Server instance. For example, if the IP address of
	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.
Unregister a vCenter Server extension	Unregisters a vCenter Server extension.

Custom Attributes Workflows

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 Workflows

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 Workflows

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	Creates a list of all virtual machine descriptor files and a list of all virtual machine disk files, for
disk files from virtual machines	all datastores.
Log all datastore files	Creates a log for every virtual machine configuration file and every virtual machine file found
	in all datastores.
Log unused datastore files	Searches the vCenter Server environment for unused files that are registered on virtual
	machines and exports a log of the files in a text file.
Upload file to datastore	Uploads a file to an existing folder on a specific datastore. The uploaded file overwrites any
	existing file with the same name in the same destination folder.

Datacenter Folder Management Workflows

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 Workflows

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

VMware, Inc.

30