How it Works
VMware
Loading...
V
Loading...
Loading...
vCenter Orchestrator - 4.0
Developer's Guide
350 pgs3.22 Mb0
Administrator’s Guide
80 pgs916.49 Kb0
User Manual
66 pgs818.13 Kb0
Table of contents
Loading...

VMware vCenter Orchestrator - 4.0, vCenter Orchestrator - 4.0.4, vCenter Orchestrator - 4.0.3, vCenter Orchestrator - 4.0.2, vCenter Orchestrator - 4.0.1 Developer's Guide

vCenter Orchestrator Developer's Guide
vCenter Orchestrator 4.0.1
This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
EN-000228-03
vCenter Orchestrator Developer's Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2009, 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.
VMware, Inc.
3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

Contents

Updated Information 7
About This Book 9
Introduction to VMware vCenter Orchestrator 11
1
Key Features of the Orchestrator Platform 11
Orchestrator User Roles and Related Tasks 12
Orchestrator Architecture 13
Developing Workflows 15
2
Principal Phases in the Workflow Development Process 16
Accessing the Orchestrator Client 17
Testing Workflows During Development 17
Workflow Editor 17
Provide General Workflow Information 20
Defining Attributes and Parameters 21
Workflow Schema 23
Obtaining Input Parameters from Users When a Workflow Starts 39
Requesting User Interactions While a Workflow Runs 44
Calling Workflows Within Workflows 52
Running a Workflow on a Selection of Objects 58
Developing Long-Running Workflows 60
Configuration Elements 65
Workflow User Permissions 66
Validating Workflows 67
Running Workflows 68
Develop a Simple Example Workflow 70
Develop a Complex Workflow 92
VMware, Inc.
Developing Actions 111
3
Reusing Actions 111
Access the Actions View 111
Components of the Actions View 112
Creating Actions 112
Scripting 115
4
Orchestrator Elements that Require Scripting 115
Limitations of the Mozilla Rhino Implementation in Orchestrator 116
Using the Orchestrator API 116
Exception Handling Guidelines 122
Orchestrator JavaScript Examples 123
3
vCenter Orchestrator Developer's Guide
Creating Resource Elements 131
5
View a Resource Element 131
Import an External Object to Use as a Resource Element 132
Edit the Resource Element Information and Access Rights 132
Save a Resource Element to a File 133
Update a Resource Element 133
Add a Resource Element to a Workflow 133
Add a Resource Element to a Web View 134
Creating Packages 137
6
Create a Package 137
Set User Permissions on a Package 138
Developing Plug-Ins 141
7
Overview of Plug-Ins 141
Contents and Structure of a Plug-In 147
Create an Orchestrator Plug-In 151
Orchestrator Plug-In API Reference 216
Elements of the vso.xml Plug-In Definition File 230
Developing a Web Services Client 247
8
Writing a Web Service Client Application 247
Web Service API Object Reference 262
Web Service API Operation Reference 267
Developing Web Views 281
9
Web View Overview 282
Weboperator Web View 282
Web View Development Tasks to Perform in Orchestrator 283
File Structure of a Web View 293
Web View Home Page 293
Web View Components 294
Accessing Server Objects from URLs 309
Create a Simple Web View Using the Default Template 312
Refactoring Orchestrator Applications After Upgrading vCenter Server 329
10
When to Refactor Applications 329
Install the VMware Infrastructure 3.5 Plug-In 330
Refactoring Packages with the Basic Refactoring Workflow 330
Refactoring Packages with the Advanced Refactoring Workflows 333
Appendix: Workflow Name Changes 337
JDBC Workflow Name Changes 337
Locking Workflow Names Unchanged 338
Mail Workflow Name Changes 338
Orchestrator Workflows 338
Refactoring Workflow Name Changes 338
SSH Workflow Name Changes 339
vCenter Server Workflow Name Changes 339
XML Workflow Name Changes 342
Index 343
Contents
VMware, Inc. 5
vCenter Orchestrator Developer's Guide

Updated Information

