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

2 VMware, Inc.

Updated Information 7

About This Book 9

Introduction to VMware vCenter Orchestrator 11

Key Features of the Orchestrator Platform 11

Orchestrator User Roles and Related Tasks 12

Orchestrator Architecture 13

Developing Workflows 15

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

Reusing Actions 111

Access the Actions View 111

Components of the Actions View 112

Creating Actions 112

Scripting 115

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

vCenter Orchestrator Developer's Guide

Creating Resource Elements 131

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

Create a Package 137

Set User Permissions on a Package 138

Developing Plug-Ins 141

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

Writing a Web Service Client Application 247

Web Service API Object Reference 262

Web Service API Operation Reference 267

Developing Web Views 281

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

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

4 VMware, Inc.

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

6 VMware, Inc.

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

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.

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.

Added Tapestry and Dojo versions in “Web View Overview,” on page 282.

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.

Added “Limitations of the Mozilla Rhino Implementation in Orchestrator,” on page 116 and “Color

Coding of Scripting Keywords,” on page 120.

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.

Added links to third-party Web development standards in “Web View Overview,” on page 282.

Corrected description of Execute permission in “Set User Permissions on a Package,” on page 138.

Corrected OGNL syntax in “vmo:WorkflowLink Component,” on page 307.

Added how to set a relative timeout and revised the information in “Requesting User Interactions While

a Workflow Runs,” on page 44.

Corrected descriptions of the Pre-defined answers and Pre-defined list of elements properties in “Workflow Input Parameter Properties,” on page 42.

Improved definitions in “Overview of Plug-Ins,” on page 141 and “Contents and Structure of a Plug-

In,” on page 147.

Complete revision of “Create an Orchestrator Plug-In,” on page 151.

Added information about how to add a plug-in tab to the configuration interface in “Create an

Orchestrator Plug-In,” on page 151.

Added missing classes to “Orchestrator Plug-In API Reference,” on page 216 and improved descriptions.

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.

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.

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:

New procedure, “Edit a Workflow from the Standard Library,” on page 18.

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.

New Chapter 5, “Creating Resource Elements,” on page 131.

Major revision of Chapter 9, “Developing Web Views,” on page 281.

New “Appendix: Workflow Name Changes,” on page 337 to reflect changes between Orchestrator 4.0 and 4.0.1.

EN-000129-01

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.

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.

8 VMware, Inc.

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.

Application developers who want to create new extensions to the Orchestrator platform.

Scripting developers who want to create new building blocks to automate certain processes.

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

Web designers who want to create or customize Web front ends for these processes, using the Web 2.0 technologies.

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.

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.

10 VMware, Inc.

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:

“Key Features of the Orchestrator Platform,” on page 11

“Orchestrator User Roles and Related Tasks,” on page 12

“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:

Actions

Workflows

Policies

The workflow engine allows you to capture business processes. It uses one of the following methods to create a step-by-step automation:

Building blocks of the library

Building blocks provided by the customer

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 plugins, 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:

Public Key Infrastructure (PKI) to sign and encrypt content imported and exported between servers

Digital Rights Management (DRM) to control how exported content might be viewed, edited and redistributed

Secure Sockets Layer (SSL) encrypted communications between the desktop client and the server and HTTPS access to the Web front end.

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:

Installing and configuring Orchestrator

Managing access rights for Orchestrator and applications

Importing and exporting packages

Enabling and disabling Web views

12 VMware, Inc.

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

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

14 VMware, Inc.

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.

Principal Phases in the Workflow Development Process on page 16

The process for developing a workflow involves a series of phases.

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.

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.

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.

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.

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.

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.

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.

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.

vCenter Orchestrator Developer's Guide

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.

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.

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.

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.

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.

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.

Running Workflows on page 68

A workflow runs according to a logical flow of events.

Develop a Simple Example Workflow on page 70

Developing a simple example workflow demonstrates the most common steps in the workflow development process.

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.

16 VMware, Inc.

Accessing the Orchestrator Client

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.

Create a Workflow on page 18

You can create workflows in the workflows hierarchical list in the Orchestrator client interface.

Edit a Workflow on page 18

You edit a workflow by using the Orchestrator client's workflow editor.

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.

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

18 VMware, Inc.

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

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

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.

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.

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.

20 VMware, Inc.

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.

Define Workflow Attributes on page 21

Workflow attributes are the data that workflows process.

Define Workflow Parameters on page 22

Input and output parameters allow you to pass information and data into and out of the workflow.

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.

Click Inputs to create input parameters.

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

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.

22 VMware, Inc.

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

abstract

back_char_esc

back_char_literal

boolean

byte

char

char_literal

class

_classResolver

const

context

debugger

dec_digits

dec_flt

default

delete

digit

double

dynamic_subscript

enum

eof

esc

exponent

export

extends

false

final

flt_literal

flt_suff

ident

implements

import

int

int_literal

interface

_keepLastEvaluation

_lastEvaluation

letter

long

_memberAccess

native

package

private

public

root

short

static

string_esc

string_literal

synchronized

this

_traceEvaluations

true

_typeConverter

volatil

with

WithinBackCharLiteral

WithinCharLiteral

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.

View Workflow Schema on page 24

You view a workflow schema in the Schema tab for that workflow in the Orchestrator client.

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.

Schema Elements on page 25

The workflow editor presents the workflow schema elements in menus in the Schema tab.

Schema Element Properties on page 28

Schema elements have properties that you can define and edit in the Schema tab of the workflow palette.

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.

Decisions on page 36

Workflows can implement decision functions that define different courses of action according to a Boolean true or false statement.

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

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.

24 VMware, Inc.

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

26 VMware, Inc.

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

Sleep

Change credential

Wait until date

Wait for custom event

Increase counter

Decrease counter

Add hours to date

Log

System log

System warning

System error

Server log

Server warning

Server error

System+server log

System+server warning

System+server error

Network

HTTP post

HTTP get

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

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.

28 VMware, Inc.

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.

User Interaction

Waiting Event

Waiting Timer

Decision

End

Exception

Action

Asynchronous Workflow

Exception

Nested Workflows

Predefined Task

Schedule Workflow

Scriptable Task

User Interaction

Waiting Event

Waiting Timer

Workflow

User Interaction

Action

Asynchronous Workflow

Custom Decision

Predefined Task

Schedule Workflow

Scriptable Task

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

Action

Asynchronous Workflow

Custom Decision

Decision

Nested Workflows

Note

Predefined Task

Schedule Workflow

Scriptable Task

User Interaction

Waiting Event

Waiting Timer

Workflow

Action

Asynchronous Workflow

Predefined Task

Schedule Workflow

Scriptable Task

Workflow

User Interaction

Action

Asynchronous Workflow

Custom Decision

Predefined Task

Schedule Workflow

Scriptable Task

Action

Asynchronous Workflow

Predefined Task

Schedule Workflow

Scriptable Task

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.

30 VMware, Inc.

Chapter 2 Developing Workflows

Logical Flow of a Workflow

The logical flow of a workflow is the progression of the workflow from one element to the next in the schema as the workflow runs. You define the logical flow of the workflow by linking elements in the schema.

The standard path is the path that the workflow takes through the logical flow if all elements run normally. The exception path is the path that the workflow takes through the logical flow if an element does not run normally.

Different styles of arrows in the workflow schema denote the different paths that the workflow can take through its logical flow.

A black arrow denotes the standard path that the workflow takes from one element to the next.

A green arrow denotes the path that the workflow takes if a Boolean decision element returns true.

A red dotted arrow denotes the path that the workflow takes if a Boolean decision element returns

false.

A thick red dotted arrow denotes the exception path that the workflow takes if a workflow element does not run correctly.

Figure 2-1 shows an example workflow schema that demonstrates the different paths that workflows can take.

Figure 2-1. Different Workflow Paths Through the Logical Flow of the Workflow

This example workflow can take the following paths through its logical flow.

Standard path, true decision result, no exceptions.

a The decision element returns true.

b The SnapVMsInResourcePool workflow runs successfully.

c The sendHtmlEmail action runs successfully.

d The workflow ends successfully in the completed state.

Standard path, false decision result, no exceptions.

a The decision element returns false.

b The operation the scriptable task element defines runs successfully.

c The sendHtmlEmail action runs successfully.

d The workflow ends successfully in the completed state.

VMware, Inc. 31

vCenter Orchestrator Developer's Guide

true decision result, exception.

a The decision element returns true.

b The SnapVMsInResourcePool workflow encounters an error.

c The workflow returns an exception and stops in the failed state.

false decision result, exception.

a The decision element returns false.

b The operation the Scriptable task element defines encounters an error.

c The workflow returns an exception and stops in the failed state.

Element Links

Links connect schema elements and define the logical flow of the workflow from one element to the next.

Elements can usually set only one outgoing link to another element in the workflow and one exception link to an element that defines its exception behavior. The outgoing link defines the standard path of the workflow. The exception link defines the exception path of the workflow. In most cases, a single schema element can receive incoming standard path links from multiple elements.

The following elements are exceptions to the preceding statements.

The Start Workflow element cannot receive incoming links and has no exception link.

Exception elements can receive multiple incoming exception links, and have no outgoing or exception links.

Decision elements have two outgoing links that define the paths the workflow takes depending on the decision's true or false result. Decisions have no exception link.

End Workflow elements cannot have outgoing links or exception links.

Create Standard Path Links

You link elements by connecting them using the connector tool in the Schema tab of the workflow editor.

When you link one element to another, you always link the elements in the order in which they run in the workflow. You always start from the element that runs first to create a link between two elements.

Prerequisites

To link elements, you must have the workflow editor open and the Schema must contain elements.

Procedure

1 Click the connector tool button in the toolbar at the top of the Schema tab to activate the connector tool.

2 Click an element to link to another element.

3 Move the pointer over the highlighted element to link to another element.

A black rectangle appears at the bottom of the element.

4 Left-click inside the element near the black rectangle, hold down the left mouse button, and move the

pointer to the target element.

An arrow appears between the two elements and the target element turns green.

5 Release the left mouse button.

The arrow remains between the two elements.

A standard path now links the elements.

32 VMware, Inc.

Chapter 2 Developing Workflows

What to do next

The elements are joined, but you have not defined the data flow. You must define the IN and OUT bindings to bind incoming and outgoing data to workflow attributes.

Data Flow of a Workflow

The data flow of a workflow is the manner in which workflow element input and output parameters bind to workflow attributes as each element of the workflow runs. You define the data flow of a workflow by using schema element bindings.

When an element in the workflow schema runs, it requires data in the form of input parameters. It takes the data for its input parameters by binding to a workflow attribute that you set when you create the workflow, or by binding to an attribute that a preceding element in the workflow set when it ran.

The element processes the data, possibly transforms it, and generates the results of its run in the form of output parameters. The element binds its resulting output parameters to new workflow attributes that it creates. Other elements in the schema can bind to these new workflow attributes as their input parameters. The workflow can generate the attributes as its output parameters at the end of its run.

Figure 2-2 shows a very simple workflow. The black arrows represent the element linking and the logical flow

of the workflow. The red lines show the data flow of the workflow.

Figure 2-2. Example of Workflow Data Flow

The data flows through the workflow as follows.

1 The workflow starts with input parameters a and b.

2 The first element processes parameter a and binds the result of the processing to workflow attribute c.

3 The first element processes parameter b and binds the result of the processing to workflow attribute d.

4 The second element takes workflow attribute c as an input parameter, processes it, and binds the resulting

output parameter to workflow attribute e.

5 The second element takes workflow attribute d as an input parameter, processes it, and generates output

parameter f.

6 The workflow ends and generates workflow attribute f as its output parameter, the result of its run.

VMware, Inc. 33

vCenter Orchestrator Developer's Guide

Element Bindings

You must bind all workflow element input and output parameters to workflow attributes. Bindings set data in the elements, and define the output and exception behavior of the elements. Links define the logical flow of the workflow, whereas bindings define the data flow.

To set data in an element, generate ouput parameters from the element after processing, and handle any errors that might occur when the element runs, you must set the element binding.

IN bindings

Set a schema element's incoming data. You bind the element's local input parameters to source workflow attributes. The IN tab lists the element's input parameters in the Local Parameter column. The IN tab lists the workflow attributes to which the local parameter binds in the Source Parameter column. The tab also shows the parameter type and a description of the parameter.

OUT bindings

Change workflow attributes and generate output parameters when an element finishes its run. The OUT tab lists the element's output parameters in the Local Parameter column. The OUT tab lists the workflow attributes to which the local parameter binds in the Source Parameter column. The tab also shows the parameter type and a description of the parameter.

Exception bindings

Link to exception handlers if the element encounters an exception when it runs.

You must use IN bindings to bind every attribute or input parameter you use in a schema element to a workflow attribute. If the element changes the values of the input parameters it receives when it runs, you must bind them to a workflow attribute by using an OUT binding. Binding the element's output parameters to workflow elements allows other elements that follow it in the workflow schema to take those output parameters as their input parameters.

A common mistake when creating workflows is to forget to bind output parameter values to reflect the changes the element makes to the workflow attributes.

IMPORTANT When you add an element that requires input and output parameters of a type that you already defined in the workflow, Orchestrator sets the bindings to these parameters. You must check that the parameters Orchestrator binds are correct, in case the workflow defines different parameters of the same type to which the element could bind.

Define Element Bindings

After you link elements to create the logical flow of the workflow, you define element bindings to define how each element processes the data it receives and generates.

Prerequisites

You must have a workflow schema in the Schema tab of the workflow editor, and have created links between the elements.

34 VMware, Inc.

Chapter 2 Developing Workflows

Procedure

1 Click an element on which to set the bindings.

The element is highlighted and the element attributes tabs appear at the bottom of the Schema tab.

2 Click the IN tab.

The contents of the IN tab depend on the type of element you selected.

If you selected a predefined task, workflow, or action element, the IN tab lists the possible local input parameters for that type of element, but the binding is not set.

If you selected another type of element, you can select from a list of input parameters and attributes you already defined for the workflow by right-clicking in the IN tab and selecting Bind to workflow attribute/parameter.

If the required attribute does not exist yet, you can create it by right-clicking in the IN tab and selecting Bind to workflow attribute/parameter > Create attribute/parameter in workflow.

3 If an appropriate parameter exists, choose an input parameter to bind, and click the Not set button in the

Source Parameter text box.

A list of possible source parameters and attributes to bind to appears.

4 Choose a source parameter to bind to the local input parameter from the list proposed.

5 (Optional) If you have not defined the source parameter to which to bind, you can create it by clicking the

Create attribute/parameter in workflow link in the parameter selection dialog box.

6 Click the OUT tab.

The contents of the OUT tab depend on the type of element you selected.

If you selected a predefined task, workflow, or action element, the OUT tab lists the possible local output parameters for that type of element, but the binding is not set.

If you selected another type of element, you can select from a list of output parameters and attributes you defined for the workflow by right-clicking in the OUT tab and selecting Bind to workflow attribute/parameter.

If the required attribute does not exist, you can create it by right-clicking in the IN tab and selecting Bind to workflow attribute/parameter > Create attribute/parameter in workflow.

7 Choose a parameter to bind.

8 Click the Source Parameter > Not set button.

9 Choose a source parameter to bind to the input parameter.

10 (Optional) If you did not define the parameter to which to bind, you can create it by clicking the Create

attribute/parameter in workflow button in the parameter selection dialog box.

You defined the input parameters that the element receives and the output parameters that it generates, and bound them to workflow attributes and parameters.

What to do next

You can create forks in the path of the workflow by defining decisions.

VMware, Inc. 35

vCenter Orchestrator Developer's Guide

Decisions

Workflows can implement decision functions that define different courses of action according to a Boolean

true or false statement.

Decisions are forks in the workflow. Workflow decisions are made according to inputs provided by you, by other workflows, by applications, or by the environment in which the workflow is running. The value of the input parameter that the decision element receives determines which branch of the fork the workflow takes. For example, a workflow decision might receive the power status of a given virtual machine as its input. If the virtual machine is powered on, the workflow takes a certain path through its logical flow. If the virtual machine is powered off, the workflow takes a different path.

Decisions are always Boolean functions. The only possible outcomes for each decision are true or false.

Custom Decisions

Custom decisions differ from standard decisions in that you define the decision statement in a script. Custom decisions return true or false according to the statement you define, as the following example shows.

decision_statement