This VMware vCenter Orchestrator Developer's Guide is updated with each release of the product or when necessary.
This table provides the update history of the VMware vCenter Orchestrator Developer's Guide.
Revision Description
EN-000228-03
EN-000228-02
EN-000228-01
n
Added “Running a Workflow on a Selection of Objects,” on page 58, “Implement the Start Workflows
in a Series and Start Workflows in Parallel Workflows,” on page 59, and an example of running a
workflow in a scripted loop in “Workflow Scripting Examples,” on page 129.
n
Added managed object references and VcOptionValue examples in “Access Managed Object Reference
Types,” on page 127 and “Set vCenter Server Option Values,” on page 129.
n
Added Tapestry and Dojo versions in “Web View Overview,” on page 282.
n
Clarified that packages import all referenced elements in “Create a Package,” on page 137 and corrected description of Execute permission in “Set User Permissions on a Package,” on page 138.
n
Added “Limitations of the Mozilla Rhino Implementation in Orchestrator,” on page 116 and “Color
Coding of Scripting Keywords,” on page 120.
n
Added more required JAR files to “Locating the Plug-In API Java Archives,” on page 153 and “Obtain
an Application to Plug in to Orchestrator,” on page 153.
n
Added links to third-party Web development standards in “Web View Overview,” on page 282.
n
Corrected description of Execute permission in “Set User Permissions on a Package,” on page 138.
n
Corrected OGNL syntax in “vmo:WorkflowLink Component,” on page 307.
n
Added how to set a relative timeout and revised the information in “Requesting User Interactions While
a Workflow Runs,” on page 44.
n
Corrected descriptions of the Pre-defined answers and Pre-defined list of elements properties in “Workflow Input Parameter Properties,” on page 42.
n
Improved definitions in “Overview of Plug-Ins,” on page 141 and “Contents and Structure of a Plug-
In,” on page 147.
n
Complete revision of “Create an Orchestrator Plug-In,” on page 151.
n
Added information about how to add a plug-in tab to the configuration interface in “Create an
Orchestrator Plug-In,” on page 151.
n
Added missing classes to “Orchestrator Plug-In API Reference,” on page 216 and improved descriptions.
n
Added missing elements and updated “Elements of the vso.xml Plug-In Definition File,” on page 230 to list which elements and attributes are mandatory.
n
Removed erroneous references to Authorizations from “Import Web View Files from a Working
Folder,” on page 290, “Create a Web View Attribute,” on page 290, and “hasRights Operation,” on
page 278.
n
New Web view section, “Provide Unique Component Names,” on page 315, and reproduced the unique component name change throughout the Web view example.
VMware, Inc. 7
vCenter Orchestrator Developer's Guide
Revision Description
EN-000228-00 Updated for the release of Orchestrator 4.0.1 with the following new information:
n
New procedure, “Edit a Workflow from the Standard Library,” on page 18.
n
New sections on “Accessing the Orchestrator Client,” on page 17, “Accessing the Orchestrator Server
File System from JavaScript and Workflows,” on page 121, “Accessing Java Classes from JavaScript,”
on page 121, “Accessing Operating System Commands from JavaScript,” on page 122, and “Accessing
the Server from Web Service Clients,” on page 250, following changes to the Orchestrator security
policy.
n
New Chapter 5, “Creating Resource Elements,” on page 131.
n
Major revision of Chapter 9, “Developing Web Views,” on page 281.
n
New “Appendix: Workflow Name Changes,” on page 337 to reflect changes between Orchestrator 4.0 and 4.0.1.
EN-000129-01
n
Updated the filenames and paths of the Refactor Tutorial example throughout the sections “Refactoring
Packages with the Basic Refactoring Workflow,” on page 330 and “Refactoring Packages with the Advanced Refactoring Workflows,” on page 333 to reflect changes in the file structure of the examples
package.
n
Updated the filenames and paths of the solar system example plug-in in “Create an Orchestrator Plug-
In,” on page 151 to reflect changes in the file structure of the examples package.
EN-000129-00 Initial release of Orchestrator 4.0.

About This Book

The VMware vCenter Orchestrator Developer's Guide provides information and instructions about how to use the VMware vCenter Orchestrator platform to develop process-automation applications for virtual environments.
Intended Audience
This document is intended for developers who want to develop applications using the Orchestrator platform. Specifically, this document is intended for the following types of developer.
n
Application developers who want to create new extensions to the Orchestrator platform.
n
Scripting developers who want to create new building blocks to automate certain processes.
n
Web service application developers who want to access these processes across a network, through technologies such as simple object access protocol (SOAP) and Web services definition language (WSDL).
n
Web designers who want to create or customize Web front ends for these processes, using the Web 2.0 technologies.
n
IT staff who want to automate processes to save time, to reduce risk and cost, and to comply with regulations or standard practices.
Example Applications
The examples applications which this document describes are available to download. You can download a ZIP file of examples from the Orchestrator documentation home page.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation, go to
http://www.vmware.com/support/pubs.
Document Feedback
VMware welcomes your suggestions for improving our documentation. If you have comments, send your feedback to docfeedback@vmware.com.
VMware, Inc.
9
vCenter Orchestrator Developer's Guide
Technical Support and Education Resources
The following technical support resources are available to you. To access the current version of this book and other books, go to http://www.vmware.com/support/pubs.
Online and Telephone Support
Support Offerings
VMware Professional Services
To use online support to submit technical support requests, view your product and contract information, and register your products, go to
http://www.vmware.com/support.
Customers with appropriate support contracts should use telephone support for the fastest response on priority 1 issues. Go to
http://www.vmware.com/support/phone_support.html.
To find out how VMware support offerings can help meet your business needs, go to http://www.vmware.com/support/services.
VMware Education Services courses offer extensive hands-on labs, case study examples, and course materials designed to be used as on-the-job reference tools. Courses are available onsite, in the classroom, and live online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides offerings to help you assess, plan, build, and manage your virtual environment. To access information about education classes, certification programs, and consulting services, go to
http://www.vmware.com/services.
Introduction to VMware vCenter
Orchestrator 1
VMware vCenter Orchestrator is a development and process-automation platform that provides a library of extensible workflows to allow you to create and run automated, configurable processes to manage the VMware vCenter infrastructure.
Orchestrator exposes every operation in the vCenter Server API, allowing you to integrate all of these operations into your automated processes. Orchestrator also allows you to integrate with other management and administration solutions through its open plug-in architecture.
This chapter includes the following topics:
n
“Key Features of the Orchestrator Platform,” on page 11
n
“Orchestrator User Roles and Related Tasks,” on page 12
n
“Orchestrator Architecture,” on page 13

Key Features of the Orchestrator Platform

Orchestrator is composed of three distinct layers: an orchestration platform that provides the common features required for an orchestration tool, a plug-in architecture to integrate control of subsystems, and a library of preexisting processes. Orchestrator is an open platform that can be extended with new plug-ins and libraries, and can be integrated into larger SOAP architectures through a set of APIs.
The following list presents the key Orchestrator features.
Persistence
Central management
Check-pointing
Versioning
VMware, Inc. 11
Production grade external databases are used to store relevant information, such as processes, states, and configuration information.
Orchestrator provides a central way to manage your processes. The application server-based platform, with full version history, allows you to have scripts and process-related primitives in one place. This way, you can avoid scripts without versioning and proper change control spread on your servers.
Every step of a process is saved in the database, which allows you to restart the server without losing state and context. This feature is especially useful for long-running processes.
All Orchestrator Platform objects have an associated version history. This feature allows basic change management when distributing processes to different project stages or locations.
vCenter Orchestrator Developer's Guide
Scripting engine
Workflow engine
Policy engine
Web 2.0 front end
The Mozilla Rhino JavaScript engine provides a way to create new building blocks for Orchestrator Platform. The scripting engine is enhanced with basic version control, variable type checking, name space management and exception handling. It can be used in the following building blocks:
n
Actions
n
Workflows
n
Policies
The workflow engine allows you to capture business processes. It uses one of the following methods to create a step-by-step automation:
n
Building blocks of the library
n
Building blocks provided by the customer
n
Plug-ins
Users, a schedule, or a policy can start workflows.
The policy engine allows monitoring and event generation to react to changing conditions. Policies can aggregate events from the platform or any of the plug­ins, which allows you to handle changing conditions on any of the integrated technologies.
The Web 2.0 front end allows new possibilities of expression and flexibility. It provides a library of user customizable components to access vCO orchestrated objects and uses Ajax technology to dynamically update content without reloading complete pages.
Security
Orchestrator provides the following advanced security functions:
n
Public Key Infrastructure (PKI) to sign and encrypt content imported and exported between servers
n
Digital Rights Management (DRM) to control how exported content might be viewed, edited and redistributed
n
Secure Sockets Layer (SSL) encrypted communications between the desktop client and the server and HTTPS access to the Web front end.
n
Advanced access rights management to provide control over access to processes and the objects manipulated by these processes.

Orchestrator User Roles and Related Tasks

vCenter Orchestrator provides different tools and interfaces based on the specific responsibilities of the two global user roles: Administrators and End Users.
Administrators
This role has full access to all of the Orchestrator platform capabilities. Basic administrative tasks include the following items:
n
Installing and configuring Orchestrator
n
Managing access rights for Orchestrator and applications
n
Importing and exporting packages
n
Enabling and disabling Web views
Orchestrator
database
vCenter
Orchestrator
Client application
vCenter
Server
browser access web service
workflow library
vCenter VI3 WMI XML SSH JDBC SMTP
3rd-party
plug-in
directory
services
workflow engine
Chapter 1 Introduction to VMware vCenter Orchestrator
n
Running workflows and scheduling tasks
n
Managing version control of imported elements
End Users
Users in this role are granted access to only the Web front end. They can run and schedule workflows and policies.

Orchestrator Architecture

Orchestrator contains a workflow library and 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 to VMware vCenter Server, to allow you to orchestrate tasks in the different environments that the plug-ins expose.
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 a directory services server to manage user accounts, and to a database to store information from the workflows that it runs. You can access Orchestrator and the workflows and objects it exposes through the Orchestrator client interface, through a Web browser, or through Web services.
Figure 1-1 shows the architecture of Orchestrator.
Figure 1-1. VMware vCenter Orchestrator Architecture
NOTE The VMware Infrastructure 3 and Microsoft plug-ins are not installed by default.
VMware, Inc. 13
vCenter Orchestrator Developer's Guide

Developing Workflows 2

You develop workflows in the Orchestrator client interface. Workflow development involves using the workflow editor, the built-in Mozilla Rhino JavaScript scripting engine, and the Orchestrator and vCenter Server APIs.
n
Principal Phases in the Workflow Development Process on page 16
The process for developing a workflow involves a series of phases.
n
Accessing the Orchestrator Client on page 17
By default, all Orchestrator users can access the Orchestrator client. However, for security reasons, the Orchestrator administrator can limit access to the Orchestrator client to members of the Orchestrator administrator LDAP group.
n
Testing Workflows During Development on page 17
You can test workflows at any point during the development process, even if you have not completed the workflow or included an end element.
n
Workflow Editor on page 17
You create and edit workflows by using the workflow editor. The workflow editor is the Orchestrator client's IDE for developing workflows.
n
Provide General Workflow Information on page 20
You provide a workflow name and desription, define attributes and certain aspects of workflow behavior, set the version number, check the signature, and set user permissions in the General tab in the workflow editor.
VMware, Inc.
n
Defining Attributes and Parameters on page 21
After you create a workflow, you must determine the workflow's global attributes and input and output parameters.
n
Workflow Schema on page 23
A workflow schema is a graphical representation of a workflow that shows the workflow as a flow diagram of interconnected workflow elements.
n
Obtaining Input Parameters from Users When a Workflow Starts on page 39
If a workflow requires input parameters, it opens a dialog box in which users enter the required input parameter values when it runs. You can organize the content and layout, or presentation, of this dialog box in Presentation tab in the workflow editor.
n
Requesting User Interactions While a Workflow Runs on page 44
A workflow can sometimes require additional input parameters from an outside source while it runs. These input parameters can come from another application or workflow, or the user can provide them directly.
15
vCenter Orchestrator Developer's Guide
n
Calling Workflows Within Workflows on page 52
Workflows can call on other workflows during their run. A workflow can start another workflow either because it requires the result of the other workflow as an input parameter for its own run, or it can start a workflow and let it continue its own run independently. Workflows can also start a workflow at a given time in the future, or start multiple workflows simultaneously.
n
Running a Workflow on a Selection of Objects on page 58
You can automate repetitive tasks by running a workflow on a selection of objects. For example, you can create a workflow that takes a snapshot of all the virtual machines in a virtual machine folder, or you can create a workflow that powers off all the virtual machines on a given host.
n
Developing Long-Running Workflows on page 60
A workflow in a waiting state consumes system resources because it constantly polls the object from which it requires a response. If you know that a workflow will potentially wait for a long time before it receives the response it requires, you can add long-running workflow elements to the workflow.
n
Configuration Elements on page 65
A configuration element is a list of attributes you can use to configure constants across a whole Orchestrator server deployment.
n
Workflow User Permissions on page 66
Orchestrator defines levels of permissions that you can apply to users or groups to allow or deny them access to workflows.
n
Validating Workflows on page 67
Orchestrator provides a workflow validation tool. Validating a workflow helps identify errors in the workflow and checks that the data flows from one element to the next correctly.
n
Running Workflows on page 68
A workflow runs according to a logical flow of events.
n
Develop a Simple Example Workflow on page 70
Developing a simple example workflow demonstrates the most common steps in the workflow development process.
n
Develop a Complex Workflow on page 92
Developing a complex example workflow demonstrates the most common steps in the workflow development process and more advanced scenarios, such as creating custom decisions and loops.