if ( return true; }else{ return false; }

){

Create Decision Element Links

Decision elements differ from other elements in that they have only true or false output parameters. Decision elements have no exception linking.

Prerequisites

You must have the workflow editor open and the Schema tab must contain elements, including at least one decision element.

Procedure

1 Click a decision element to link to two other elements to define two possible branches in the workflow.

2 Click the connector tool button in the toolbar at the top of the Schema tab.

3 Move the pointer over the highlighted decision element to link to two other elements.

If you hold the pointer over the left side of the decision element, a green arrow appears at the bottom of the element. The green arrow represents the true path the workflow takes if the input parameter or attribute received by the decision element matches the decision statement.

If you hold the pointer over the right side of the decision element, a red arrow appears at the bottom of the element. The red arrow represents the false path the workflow takes if the input parameter or attribute received by the decision element does not match the decision statement.

4 Left-click inside the left side of the decision element, hold down the left mouse button, and move the

pointer to the target element.

A green arrow appears between the two elements and the target element turns green.

5 Release the left mouse button.

The green arrow remains between the two elements. You have defined the path the workflow takes when the decision element receives the expected value.

36 VMware, Inc.

Chapter 2 Developing Workflows

6 Left-click inside the right side of the decision element, hold down the left mouse button, and move the

pointer to the target element.

A dotted red arrow appears between the two elements and the target element turns green.

7 Release the left mouse button.

The dotted red arrow remains between the two elements. You have defined the path the workflow takes when the decision element receives unexpected input.

You have defined two possible true or false paths for the workflow to take, depending on the input parameter or attribute the decision element receives.

What to do next

The decision element is linked to two other elements, but you did not define how the workflow determines which path to take. You must define the decision statement.

Create Workflow Branches Using Decisions

Decision elements are simple Boolean functions that you use to create branches in workflows. Decision elements determine whether or not the input received matches the decision statement you set. As a function of this decision, the workflow continues its course along one of two possible paths.

Prerequisites

You must have a decision element linked to two other elements in the schema in the workflow editor before you define the decision.

Procedure

1 Click the decision element.

2 Click the Decision tab in the element properties tabs at the bottom of the Schema tab.

3 Click the Not Set (NULL) link to select the possible source input parameter for this decision.

A dialog box appears, which lists all the attributes and input parameters you defined in this workflow.

4 Select an input parameter from the list by double-clicking it.

5 (Optional) If you did not define the source parameter to which to bind, you can create it by clicking the

Create attribute/parameter in workflow link in the parameter selection dialog box.

6 Select a decision statement from the drop-down menu.

The statements the menu proposes are contextual, and differ according to the type of input parameter selected.

7 Add a value for the statement to match.

Depending on the input type and the statement you select, you might see a Not Set (NULL) link in the value text box. Clicking this link gives you a predefined choice of values. Otherwise, for example for Strings, this is a text box in which you provide a value.

You defined a statement for the decision element. When the decision element receives the input parameter, it compares the value of the input parameter to the value in the statement and determines whether the statement is true or false.

What to do next

You must set up how the workflow handles exceptions.

VMware, Inc. 37

vCenter Orchestrator Developer's Guide

Exception Handling

Exception handling catches any errors that occur when a schema element runs. Exception handling defines how the schema element behaves when the error occurs.

All elements in a workflow, except for decisions and start and end elements, contain a specific output parameter type that serves only for handling exceptions. If an element encounters an error during its run, it can send an error signal to an exception handler. Exception handlers catch the error and react according to the errors they receive. If the exception handlers you define cannot handle a certain error, you can bind an element's exception output parameter to an Exception element, which ends the workflow run in the failed state.

Exceptions act as a try and catch sequence within a workflow element. If you do not need to handle a given exception in an element, you do not have to bind that element's exception output parameter.

The output parameter type for exceptions is always an errorCode object.

Create Exception Bindings

Elements can set bindings that define how the workflow behaves if it encounters an error in that element.

Prerequisites

The Schema tab of the workflow editor must contain elements.

Procedure

1 Click the element on which to set the exception binding.

2 Click the connector tool button in the toolbar at the top of the Schema tab or hold down Ctrl and move

the pointer over the right of the element for which to set the exception binding.

A red rectangle appears on the right of the element.

3 Left-click inside the element near the red rectangle, hold down the left mouse button, and move the pointer

to the target element.

A thick dotted red arrow links the two elements. The target element defines the behavior of the workflow if the element that links to it encounters an error.

4 Click the element that links to the exception handling element.

5 Click the Exceptions tab in the schema element properties tabs at the bottom of the Schema tab.

6 Click the Not set button to set the Output Exception Binding value.

Select a parameter to bind to the exception output parameter from the exception attribute binding dialog box.

Click Create parameter/attribute in workflow to create an exception output parameter.

7 Click the target element that defines the exception handling behavior.

8 Click the IN tab in the schema element properties tabs at the bottom of the Schema tab.

9 Right-click in the IN tab and select Bind to workflow parameter/attribute.

10 Select the exception output parameter and click Select.

38 VMware, Inc.

Chapter 2 Developing Workflows

11 Click the OUT tab for the exception handling element in the schema element properties tabs at the bottom

of the Schema tab

12 Define the behavior of the exception handling element.

Right-click in the OUT tab and select Bind to workflow parameter/attribute to select an output parameter for the exception handling element to generate.

Click the Scripting tab and use JavaScript to define the behavior of the exception handling element.

You defined how the element handles exceptions.

What to do next

You must define how to obtain input parameters from users when they run the workflow.

Obtaining Input Parameters from Users When a Workflow Starts

The way you organize parameters in the Presentation tab translates into the input parameters dialog box when the workflow runs, and in the dialog box that opens when you run a workflow from a Web view.

The Presentation tab also allows you to add descriptions of the input parameters to help users when they provide input parameters. You can also set properties and constraints on parameters in the Presentation tab to limit the parameters that users provide. If the parameters the user provides do not meet the constraints you set in the Presentation tab, the workflow will not run.

Creating the Input Parameters Dialog Box In the Presentation Tab on page 39

You define the layout of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab of the workflow editor.

Setting Parameter Properties on page 41

Orchestrator allows you to define properties to qualify the input parameter values that users provide when they run workflows. The parameter properties you define impose limits on the types and values of the input parameters the users provide.

Creating the Input Parameters Dialog Box In the Presentation Tab

You define the layout of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab of the workflow editor.

The Presentation tab allows you to group input parameters into categories and to define the order in which these categories appear in the input parameters dialog box.

Presentation Descriptions

You can add an associated description for each parameter or group of parameters, which appears in the input parameters dialog box. The descriptions provide information to the users to help them provide the correct input parameters. You can enhance the layout of the description text by using HTML formatting.

Defining Presentation Input Steps

By default, the input parameters dialog box lists all the required input parameters in a single list. To help users enter input parameters, you can define nodes, called input steps, in the presentation tab. Input steps group input parameters of a similar nature. The input parameters under an input step appear in a distinct section in the input parameters dialog box when the workflow runs.

VMware, Inc. 39

vCenter Orchestrator Developer's Guide

Defining Presentation Display Groups

Each input step can have nodes of its own called display groups. The display groups define the order in which parameter input text boxes appear within their section of the input parameters dialog box. You can define display groups independently of input steps.

Create the Presentation of the Input Parameters Dialog Box

You create the presentation of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab in the workflow editor.

Prerequisites

You must have created a workflow and a defined list of input parameters.

Procedure

1 In the workflow editor, click the Presentation tab.

By default, all of the workflow's parameters appear under the main Presentation node in the order in which you create them.

2 Right-click the Presentation node and select Create new step.

A New Step node appears under the Presentation node.

3 Double-click the New Step node to provide it with an appropriate name and press Enter.

This name appears as a section header in the input parameters dialog box when the workflow runs.

4 Click the input step and add a description in the General tab in the bottom half of the Presentation tab.

This description appears in the input parameters dialog box to provide information to the users to help them provide the correct input parameters. You can enhance the layout of the description text by using HTML formatting.

5 Right-click the input step you created and select Create display group.

A New Group node appears under the input step node.

6 Double-click the New Group node and provide it with an appropriate name.

This name appears as a subsection header in the input parameters dialog box when the workflow runs.

7 Click the display group and add a description in the General tab in the bottom half of the Presentation

tab.

This description appears in the input parameters dialog box. You can enhance the layout of the description text by using HTML formatting. You can add a parameter value to a group description by using an OGNL statement, such as ${#param}.

8 Repeat the preceding steps until you have created all the input steps and display groups to appear in the

input parameters dialog box when the workflow runs.

9 Drag parameters from under the Presentation node to the steps and groups of your choice.

You created the layout of the input parameters dialog box through which users provide input parameter values when the workflow runs.

What to do next

You must set the parameter properties.

40 VMware, Inc.

Chapter 2 Developing Workflows

Setting Parameter Properties

Every parameter can have several properties. You define an input parameter's properties in the Properties tab for a given parameter in the Presentation tab.

Parameter properties validate the input parameters and modify the way that text boxes appear in the input parameters dialog box. Some parameter properties can create dependencies between parameters.

Static and Dynamic Parameter Property Values

A parameter property value can be either static or dynamic. Static property values remain constant. If you set a property value to static, you set or select the property's value from a list that the workflow editor generates according to the parameter type.

Dynamic property values depend on the value of another parameter or attribute. You define the functions by which dynamic properties obtain values by using an object graph navigation language (OGNL) expression. If a dynamic parameter property value depends on the value of another parameter property value and the other parameter property value changes, the OGNL expression recalculates and changes the dynamic property value.

Set Parameter Properties

When a workflow starts, it validates input parameter values from users against any parameter properties that you set.

Prerequisites

You must have a workflow and defined a list of input parameters before setting the parameter constraints.

Procedure

1 In the workflow editor, click the Presentation tab.

2 Click a parameter in the Presentation tab.

The parameter's General and Properties tabs appear at the bottom of the Presentation tab.

3 Click the parameter's Properties tab.

4 Right-click in the Properties tab and select Add property.

A dialog box opens, presenting a list of the possible properties for a parameter of the type selected.

5 Select a property from the list presented in the dialog box and click OK.

The property appears in the Properties tab.

6 Under Value, make the property value either static or dynamic by selecting the corresponding symbol

from the drop-down menu.

Option Description

Static property

Dynamic property

VMware, Inc. 41

vCenter Orchestrator Developer's Guide

7 If you set the property value to static, you select a property value according to the type of parameter for

which you are setting the properties.

8 If you set the property value to dynamic, you define the function to obtain the parameter property value

by using an OGNL expression.

The workflow editor provides help writing the OGNL expression.

Click the

icon to obtain a list of all the attributes and parameters defined by the workflow that

this expression can call upon.

Click the icon to obtain a list of all the actions in the Orchestrator API that return an output parameter of the type for which you are defining the properties.

Clicking items in the proposed lists of parameters and actions adds them to the OGNL expression.

9 Click Save at the bottom of the workflow editor.

You defined the properties of the workflow's input parameters.

What to do next

Validate and debug the workflow.

Workflow Input Parameter Properties

You can set parameter properties to constrain the input parameters that users provide when they run workflows.

The possible properties for each type of parameter are listed in Table 2-5.

Table 2-5. Workflow Input Parameter Properties

Parameter Property Parameter Type Description

Maximum string length String Sets a maximum length for the

parameter.

Minimum string length String Sets a minimum length for the

parameter.

Matching regular expression String Validates the input using a regular

expression.

Maximum number value Number Sets a maximum value for the

parameter.

Minimum number value Number Sets a minimum value for the

parameter.

Number format Number Formats the input for the parameter.

Mandatory Any Makes the parameter mandatory.

Predefined answers All simple types Pre-defines a list of possible values for

the property as an array of simple types. You either define the array manually or the property calls an action that returns an array of objects of the appropriate type.

Predefined list of elements Any simple or complex types Pre-defines a list of possible values for

the property as an array of simple or complex types. Calls an action that returns an array of objects of the appropriate type.

42 VMware, Inc.

Table 2-5. Workflow Input Parameter Properties (Continued)

Parameter Property Parameter Type Description

Chapter 2 Developing Workflows

Show parameter input Any Shows or hides a parameter text box in

Hide parameter input Any Similar to Show parameter input, but

Matching expression Any parameter type obtained from a

plug-in

Show in inventory Any parameter type obtained from a

plug-in

Specify a root object to be shown in the chooser. Root object is provided from a paramter or attribute.

Select as Any parameter type obtained from a

Default value Any Default value for this parameter.

Custom validation OGNL scriptable validation If the OGNL expression returns a string,

Auto start Boolean Starts the workflow automatically.

Mandatory input Boolean Makes this parameter mandatory. The

Data binding Any Binds to a property that you have

Authorized only Any parameter type obtained from a

Multi-lines text input Any Allows users to enter multiple lines of

Any parameter type obtained from a plug-in

plug-in

the presentation dialog box, depending on the value of a preceding Boolean parameter.

takes the negative value of a previous Boolean parameter.

The input parameter matches a given expression.

If set, you can run the present workflow on any object of this type by rightclicking it in the inventory view and selecting Run workflow.

Specifies the root object if the selector for this parameter is a hierarchical list selector.

Use a list or hierarchical list selector to select the parameter.

the validation shows this string as the text of the error result.

workflow will not run without it.

already defined in another parameter.

Only authorized users can access this parameter.

text in the input parameters dialog box.

Predefined Constant Values for OGNL Expressions

You can use predefined constants when you create OGNL expressions to obtain dynamic parameter property values.

Orchestrator defines the following constants for use in OGNL expressions.

Table 2-6. Predefined OGNL Constant Values

Constant Value Description

${#__current}

${#__username}

${#__userDisplayName}

${#__serverUrl}

${#__datetime}

VMware, Inc. 43

Current value of the custom validation property or matching expression property

Username of the user who started the workflow

Display name of the user who started the workflow

URL containing the IP address of the server from which the user starts the workflow

Current date and time

vCenter Orchestrator Developer's Guide

Table 2-6. Predefined OGNL Constant Values (Continued)

Constant Value Description

${#__date}

${#__timezone}

Current date, with time set to 00:00:00

Current timezone

Requesting User Interactions While a Workflow Runs

For example, if a certain event occurs while a workflow runs, the workflow can request human interaction to decide what course of action to take. The workflow waits before continuing, either until the user responds to the request for information, or until the waiting time exceeds a possible timeout period. If the waiting time exceeds the timeout period, the workflow returns an exception.

The default attributes for user interactions are security.group and timeout.date. When you set the

security.group attribute to a given LDAP user group, you limit the permission to respond to the user

interaction request to members of that user group.

When you set the timeout.date attribute, you set a time and date until which the workflow waits for the information from the user. You can set an absolute date, or you can create a scripted workflow element to calculate a time relative to the current time.

Procedure

1 Add a User Interaction to a Workflow on page 45

You request input parameters from users during a workflow run by adding a User Interaction schema element to the workflow. When a workflow encounters a User Interaction element, it suspends its run and waits for the user to provide the data that it requires.

2 Set the User Interaction security.group Attribute on page 45

The security.group attribute of a user interaction element sets which users or groups of users have permission to respond to the user interaction.

3 Set the timeout.date Attribute to an Absolute Date on page 46

You set the timeout.date attribute for a user interaction to set how long the workflow waits for a user to respond to a user interaction.

4 Calculate a Relative Timeout for User Interactions on page 47

You can calculate in a Date object a relative time and date at which a user interaction times out.

5 Set the timeout.date Attribute to a Relative Date on page 48

You can set the timeout.date attribute of a User Interaction element to a relative time and date by binding it to a Date object. You define the object in a scripted function.

6 Define the External Inputs for a User Interaction on page 49

You specify the information that users must provide during a workflow run as the input parameters of a user interaction.

7 Define User Interaction Exception Behavior on page 49

If a user does not provide the input parameters within the timeout period, the user interaction returns an exception. You can define the exception behavior in a scripted function.

44 VMware, Inc.

Chapter 2 Developing Workflows

8 Create the Input Parameters Dialog Box for the User Interaction on page 51

Users provide input parameters during a workflow run in an input parameters dialog box, in the same way that they provide input parameters when a workflow first starts.

9 Respond to a Request for a User Interaction on page 52

Workflows that require interactions from users during their run suspend their run either until the user provides the required information or until the workflow times out.

Add a User Interaction to a Workflow

Prerequisites

Create a workflow

Open the workflow for editing in the workflow editor

Add some elements to the workflow schema

Procedure

1 Drag a User Interaction element to the appropriate position in the workflow schema.

2 Link the User Interaction element to the elements that precede and follow it.

3 Click the User Interaction element to display its properties tabs in the bottom half of the Schema tab.

4 Provide a name and a description for the user interaction in the Info tab.

5 Click Save.

You added a user interaction element to a workflow. When the workflow reaches this element, it waits for information from the user before continuing its run.

What to do next

Set the security.group attribute of the user interaction to limit permission to respond to the user interaction to a user or user group. See “Set the User Interaction security.group Attribute,” on page 45.

Set the User Interaction security.group Attribute

The security.group attribute of a user interaction element sets which users or groups of users have permission to respond to the user interaction.

Prerequisites

Create a workflow.

Open the workflow for editing in the workflow editor.

Add some elements and a user interaction to the workflow schema.

Identify an LDAP user group to respond to the user interaction request.

Procedure

1 Click the User Interaction element in the workflow schema.

2 Click the Attributes tab for the user interaction.

3 Click Not set for the security.group source parameter to set which users can respond to the user

interaction.

VMware, Inc. 45

vCenter Orchestrator Developer's Guide

4 (Optional) Select NULL to allow all users to respond to the request for user interaction.

5 To limit the permission to respond to a specific user or user group, click Create parameter/attribute in

workflow.

The Parameter information dialog box opens.

6 Name the parameter.

7 Select Create workflow ATTRIBUTE with the same name to create the LdapGroup attribute in the

workflow.

8 Click Not set for the parameter value to open the LdapGroup selection box.

9 Type the name of the LDAP user group in the Filter text box.

10 Select the LDAP user group from the list and click Select.

For example, selecting the Administrators group means that only members of that group can respond to this request for user interaction.

You limited the permission to respond to the user interaction request.

11 Click OK to close the Parameter information dialog box.

You set the security.group attribute for the user interaction.

What to do next

Set the timer.date attribute to set the timeout period for the user interaction.

To set the timeout to an absolute date and time, see “Set the timeout.date Attribute to an Absolute

Date,” on page 46.

To create a function to calculate a timeout that is relative to the current date and time, see “Calculate a

Relative Timeout for User Interactions,” on page 47.

Set the timeout.date Attribute to an Absolute Date

You set the timeout.date attribute for a user interaction to set how long the workflow waits for a user to respond to a user interaction.

You set an absolute time and date in the Date object. When the time on the given date arrives, the workflow that is waiting for a user interaction times out and ends in the Failed state. For example, you can set the user interaction to timeout at midday on February 12th. To calculate a timeout that is relative to the current time and date, see “Calculate a Relative Timeout for User Interactions,” on page 47.

Prerequisites

Open a workflow for editing in the workflow editor.

Add a user interaction element to the workflow schema.

Set the security.group attribute for the user interaction.

Procedure

1 Click the User Interaction element in the workflow schema.

2 Click the Attributes tab for the user interaction.

3 Click Not set for the timeout.date source parameter to set the timeout parameter value.

4 (Optional) Select NULL to allow the user interaction to set the workflow to wait indefinitely for the user

to respond to the user interaction.

46 VMware, Inc.

Chapter 2 Developing Workflows

5 Click Create parameter/attribute in workflow to set the workflow to fail after a timeout period.

The Parameter information dialog box opens.

6 Name the parameter.

7 Select Create workflow ATTRIBUTE with the same name to create a Date attribute in the workflow.

8 Click Not set for the parameter Value.

9 Use the calendar to select an absolute date and time until which the workflow waits for the user to respond.

10 Click OK to close the calendar.

11 Click OK to close the Parameter information dialog box.

You set the timeout.date attribute to an absolute date. The workflow times out if the user does not respond to the user interaction before this time and date.

What to do next

Define the external input parameters that the user interaction requires from the user. See “Define the External

Inputs for a User Interaction,” on page 49.

Calculate a Relative Timeout for User Interactions

You can calculate in a Date object a relative time and date at which a user interaction times out.

You can set an absolute time and date in a Date object. When the time on the given date arrives, the request for a user interaction times out. Alternatively, you can create a workflow element that calculates and generates a relative Date object according to a function that you define. For example, you can create a relative Date object that adds 24 hours to the current time.

Prerequisites

Open a workflow for editing in the workflow editor.

Add a user interaction element to the workflow schema.

Set the security.group attribute for the user interaction.

Procedure

1 Drag a Scriptable Task element from the Generic menu to the schema of a workflow, above the element

that requires the relative Date object for its timeout.date attribute.

2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema.

3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab.

4 Provide a name and description for the scripted workflow element in the Info properties tab.

5 Right-click in the OUT properties tab, and select Bind to workflow parameter/attribute.

6 Click Create parameter/attribute in workflow to create a workflow attribute.

a Name the attribute timerDate.

b Select Date from the list of attribute types.

c Select Create workflow ATTRIBUTE with the same name.

d Leave the attribute value set to Not set, because a scripted function will provide this value.

e Click OK.

7 Click the Scripting tab for the scripted workflow element.

VMware, Inc. 47

vCenter Orchestrator Developer's Guide

8 Define a function to calculate and generate a Date object named timerDate in the scripting pad in the

Scripting tab.

For example, you can create a Date object by implementing the following JavaScript function, in which the timeout period is a relative delay in milliseconds.

timerDate = new Date(); System.log( "Current date : '" + timerDate + "'" ); timerDate.setTime( timerDate.getTime() + (86400 * 1000) ); System.log( "Timer will expire at '" + timerDate + "'" );

The preceding example JavaScript function defines a Date object that obtains the current date and time by using the getTime method and adds 86,400,000 milliseconds, or 24 hours. The Scriptable Task element generates this value as its output parameter.

9 Click Save.

You created a function that calculates a time and date relative to the current time and date and generates a

Date object. A User Interaction element can receive this Date object as an input parameter to set the timeout

period until which it waits for input from the user. When the workflow arrives at the User Interaction element, it suspends its run and waits either until the user provides the required information, or for 24 hours before it times out.

What to do next

You must bind the Date object to the User Interaction element's timeout.date parameter. See “Set the

timeout.date Attribute to a Relative Date,” on page 48.

Set the timeout.date Attribute to a Relative Date

You can set the timeout.date attribute of a User Interaction element to a relative time and date by binding it to a Date object. You define the object in a scripted function.

If you create a relative Date object in a scripted function, you can bind the timeout.date attribute of a user interaction to this Date object. For example, if you bind the timeout.date attribute to a Date object that adds 24 hours to the current time, the user interaction times out after waiting for 24 hours.

Prerequisites

Add a user interaction element to the workflow schema.

Set the security.group attribute for the user interaction.

Create a scripted function that calculates a relative time and date and encapsulates it in a Date object in the workflow. See “Calculate a Relative Timeout for User Interactions,” on page 47.

Procedure

1 Click the User Interaction element in the workflow schema.

2 Click the Attributes tab for the user interaction.

3 Click Not set for the timeout.date source parameter to set the timeout parameter value.

4 Select the Date object that encapsulates a relative time and date that you defined in a scripted function and

click Select.

You set the timeout.date attribute to a relative date and time that a scripted function calculates.

What to do next

Define the external input parameters that the user interaction requires from the user. See “Define the External

Inputs for a User Interaction,” on page 49.

48 VMware, Inc.

Chapter 2 Developing Workflows

Define the External Inputs for a User Interaction

You specify the information that users must provide during a workflow run as the input parameters of a user interaction.

When a workflow reaches a user interaction element, it waits until a user provides the information that the user interaction requires as its input parameters.

Prerequisites

Add a user interaction element to the workflow schema.

Set the security.group attribute for the user interaction.

Set the timer.date attribute for the user interaction

Procedure

1 Click the User Interaction element in the workflow schema.

2 Click the External Inputs tab.

3 Right-click in the External Inputs tab and select Bind to workflow parameter/attribute to define the

parameters that the user must provide in the user interaction.

4 (Optional) If you already defined the input parameters in the workflow, select the parameters from the

proposed list.

5 Click Create parameter/attribute in the workflow to create a workflow attribute to bind to the input

parameter that the user provides.

6 Give the parameter an appropriate name.

7 Select the input parameter type from the list of types by searching for an object type in the Filter box.

For example, if the user interaction requires the user to provide a virtual machine as an input parameter, select VC:VirtualMachine.

8 Select Create workflow ATTRIBUTE with the same name to bind the input parameter that the user

provides to a new attribute in the workflow.

9 Leave the input parameter value set to Not set.

The user provides this value when they respond to the user interaction during the workflow run.

10 Click OK to close the Parameter information dialog box.

You defined the input parameters that the user provides during a user interaction.

What to do next

Define the exception behavior if the user interaction encounters an error. See “Define User Interaction

Exception Behavior,” on page 49.

Define User Interaction Exception Behavior

If a user does not provide the input parameters within the timeout period, the user interaction returns an exception. You can define the exception behavior in a scripted function.

If you do not define the action for the workflow to take if the user interaction times out, the workflow ends in the Failed state. Defining the exception behavior is a good workflow development practice.

VMware, Inc. 49

vCenter Orchestrator Developer's Guide

Prerequisites

Add a user interaction element to the workflow schema.

Set the security.group and timer.date attributes for the user interaction.

Define the external input parameters of the user interaction.

Procedure

1 Click the User Interaction element in the workflow schema.

2 Click the Exception tab.

3 Click Not set for the output exception binding.

4 Click Create parameter/attribute in workflow to create an exception attribute to which to bind the user

interaction.

The Parameter information dialog box opens.

5 Create an errorCode attribute.

An errorCode attribute has the following default properties:

Name: errorCode

Type: string

Create: Create workflow ATTRIBUTE with the same name

Value: Type an appropriate error message.

6 Click OK to close the Parameter information dialog box.

7 Drag a scriptable task element next to the user interaction element in the workflow schema.

8 Link the exception output of the user interaction element to the scriptable task element.

A dotted red arrow between the two elements represents the exception link. The scriptable task element binds automatically to the errorCode attribute from the user interaction.

9 Double-click the scriptable task element and provide an appropriate name.

For example, Log timeout.

10 In the Scripting tab of the scriptable task element, write a JavaScript function to handle the exception.

For example, to record the timeout in the Orchestrator log, write the following function:

System.log("No response from user. Timed out.");

11 Link and bind the scriptable task element that handles exceptions to the element that follows it in the

workflow.

For example, link and bind the scriptable task element to a Throw exception element to end the workflow with an error.

You defined the exception behavior if the user interaction times out.

What to do next

Create the dialog box in which users provide input parameters. See “Create the Input Parameters Dialog Box

for the User Interaction,” on page 51.

50 VMware, Inc.

Chapter 2 Developing Workflows

Create the Input Parameters Dialog Box for the User Interaction

Users provide input parameters during a workflow run in an input parameters dialog box, in the same way that they provide input parameters when a workflow first starts.

You create the layout of the dialog box in the Presentation tab of the user interaction element, not in the Presentation tab for the whole workflow. The Presentation tab of the whole workflow creates the layout of the input parameters dialog box that appears when you start a workflow. The Presentation tab of the user interaction element creates the layout of the input parameters dialog box that opens when a workflow arrives at a user interaction element during its run.

Prerequisites

Add a user interaction element to the workflow schema.

Set the security.group and timer.date attributes for the user interaction.

Define the external input parameters of the user interaction.

Define the exception behavior.

Procedure

1 Click the User Interaction element in the workflow schema.

2 Click the Presentation tab of the user interaction element.

The Presentation tab shows the external input parameters that you created for the user interaction.

3 (Optional) Right-click the Presentation node in the Presentation tab and select Create new step.

Steps allow you to create sections in the dialog box, with descriptions and headings under which you can organize the input parameters.

4 (Optional) Right-click the Presentation node in the Presentation tab and select Create display group.

Display groups allow you to sort the order in which input parameters appear in the steps, and allow you to add sub-headers and instructions to the dialog box.

5 Click an input parameter in the list and add a description of the input parameter in the General tab for

that parameter.

The description text that you type appears as a label in the input parameters dialog box to inform the user of the information they must provide when they respond to the user interaction.

6 Define input parameter properties.

Input parameter properties allow you to qualify the input parameter values that users can provide, and to determine parameter values dynamically by using OGNL expressions.

7 Click Save and close to close the workflow editor.

You created the input parameters dialog box in which users provide input parameters to respond to a user interaction during a workflow run.

What to do next

For information about creating the presentation steps and groups and setting input parameter properties, see

“Creating the Input Parameters Dialog Box In the Presentation Tab,” on page 39.

VMware, Inc. 51

vCenter Orchestrator Developer's Guide

Respond to a Request for a User Interaction

Workflows that require interactions from users during their run suspend their run either until the user provides the required information or until the workflow times out.

Workflows that require user interactions define which users can provide the required information and direct the requests for interaction.

Prerequisites

At least one workflow in Waiting for User Interaction state.

Procedure

1 Click the My Orchestrator view in the Orchestrator client.

2 Click the Waiting for Input tab.

The Waiting for Input tab lists the workflows that are waiting for user inputs that you or members of your user group have permission to provide.

3 Double-click a workflow that is waiting for input.

The workflow token that is waiting for input appears in the Workflows hierarchical list with the following

symbol: .

4 Right-click the workflow token and select Answer.

5 Follow the instructions in the input parameters dialog box to provide the information that the workflow

requires.

You provided information to a workflow that was waiting for user input during its run.

Calling Workflows Within Workflows

Workflow Elements that Call Workflows on page 53

There are four ways to call other workflows from within a workflow. Each way of calling a workflow or workflows is represented by a different workflow schema element.

Call a Workflow Synchronously on page 55

Calling a workflow synchronously runs the called workflow as a part of the run of the calling workflow. The calling workflow can use the called workflow's output parameters as input parameters when it runs its subsequent schema elements.

Call a Workflow Asynchronously on page 55

Calling a workflow asynchronously runs the called workflow independently of the calling workflow. The calling workflow continues its run without waiting for the called workflow to complete.

52 VMware, Inc.

Chapter 2 Developing Workflows

Schedule a Workflow on page 56

You can call a workflow from a workflow and schedule it to start at a later time and date.

Call Several Workflows Simultaneously on page 57

Calling several workflows simultaneously runs the called workflows synchronously as part of the run of the calling workflow. The calling workflow waits for all of the called workflows to complete before it continues. The calling workflow can use the results of the called workflows as input parameters when it runs its subsequent schema elements.

Workflow Elements that Call Workflows

There are four ways to call other workflows from within a workflow. Each way of calling a workflow or workflows is represented by a different workflow schema element.

Synchronous Workflows

Asynchronous Workflows

A workflow can start another workflow synchronously. The called workflow runs as an integral part of the calling workflow's run, and runs in the same memory space as the calling workflow. The calling workflow starts another workflow, then waits until the end of the called workflow's run before it starts running the next element in its schema. Usually, you call a workflow synchronously because the calling workflow requires the output of the called workflow as an input parameter for a subsequent schema element. For example, a workflow can call the Start virtual machine and wait workflow to start a virtual machine, and then obtain the IP address of this virtual machine to pass to another element or to a user by email.

A workflow can start a workflow asynchronously. The calling workflow starts another workflow, but the calling workflow immediately continues running the next element in its schema, without waiting for the result of the called workflow. The called workflows run with input parameters that the calling workflow defines, but the lifecycle of the called workflow is independent from the lifecycle of the calling workflow. Asynchronous workflows allow you to create chains of workflows that pass input parameters from one workflow to the next. For example, a workflow can create various objects during its run. The workflow can then start asynchronous workflows that use these objects as input parameters in their own runs. When the original workflow has started all the required workflows and run its remaining elements, it ends. However, the asynchronous workflows it started continue their runs independently of the workflow that started them.

To make the calling workflow wait for the result of the called workflow, either use a nested workflow or create a scriptable task that retrieves the state of the workflow token of the called workflow and then retrieves the result of the workflow when it completes.

Scheduled Workflows

A workflow can call a workflow but defer starting that workflow until a later time and date. The calling workflow then continues its run until it ends. Calling a scheduled workflow creates a task to start that workflow at the given time and date. When the calling workflow has run, you can view the scheduled workflow in the Scheduler and My Orchestrator views in the Orchestrator client.

VMware, Inc. 53

vCenter Orchestrator Developer's Guide

Scheduled workflows only run once. You can schedule a workflow to run recurrently by calling the Workflow.scheduleRecurrently method in a scriptable task element in a synchronous workflow.

Nested Workflows

A workflow can start several workflows simultaneously by nesting several workflows in a single schema element. All the workflows listed in the nested workflow element start simultaneously when the calling workflow arrives at the nested workflows element in its schema. Significantly, each nested workflow starts in a different memory space from the memory space of the calling workflow. The calling workflow waits until all the nested workflows have completed their runs before it starts running the next element in its schema. The calling workflow can thus use the results of the nested workflows as input parameters when it runs its remaining elements.

Propagate Workflow Changes to other Workflows

If you call a workflow from within another workflow, Orchestrator imports that workflow's input parameters into the calling workflow at the moment you add the workflow element to the schema, rather than referencing it.

As a consequence, if you change the called workflow after you have added it to another workflow, the calling workflow calls on the new version of the called workflow, but does not import any new input parameters. To prevent changes to workflows affecting the behavior of other workflows that call them, Orchestrator does not propagate the new input parameters automatically to the calling workflows.

To propagate parameters from one workflow to other workflows that call it, you must find the workflows that call the workflow, and synchronize the workflows manually.

Prerequisites

You need a workflow that another workflow or workflows call.

Procedure

1 Modify and save a workflow that other workflows call.

2 Close the workflow editor.

3 Navigate to the workflow you changed in the hierarchical list in the Workflows view in the Orchestrator

client.

4 Right-click the workflow, and select References > Find Elements that Use this Element.

A list of workflows that call this workflow appears.

5 Double-click a workflow in the list to highlight it in the Workflows view in the Orchestrator client.

6 Right-click the workflow, and select Edit.

The workflow editor opens.

7 Click the Schema tab in the workflow editor.

8 Right-click the workflow element for the changed workflow from the workflow schema and select

Synchronize > Synchronize Parameters.

9 Click Continue in the confirmation dialog box.

10 Save and close the workflow editor.

11 Repeat Step 5 to Step 10 for all the workflows that use the modified workflow.

You propagated a changed workflow to other workflows that call it.

54 VMware, Inc.

Chapter 2 Developing Workflows

Call a Workflow Synchronously

You call workflows synchronously from another workflow by using the Workflow element.

Prerequisites

Open a workflow for editing in the workflow editor

Add some elements to the workflow schema

Procedure

1 Drag a Workflow element from the Action & Workflow menu to the appropriate position in the workflow

schema.

The Choose workflow selection dialog box appears.

2 Search for ands select the workflow you want and click OK.

If the search returns a partial result, narrow your search criterion or increase the number of search results from the Tools > User preferences menu in the client.

3 Link the Workflow element to the elements that precede and follow it in the workflow schema.

4 Click the Workflow element to show its properties tabs in the bottom half of the Schema tab.

5 Bind the required input parameters to the workflow in the IN tab of the workflow schema element.

6 Bind the required output parameters to the workflow in the OUT tab of the workflow schema element's.

7 Define the exception behavior of the workflow in the Exceptions tab.

8 Click Save at the bottom of the workflow editor.

You called a workflow synchronously from another workflow. When the workflow reaches the synchronous workflow during its run, the synchronous workflow starts, and the initial workflow waits for it to complete before continuing its run.

What to do next

You can call a workflow asynchronously from a workflow.

Call a Workflow Asynchronously

Calling a workflow asynchronously runs the called workflow independently of the calling workflow. The calling workflow continues its run without waiting for the called workflow to complete.

You call workflows asynchronously from another workflow by using the Asynchronous Workflow element.

Prerequisites

Open a workflow for editing in the workflow editor

Add some elements to the workflow schema

VMware, Inc. 55

vCenter Orchestrator Developer's Guide

Procedure

1 Drag an Asynchronous Workflow element from the Action & Workflow menu to the appropriate position

in the workflow schema.

The Choose workflow selection dialog box appears.

2 Search for and select the desired workflow from the list and click OK.

3 Link the Asynchronous Workflow element to the elements that precede and follow it in the workflow

schema.

4 Click the Asynchronous Workflow element to show its properties tabs in the bottom half of the

Schema tab.

5 Bind the required input parameters to the workflow in IN tab of the asynchronous workflow element.

6 Bind the required output parameter in the OUT tab of the asynchronous workflow element.

You can bind the output parameter either to the called workflow, or to that workflow's result.

Bind to the called workflow to return that workflow as an output parameter

Bind to the workflow token of the called workflow to return the result of running the called workflow.

7 Define the exception behavior of the asynchronous workflow element in the Exceptions tab.

8 Click Save at the bottom of the workflow editor.

You called a workflow asynchronously from another workflow. When the workflow reaches the asynchronous workflow during its run, the asynchronous workflow starts, and the initial workflow continues its run without waiting for the asynchronous workflow to finish.

What to do next

You can schedule a workflow to start at a later time and date.

Schedule a Workflow

You can call a workflow from a workflow and schedule it to start at a later time and date.

You schedule workflows in another workflow by using the Schedule Workflow element.

Prerequisites

Create a workflow, open it for editing in the workflow editor, and add some elements to the workflow schema.

Procedure

1 Drag a Schedule Workflow element from the Action & Workflow menu to the appropriate position in

the workflow schema.

2 Search for the workflow to call by typing part of its name in the text box.

3 Select the workflow from the list and click OK.

4 Link the Schedule Workflow element to the elements that precede and follow it in the workflow schema.

5 Click the Schedule Workflow element to show its properties tabs in the bottom half of the Schema tab.

6 Click the IN property tab.

A parameter named workflowScheduleDate appears in the list of properties to define, together with the input parameters of the calling workflow.

7 Click Not set for the workflowScheduleDate parameter to set the parameter.

8 Click Create parameter/attribute in workflow to create the parameter and set the parameter value.

56 VMware, Inc.

Chapter 2 Developing Workflows

9 Click Not set for Value to set the parameter value.

10 Use the calendar that appears to set the date and time to start the scheduled workflow and click OK.

11 Bind the remaining input parameters to the scheduled workflow in the IN tab of the scheduled workflow

element.

12 Bind the required output parameters to the Task object in the OUT tab of the scheduled workflow element.

13 Define the exception behavior of the scheduled workflow element in the Exceptions tab.

14 Click Save at the bottom of the workflow editor.

You scheduled a workflow to start at a given time and date from another workflow.

What to do next

You can call multiple workflows simultaneously from a workflow.

Call Several Workflows Simultaneously

You call several workflows simultaneously from another workflow by using the Nested Workflows element. You can use nested workflows to run workflows with user credentials that are different from the credentials of the user of the calling workflow.

Prerequisites

Open a workflow for editing in the workflow editor.

Add some elements to the workflow schema.

Procedure

1 Drag a Nested Workflows element from the Action & Workflow menu to the appropriate position in the

workflow schema.

The Choose workflow selection dialog box appears.

2 Search for and select a workflow to start and click OK.

3 Link the Nested Workflows element to the elements that precede and follow it in the workflow schema.

4 Click the Nested Workflows element to show its properties tabs in the bottom half of the Schema tab.

5 Click the Workflows tab.

The workflow you selected in Step 2 appears in the tab.

6 Set the IN and OUT bindings for this workflow in the IN and OUT tabs in the right panel of the

Workflows schema element properties tab.

7 Click the Connection Info tab in the right panel of the Workflows schema element properties tab.

The Connection Info tab allows you to access workflows stored in a different server to the local one, using the appropriate credentials.

8 To access workflows on a remote server, select Remote and click Not set to provide a host name or IP

address for the remote server.

VMware, Inc. 57

vCenter Orchestrator Developer's Guide

9 Define the credentials with which to access the remote server.

Select Inherit to use the same credentials as the user who runs the calling workflow.

Select Dynamic and click Not set to select a set of dynamic credentials that a parameter of the

credentials type defines elsewhere in the workflow.

Select Static and click Not set to enter the credentials directly.

10 Click the Add Workflow button in the Workflows tab to select more workflows to add to the nested

workflow element.

11 Repeat Step 2 to Step 9 to define the settings for each of the workflows you add.

12 Click the nested workflow element in the workflow schema.

The number of workflows nested in the element appears as a numeral on the nested workflows element.

You called several workflows simultaneously from a workflow.

What to do next

You can define long-running workflows.

Running a Workflow on a Selection of Objects

You can use one of the following methods to run a workflow on a selection of objects.

Run the Library > vCenter > Batch > Run a workflow on a selection of objects workflow.

Create a workflow that calls the Orchestrator > Start workflows in a series or Start workflows in parallel workflows.

Create a workflow that obtains an array of objects and runs a workflow on each object in the array in a loop of workflow elements.

Run a workflow from JavaScript by calling the Workflow.execute() method in a For loop in a scripted element in a workflow.

Which method you choose to run a workflow on a selection of objects depends on the workflow to run and can affect the performance of the workflow. For example, running the Run a workflow on a selection of objects workflow is the simplest way to run a workflow on multiple objects and requires no workflow development, but it can only run workflows that take a single input parameter.

Creating a workflow that calls the Start workflows in a series or Start workflows in parallel workflows allows you to run on multiple objects workflows that take more than one input parameter. The calling workflow must create a properties array to pass the input parameters to the Start workflows in a series or Start workflows in parallel workflow. These workflows are only for use in other workflows. Do not run them directly.

Running a workflow in a For loop in a scripted element is faster than running a workflow in a loop of workflow elements, but it is less flexible and limits the potential for reuse. Most importantly, running a workflow in a scripted loop loses the checkpointing that Orchestrator performs when it starts each element in a workflow run. As a consequence, if the Orchestrator server stops while the scripted loop is running, when the server restarts, the workflow will resume at the beginning of the scripted element, repeating the whole loop. If the Orchestrator server stops while running a workflow with a loop of workflow elements, the workflow will resume at the specific element in the loop that was running when the server stopped.

For more information about the Batch workflows, see the vCenter Orchestrator Administration Guide.

How to create a workflow that runs a workflow on an array of objects in a loop of workflow elements is demonstrated in “Develop a Complex Workflow,” on page 92.

58 VMware, Inc.

Chapter 2 Developing Workflows

How to run a workflow in a scripted For loop is demonstrated in “Workflow Scripting Examples,” on page 129.

Implement the Start Workflows in a Series and Start Workflows in Parallel Workflows

You can use the Start workflows in a series and Start workflows in parallel workflows to run a workflow on a selection of objects.

You cannot run the Start workflows in a series and Start workflows in parallel workflows directly. You must include them in another workflow that you create. To use the Start workflows in a series and Start workflows in parallel workflows to run a workflow on a selection of objects, you must obtain the objects on which to run the workflow. You pass these objects and any other input parameters that the workflow requires to the workflow as an array of properties. The Start workflows in a series and Start workflows in parallel workflows emit the results of running the workflow on the selection of objects as an array of WorkflowToken objects.

You implement the Start workflows in a series and Start workflows in parallel workflows in the same way. The Start workflows in a series workflow runs the workflow on each object sequentially. The Start workflows in parallel workflow runs the workflow on all the objects simultaneously.

Prerequisites

Open a workflow for editing in the workflow editor.

Procedure

1 In the workflow schema, add a scriptable task element or an action to obtain a list of objects on which to

run the workflow.

For example, to run a workflow on all the virtual machines in a virtual machine folder, you can add the

getAllVirtualMachinesByFolder action to the workflow.

2 Link the scripted element or action and bind the input and output of the scripted element or action to

workflow inputs or attributes.

For example, you can bind the vmFolder input of the getAllVirtualMachinesByFolder action to a workflow input parameter and the actionResult output to a workflow attribute in the calling workflow.

3 Add a scriptable task element to cast the list of objects into a properties array.

For example, if the objects on which to run the workflow are an array of virtual machines, allVMs, returned by the actionResult output of the getAllVirtualMachinesByFolder action, you can write the following script to cast the objects into a properties array.

propsArray = new Array();

for each (var vm in allVMs) { var prop = new Properties(); prop.put("vm", vm); propsArray.push(prop); }

4 Link the scriptable task element and bind its inputs and outputs to workflow attributes.

In the example scriptable task element in Step 3, you bind the input to the allVMs array of virtual machines and you create the propsArray output attribute as an array of Properties objects.

5 Add a workflow element to the workflow schema.

6 Select either of the Start workflows in a series or Start workflows in parallel workflows and link the

workflow element to the other elements.

VMware, Inc. 59

vCenter Orchestrator Developer's Guide

7 Bind the wf input of the Start workflows in a series or Start workflows in parallel workflow to the workflow

to run on the objects.

For example, to remove any snapshots of all the virtual machines returned by the

getAllVirtualMachinesByFolder action, select the Remove all snapshots workflow.

8 Bind the parameters input of the Start workflows in a series or Start workflows in parallel workflow to

the array of Properties objects that contains the objects on which to run the workflow.

For example, bind the parameters input to the propsArray attribute defined in Step 4.

9 (Optional) Bind the workflowTokens output of the Start workflows in a series or Start workflows in parallel

workflow to an attribute in the workflow.

10 Add and link an end element to the workflow, or continue adding more elements that use the results of

running the Start workflows in a series or Start workflows in parallel workflow.

You created a workflow that uses either of the Start workflows in a series or Start workflows in parallel workflows to run a workflow on a selection of objects.

Developing Long-Running Workflows

Every running workflow consumes a system thread. When a workflow reaches a long-running workflow element, the long-running workflow element sets the workflow into a passive state. The long-running workflow element then passes the workflow information to a single thread that polls the system for all longrunning workflow elements running in the server. Rather than each long-running workflow element constantly attempting to retrieve information from the system, long-running workflow elements remain passive for a set duration, while the long-running workflow thread polls the system on its behalf.

You set the duration of the wait in one of the following ways:

Set a timer, encapsulated in a Date object, that suspends the workflow until a certain time and date. You implement long-running workflow elements that are based on a timer by including a Waiting Timer element in the schema.

Define a trigger event, encapsulated in a Trigger object, that restarts the workflow after the trigger event occurs. You implement long-running workflow elements that are based on a trigger by adding a Waiting Event element or a User Interaction element in the schema.

Set a Relative Time and Date for Timer-Based Workflows

You can set the timer.date attribute of a Waiting Timer element to a relative time and date by binding it to a

Date object. You define the Date object in a scripted function.

When the time on the given date arrives, the long-running workflow that is based on a timer reactivates and continues its run. For example, you can set the workflow to reactivate at midday on February 12. Alternatively, you can create a workflow element that calculates and generates a relative Date object according to a function that you define. For example, you can create a relative Date object that adds 24 hours to the current time.

Prerequisites

You created a workflow, opened it for editing in the workflow editor, and added some elements to the workflow schema.

60 VMware, Inc.

Chapter 2 Developing Workflows

Procedure

1 Drag a Scriptable Task element from the Generic menu to the schema of a workflow, above the element

that requires the relative Date object for its timeout.date attribute.

2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema.

3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab.

4 Provide a name and description for the scripted workflow element in the Info properties tab.

5 Right-click in the OUT properties tab, and select Bind to workflow parameter/attribute.

6 Click Create parameter/attribute in workflow to create a workflow attribute.

a Name the attribute timerDate.

b Select Date from the list of attribute types.

c Select Create workflow ATTRIBUTE with the same name.

d Leave the attribute value set to Not set, because a scripted function will provide this value.

e Click OK.

7 Click the Scripting tab for the scripted workflow element.

8 Define a function to calculate and generate a Date object named timerDate in the scripting pad in the

Scripting tab.

For example, you can create a Date object by implementing the following JavaScript function, in which the timeout period is a relative delay in milliseconds.

timerDate = new Date(); System.log( "Current date : '" + timerDate + "'" ); timerDate.setTime( timerDate.getTime() + (86400 * 1000) ); System.log( "Timer will expire at '" + timerDate + "'" );

9 Click Save.

You created a function that calculates and generates a Date object. A Waiting Timer element can receive this

Date object as an input parameter, to suspend a long-running workflow until the date encapsulated in this

object. When the workflow arrives at the Waiting Timer element, it suspends its run and waits for 24 hours before continuing.

What to do next

You must add a Waiting Timer element to a workflow to implement a long-running workflow that is based on a timer.

Create a Timer-Based Long-Running Workflow

If you know a workflow will have to wait for a response from an outside source for a predictable time, you can implement it as a timer-based long-running workflow. A timer-based long-running workflow waits until a given time and date before resuming.

You implement a workflow as a timer-based long-running workflow by using the Waiting Timer element.

Prerequisites

You must have created a workflow, opened it for editing in the workflow editor, and added some elements to the workflow schema.

VMware, Inc. 61

vCenter Orchestrator Developer's Guide

Procedure

1 Drag a Waiting Timer element from the Generic menu to the position in the workflow schema at which

to suspend the workflow's run.

2 Link the Waiting Timer element to the elements that precede and follow it in the workflow schema.

If you implement a scriptable task to calculate the time and date, this element must precede the Waiting Timer element.

3 Click the Waiting Timer element to show its properties tabs in the bottom half of the Schema tab.

4 Provide a description of the reason for implementing the timer in the Info properties tab.

5 Click the Attributes properties tab.

The timer.date parameter appears in the list of attributes.

6 Click the timer.date parameter's Not set button to bind the parameter to an appropriate Date object.

The Waiting Timer selection dialog box opens, presenting a list of possible bindings.

Select a predefined Date object from the proposed list, for example one defined by a Scriptable Task element elsewhere in the workflow.

Alternatively, create a Date object that sets a specific date and time for the workflow to await.

7 (Optional) Create a Date object that sets a specific date and time that the workflow awaits.

a Click Create parameter/attribute in workflow in the Waiting Timer selection dialog box.

The Parameter information dialog box appears.

b Give the parameter an appropriate name.

c Leave the type set to Date.

d Click Create workflow ATTRIBUTE with the same name.

e Click the Value property's Not set button to set the parameter value.

A calendar appears.

f Use the calendar to set a date and time at which to restart workflow.

g Click OK.

8 Click Save at the bottom of the workflow editor.

You defined a timer that suspends a timer-based long-running workflow until a set time and date.

What to do next

You can create a long-running workflow that waits for a trigger event before continuing.

Create a Trigger Object

Trigger objects monitor event triggers that plug-ins define. For example, the vCenter Server plug-in defines these events as Task objects. When the task ends, the trigger sends a message to a waiting trigger-based longrunning workflow element, to restart the workflow.

The time-consuming event for which a trigger-based long-running workflow waits must return a VC:Task object. For example, the startVM action to start a virtual machine returns a VC:Task object, so that subsequent elements in a workflow can monitor its progress. A trigger-based long-running workflow's trigger event requires this VC:Task object as an input parameter.

62 VMware, Inc.

Chapter 2 Developing Workflows

You create a Trigger object in a JavaScript function in a Scriptable Task element. This Scriptable Task element can be part of the trigger-based long-running workflow that waits for the trigger event. Alternatively, it can be part of a different workflow that provides input parameters to the trigger-based long-running workflow. The trigger function must implement the createEndOfTaskTrigger() method from the Orchestrator API.

IMPORTANT You must define a timeout period for all triggers, otherwise the workflow can wait indefinitely.

Prerequisites

You must have created a workflow, opened it for editing in the workflow editor, and added some elements to the workflow schema. The workflow must declare a VC:Task object as an attribute or input parameter, such as a VC:Task object from a workflow or workflow element that starts or clones a virtual machine.

Procedure

1 Drag a Scriptable Task element from the Generic menu into the schema of a workflow.

2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema.

One of the elements that precedes the Scriptable Task must generate a VC:Task object as its output parameter.

3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab.

4 Provide a name and description for the trigger in Info properties tab.

5 Click the IN properties tab.

6 Right-click in the IN tab and select Bind to workflow parameter/attribute.

The input parameter selection dialog box opens.

7 Select or create an input parameter of the type VC:Task.

This VC:Task object represents the time-consuming event that another workflow or element launches.

8 (Optional) Select or create an input parameter of the Number type to define a timeout period in seconds.

9 Click the OUT properties tab.

10 Right-click in the OUT tab and select Bind to workflow parameter/attribute.

The output parameter selection dialog box opens.

11 Create an output parameter with the following properties.

a Create the Name property with the value trigger.

b Create the Type property with the value Trigger.

c Click Create ATTRIBUTE with same name to create the attribute.

d Leave the value as Not set.

12 Define any exception behavior in the Exceptions properties tab.

13 Define a function to generate a Trigger object in the Scripting tab.

For example, you could create a Trigger object by implementing the following JavaScript function.

trigger = task.createEndOfTaskTrigger(timeout);

The createEndOfTaskTrigger() method returns a Trigger object that monitors a VC:Task object named

task.

14 Click Save at the bottom of the workflow editor.

You defined a workflow element that creates a trigger event for a trigger-based long-running workflow. The trigger element generates a Trigger object as its output parameter, to which a Waiting Event element can bind.

VMware, Inc. 63

vCenter Orchestrator Developer's Guide

What to do next

You must bind this trigger event to a Waiting Event element in a trigger-based long-running workflow.

Create a Trigger-Based Long-Running Workflow

If you know a workflow will have to wait for a response from an outside source during its run, but do not know how long that wait will last, you can implement it as a trigger-based long-running workflow. A triggerbased long-running workflow waits for a defined trigger event to occur before resuming.

You implement a workflow as a trigger-based long-running workflow by using the Waiting Event element. When the trigger-based long-running workflow arrives at the Waiting Event element, it will suspend its run and wait in a passive state until it receives a message from the trigger. During the waiting period, the passive workflow does not consume a thread, but rather the long-running workflow element passes the workflow information to the single thread that monitors all long-running workflows in the server.

Prerequisites

You must have created a workflow, opened it for editing in the workflow editor, added some elements to the workflow schema, and defined a trigger event, encapsulated in a Trigger object.

Procedure

1 Drag a Waiting Event element from the Generic menu to the position in the workflow schema at which

you want to suspend the workflow's run.

2 Link the Waiting Event element to the elements that precede and follow it in the workflow schema.

The scriptable task that declares the trigger must immediately precede the Waiting Event element.

3 Click the Waiting Event element to show its properties tabs in the bottom half of the Schema tab.

4 Provide a description of the reason for the wait in the Info properties tab.

5 Click the Attributes properties tab.

The trigger.ref parameter appears in the list of attributes.

6 Click the trigger.ref parameter's Not set link to bind the parameter to an appropriate Trigger object.

The Waiting Event selection dialog box opens, presenting a list of possible parameters to which to bind.

7 Select a predefined Trigger object from the proposed list.

This Trigger object represents a trigger event that another workflow or workflow element defines.

8 Define any exception behavior in the Exceptions properties tab.

9 Click Save at the bottom of the workflow editor.

You defined a workflow element that suspends a trigger-based long-running workflow, that waits for a specific trigger event before restarting.

What to do next

You can run a workflow.

64 VMware, Inc.

Configuration Elements

A configuration element is a list of attributes you can use to configure constants across a whole Orchestrator server deployment.

All the workflows, actions, policies, and Web views running in a particular Orchestrator server can use the attributes you set in a configuration element. Setting attributes in configuration elements allows you to make the same attribute values available to all the workflows, actions, policies, and Web views running in the Orchestrator server.

If you create a package containing a workflow, action, policy, or Web view that uses an attribute from a configuration element, Orchestrator automatically includes the configuration element in the package, but not its value. If you import a package containing a configuration element into another Orchestrator server, the configuration element attribute values are not set. You must set the attributes with values appropriate to the server in which you have imported the package. For example, if you create a workflow that requires attribute values that depend on the Orchestrator server on which it runs, setting those attributes in a configuration element allows you to export that workflow so that another Orchestrator server can use it. If you set the serverspecific attributes directly in the workflow, the workflow might not work if you import it into another server, because it might not find the attribute values it requires. Because the attribute values in an imported configuration element are not set, you have to set them with values appropriate to the new server. Configuration elements therefore allow you to exchange workflows, actions, policies and Web views between servers more easily.

Chapter 2 Developing Workflows

Create a Configuration Element

Configuration elements allow you to set common attributes across an Orchestrator server. All elements that are running in the server can call on the attributes you set in a configuration element. Creating configuration elements allows you to define common attributes once in the server, rather than individually in each element.

Procedure

1 Click the Configurations view in the Orchestrator client.

2 Right-click a folder in the hierarchical list of folders and select New category to create a new category.

3 Provide a name for the folder and click OK.

4 Right-click the folder you created and select New element.

5 Provide a name for the configuration element and click OK.

6 Right-click the element and select Edit.

The configuration element editor opens.

7 Increment the version number by clicking the version digits in the General tab and providing a version

comment.

8 Provide a description of the configuration element in the Description text box in the General tab.

9 Click the Attributes tab.

10 Right-click in the tab and select Add attribute to create a new attribute.

11 Click the attribute values under Name, Type, Value, and Description to set the attribute name, type,

value, and description.

12 Click the Permissions tab.

13 Click Add access rights to grant permission to access this configuration element to a group of users.

14 Search for a user group in the Filter text box and select the relevant user group from the proposed list.

VMware, Inc. 65

vCenter Orchestrator Developer's Guide

15 Check the appropriate check boxes to set the access rights for the selected user group.

You can set the following permissions on the configuration element.

Permission Description

View

Inspect

Execute

Edit

Admin

16 Click Save and Close to exit the configuration element editor.

You defined a configuration element that sets common attributes across an Orchestrator server.

What to do next

You can use the configuration element to provide attributes to workflows or actions.

Workflow User Permissions

Users can view the configuration element, but cannot view the schemas or scripting.

Users can view the configuration element, including the schemas and scripting.

Users can run the elements in the configuration element.

Users can edit the elements in the configuration element.

Users can set permissions on the elements in the configuration element.

Orchestrator defines levels of permissions that you can apply to users or groups to allow or deny them access to workflows.

View

The user can view the elements in the workflow, but cannot view the schema or scripting.

Inspect

The user can view the elements in the workflow, including the schema and scripting.

Execute

Edit

Admin

The user can run the workflow.

The user can edit the workflow.

The user can set permissions on the workflow.

Permissions are not cumulative. For example, to grant a user full permissions, you must set all the permissions, not just Admin. All the permissions require the View permission.

If you do not set any permissions on a workflow, the workflow inherits the permissions from the category that contains it. If you do set permissions on a workflow, those permissions override the permissions of the category that contains it, even if the permissions of the category are more restrictive.

Set User Permissions on a Workflow

You set levels of permission on a workflow to limit the access that users or user groups can have to that workflow.

You select the users and user groups for which to set permissions from the users and user groups in the Orchestrator LDAP server.

Prerequisites

Create a workflow, open it for editing in the workflow editor, and add to it the necessary elements.

66 VMware, Inc.

Procedure

1 Click the Permissions tab.

2 Click the Add access rights link to define permissions for a new user or user group.

3 Search for a user or user group.

The search results show all of the users and user groups from the Orchestrator LDAP server that match the search.

4 Select a user or user group and click OK.

5 Right-click the user and select Add access rights.

6 Check the appropriate check boxes to set the level of permissions for this user and click OK.

To allow a user to view the workflow, inspect the schema and scripting, run and edit the workflow, and change the permissions, you must check all check boxes.

7 Click Save and Close to exit the editor.

You set the appropriate user permissions on a workflow.

Validating Workflows

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.

Chapter 2 Developing Workflows

When you validate a workflow, the validation tool creates a list of any errors or warnings. Clicking an error in the list highlights the workflow element that contains the error.

If you run the validation tool in the workflow editor, the tool provides suggested quick fixes for the errors it detects. Some quick fixes require you to provide additional information or input parameters. Other quick fixes resolve the error for you.

Workflow validation checks the data bindings and connections between elements. Workflow validation does not check the data processing that each element in the workflow performs. Consequently, a valid workflow can run incorrectly and produce erroneous results if a function in a schema element is incorrect.

By default, Orchestrator always performs workflow validation when you run a workflow. You can change the default validation behavior in the Orchestrator client. See “Testing Workflows During Development,” on page 17. For example, sometimes during workflow development you might want to run a workflow that you know to be invalid, for testing purposes.

Validate a Workflow and Fix Validation Errors

You can validate workflows in either the Orchestrator client or in the workflow editor. However, you can only fix validation errors if you have opened the workflow for editing in the workflow editor.

Prerequisites

You must have a complete workflow to validate, with schema elements linked and bindings defined.

Procedure

1 Click the Workflows view.

2 Navigate to a workflow in the Workflows hierarchical list.

3 (Optional) Right-click the workflow and select Validate workflow.

If the workflow is valid, a confirmation message appears. If the workflow is invalid, a list of errors appears.

4 (Optional) Close the Workflow Validation dialog box.

VMware, Inc. 67

vCenter Orchestrator Developer's Guide

5 Right-click the workflow and select Edit to open the workflow editor.

6 Click the Schema tab.

7 Click the Validate button in the Schema tab toolbar.

If the workflow is valid, a confirmation message appears. If the workflow is invalid, a list of errors appears.

8 If the workflow is invalid, click on an error message.

The validation tool highlights the schema element in which the error occurs by adding a red icon to it. Where possible, the validation tool proposes a Quick fix action.

If you agree with the proposed Quick fix action, click it to perform that action.

If you disagree with the proposed Quick fix action, close the Workflow Validation dialog box and fix the schema element manually.

Always check that the Quick Fix that Orchestrator proposes is appropriate. For example, the proposed action might be to delete an unused attribute, when in fact that attribute has not been correctly bound.

9 Repeat the preceding steps until you have eliminated all validation errors.

You validated a workflow, and possibly fixed any validation errors.

What to do next

You can run the workflow.

Running Workflows

A workflow runs according to a logical flow of events.

When you run a workflow, each schema element in the workflow runs according to the following sequence.

1 The workflow binds the workflow token attributes and input parameters to the schema element's input

parameters.

2 The schema element runs.

3 The schema element's output parameters are copied to the workflow token attributes and workflow output

parameters.

4 The workflow token attributes and output parameters are stored in the database.

5 The next schema element starts running.

This sequence repeats for each schema element until the end of the workflow.

Workflow Token Check Points

When a workflow runs, each schema element is a check point. After each schema element runs, Orchestrator stores workflow token attributes in the database, and the following schema element starts running. If the workflow stops unexpectedly, the next time the Orchestrator server restarts, the currently active schema element runs again, and the workflow continues from the start of the schema element that was running when the interruption happened. However, Orchestrator does not implement transaction management or a roll-back function.

End of Workflow

The workflow ends if the current active schema element is an end element or if an element has no outgoing connection. Validating a workflow with no end element returns a warning, but the workflow will run successfully. After the workflow reaches an end element, other workflows or applications can use the workflow's output parameters.

68 VMware, Inc.

Chapter 2 Developing Workflows

Run a Workflow

You can perform automated operations in vCenter Server by running workflows from the standard library or workflows that you create.

For example, you can create a virtual machine by running the Create simple virtual machine workflow.

Prerequisites

You must have configured the vCenter plug-in. For details, see vCenter Orchestrator Installation and Configuration Guide.

Procedure

1 Click the Workflows view in the Orchestrator client.

2 In the workflows hierarchical list, open Library > vCenter > Virtual machine management > Basic to

navigate to the Create simple virtual machine workflow.

3 Right-click the Create simple virtual machine workflow and select Execute workflow.

4 Provide the following information into the Execute workflow input parameters dialog box to create a

virtual machine in a vCenter Server connected to Orchestrator.

Option Action

Virtual machine name

Virtual machine folder

Size of the new disk in GB

Memory size in MB

Number of virtual CPUs

Virtual machine guest OS

Host on which to create the virtual machine

Resource pool

The network to connect to

Datastore in which to store the virtual machine files

5 Click Submit to run the workflow.

Name the virtual machine orchestrator-test.

a Click Not set for the Virtual machine folder value.

b Select a virtual machine folder from the inventory.

The Select button is inactive until you select an object of the correct type, in this case, VC:VmFolder.

Type an appropriate numeric value.

Select an appropriate number of CPUs from the Number of virtual CPUs drop-down menu.

Click the Not Set link and select a guest operating system from the list.

Click Not set for the Host on which to create the virtual machine value and navigate through the vCenter Server infrastructure hierarchy to a host machine.

Click Not set for the Resource pool value and navigate through the vCenter Server infrastructure hierarchy to a resource pool.

Click Not set for the The network to connect to value and select a network.

Press Enter in the Filter text box to see all the available networks.

Click Not set for the Datastore in which to store the virtual machine value and navigate through the vCenter Server infrastructure hierarchy to a datastore.

A workflow token appears under the Create simple virtual machine workflow, showing the workflow running icon.

6 Click the workflow token to view the status of the workflow as it runs.

7 Click the Events tab in the workflow token view to follow the progress of the workflow token until it

completes.

8 Click the Inventory view in the Orchestrator client.

VMware, Inc. 69

vCenter Orchestrator Developer's Guide

9 Navigate through the vCenter Server infrastructure hierarchy to the resource pool you defined.

If the virtual machine does not appear in the list, click the refresh button to reload the inventory.

The orchestrator-test virtual machine is present in the resource pool.

10 (Optional) Right-click the orchestrator-test virtual machine in the Inventory view to see a contextual

list of the workflows that you can run on the orchestrator-test virtual machine.

The Create simple virtual machine workflow ran successfully.

What to do next

You can log in vSphere Client and manage the new virtual machine.

Develop a Simple Example Workflow

Developing a simple example workflow demonstrates the most common steps in the workflow development process.

The example workflow, named Start VM and Send Email, starts an existing virtual machine in the vCenter Server and sends an email to the administrator to confirm that the virtual machine has started.

The example workflow performs the following tasks:

1 Prompts the user for a virtual machine to start.

2 Prompts the user for the email address of a person to inform that the virtual machine has started, or that

an error occurred.

3 Checks whether or not the requested virtual machine is already powered on.

4 Sends the request to the vCenter Server to start the requested virtual machine.

5 Waits for vCenter Server to start up the requested virtual machine, and returns an error if the virtual

machine fails to start or if starting the virtual machine takes too long.

6 Waits for vCenter Server to start up VMware Tools on the virtual machine. Returns an error if the virtual

machine fails to start or if starting VMware Tools takes too long.

7 Verifies that the virtual machine is running.

8 Sends a notification email to the relevant person, to inform them that the machine has started or that an

error occurred.

The ZIP file of Orchestrator examples that you can download from the Orchestrator documentation homepage contains a completed version of the Start VM and Send Email workflow. For details about where to download the Orchestrator examples bundle, see “Example Applications,” on page 9.

The process for developing a simple workflow consists of the following tasks.

Prerequisites

Before you attempt to develop this simple workflow example, read all the other sections of Chapter 2,

“Developing Workflows,” on page 15.

Procedure

1 Create the Simple Workflow Example on page 72

The first step in the workflow development process is to create the workflow.

2 Define the Simple Workflow Example Parameters on page 73

You define workflow attributes and parameters in the workflow editor.

70 VMware, Inc.

Chapter 2 Developing Workflows

3 Create the Simple Workflow Example Schema on page 73

You create a workflow schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.

4 Link the Simple Workflow Example Elements on page 75

You link a workflow's elements in the Schema tab of the workflow editor. The linking defines the flow of data through the workflow.

5 Create Workflow Zones on page 76

You can emphasize different zones in workflow by adding workflow notes of different colors. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.

6 Define the Simple Workflow Example Decision Bindings on page 77

You bind a workflow's elements together in the Schema tab of the workflow editor. Decision bindings define how decision elements compare the input parameters received to the decision statement, and generate output parameters according to whether the input parameters match the decision statement.

7 Bind the Simple Workflow Example Action Elements on page 78

You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the action elements process input parameters and generate output parameters.

8 Bind the Simple Workflow Example Scripted Task Elements on page 81

You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the scripted task elements process input parameters and generate output parameters. You also bind the scriptable task elements to their JavaScript functions.

9 Define the Simple Example Workflow Exception Bindings on page 88

You define exception bindings in the Schema tab in the workflow editor. Exception bindings define how elements process errors.

10 Set the Simple Workflow Example Attribute Read-Write Properties on page 88

You can define whether parameters and attributes are read-only constants or writeable variables. You can also set limitations on the values that users can provide for input parameters.

11 Set the Simple Workflow Example Parameter Properties on page 89

You set the parameter properties in the Presentation tab in the workflow editor. Setting the parameter properties affects the behavior of the parameter, and places constraints on the possible values for that parameter.

12 Set the Layout of the Simple Workflow Example Input Parameters Dialog Box on page 90

You create the layout, or presentation, of the input parameters dialog box in the Presentation tab of the workflow editor. The input parameters dialog box opens when users run a workflow, and is the means by which users enter the input parameters with which the workflow runs.

13 Validate and Run the Simple Workflow Example on page 91

After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.

VMware, Inc. 71

vCenter Orchestrator Developer's Guide

Create the Simple Workflow Example

The first step in the workflow development process is to create the workflow.

Prerequisites

The following components are installed and configured on the system.

vCenter Server, controlling some virtual machines, at least one of which is powered off

Access to an SMTP server

A valid email address

For information about how to install and configure vCenter, see the ESX and vCenter Server Installation Guide. For information about how to configure Orchestrator to use an SMTP server, see the Orchestrator Installation and Configuration Guide.

To write a workflow, you must have an Orchestrator user account with at least View, Execute, Inspect, Edit, and preferably Admin permissions on the server or on the workflow folder in which you are working.

Procedure

1 Start the Orchestrator client interface.

2 Log in using the Orchestrator username and password.

3 Click Workflows on the left side of the client interface.

4 Right-click the root of the workflows list and select Add category.

5 Name the new folder Workflow Examples and click OK.

6 Right-click the Workflow Examples folder and select New Workflow.

7 Name the new workflow Start VM and Send Email and click OK.

8 Right-click the Start VM and Send Email workflow and select Edit.

The workflow editor opens.

9 In the General tab, click the version number digits to increment the version number.

Because this is the initial creation of the workflow, set the version to 0.0.1.

10 Click the Server restart behavior value in the General tab to set whether the workflow resumes after a

server restart.

11 Type a description of what the workflow does in the Description text box in the General tab.

For example, you can add the following description.

This workflow starts a virtual machine and sends a confirmation email to the Orchestrator administrator.

12 Click Save at the bottom of the General tab.

You created a workflow called Start VM and Send Email, but you did not define its functions.

What to do next

You must define the workflow's attributes and input and output parameters.

72 VMware, Inc.

Chapter 2 Developing Workflows

Define the Simple Workflow Example Parameters

You define workflow attributes and parameters in the workflow editor.

Prerequisites

You must have created the Start VM and Send Email workflow, and opened it for editing in the workflow editor.

Procedure

1 Click the Inputs tab in the workflow editor.

2 Right-click in the Inputs tab and select Add Parameter.

A parameter named arg_in_0 appears in the Inputs tab.

3 Click arg_in_0.

4 Type the name vm in the Choose Attribute Name dialog box and click OK.

5 Click the Type text box and type vc:virtualm in the search text box in the parameter type dialog box.

6 Select VC:VirtualMachine from the proposed list of parameter types and click Accept.

7 Add a description of the parameter in the description text box.

For example, type The virtual machine to power on.

8 Repeat the above process to create a second input parameter, with the following values.

Name: toAddress

Type: String

Description: The email address of the person to inform of the result of this workflow

9 Click Save at the bottom of the Inputs tab.

You defined the workflow's input parameters.

What to do next

You must create the workflow's schema.

Create the Simple Workflow Example Schema

You create a workflow schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.

Prerequisites

You must created the Start VM and Send Email workflow and defined its parameters.

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 decision element to under the start element in the schema.

4 Double-click the decision element and change its name to VM powered on?

5 Click Action & Workflow and drag an action element to under the decision element.

The action selection dialog box appears.

VMware, Inc. 73

vCenter Orchestrator Developer's Guide

6 Type start in the Search text box.

7 Select the startVM action and click Select.

8 Drag the following action elements into the schema, one beneath the other under the startVM action

element.

vim3WaitTaskEnd

Suspends the workflow run and polls an ongoing vCenter Server task at regular intervals, until that task is finished. In the present example, the

startVM action starts a virtual machine and the vim3WaitTaskEnd action

makes the workflow wait while the virtual machine starts up. After the virtual machine starts, the vim3WaitTaskEnd lets the workflow resume.

vim3WaitToolsStarted

Suspends the workflow run and waits until VMware Tools start on the target virtual machine.

9 Click the Generic menu and drag a scriptable task element under the vim3WaitToolsStarted action

element.

10 Double-click the scriptable task element and rename it OK.

11 Drag another scriptable task element to the left of the startVM action element.

Name this scripted element Already started.

12 Drag more scripted elements into the schema, as follows.

Drag a scripted element to the right of startVM and name it startVM failed.

Drag a scripted element to the right of vim3WaitTaskEnd and name it Timeout 1.

Drag a scripted element to the right of vim3WaitToolsStarted and name it Timeout 2.

Drag a scripted element to the right of OK and name it Send Email.

Drag a scripted element to the right of Timeout 2 and name it Send Email Failed.

13 Drag an end element to the right of Send Email.

14 Click Save at the bottom of the workflow editor Schema tab.

Figure 2-3 shows the layout of the Start VM and Send Email workflow schema elements.

Figure 2-3. Start VM and Send Email Example Workflow Schema Elements

What to do next

You must now link the workflow elements together.

74 VMware, Inc.

Chapter 2 Developing Workflows

Link the Simple Workflow Example Elements

You link a workflow's elements in the Schema tab of the workflow editor. The linking defines the flow of data through the workflow.

Prerequisites

You must have created the Start VM and Send Email workflow, defined its parameters, and laid out its schema.

Procedure

1 Click the connector tool button in the toolbar at the top of the Schema tab in the workflow editor.

2 Click the start element, and holding the left mouse button down, move the pointer to the VM Powered

On? decision element.

You have linked the start element to the decision element.

3 Link the remaining elements as described in the following table.

Table 2-7. Simple Workflow Example Links

Click Link to Type of Arrow Description

Left side of VM Powered On? decision element

Right side of VM Powered On? decision element

Middle of startVM action element

Middle of vim3WaitTaskEnd action element

Middle of

vim3WaitToolsStarted

action element

Middle of Already Started scriptable task element

Right side of startVM action element

Right side of vim3WaitTaskEnd action element

Right side of

vim3WaitToolsStarted

action element

Middle of StartVM Failed scriptable task element

Middle of both Timeout scripted elements

Middle of OK scriptable task element

Right side of Send Email scriptable task element

Already Started

scriptable task element

startVM action element Red dotted Input does not match

vim3WaitTaskEnd action

element

vim3WaitToolsStarted

action element

OK scriptable task element Black Normal workflow

vim3WaitToolsStarted

action element

StartVM Failed scriptable task element

Timeout 1 scriptable task element

Timeout 2 scriptable task element

Send Email scriptable task element

Send Email Failed

scriptable task element

Green Input matches decision

statement

decision statement

Black Normal workflow

progression

Black Normal workflow

progression

Black Normal workflow

progression

Thick red dotted Exception handling

Black Normal workflow

progression

Black Normal workflow

progression

Black Normal workflow

progression

Thick red dotted Exception handling

VMware, Inc. 75

vCenter Orchestrator Developer's Guide

Table 2-7. Simple Workflow Example Links (Continued)

Click Link to Type of Arrow Description

Middle of Send Email scriptable task element

Middle of Send Email Failed scriptable task element

End element Black Normal workflow

progression

End element Black Normal workflow

progression

4 Click Save at the bottom of the workflow editor Schema tab.

Figure 2-4 shows what the linked elements of the Start VM and Send Email workflow should look like.

Figure 2-4. Linking the Elements of the Start VM and Send Email Example Workflow

What to do next

You can highlight different zones in the workflow.

Create Workflow Zones

You can emphasize different zones in workflow by adding workflow notes of different colors. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.

Prerequisites

You must have created the Start VM and Send Email workflow, laid out its schema, and linked the schema elements together.

Procedure

1 Drag a workflow note element from the Generic menu into the workflow editor.

2 Position the workflow note over the Already started scriptable task element.

3 Drag the edges of the workflow note to resize it so that it surrounds the Already started scriptable task

element.

4 Double-click the text and add a description. For example,

Path if virtual machine is already powered on.

76 VMware, Inc.

Chapter 2 Developing Workflows

5 Click Color in the Info tab at the bottom of the workflow editor and select the background color.

6 Repeat the preceding steps to highlight other zones in the workflow.

Place a note over the vertical sequence of elements from the VM powered on? decision element to the

OK element. Add the description Start VM path.

Place a note over the startVM failed, both Timeout scriptable task elements and the Send Email

Failed scriptable task element. Add the description Error handling.

Place a note over the Send Email scriptable task element. Add the description Send email.

Figure 2-5 shows what the example workflow zones should look like.

Figure 2-5. Start VM and Send Email Example Workflow Zones

What to do next

Define the bindings between the element parameters.

Define the Simple Workflow Example Decision Bindings

Prerequisites

You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements together.

Procedure

1 Click the VM Powered On? decision element.

2 Click the Decision tab in the schema element properties pane at the bottom of the Schema tab.

3 Click the Not set (NULL) button and select vm as the decision element's input parameter from the list of

proposed parameters.

4 Select the state equals statement from the list of decision statements proposed in the drop-down menu.

A Not set button appears in the value text box, which presents you with a limited choice of possible values.

5 Select poweredOn.

6 Click Save at the bottom of the workflow editor's Schema tab.

You have defined the true or false statement against which the decision element will compare the value of the input parameter it receives.

VMware, Inc. 77

vCenter Orchestrator Developer's Guide

What to do next

You must define the bindings for the other elements in the workflow.

Bind the Simple Workflow Example Action Elements

You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the action elements process input parameters and generate output parameters.

Prerequisites

You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements together.

Procedure

1 Click the startVM action element.

2 Set the following general information in the Info tab.

Interaction

Color

Business status

Description

No external interaction

None

Check the check box and add the text Sending start VM.

Leave the text Start / Resume a VM. Return the start task

3 Click the IN tab in the schema element properties pane at the bottom of the Schema tab.

You will see the two possible input parameters available to the startVM action, vm and host.

Orchestrator automatically binds the vm parameter to vm[in-parameter] because the startVM action can only take a VC:VirtualMachine as an input parameter. Orchestrator detected the vm parameter you defined when you set the workflow input parameters and so bound it to the action automatically.

4 Set host to NULL.

This is an optional parameter, so you can set it to null. However, if you leave it set to Not set, the workflow will not validate.

5 Click the OUT tab in the schema element properties pane.

The default output parameter that all actions generate, actionResult, appears.

6 Click the actionResult parameter's Not set button.

7 Click the Create parameter/attribute in workflow button.

The Parameter Information dialog box opens, where you can define the values for this output parameter. The output parameter type for the startVM action is a VC:Task object.

8 Name the parameter powerOnTask.

9 Provide a description for this parameter.

For example, Contains the result of powering on a VM.

10 Click Create workflow ATTRIBUTE with the same name.

11 Click OK to exit the Parameter Information dialog box.

78 VMware, Inc.

Chapter 2 Developing Workflows

12 Repeat the preceding steps to bind the input and output parameters to the vim3WaitTaskEnd and

vim3WaitToolsStarted action elements.

“Simple Workflow Example Action Element Bindings,” on page 79 lists the bindings for the

vim3WaitTaskEnd and vim3WaitToolsStarted action elements.

13 Click Save at the bottom of the workflow editor's Schema tab.

The action elements' input and output parameters are bound to the appropriate parameter types and values.

What to do next

Bind the scriptable task elements and define their functions.

Simple Workflow Example Action Element Bindings

Bindings define how the simple workflow example's action elements process input and output parameters.

When defining bindings, Orchestrator presents parameters you have already defined in the workflow as candidates for binding. If you have not defined the required parameter in the workflow yet, the only parameter choice is NULL. Click Create parameter/attribute in workflow to create a new parameter.

vim3WaitTaskEnd Action

The vim3WaitTaskEnd action element declares constants to track the progress of a task and a polling rate.

Table 2-8 shows the input and output parameter bindings that the vim3WaitTaskEnd action requires.

Table 2-8. Binding Values of the vim3WaitTaskEnd Action

Bind to Existing or

Parameter Name Binding Type

task

progress

IN Create

Create Parameter? Binding Values

Local Parameter: task

Source parameter:

task[attribute]

Type: VC:Task

Description:

The vCenter server task currently running.

Local Parameter: progress

Source parameter:

progress[attribute]

Type: Boolean

Value: No (false)

Description:

Log progress while waiting for the vCenter Server task to complete.

VMware, Inc. 79

vCenter Orchestrator Developer's Guide

Table 2-8. Binding Values of the vim3WaitTaskEnd Action (Continued)

Parameter Name Binding Type

pollRate

actionResult

Bind to Existing or Create Parameter? Binding Values

IN Create

OUT Create

Local Parameter: pollRate

Source parameter:

pollRate[attribute]

Type: number

Value: 2

Description:

Polling rate in seconds at which vim3WaitTaskEnd checks the advancement of the vCenter server task.

Local Parameter:

actionResult[attribute]

Source parameter:

returnedManagedObject[attri bute]

Type: Any

Description:

The returned managed object from the waitTaskEnd action.

vim3WaitToolsStarted Action

The vim3WaitToolsStarted action element waits until VMware Tools have installed on a virtual machine, and defines a polling rate and a timeout period. Table 2-9 shows the input parameter bindings the

vim3WaitToolsStarted action requires.

The vim3WaitToolsStarted action element has no output, so requires no output binding.

80 VMware, Inc.

Table 2-9. Binding Values of the vim3WaitToolsStarted Action

Bind to Existing or

Parameter Name Binding Type

pollingRate

timeout

IN Automatic binding

IN Bind

IN Create

Create Parameter? Binding Values

Chapter 2 Developing Workflows

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Value: Not editable, variable is not a workflow attribute.

Description:

The virtual machine to start.

Local Parameter: pollRate

Source parameter:

pollRate[attribute]

Type: number

Description:

The polling rate in seconds at which vim3WaitTaskEnd checks the advancement of the vCenter server task.

Local Parameter: timeout

Source parameter:

timeout[attribute]

Type: number

Value: 10

Description:

The timeout limit that vim 3WaitToolsStarted waits before throwing an exception.

Bind the Simple Workflow Example Scripted Task Elements

Prerequisites

You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements.

Procedure

1 Click the Already Started scriptable task element.

2 Set the following general information in the Info tab.

Interaction

Color

Business status

Description

No external interaction

None

Check the check box and add the text VM already powered on.

Leave the text

The VM is already powered on, bypassing startVM and waitTaskEnd, checking if the VM tools are up and running.

VMware, Inc. 81

vCenter Orchestrator Developer's Guide

3 Click the IN tab in the schema element properties pane at the bottom of the Schema tab.

Because this is a custom scriptable task element, no properties are predefined for you.

4 Right-click in the IN tab and select Bind to workflow parameter/attribute.

5 Select vm from the proposed list of parameters.

6 Leave the OUT and Exception tabs blank.

This element does not generate an output parameter or exception.

7 Click the Scripting tab.

8 Add the following JavaScript function.

//Writes the following event in the vCO database Server.log("VM '"+ vm.name +"' already started");

9 Repeat the preceding steps to bind the remaining input parameters to the other scriptable task elements.

“Simple Workflow Example Scriptable Task Element Bindings,” on page 82 lists the bindings for the

Start VM failed, both Timeout or Error, Send Email Failed, and the OK scriptable task elements.

10 Click Save at the bottom of the workflow editor's Schema tab.

You have bound the scriptable task elements to their input and output parameters, and provided the scripting that defines their function.

What to do next

You must define the exception handling.

Simple Workflow Example Scriptable Task Element Bindings

Bindings define how the simple workflow example's scriptable task elements process input parameters. You also bind the scriptable task elements to their JavaScript functions.

Start VM Failed Scriptable Task

The Start VM Failed scriptable task element handles any exceptions that the startVM action returns by setting the content of an email notification about the failure to start the virtual machine, and writing the event in the Orchestrator log.

Table 2-10 shows the input and output parameter bindings that the Start VM Failed scriptable task element

requires.

82 VMware, Inc.

Table 2-10. Bindings of the Start VM Failed Scriptable Task Element

Bind to Existing or

Parameter Name Binding Type

errorCode

body

IN Bind

IN Create

OUT Create

Create Parameter? Binding Values

Chapter 2 Developing Workflows

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Description:

The virtual machine to power on.

Local Parameter: errorCode

Source parameter:

errorCode[attribute]

Type: string

Description:

Catch any exceptions while powering on a VM.

Local Parameter: body

Source parameter:

body[attribute]

Type: string

Description: The email body

The Start VM Failed scriptable task element performs the following scripted function.

body = "Unable to execute powerOnVM_Task() on VM '"+vm.name+"', exception found: "+errorCode; //Writes the following event in the vCO database Server.error("Unable to execute powerOnVM_Task() on VM '"+vm.name, "Exception found: "+errorCode);

Timeout 1 Scriptable Task Element

The Timeout 1 scriptable task element handles any exceptions that the vim3WaitTaskEnd action returns by setting the content of an email notification about the failure of the task, and writing the event in the Orchestrator log.

Table 2-11 shows the input and output parameter bindings that the Timeout 1 scriptable task element requires.

VMware, Inc. 83

vCenter Orchestrator Developer's Guide

Table 2-11. Bindings of the Timeout 1 Scriptable Task Element

Parameter Name Binding Type

errorCode

body

Bind to Existing or Create Parameter? Binding Values

IN Bind

OUT Bind

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Description:

The virtual machine to start.

Local Parameter: errorCode

Source parameter:

errorCode[attribute]

Type: string

Description:

Catch any exceptions while powering on a VM.

Local Parameter: body

Source parameter:

body[attribute]

Type: string

Description: The email body

The Timeout 1 scriptable task element requires the following scripted function.

body = "Error while waiting for poweredOnVM_Task() to complete on VM '"+vm.name+"', exception found: "+errorCode; //Writes the following event in the vCO database Server.error("Error while waiting for poweredOnVM_Task() to complete on VM '"+vm.name, "Exception found: "+errorCode);

Timeout 2 Scriptable Task Element

The Timeout 2 scriptable task element handles any exceptions that the vim3WaitToolsStarted action returns by setting the content of an email notification about the failure of the task, and writing the event in the Orchestrator log.

Table 2-12 shows the input and output parameter bindings that the Timeout 2 scriptable task element requires.

84 VMware, Inc.

Table 2-12. Bindings of the Timeout 2 Scriptable Task Element

Bind to Existing or

Parameter Name Binding Type

errorCode

body

IN Bind

OUT Bind

Create Parameter? Binding Values

Chapter 2 Developing Workflows

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Description:

The virtual machine to power on.

Local Parameter: errorCode

Source parameter:

errorCode[attribute]

Type: string

Description:

Catch any exceptions while powering on a VM.

Local Parameter: body

Source parameter:

body[attribute]

Type: string

Description: The email body

The Timeout 2 scriptable task element requires the following scripted function.

body = "Error while waiting for VMware tools to be up on VM '"+vm.name+"', exception found: "+errorCode; //Writes the following event in the vCO database Server.error("Error while waiting for VMware tools to be up on VM '"+vm.name, "Exception found: "+errorCode);

OK Scriptable Task Element

The OK scriptable task element receives notice that the virtual machine has started successfully, sets the content of an email notification about the successful start of the virtual machine, and writes the event in the Orchestrator log.

Table 2-13 shows the input and output parameter bindings that the OK scriptable task element requires.

Table 2-13. Bindings of the OK Scriptable Task Element

Bind to Existing or

Parameter Name Binding Type

body

IN Bind

OUT Bind

Create Parameter? Binding Values

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Description:

The virtual machine to power on.

Local Parameter: body

Source parameter:

body[attribute]

Type: string

Description: The email body

VMware, Inc. 85

vCenter Orchestrator Developer's Guide

The OK scriptable task element requires the following scripted function.

body = "The VM '"+vm.name+"' has started successfully and is ready for use"; //Writes the following event in the vCO database Server.log(body);

Send Email Failed Scriptable Task Element

The Send Email Failed scriptable task element receives notice that the sending of the email failed, and writes the event in the Orchestrator log.

Table 2-14 shows the input parameter bindings that the Send Email Failed scriptable task element requires.

Table 2-14. Bindings of the Send Email Failed Scriptable Task Element

Parameter Name Binding Type

toAddress

emailErrorCode

Bind to Existing or Create Parameter? Binding Values

IN Bind

IN Create

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Description:

The virtual machine to power on.

Local Parameter: toAddress

Source parameter:

toAddress[in-parameter]

Type: string

Description:

The email address of the person to inform of the result of this workflow

Local Parameter:

emailErrorCode

Source parameter:

emailErrorCode[attrbute]

Type: string

Description:

Catch any exceptions while sending an email

The Send Email Failed scriptable task element requires the following scripted function.

//Writes the following event in the vCO database Server.error("Couldn't send result email to '"+toAddress+"' for VM '"+vm.name, "Exception found: "+emailErrorCode);

Send Email Scriptable Task Element

The purpose of the Start VM and Send Email workflow is to inform an administrator when it starts a virtual machine. To do so, you must define the scriptable task that sends an email. To send the email, the Send Email scriptable task element needs an SMTP server, addresses for the sender and recipient of the email, the email subject, and the email content.

Table 2-15 shows the input and output parameter bindings that the Send Email scriptable task element requires.

86 VMware, Inc.

Table 2-15. Bindings of the Send Email Scriptable Task Element

Bind to Existing or

Parameter Name Binding Type

toAddress

body

smtpHost

fromAddress

subject

IN Bind

IN Create

Create Parameter? Binding Values

Chapter 2 Developing Workflows

Local Parameter: vm

Source parameter: vm[inparameter]

Type: VC:VirtualMachine

Description:

The virtual machine to power on.

Local Parameter: toAddress

Source parameter:

toAddress[in-parameter]

Type: string

Description:

The email address of the person to inform of the result of this workflow

Local Parameter: body

Source parameter:

body[attribute]

Type: string

Description: The email body

Local Parameter: smtpHost

Source parameter:

smtpHost[attribute]

Type: string

Description:

The email SMTP server

Local Parameter: fromAddress

Source parameter:

fromAddress[attribute]

Type: string

Description:

The email address of the sender

Local Parameter: subject

Source parameter:

subject[attribute]

Type: string

Description:

The email subject

The Send Email scriptable task element requires the following scripted function.

//Create an instance of EmailMessage var myEmailMessage = new EmailMessage() ;

//Apply methods on this instance that populate the email message myEmailMessage.smtpHost = smtpHost; myEmailMessage.fromAddress = fromAddress; myEmailMessage.toAddress = toAddress; myEmailMessage.subject = subject; myEmailMessage.addMimePart(body , "text/html");

VMware, Inc. 87

vCenter Orchestrator Developer's Guide

//Apply the method that sends the email message myEmailMessage.sendMessage(); System.log("Sent email to '"+toAddress+"'");

Define the Simple Example Workflow Exception Bindings

You define exception bindings in the Schema tab in the workflow editor. Exception bindings define how elements process errors.

The following elements in the workflow return exceptions: startVM, vim3WaitTaskEnd, Send Email, and

vim3WaitToolsStarted.

Prerequisites

You must have created the Start VM and Send Email workflow, defined its parameters, and laid out its schema.

Procedure

1 Click the startVM action element.

2 Click the Exceptions tab at the bottom of the Schema tab.

3 Click the Not set button.

4 Select errorCode from the proposed list.

5 Repeat the preceding steps to set the exception binding to errorCode for both vim3WaitTaskEnd and

vim3WaitToolsStarted.

6 Click the Send Email scriptable task element.

7 Click the Exceptions tab at the bottom of the Schema tab.

8 Click the Not set button.

9 Select emailErrorCode from the proposed list.

10 Click Save at the bottom of the workflow editor's Schema tab.

You have defined the exception binding for the elements that return exceptions.

What to do next

You must set the read and write properties on the attributes and parameters.

Set the Simple Workflow Example Attribute Read-Write Properties

You can define whether parameters and attributes are read-only constants or writeable variables. You can also set limitations on the values that users can provide for input parameters.

Setting certain parameters to read-only allows other developers to adapt the workflow or to modify it without breaking the workflow's core function.

Prerequisites

You must have created a workflow, laid out and linked its schema, and defined the IN, OUT, and exception bindings for all elements.

88 VMware, Inc.

Chapter 2 Developing Workflows

Procedure

1 Click the General tab at the top of the workflow editor.

Under Attributes is a list of all the attributes you defined, with check boxes next to each attribute. When you check these checkboxes, you set attributes as read-only.

2 Check the check boxes to make the following attributes read-only constants:

progress

pollRate

timeout

smtpHost

fromAddress

subject

You have defined which of the workflow's attributes are constants and which are variables.

What to do next

You must set the parameter properties and place constraints on the possible values for that parameter.

Set the Simple Workflow Example Parameter Properties

Prerequisites

You must have created a workflow, laid out and linked its schema, and defined the IN, OUT, and exception bindings for all elements.

Procedure

1 Click the Presentation tab.

The two input parameters you defined for this workflow are listed.

2 Click the (VC:VirtualMachine)vm parameter.

3 Add a description in the Description tab in the bottom half of the screen.

For example, type The virtual machine to start.

4 Click the Properties tab in the bottom half of the screen.

This tab allows you to set the properties of the (VC:VirtualMachine)vm parameter.

5 Right-click the Properties tab and select Add Property.

6 Select Mandatory input from the list of proposed properties.

When you select this property, users cannot run the Start VM and Send Email workflow without providing a virtual machine to start.

7 Set the value of the Mandatory input property to Yes.

8 Right-click on the Properties tab and select Add Property again.

9 Select Select value as from the list of proposed properties.

When you set this property, you set how the user selects the value of the (VC:VirtualMachine)vm input parameter.

VMware, Inc. 89

vCenter Orchestrator Developer's Guide

10 Select list from the list of possible values.

11 Click the (string)toAddress parameter in the top half of the Presentation tab.

12 Add a description in the Description tab in the bottom half of the screen.

For example, type The email address of the person to notify.

13 Click the Properties tab for (string)toAddress.

14 Right-click the Properties tab and select Add Property > Mandatory input.

15 Set the value of the Mandatory input property to Yes.

16 Right-click the Properties tab and select Add Property > Matching regular expression.

This property allows you to set constraints on what users can provide as input.

17 Click the Value text box for Matching regular expression and set the constraints to

[a-zA-Z0-9_%-+.]+@[a-zA-Z0-9-.]+\.[a-zA-Z]{2,4}

Setting these constraints limits user input to characters that are appropriate for email addresses. If the user tries to input any other character for the email address of the recipient when they start the workflow, the workflow will not start.

You have made both parameters mandatory, defined how the user can select the virtual machine to start, and limited the characters that can be input for the recipient's email address.

What to do next

You must create the layout, or presentation, of the input parameters dialog box in which users enter a workflow's input parameter values when they run it.

Set the Layout of the Simple Workflow Example Input Parameters Dialog Box

The layout you define in the Presentation tab also defines the layout of the input parameter dialog boxes for workflows you run using a Web view.

Prerequisites

You must have created a workflow, laid out and linked its schema, defined the IN, OUT, and exception bindings for all elements, and set the attribute and parameter properties.

Procedure

1 Click the Presentation tab in the workflow editor.

2 Right-click the Presentation node in the presentation hierarchical list and select Create display group.

A New Step node and a New Group sub-node appear under the Presentation node.

3 Right-click New Step and select Delete.

Because this workflow only has two parameters, you do not need multiple layers of display sections in the input parameters dialog box.

4 Double-click New Group to edit the group name and press Enter.

For example, name the display group Virtual Machine.

The text you enter here appears as a heading in the input parameter dialog box when users start the workflow.

90 VMware, Inc.

Chapter 2 Developing Workflows

5 Provide a description of the Virtual Machine display group in the Description text box in the General tab

at the bottom of the Presentation tab.

For example, type Select the virtual machine to start.

The text you enter here appears as a prompt in the input parameter dialog box when users start the workflow.

6 Drag the (VC:VirtualMachine)vm parameter under the Virtual Machine display group.

The text box in the input parameters dialog box in which the user enters the virtual machine to start will appear under the heading Virtual Machine.

7 Repeat the preceding steps to create a display group for the toAddress parameter, setting the following

properties:

a Create a display group named Recipient's Email Address.

b Add a description for the display group, for example,

Enter the email address of the person to notify when this virtual machines is powered-on.

c Drag the toAddress property under the Recipient's Email Address display group.

You have set up the layout of the input parameters dialog box that appears when users run the workflow.

What to do next

You have completed the development of the simple workflow example. You can now validate and run the workflow.

Validate and Run the Simple Workflow Example

After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.

Prerequisites

Create a workflow, lay out its schema, define the links and bindings, define the parameter properties, and create the presentation of the input parameters dialog box.

Procedure

1 Click Validate in the Schema tab of the workflow editor.

The validation tool locates any errors in the definition of the workflow.

2 When you have eliminated any errors, click Save and Close at the bottom of the workflow editor.

You return to the Orchestrator client.

3 Click the Workflows view.

4 Select Workflow Examples > Start VM and Send Email in the workflow hierarchical list.

5 Right-click the Start VM and Send Email workflow and select Execute workflow.

The input parameters dialog box opens and prompts you for a virtual machine to start and an email address of a person to inform.

6 Select a virtual machine to start in the vCenter Server from the proposed list.

7 Enter an email address to which to send email notifications.

VMware, Inc. 91

vCenter Orchestrator Developer's Guide

8 Click Submit to start the workflow.

A workflow token appears under the Start VM and Send Email workflow.

9 Click the workflow token to follow the progress of the workflow as it runs.

If the workflow ran successfully, the virtual machine you identified is in the powered-on state, and the email recipient you defined receives a confirmation email.

Develop a Complex Workflow

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.

In the complex workflow exercise, you develop a workflow that takes a snapshot of all the virtual machines contained in a given resource pool. The workflow you create will perform the following tasks:

1 Prompts the user for a resource pool that contains the virtual machines of which to take snapshots.

2 Determines whether the resource pool contains running virtual machines.

3 Determines how many running virtual machines the resource contains.

4 Verifies whether an individual virtual machine running in the pool meets specific criteria for a snapshot

to be taken.

5 Takes the snapshot of the virtual machine.

6 Determines whether more virtual machines exist in the pool of which to take snapshots.

7 Repeats the verification and snapshot process until the workflow has taken snapshots of all eligible virtual

machines in the resource pool.

The ZIP file of Orchestrator examples that you can download from the Orchestrator documentation homepage contains a completed version of the Take a Snapshot of All Virtual Machines in a Resource Pool workflow. For details about where to download the Orchestrator examples bundle, see “Example Applications,” on page 9.

Prerequisites

Before you attempt to develop this complex workflow, follow the exercises in “Develop a Simple Example

Workflow,” on page 70. The procedures to develop a complex workflow provide the broad steps of the

development process, but are not as detailed as the simple workflow exercises.

Procedure

1 Create the Complex Workflow on page 93

The first step in the workflow development process is to create the workflow in the Orchestrator client.

2 Define the Complex Workflow Example Input Parameters on page 94

You define workflow input parameters in the workflow editor. The input parameters provide data for the workflow to process.

3 Create a Custom Action For the Complex Workflow Example on page 94

The Check VM scriptable element calls on an actions that does not exist in the Orchestrator API. You must create the getVMDiskModes action.

4 Create the Complex Workflow Example Schema on page 95

You create a workflow's schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.

5 Link the Complex Workflow Example Schema Elements on page 96

You link a workflow's elements together in the Schema tab of the workflow editor. The linking defines the logical flow the workflow.

92 VMware, Inc.

Chapter 2 Developing Workflows

6 Create the Complex Workflow Example Zones on page 98

Optionally, you can highlight different zones of the workflow by adding workflow notes. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.

7 Define the Complex Workflow Example Bindings on page 99

You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define the data flow of the workflow. You also bind the scriptable task elements to their JavaScript functions.

8 Set the Complex Workflow Example Attribute Properties on page 108

You set the attribute properties in the General tab in the workflow editor.

9 Create the Layout of the Complex Workflow Example Input Parameters on page 108

10 Validate and Run the Complex Workflow Example on page 109

After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.

Create the Complex Workflow

The first step in the workflow development process is to create the workflow in the Orchestrator client.

Prerequisites

The following components are installed and configured on the system.

vCenter Server, controlling a resource pool that contains some virtual machines

The Workflow Examples folder in the workflows hierarchical list, that you created in “Create the Simple

Workflow Example,” on page 72.

For information about how to install and configure vCenter, see the ESX and vCenter Server Installation Guide. For information about how to configure Orchestrator, see the Orchestrator Installation and Configuration Guide.

Procedure

1 Select Workflows > Workflow Examples.

2 Create a workflow called Take a Snapshot of All Virtual Machines in a Resource Pool.

3 Open the workflow editor by right-clicking the new workflow and selecting Edit.

4 In the General tab of the workflow editor, click the version number digits to increment the version number.

Because this is the initial creation of the workflow, set the version to 0.0.1.

5 Click the Server restart behavior value in the General tab to set whether the workflow resumes after a

server restart.

6 Type a description of what the workflow does in the Description text box in the General tab.

7 Click Save at the bottom of the General tab.

You created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.

What to do next

You can now continue editing the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.

VMware, Inc. 93

vCenter Orchestrator Developer's Guide

Define the Complex Workflow Example Input Parameters

You define workflow input parameters in the workflow editor. The input parameters provide data for the workflow to process.

Prerequisites

You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, and opened it for editing in the workflow editor.

Procedure

1 Click the Inputs tab in the workflow editor.

2 Define the following input parameter.

Name: resourcePool

Type: VC:ResourcePool

Description: The resource pool containing the virtual machines of which to take snapshots.

3 Click the Outputs tab in the workflow editor.

4 Define the following output parameter.

Name: snapshotVmArrayOut

Type: Array/VC:VirtualMachine

Description: The Array of virtual machines of which snapshots have been taken.

You have defined the workflow input parameter.

What to do next

You can create a workflow schema.

Create a Custom Action For the Complex Workflow Example

The Check VM scriptable element calls on an actions that does not exist in the Orchestrator API. You must create the getVMDiskModes action.

For more detail about creating actions, see Chapter 3, “Developing Actions,” on page 111.

Prerequisites

You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.

Procedure

1 Close the workflow editor by clicking Save and Close.

2 Click the Actions view in the Orchestrator client.

3 Right-click the root of the actions hierarchical list and select New Module.

4 Name the new module com.vmware.example.

5 Right-click the com.vmware.example module and select Add Action.

6 Create an action called getVMDiskModes.

7 Right-click getVMDiskModes and select Edit.

8 Increment the version number in the General tab in the actions editor by clicking the version digits.

94 VMware, Inc.

Chapter 2 Developing Workflows

9 Add the following description of the action in the General tab.

This action returns an array containing the disk modes of all disks on a VM. The elements in the array each have one of the following string values:

- persistent

- independent-persistent

- nonpersistent

- independent-nonpersistent Legacy values:

- undoable

- append

10 Click the Scripting tab.

11 Right-click in the top pane of the Scripting tab and select Add Parameter to create the following input

parameter.

Name: vm

Value: VC:VirtualMachine

Description: The virtual machine for which to return the Disk Modes

12 Add the following scripting in the bottom of the Scripting tab.

The following code returns an array of disk modes for the disks of the virtual machine.

13 Click Save and Close to exit the Actions palette.

You have defined the custom action the Take a Snapshot of All Virtual Machines in a Resource Pool workflow requires.

What to do next

You must create the workflow schema.

Create the Complex Workflow Example Schema

You create a workflow's schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.

Prerequisites

You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, defined its input parameter, and created the getVMDiskModes action.

Procedure

1 Right-click the Take a Snapshot of All Virtual Machines in a Resource Pool workflow to open the workflow

editor.

2 Click the Schema tab in the workflow editor.

VMware, Inc. 95

vCenter Orchestrator Developer's Guide

3 Add the following schema elements to the workflow schema.

Table 2-16. Complex Workflow Example Schema Elements

Element Type Element Name Position in Schema

Scriptable task Initializing Below start element

Decision VMs to Process? Below Initializing scriptable task

Scriptable task Pool Has No VMs Below Virtual Machines to Process?

Custom decision Remaining VMs? Right of Virtual Machines to Process?

Action

Custom decision Create snapshot? Right of getVMDiskModes action

Workflow Create a snapshot Above Create snapshot? decision

Scriptable task VM Snapshots Left of Create a snapshot workflow

Scriptable task Increment Left of VM Snapshots scriptable task

Scriptable task Log Exception Above VM Snapshots scriptable task

Scriptable task Set Output Below Remaining VMs? custom

End element No name Right of Set Output scriptable task

getVMDiskModes

custom decision

Right of Virtual Machines Remaining? custom decision

decision

4 Click Save at the bottom of the Schema tab.

You have created the structure of the workflow.

Figure 2-6. Layout of the Take a Snapshot of All Virtual Machines in a Resource Pool Schema Elements

What to do next

You can now link the workflow elements together.

Link the Complex Workflow Example Schema Elements

You link a workflow's elements together in the Schema tab of the workflow editor. The linking defines the logical flow the workflow.

Prerequisites

You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, defined its input parameter, and created its schema.

96 VMware, Inc.

Chapter 2 Developing Workflows

Procedure

1 Click the connector tool button in the toolbar at the top of the Schema tab in the workflow editor.

2 Create the following links between the elements in the schema.

Table 2-17. Complex Workflow Example Links

Starting Element Target Element

Start element Initializing scripted element

Initializing scripted element VMs to Process? custom decision

VMs to Process? decision's true result VMs Remaining? custom decision

VMs to Process? decision's false result Has No VMs scriptable task

Has No VMs scriptable task Set Output scriptable task

VMs Remaining? custom decision's true result getVMDisksModes action

VMs Remaining? custom decision's false result Set Output scriptable task

getVMDisksModes action Create Snapshot? decision

getVMDisksModes action exception link Log Exception scriptable task

Create Snapshot? custom decision's true result Create a snapshot workflow

Create Snapshot? custom decision's false result Increment scriptable task

Create a snapshot workflow VM Snapshots scriptable task

Create a snapshot workflow exception link Log Exception scriptable task

VM Snapshots scriptable task Increment scriptable task

Increment scriptable task VMs Remaining? custom decision

Log Exception scriptable task Increment scriptable task

Set Output scriptable task End element

3 Click Save at the bottom of the workflow editor's Schema tab.

Figure 2-7 shows what the linked elements of the Take a Snapshot of All Virtual Machines in a Resource Pool

workflow should look like.

Figure 2-7. Linking of the Take a Snapshot of All Virtual Machines in a Resource Pool Example Workflow

What to do next

You can optionally define workflow zones by using workflow notes.

VMware, Inc. 97

vCenter Orchestrator Developer's Guide

Create the Complex Workflow Example Zones

Optionally, you can highlight different zones of the workflow by adding workflow notes. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.

Prerequisites

You must have created the workflow, created its schema, and linked the schema elements .

Procedure

1 Create the following workflow zones by using workflow notes.

Elements in Zone Description

Start element; Initialize scriptable task; VMs to Process? custom decision

Pool has no VMs scriptable task.

VMs remaining? custom decision; getVMDisksModes action, Create Snapshot? decision; Create a snapshot workflow; VM Snapshots scriptable task; Increment scriptable task; Log Exception scriptable task

Set Output scriptable task; End element

2 Click Save at the bottom of the workflow editor Schema tab.

Get an array of virtual machines from a resource pool, initialize the counter of the Array and set the first virtual machine to be treated, if any.

Resource pool contains no virtual machines of which to take snapshots.

Check whether any virtual machines remain in the resource pool, check that a virtual machine meets the snapshot criteria, take a snapshot, then loop until a snapshot has been taken of all the virtual machines.

Generates the resulting array of virtual machines of which snapshots have been taken.

Your workflow zones should look like the following diagram.

Figure 2-8. Schema Diagram for Take Snapshot of all Virtual Machines in a Resource Pool Example Workflow

What to do next

You must define the bindings between the element parameters.

98 VMware, Inc.

Chapter 2 Developing Workflows

Define the Complex Workflow Example Bindings

Prerequisites

You must already have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, defined its input parameter, created its schema, and linked the schema elements together.

Procedure

1 Click the Schema tab in the workflow editor.

2 Define the bindings shown in “Complex Workflow Example Bindings,” on page 99.

3 Click Save at the bottom of the workflow editor Schema tab.

All the elements' input and output parameters are bound to the appropriate parameter types and values.

What to do next

You must set the attribute properties.

Complex Workflow Example Bindings

Bindings define how the simple workflow example's action elements process input and output parameters.

The Take Snapshots of All Virtual Machines in a Resource Pool workflow requires the following input and output parameter bindings. You also define the JavaScript functions for the scriptable task elements.

In cases in which you bind to existing parameters, the binding inherits the type and description values from the original parameter.

Initializing Scriptable Task

The Initializing scriptable task element initializes the attributes of the workflow. Table 2-18 shows the input and output parameter bindings that the Initializing scriptable task element requires.

Table 2-18. Bindings of the Initializing Scriptable Task Element

Bind to Existing or Create

Parameter Name Binding Type

resourcePool

allVMs

IN Bind

OUT Create

Parameter? Binding Values

Local parameter: resourcePool

Source parameter:

resourcePool[in-parameter]

Type: VC:ResourcePool

Description:

The resource pool containing the virtual machines of which to take snapshots

Local parameter: allVMs

Source parameter:

allVMs[attribute]

Type:

Array/VC:VirtualMachine

Description:

The virtual machines in the resource pool.

VMware, Inc. 99

vCenter Orchestrator Developer's Guide

Table 2-18. Bindings of the Initializing Scriptable Task Element (Continued)

Parameter Name Binding Type

numberOfVMs

vmCounter

snapshotVmArray

Bind to Existing or Create Parameter? Binding Values

OUT Create

Local parameter: numberOfVMs

Source parameter:

numberOfVMs[attribute]

Type: number

Description:

The number of virtual machines found in the resourcePool

Local parameter: vmCounter

Source parameter:

vmCounter[attribute]

Type: number

Description:

The counter of the virtual machines inside the array

Local parameter: vm

Source parameter: vm[attribute]

Type: VC:VirtualMachine

Description:

The current virtual machine having a snapshot taken

Local parameter:

snapshotVmArray

Source parameter:

snapshotVmArray[attribute]

Type:

Array/VC:VirtualMachine

Description:

The Array of virtual machines of which snapshots have been taken

The Initialize scriptable task element performs the following scripted function.

//Retrieve an array of virtual machines contained in the specified Resource Pool allVMs = resourcePool.vm; //Initialize the size of the Array and the first VM to snapshot if (allVMs!=null && allVMs.length!=0) { numberOfVms = allVMs.length; vm = allVMs[0]; } else { numberOfVms = 0; } //Initialize the VM counter vmCounter = 0; //Initializing the array of VM snapshots snapshotVmArray = new Array();

VMs to Process? Decision Element

The VMs to Process? decision element determines whether any virtual machines of which to take snapshots exist in the resource pool. Table 2-19 shows the bindings that the VMs to Process? decision element requires.

100 VMware, Inc.

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

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Updated Information

About This Book

Key Features of the Orchestrator Platform

Orchestrator User Roles and Related Tasks

Orchestrator Architecture

Developing Workflows 2

Principal Phases in the Workflow Development Process

Accessing the Orchestrator Client

Testing Workflows During Development

Workflow Editor

Create a Workflow

Edit a Workflow

Edit a Workflow from the Standard Library

Workflow Editor Tabs

Provide General Workflow Information

Defining Attributes and Parameters

Define Workflow Attributes

Define Workflow Parameters

Attribute and Parameter Naming Restrictions

Workflow Schema

View Workflow Schema

Building a Workflow in the Workflow Schema

Edit a Workflow Schema

Modify Search Results

Schema Elements

Schema Element Properties

Edit a Schema Element's Global Properties

Schema Element Properties Tabs

Links and Bindings

Logical Flow of a Workflow

Element Links

Create Standard Path Links

Data Flow of a Workflow

Element Bindings

Define Element Bindings

Decisions

Create Decision Element Links

Create Workflow Branches Using Decisions

Exception Handling

Create Exception Bindings

Obtaining Input Parameters from Users When a Workflow Starts

Creating the Input Parameters Dialog Box In the Presentation Tab

Create the Presentation of the Input Parameters Dialog Box

Setting Parameter Properties

Set Parameter Properties

Workflow Input Parameter Properties

Predefined Constant Values for OGNL Expressions

Requesting User Interactions While a Workflow Runs

Add a User Interaction to a Workflow

Set the User Interaction security.group Attribute

Set the timeout.date Attribute to an Absolute Date

Calculate a Relative Timeout for User Interactions

Set the timeout.date Attribute to a Relative Date

Define the External Inputs for a User Interaction

Define User Interaction Exception Behavior

Create the Input Parameters Dialog Box for the User Interaction

Respond to a Request for a User Interaction

Calling Workflows Within Workflows

Workflow Elements that Call Workflows

Propagate Workflow Changes to other Workflows

Call a Workflow Synchronously

Call a Workflow Asynchronously

Schedule a Workflow

Call Several Workflows Simultaneously

Running a Workflow on a Selection of Objects

Implement the Start Workflows in a Series and Start Workflows in Parallel Workflows

Developing Long-Running Workflows

Set a Relative Time and Date for Timer-Based Workflows

Create a Timer-Based Long-Running Workflow

Create a Trigger Object

Create a Trigger-Based Long-Running Workflow

Configuration Elements

Create a Configuration Element

Workflow User Permissions

Set User Permissions on a Workflow