Principal Phases in the Workflow Development Process

The process for developing a workflow involves a series of phases.
The order in which you perform the tasks that developing a workflow involves generally conforms to the following sequence of phases.
1 Provide general information about the workflow.
2 Create the input parameters.
3 Create the logical flow of the workflow by laying out and linking the schema.
4 Bind the input and output parameters of each element to workflow attributes, creating the necessary
parameters and attributes as you define each element.
5 Write any necessary scripts for scriptable task or custom decision elements.
6 Create the layout and behavior of the input parameters dialog box that the user sees when they run the
workflow by creating the workflow presentation.
7 Validate the workflow.

Accessing the Orchestrator Client

By default, all Orchestrator users can access the Orchestrator client. However, for security reasons, the Orchestrator administrator can limit access to the Orchestrator client to members of the Orchestrator administrator LDAP group.
If the Orchestrator administrator has limited the access to the client and if you are not a member of the Orchestrator administrator group, you cannot log in to the Orchestrator client.
To allow you to access the Orchestrator client, the administrator must either add you to the Orchestrator administrator LDAP group, or enable all users to access the Orchestrator client.
See the VMware vCenter Orchestrator Administration Guide for information about setting LDAP groups and enabling and disabling access to the Orchestrator client.

Testing Workflows During Development

You can test workflows at any point during the development process, even if you have not completed the workflow or included an end element.
By default, Orchestrator checks that a workflow is valid before you can run it. You can deactivate automatic validation during workflow development, to run partial workflows for testing purposes.
Chapter 2 Developing Workflows
NOTE Do not forget to reactivate automatic validation when you finish developing the workflow.
Procedure
1 In the Orchestrator client menu, click Tools > User Preferences.
2 Click the Workflows tab.
3 Uncheck the Validate workflow before executing it check box.
You deactivated automatic workflow validation.

Workflow Editor

You create and edit workflows by using the workflow editor. The workflow editor is the Orchestrator client's IDE for developing workflows.
You open the workflow editor by editing an existing workflow.
n
Create a Workflow on page 18
You can create workflows in the workflows hierarchical list in the Orchestrator client interface.
n
Edit a Workflow on page 18
You edit a workflow by using the Orchestrator client's workflow editor.
n
Edit a Workflow from the Standard Library on page 18
Orchestrator provides a standard library of workflows that you can use to automate operations in the virtual infrastructure. The workflows in the standard library are locked in the read-only state.
n
Workflow Editor Tabs on page 19
The workflow editor consists of tabs in which you edit the components of the workflows.
VMware, Inc. 17
vCenter Orchestrator Developer's Guide

Create a Workflow

You can create workflows in the workflows hierarchical list in the Orchestrator client interface.
Procedure
1 In the Orchestrator client, click the Workflows view.
2 (Optional) Right-click the root of the workflows hierarchical list, or a folder in the list, and select Add
category to create a new workflow folder.
3 (Optional) Name the new folder.
4 Right-click the new folder or an existing folder and select New workflow.
5 Name the new workflow and click OK.
The new empty workflow is created in the folder you chose.
What to do next
You can edit the workflow.

Edit a Workflow

You edit a workflow by using the Orchestrator client's workflow editor.
Procedure
1 In the Orchestrator client, click the Workflows view.
2 Expand the workflows hierarchical list to navigate to the workflow to edit.
3 Click the workflow to edit.
4 Open the workflow for editing by right-clicking the workflow and selecting Edit.
The workflow editor opens, allowing you to edit the workflow.

Edit a Workflow from the Standard Library

Orchestrator provides a standard library of workflows that you can use to automate operations in the virtual infrastructure. The workflows in the standard library are locked in the read-only state.
To edit a workflow from the standard library, create a duplicate of that workflow. You can edit duplicate workflows or custom workflows.
Procedure
1 Click in the Workflows view in the Orchestrator client.
2 (Optional) Right-click the root of the hierarchical list of workflow folders and select New category to create
a folder to contain the workflow to edit.
3 Expand the Library hierarchical list of standard workflows to navigate to the workflow to edit.
4 Right-click the workflow to edit.
The Edit option is dimmed. The workflow is read-only.
5 Right-click the workflow and select Duplicate workflow.
6 Provide a name for the duplicate workflow.
By default, Orchestrator names the duplicate workflow Copy of
workflow_name
.
Chapter 2 Developing Workflows
7 Click the Workflow category value to search for a folder in which to save the duplicate workflow.
Select the folder you created in Step 2. If you did not create a folder, select a folder that is not in the library of standard workflows.
8 Click Yes or No to copy the workflow version history to the duplicate.
Option Description
Yes
No
The version history of the original workflow is replicated in the duplicate.
The version of the duplicate reverts to 0.0.0.
9 Click Duplicate to duplicate the workflow.
10 Right-click the duplicate workflow and select Edit.
The workflow editor opens. You can edit the duplicate workflow.
You duplicated a workflow from the standard library. You can edit the duplicate workflow.

Workflow Editor Tabs

The workflow editor consists of tabs in which you edit the components of the workflows.
Table 2-1. Workflow Editor Tabs
Tab Description
General Edit the workflow name, provide a description of what the
workflow does, set the version number, see the user permissions, define the behavior of the workflow if the Orchestrator server restarts, and define the workflow's global attributes.
Inputs Define the parameters that the workflow requires when it
runs. These input parameters are the data that the workflow processes. The workflow's behavior changes according to these parameters.
Outputs Define the values that the workflow generates when it
completes its run. Other workflows or actions can use these values when they run.
Schema Build the workflow. You build the workflow by dragging
workflow schema elements from the workflow palette on the left side of the Schema tab. Clicking an element in the schema diagram allows you to define and edit the element's behavior in the bottom half of the Schema tab.
Presentation Defines the layout of the user input dialog box that appears
when users run a workflow. You arrange the parameters and attributes into presentation steps and groups to ease identification of parameters in the input parameters dialog box. You define the constraints on the input parameters that users can provide in the presentation by setting the parameter properties.
Parameters Reference Shows which workflow elements consume the attributes and
parameters in the logical flow of the workflow. This tab also shows the constraints on these parameters and attributes that you define in the Presentation tab.
Executions Provides details about each time a particular workflow runs.
This information includes the workflow's status, the user who ran it, the business status of the current element, and the time and date when the workflow started and ended.
VMware, Inc. 19
vCenter Orchestrator Developer's Guide
Table 2-1. Workflow Editor Tabs (Continued)
Tab Description
Events Provides information about each individual event that
Permissions Sets the permissions to interact with the workflow for users

Provide General Workflow Information

You provide a workflow name and desription, define attributes and certain aspects of workflow behavior, set the version number, check the signature, and set user permissions in the General tab in the workflow editor.
Prerequisites
Create a workflow and open the workflow editor for that workflow.
Procedure
1 Click the General tab in the workflow editor.
2 Click the Version digits to set a version number for the workflow.
The Version Comment dialog box opens.
3 Type a comment for this version of the workflow and click OK.
For example, type Initial creation if you just created the workflow.
occurs when the workflow runs. This information includes a description of the event, the user who triggered it, the type and origin of the event, and the time and date when it occurred.
or groups of users.
4 Define how the workflow behaves if the Orchestrator server restarts by setting the Server restart
behavior value.
n
Leave the default value of Resume workflow execution to make the workflow resume at the point at which its run was interrupted when the server stopped.
n
Click Resume workflow execution and select DON'T resume workflow execution (set as FAILED) to prevent the workflow from restarting if the Orchestrator server restarts.
Prevent the workflow from restarting if the workflow depends on the environment in which it runs. For example, if a workflow requires a specific vCenter Server and you reconfigure Orchestrator to connect to a different vCenter Server, restarting the workflow after you restart the Orchestrator server causes the workflow to fail.
5 Type a detailed description of the workflow in the Description text box.
6 Click Save at the bottom of the workflow editor.
A green message at the bottom left of the workflow editor confirms that you saved your changes.
You defined aspects of the workflow behavior, set the version, and defined the operations that users can perform on the workflow.
What to do next
You must define the workflow attributes and parameters.

Defining Attributes and Parameters

After you create a workflow, you must determine the workflow's global attributes and input and output parameters.
Workflow attributes are data that workflows process internally. Workflow input parameters are data that comes from an outside source, such as a user or another workflow. Workflow output parameters are data that the workflow delivers when it ends.
n
Define Workflow Attributes on page 21
Workflow attributes are the data that workflows process.
n
Define Workflow Parameters on page 22
Input and output parameters allow you to pass information and data into and out of the workflow.
n
Attribute and Parameter Naming Restrictions on page 22
You can use OGNL expressions to determine input parameters dynamically when a workflow runs. The Orchestrator OGNL parser uses certain keywords during OGNL processing that you cannot use in workflow attribute or parameter names.

Define Workflow Attributes

Chapter 2 Developing Workflows
Workflow attributes are the data that workflows process.
NOTE You can also define workflow attributes in the workflow schema elements when you create the workflow schema. It is often easier to define an attribute when you create the workflow schema element that processes it.
Prerequisites
You must have created a workflow and opened the workflow editor for that workflow.
Procedure
1 Click the General tab in the workflow editor.
The attributes pane appears in the bottom half of the General tab.
2 Right-click in the attributes pane and select Add Attribute.
A new attribute appears in the attributes list, with String as its default type.
3 Click the attribute name to change it.
The default name is att<X>, where <X> is a number.
NOTE Workflow attributes must not have the same name as any of the workflow's parameters.
4 Click the attribute type to select a new type from a list of possible values.
The default attribute type is String.
5 Click the attribute value to set or select a value according to the attribute type.
6 Add a description of the attribute in the Description text box.
VMware, Inc. 21
vCenter Orchestrator Developer's Guide
7 If the attribute is a constant rather than a variable, click the check box to the left of the attribute name to
make its value read-only.
The lock icon ( ) identifies the column of read-only check boxes.
8 (Optional) If you decide that the attribute should be an input or output parameter rather than an attribute,
right-click the attribute and select Move as INPUT/OUTPUT parameter to change the attribute into a parameter.
You defined an attribute for the workflow.
What to do next
You can define the workflow's input and output parameters.

Define Workflow Parameters

Input and output parameters allow you to pass information and data into and out of the workflow.
You define a workflow's parameters in the workflow editor. The input parameters are the data upon which the workflow acts that the user provides when they run the workflow. The output parameters are the data the workflow returns when it completes.
Prerequisites
You must have created a workflow and opened the workflow editor for that workflow.
Procedure
1 Click the appropriate tab in the workflow editor.
n
Click Inputs to create input parameters.
n
Click Outputs to create output parameters.
2 Right-click in the parameters tab and select Add Parameter.
A new parameter appears in the attributes list, with String as its default type.
3 Click the parameter name to change it.
The default name is arg_in_<X> for input parameters and arg_out_<X> for output parameters, where <X> is a number.
4 Click the parameter type value to change it from String to a different value from a list of possible values.
5 Add a description of the parameter in the Description text box.
6 (Optional) If you later decide that the parameter should be an attribute rather than a parameter, right-click
the parameter and select Move as attribute to change the parameter into an attribute.
You have defined an input or output parameter for the workflow.
What to do next
After you define the workflow's parameters, build the workflow schema.

Attribute and Parameter Naming Restrictions

You can use OGNL expressions to determine input parameters dynamically when a workflow runs. The Orchestrator OGNL parser uses certain keywords during OGNL processing that you cannot use in workflow attribute or parameter names.
Using a reserved OGNL keyword as a prefix to an attribute name does not break OGNL processing. For example, you can name a parameter trueParameter. Reserved keywords are not case-sensitive.
Chapter 2 Developing Workflows
You cannot use the following keywords in workflow attribute and parameter names.
Table 2-2. Forbidden Keywords in Attribute and Parameter Names
Forbidden Keyword Forbidden Keyword Forbidden Keyword
n
abstract
n
back_char_esc
n
back_char_literal
n
boolean
n
byte
n
char
n
char_literal
n
class
n
_classResolver
n
const
n
context
n
debugger
n
dec_digits
n
dec_flt
n
default
n
delete
n
digit
n
double
n
dynamic_subscript
n
enum
n
eof
n
esc
n
exponent
n
export
n
extends
n
false
n
final
n
flt_literal
n
flt_suff
n
ident
n
implements
n
import
n
in
n
int
n
int_literal
n
interface
n
_keepLastEvaluation
n
_lastEvaluation
n
letter
n
long
n
_memberAccess
n
native
n
package
n
private
n
public
n
root
n
short
n
static
n
string_esc
n
string_literal
n
synchronized
n
this
n
_traceEvaluations
n
true
n
_typeConverter
n
volatil
n
with
n
WithinBackCharLiteral
n
WithinCharLiteral
n
WithinStringLiteral

Workflow Schema

A workflow schema is a graphical representation of a workflow that shows the workflow as a flow diagram of interconnected workflow elements.
n
View Workflow Schema on page 24
You view a workflow schema in the Schema tab for that workflow in the Orchestrator client.
n
Building a Workflow in the Workflow Schema on page 24
Workflow schemas consist of a sequence of schema elements. Workflow schema elements are the building blocks of the workflow, and can represent decisions, scripted tasks, actions, exception handlers, or even other workflows.
n
Schema Elements on page 25
The workflow editor presents the workflow schema elements in menus in the Schema tab.
n
Schema Element Properties on page 28
Schema elements have properties that you can define and edit in the Schema tab of the workflow palette.
n
Links and Bindings on page 30
Links between elements determine the logical flow of the workflow. Bindings populate elements with data from other elements by binding input and output parameters to workflow attributes.
n
Decisions on page 36
Workflows can implement decision functions that define different courses of action according to a Boolean true or false statement.
n
Exception Handling on page 38
Exception handling catches any errors that occur when a schema element runs. Exception handling defines how the schema element behaves when the error occurs.
VMware, Inc. 23
vCenter Orchestrator Developer's Guide

View Workflow Schema

You view a workflow schema in the Schema tab for that workflow in the Orchestrator client.
Procedure
1 Navigate to a workflow in the workflow hierarchical list.
2 Click the workflow.
Information about that workflow appears in the right pane.
3 Select the Schema tab in the right pane.
You see the graphical representation of the workflow.

Building a Workflow in the Workflow Schema

Workflow schemas consist of a sequence of schema elements. Workflow schema elements are the building blocks of the workflow, and can represent decisions, scripted tasks, actions, exception handlers, or even other workflows.
You build workflows in the workflow editor by dragging schema elements from the workflow palette on the left of the workflow editor into the workflow schema diagram.
Edit a Workflow Schema
You build a workflow by creating a sequence of schema elements in the workflow editor's Schema tab.
Repeat this procedure until you have added all of the required schema elements to the workflow schema. A workflow schema must have at least one End workflow element, but it can have several.
Prerequisites
Open a workflow for editing in the workflow editor.
Procedure
1 Click the Schema tab in the workflow editor.
2 Click the Generic menu on the left of the Schema tab.
3 Drag a schema element from the Generic menu to the workflow schema.
4 Double-click the element you dragged to the workflow schema.
Double-clicking an element allows you to name the element. You must provide elements with unique names in the context of the workflow.
a Type an appropriate element name in the schema element.
b Press the Enter key.
You cannot rename Waiting timer, Waiting event, End workflow, or Throw exception elements.
5 Right-click an element in the schema and select Copy.
6 Right-click at an appropriate position in the schema and select Paste.
Copying and pasting existing schema elements is a quick way of adding similar elements to the schema. All of the settings of the copied element appear in the pasted element, except for the business state. Adjust the pasted element settings accordingly.
Chapter 2 Developing Workflows
7 Drag schema elements from the Basic, Log, or Network menus to the workflow schema.
You can edit the names of the elements in the Basic, Log, or Network menus. You cannot edit their scripting.
8 Drag schema elements from the Action & Workflow menu to the workflow schema.
When you drag actions or workflows to the workflow schema, a dialog box appears that allows you to search for the action or workflow to insert.
9 Type the name or part of the name of the workflow or action to insert in the workflow.
The workflows or actions that match the search appear in the dialog box.
10 Double-click a workflow or action to select it.
You inserted the workflow or action in the workflow schema.
What to do next
Define the properties of the elements you added to the workflow schema and link and bind them all together.
Modify Search Results
You use the Search text box to find elements such as workflows or actions. If a search returns a partial result, you can modify the number of results that the search returns.
When you use the search for an element, a green message box indicates that the search lists all the results. A yellow message box indicates that the search lists only partial results.
Procedure
1 (Optional) If you are editing a workflow in the workflow editor, click Save and Close to exit the editor.
2 From the Orchestrator client menu, select Tools > User Preferences.
3 Click the General tab.
4 Type the number of results for searches to return in the Finder Maximum Size text box.
5 Click Save and Close in the User Preferences dialog box.
You modified the number of results that searches return.

Schema Elements

The workflow editor presents the workflow schema elements in menus in the Schema tab.
Table 2-3 describes all of the schema elements from which you can build workflows.
Table 2-3. Schema Elements and Icons
Schema Element Name Description Icon
Start Workflow The starting point of the workflow. All
workflows contain this element and it cannot be removed from the workflow schema. A workflow can have only one start element. Start elements have one output and no input.
Scriptable Task General purpose tasks you define. You write
JavaScript functions in this element.
Icon Location in Workflow editor
Always present in the
Schema tab
Generic workflow palette
VMware, Inc. 25
vCenter Orchestrator Developer's Guide
Table 2-3. Schema Elements and Icons (Continued)
Schema Element Name Description Icon
Decision Boolean function. Decision elements take
Custom Decision Boolean function. Custom decisions can take
User Interaction Allows users to pass new input parameters
Waiting Timer Used by long-running workflows. When a
Waiting Event Used in long-running workflows. When a
End Workflow The end point of the workflow. You can have
one input parameter and return either true or false. The type of decision the element makes depends on the type of the input parameter. Decision elements allow the workflow to branch into different directions, depending on the input parameter the decision element receives. If the received input parameter corresponds to an expected value, the workflow continues along a certain route. If the input is not the expected value, the workflow continues on an alternative path.
several input parameters and act upon them according to custom scripts. Returns either true or false.
into the workflow. You can design how the user interaction element presents the request for input parameters and place constraints on the parameters that users can provide. You can set permissions to determine which users can provide the input parameters. When a running workflow arrives at a user interaction element, it enters a passive state and prompts the user for input. You can set a timeout period within which the users can answer. The workflow resumes according to the data the user passes to it, or returns an exception if the timeout period expires. While it is waiting for the user to respond, the workflow token is in the waiting state.
running workflow arrives at a Waiting Timer element it enters a passive state. You set an absolute date at which the workflow resumes running. While it is waiting for the date, the workflow token is in the waiting- signal state.
running workflow arrives at a Waiting Event element it enters a passive state. You define a trigger event that the workflow awaits before it resumes running. While it is waiting for the event, the workflow token is in the waiting-signal state.
multiple end elements in a schema, to represent the different possible outcomes of the workflow. End elements have one input with no output. When a workflow reaches an End Workflow element, the workflow token enters the completed state.
Icon Location in Workflow editor
Generic workflow palette
Generic workflow palette
Generic workflow palette
Generic workflow palette
Generic workflow palette
Generic workflow palette
Table 2-3. Schema Elements and Icons (Continued)
Schema Element Name Description Icon
Thrown Exception Creates an exception and stops the
workflow. Multiple occurrences of this element can be present in the workflow schema. Exception elements have one input parameter, which can only be of the String type, and have no output parameter. When a workflow reaches an Exception element, the workflow token enters the failed state.
Workflow Note Allows you to annotate sections of the
workflow. You can stretch notes to delineate sections of the workflow. You can change the background color of the notes to differentiate between different workflow zones. Workflow notes provide visual information only, to help you understand the schema.
Pre-Defined Task Noneditable scripted elements that perform
standard tasks that workflows commonly use. The following tasks are predefined:
Basic
n
Sleep
n
Change credential
n
Wait until date
n
Wait for custom event
n
Increase counter
n
Decrease counter
n
Add hours to date
Log
n
System log
n
System warning
n
System error
n
Server log
n
Server warning
n
Server error
n
System+server log
n
System+server warning
n
System+server error
Network
n
HTTP post
n
HTTP get
n
Send custom event
Action Calls on an action from the Orchestrator
libraries of actions. When a workflow reaches an action element, it calls and runs that action.
Workflow Starts another workflow synchronously. As
soon as a workflow reaches a workflow element in its schema, it runs that workflow as part of its own process. The original workflow does not continue until the called workflow completes its run.
Chapter 2 Developing Workflows
Icon Location in Workflow editor
Generic workflow palette
Generic workflow palette
Basic, Log, and Network
workflow palette
Action & Workflow
workflow palette
Action & Workflow
workflow palette
VMware, Inc. 27
vCenter Orchestrator Developer's Guide
Table 2-3. Schema Elements and Icons (Continued)
Schema Element Name Description Icon
Asynchronous Workflows
Schedule Workflow Creates a task to run the workflow at a set
Nested Workflows Starts several workflows simultaneously.
Starts a workflow asynchronously. When a workflow reaches an asynchronous workflow element, it starts that workflow and continues its own run. The original workflow does not wait for the called workflow to finish before continuing.
time, then the workflow continues its run.
You can choose to nest local workflows and remote workflows that are in a different Orchestrator server. You can also run workflows with different credentials. The workflow waits until all the nested workflows complete before it continues its run.
Icon Location in Workflow editor
Action & Workflow
workflow palette
Action & Workflow
workflow palette
Action & Workflow
workflow palette

Schema Element Properties

Schema elements have properties that you can define and edit in the Schema tab of the workflow palette.
Edit a Schema Element's Global Properties
You define a schema element's global properties in the schema element's Info tab.
Prerequisites
The Schema tab of the workflow editor must contain elements.
Procedure
1 Click the Schema tab in the workflow editor.
2 Select an element to edit by clicking a schema element in the workflow schema.
The schema element's properties tabs appear at the bottom of the workflow editor.
3 Click the Info tab.
4 Provide a name for the schema element in the Name text box.
This is the name that appears in the schema element in the workflow schema diagram.
5 Click the Interaction text box and select a description from the list.
The Interaction property allows you to select between standard descriptions of how this element interacts with objects outside of the workflow. This property is for information only.
6 (Optional) Click Color to change the background color of the schema element.
You can highlight certain sections of the schema by changing the color of individual workflow elements.
7 Provide a business status description in the Business Status text box.
The Business Status property is a brief description of what this element does. When a workflow is running, the workflow token shows the Business Status of each element as it runs. This feature is useful for tracking workflow status.
Chapter 2 Developing Workflows
Schema Element Properties Tabs
You access a schema element's properties by clicking on a schema element that you have dragged into the workflow schema. The element properties appear in tabs at the bottom of the workflow editor.
Different element types present different properties tabs, as shown in Table 2-4.
Table 2-4. Properties Tabs per Schema Element
Schema Element Property Tab Description Applies to Schema Element Type
Attributes Attributes that elements require
from an external source, such as the user, an event, or a timer. The attributes can be a timeout limit, a time and date, a trigger, or user credentials.
Decision Defines the decision statement.
The input parameter that the decision element receives either matches or does not match the decision statement, resulting two possible courses of action.
End Workflow Stops the workflow, either
because the workflow completed successfully, or because it encountered an error and returned an exception.
Exception How this schema element
behaves in the event of an exception.
External Inputs Input parameters that the user
must provide at a certain moment while the workflow runs.
IN The IN binding for this element.
The IN binding defines the way in which the schema element receives input from the element that precedes it in the workflow.
n
User Interaction
n
Waiting Event
n
Waiting Timer
Decision
n
End
n
Exception
n
Action
n
Asynchronous Workflow
n
Exception
n
Nested Workflows
n
Predefined Task
n
Schedule Workflow
n
Scriptable Task
n
User Interaction
n
Waiting Event
n
Waiting Timer
n
Workflow
User Interaction
n
Action
n
Asynchronous Workflow
n
Custom Decision
n
Predefined Task
n
Schedule Workflow
n
Scriptable Task
n
Workflow
VMware, Inc. 29
vCenter Orchestrator Developer's Guide
Table 2-4. Properties Tabs per Schema Element (Continued)
Schema Element Property Tab Description Applies to Schema Element Type
Info The schema element's general
OUT The OUT binding for this
Presentation Defines the layout of the input
Scripting Shows the JavaScript function
Visual Binding Shows a graphical
Workflows Selects the workflows to nest. Nested Workflows
properties and description. The information the Info tab displays depends on the type of schema element.
element. The OUT binding defines the way in which the schema element binds output parameters to the workflow attributes or to the workflow output parameters.
parameters dialog box the user sees if the workflow needs user input while it is running.
that defines the behavior of this schema element. For Asynchronous Workflow, Schedule Workflow, and Action elements this scripting is read­only. For scriptable task and custom decision elements, you edit the JavaScript in this tab.
representation of how the parameters and attributes of this schema element bind to the parameters and attributes of the elements that come before and after it in the workflow. This is another representation of the element's IN and OUT bindings.
n
Action
n
Asynchronous Workflow
n
Custom Decision
n
Decision
n
Nested Workflows
n
Note
n
Predefined Task
n
Schedule Workflow
n
Scriptable Task
n
User Interaction
n
Waiting Event
n
Waiting Timer
n
Workflow
n
Action
n
Asynchronous Workflow
n
Predefined Task
n
Schedule Workflow
n
Scriptable Task
n
Workflow
User Interaction
n
Action
n
Asynchronous Workflow
n
Custom Decision
n
Predefined Task
n
Schedule Workflow
n
Scriptable Task
n
Action
n
Asynchronous Workflow
n
Predefined Task
n
Schedule Workflow
n
Scriptable Task
n
Workflow

Links and Bindings

Links between elements determine the logical flow of the workflow. Bindings populate elements with data from other elements by binding input and output parameters to workflow attributes.
To understand links and bindings, you must understand the difference between the logical flow of a workflow and the data flow of a workflow.
Loading...
+ 320 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use