VMware vCenter Orchestrator - 5.5.1 User Manual

Developing with VMware vCenter

Orchestrator

vCenter Orchestrator 5.5.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-001341-00

Developing with VMware vCenter Orchestrator

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

VMware, Inc.

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

2 VMware, Inc.

Developing with VMware vCenter Orchestrator 7

Developing Workflows 9

Key Concepts of Workflows 11

Workflow Parameters 11

Workflow Attributes 11

Workflow Schema 12

Workflow Presentation 12

Workflow Tokens 12

Phases in the Workflow Development Process 12

Access Rights for the Orchestrator Client 12

Testing Workflows During Development 13

Creating and Editing a Workflow 13

Create a Workflow 13

Edit a Workflow 14

Edit a Workflow from the Standard Library 14

Workflow Editor Tabs 15

Provide General Workflow Information 15

Defining Attributes and Parameters 16

Define Workflow Parameters 17

Define Workflow Attributes 17

Attribute and Parameter Naming Restrictions 18

Workflow Schema 19

View Workflow Schema 20

Building a Workflow in the Workflow Schema 20

Schema Elements 23

Schema Element Properties 26

Links and Bindings 29

Decisions 34

Exception Handling 37

Foreach Elements and Composite Types 38

Obtaining Input Parameters from Users When a Workflow Starts 41

Creating the Input Parameters Dialog Box In the Presentation Tab 41

Setting Parameter Properties 43

Requesting User Interactions While a Workflow Runs 46

Add a User Interaction to a Workflow 47

Set the User Interaction security.group Attribute 47

Set the timeout.date Attribute to an Absolute Date 48

Calculate a Relative Timeout for User Interactions 49

Set the timeout.date Attribute to a Relative Date 50

Define the External Inputs for a User Interaction 51

Define User Interaction Exception Behavior 52

VMware, Inc.

Developing with VMware vCenter Orchestrator

Create the Input Parameters Dialog Box for the User Interaction 53

Respond to a Request for a User Interaction 54

Calling Workflows Within Workflows 54

Workflow Elements that Call Workflows 55

Call a Workflow Synchronously 57

Call a Workflow Asynchronously 58

Schedule a Workflow 59

Prerequisites for Calling a Remote Workflow from Within Another Workflow 59

Call Several Workflows Simultaneously 60

Running a Workflow on a Selection of Objects 61

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

Developing Long-Running Workflows 63

Set a Relative Time and Date for Timer-Based Workflows 63

Create a Timer-Based Long-Running Workflow 64

Create a Trigger Object 66

Create a Trigger-Based Long-Running Workflow 67

Configuration Elements 68

Create a Configuration Element 68

Workflow User Permissions 69

Set User Permissions on a Workflow 70

Validating Workflows 70

Validate a Workflow and Fix Validation Errors 71

Debugging Workflows 72

Debug a Workflow 72

Example Workflow Debugging 73

Running Workflows 73

Run a Workflow in the Workflow Editor 74

Run a Workflow 74

Resuming a Failed Workflow Run 76

Set the Behavior for Resuming a Failed Workflow Run 76

Set Custom Properties for Resuming Failed Workflow Runs 77

Resume a Failed Workflow Run 77

Generate Workflow Documentation 78

Use Workflow Version History 78

Restore Deleted Workflows 79

Develop a Simple Example Workflow 79

Create the Simple Workflow Example 81

Create the Schema of the Simple Workflow Example 82

Create the Simple Workflow Example Zones 84

Define the Parameters of the Simple Workflow Example 85

Define the Simple Workflow Example Decision Bindings 86

Bind the Action Elements of the Simple Workflow Example 87

Bind the Simple Workflow Example Scripted Task Elements 90

Define the Simple Workflow Example Exception Bindings 97

Set the Read-Write Properties for Attributes of the Simple Workflow Example 98

Set the Simple Workflow Example Parameter Properties 98

Set the Layout of the Simple Workflow Example Input Parameters Dialog Box 100

Validate and Run the Simple Workflow Example 101

4 VMware, Inc.

Develop a Complex Workflow 102

Create the Complex Workflow Example 103

Create a Custom Action for the Complex Workflow Example 104

Create the Schema of the Complex Workflow Example 105

Create the Complex Workflow Example Zones 107

Define the Parameters of the Complex Workflow Example 109

Define the Bindings for the Complex Workflow Example 109

Set the Complex Workflow Example Attribute Properties 119

Create the Layout of the Complex Workflow Example Input Parameters 119

Validate and Run the Complex Workflow Example 120

Contents

Scripting 123

Orchestrator Elements that Require Scripting 123

Limitations of the Mozilla Rhino Implementation in Orchestrator 124

Using the Orchestrator Scripting API 124

Access the Scripting Engine from the Workflow Editor 125

Access the Scripting Engine from the Action or Policy Editor 126

Access the Orchestrator API Explorer 126

Use the Orchestrator API Explorer to Find Objects 126

Writing Scripts 127

Add Parameters to Scripts 129

Accessing the Orchestrator Server File System from JavaScript and Workflows 129

Accessing Java Classes from JavaScript 130

Accessing Operating System Commands from JavaScript 130

Exception Handling Guidelines 130

Orchestrator JavaScript Examples 131

Basic Scripting Examples 132

Email Scripting Examples 133

File System Scripting Examples 135

LDAP Scripting Examples 135

Logging Scripting Examples 136

Networking Scripting Examples 136

Workflow Scripting Examples 136

Developing Actions 139

Reusing Actions 139

Access the Actions View 139

Components of the Actions View 140

Creating Actions 140

Create an Action 140

Find Elements That Implement an Action 141

Action Coding Guidelines 141

Use Action Version History 143

Restore Deleted Actions 143

Creating Resource Elements 145

View a Resource Element 145

Import an External Object to Use as a Resource Element 146

VMware, Inc. 5

Developing with VMware vCenter Orchestrator

Edit the Resource Element Information and Access Rights 146

Save a Resource Element to a File 147

Update a Resource Element 147

Add a Resource Element to a Workflow 148

Add a Resource Element to a Web View 148

Creating Packages 151

Create a Package 152

Set User Permissions on a Package 153

Creating Plug-Ins by Using Maven 155

Create an Orchestrator Plug-In with Maven from an Archetype 155

Index 157

6 VMware, Inc.

Developing with VMware vCenter Orchestrator

Developing with VMware vCenter Orchestrator provides information and instructions for developing custom VMware® vCenter Orchestrator workflows and actions.

In addition, the documentation contains information about the Orchestrator elements that require scripting and provides JavaScript examples. Developing with VMware vCenter Orchestrator also provides instructions about how to create resources and packages.

Intended Audience

This information is intended for developers who want to create custom Orchestrator workflows and actions, as well as custom building blocks.

VMware, Inc.

Developing with VMware vCenter Orchestrator

8 VMware, Inc.

Developing Workflows 1

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.

Key Concepts of Workflows on page 11

Workflows consist of a schema, attributes, and parameters. The workflow schema is the main component of a workflow as it defines all the workflow elements and the logical connections between them. The workflow attributes and parameters are the variables that workflows use to transfer data. Orchestrator saves a workflow token every time a workflow runs, recording the details of that specific run of the workflow.

Phases in the Workflow Development Process on page 12

The process for developing a workflow involves a series of phases. You can follow a different sequence of phases or skip a phase, depending on the type of workflow that you are developing. For example, you can create a workflow without custom scripting.

Access Rights for the Orchestrator Client on page 12

By default, only members of the Orchestrator administrator LDAP group can access the Orchestrator client.

VMware, Inc.

Testing Workflows During Development on page 13

You can test workflows at any point during the development process, even if you have not completed the workflow or included an end element.

Creating and Editing a Workflow on page 13

You create workflows in the Orchestrator client and edit them in the workflow editor. The workflow editor is the IDE of the Orchestrator client for developing workflows.

Provide General Workflow Information on page 15

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.

Defining Attributes and Parameters on page 16

After you create a workflow, you must define the global attributes, input parameters, and output parameters of the workflow.

Workflow Schema on page 19

A workflow schema is a graphical representation of a workflow that shows the workflow as a flow diagram of interconnected workflow elements. The workflow schema defines the logical flow of a workflow.

Developing with VMware vCenter Orchestrator

Obtaining Input Parameters from Users When a Workflow Starts on page 41

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.

(Optional) Requesting User Interactions While a Workflow Runs on page 46

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.

Calling Workflows Within Workflows on page 54

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 61

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 63

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 68

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 69

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

Validating Workflows on page 70

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.

Debugging Workflows on page 72

Orchestrator provides a workflow debugging tool. You can debug a workflow to inspect the input and output parameters and attributes at the start of any activity, replace parameter or attribute values during a workflow run in edit mode, and resume a workflow from the last failed activity.

Running Workflows on page 73

An Orchestrator workflow runs according to a logical flow of events.

Resuming a Failed Workflow Run on page 76

If a workflow fails, Orchestrator provides an option to resume the workflow run from the last failed activity.

Generate Workflow Documentation on page 78

You can export documentation in PDF format about a workflow or a workflow folder that you select at any time.

Use Workflow Version History on page 78

You can use version history to revert a workflow to a previously saved state. You can revert the workflow state to an earlier or a later workflow version. You can also compare the differences between the current state of the workflow and a saved version of the workflow.

10 VMware, Inc.

Restore Deleted Workflows on page 79

You can restore workflows that have been deleted from the workflow library.

Develop a Simple Example Workflow on page 79

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

Develop a Complex Workflow on page 102

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.

Key Concepts of Workflows

Workflow Parameters

Workflows receive input parameters and generate output parameters when they run.

Chapter 1 Developing Workflows

Input Parameters

Most workflows require a certain set of input parameters to run. An input parameter is an argument that the workflow processes when it starts. The user, an application, another workflow, or an action passes input parameters to a workflow for the workflow to process when it starts.

For example, if a workflow resets a virtual machine, the workflow requires as an input parameter the name of the virtual machine.

Output Parameters

A workflow's output parameters represent the result from the workflow run. Output parameters can change when a workflow or a workflow element runs. While workflows run, they can receive the output parameters of other workflows as input parameters.

For example, if a workflow creates a snapshot of a virtual machine, the output parameter for the workflow is the resulting snapshot.

Workflow Attributes

Workflow elements process data that they receive as input parameters, and set the resulting data as workflow attributes or output parameters.

Read-only workflow attributes act as global constants for a workflow. Writable attributes act as a workflow’s global variables.

You can use attributes to transfer data between the elements of a workflow. You can obtain attributes in the following ways:

Define attributes when you create a workflow

Set the output parameter of a workflow element as a workflow attribute

Inherit attributes from a configuration element

VMware, Inc. 11

Developing with VMware vCenter Orchestrator

Workflow Schema

A workflow schema is a graphical representation that shows the workflow as a flow diagram of interconnected workflow elements. The workflow schema is the most important element of a workflow as it determines its logic.

Workflow Presentation

When users run a workflow, they provide the values for the input parameters of the workflow in the workflow presentation. When you organize the workflow presentation, consider the type and number of input parameters of the workflow.

Workflow Tokens

A workflow token represents a workflow that is running or has run.

A workflow is an abstract description of a process that defines a generic sequence of steps and a generic set of required input parameters. When you run a workflow with a set of real input parameters, you receive an instance of this abstract workflow that behaves according to the specific input parameters you give it. This specific instance of a completed or a running workflow is called a workflow token.

Workflow Token Attributes

Workflow token attributes are the specific parameters with which a workflow token runs. The workflow token attributes are an aggregation of the workflow's global attributes and the specific input and output parameters with which you run the workflow token.

Phases in the Workflow Development Process

Generally, you develop a workflow through the following phases.

1 Create a new workflow or create a duplicate of an existing workflow from the standard library.

2 Provide general information about the workflow.

3 Define the input parameters of the workflow.

4 Lay out and link the workflow schema to define the logical flow of the workflow.

5 Bind the input and output parameters of each schema element to workflow attributes.

6 Write the necessary scripts for scriptable task elements or custom decision elements.

7 Create the workflow presentation to define the layout of the input parameters dialog box that the users

see when they run the workflow.

8 Validate the workflow.

Access Rights for the Orchestrator Client

By default, only members of the Orchestrator administrator LDAP group can access the Orchestrator client.

The Orchestrator administrator can grant access to the Orchestrator client to other user groups by setting at least the View permission.

12 VMware, Inc.

To allow you to access the Orchestrator client, the administrator must either add you to the Orchestrator administrator LDAP group, or set View, Inspect, Edit, Execute, or Admin permissions to a group that you are a member of.

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.

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 Deselect the Validate workflow before running it check box.

You deactivated automatic workflow validation.

Chapter 1 Developing Workflows

Creating and Editing a Workflow

You create workflows in the Orchestrator client and edit them in the workflow editor. The workflow editor is the IDE of the Orchestrator client for developing workflows.

You open the workflow editor by editing an existing workflow.

Create a Workflow on page 13

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

Edit a Workflow on page 14

You edit a workflow to make changes to an existing workflow or to develop a new empty workflow.

Edit a Workflow from the Standard Library on page 14

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 15

The workflow editor consists of tabs on which you edit the components of the workflows.

Create a Workflow

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

Procedure

1 Click the Workflows view.

2 (Optional) Right-click the root of the workflows hierarchical list, or a folder in the list, and select Add

folder to create a new workflow folder.

3 (Optional) Type the name of 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.

A new empty workflow is created in the folder that you chose.

VMware, Inc. 13

Developing with VMware vCenter Orchestrator

What to do next

You can edit the workflow.

Edit a Workflow

You edit a workflow to make changes to an existing workflow or to develop a new empty workflow.

Procedure

1 Click the Workflows view.

2 Expand the workflows hierarchical list to navigate to the workflow that you want to edit.

3 To open the workflow for editing, right-click the workflow and select Edit.

The workflow editor opens the workflow for editing.

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, you must create a duplicate of that workflow. You can edit duplicate workflows or custom workflows.

Procedure

1 Click the Workflows view.

2 (Optional) Right-click the root of the hierarchical list of workflow folders and select New folder to

create a folder to contain the workflow to edit.

3 Expand the Library hierarchical list of standard workflows to navigate to the workflow to edit.

4 Right-click the workflow to edit.

The Edit option is dimmed. The workflow is read-only.

5 Right-click the workflow and select Duplicate workflow.

6 Provide a name for the duplicate workflow.

By default, Orchestrator names the duplicate workflow Copy of workflow_name.

7 Click the Workflow folder 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.

14 VMware, Inc.

Chapter 1 Developing Workflows

Workflow Editor Tabs

The workflow editor consists of tabs on which you edit the components of the workflows.

Table 1‑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 Define 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 References View 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.

Workflow Tokens View details about each workflow run. 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.

Events View information about each individual event that 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.

Permissions Set the permissions to interact with the workflow for users

or groups of users.

Provide General Workflow Information

Prerequisites

Open a workflow for editing in the workflow editor.

VMware, Inc. 15

Developing with VMware vCenter Orchestrator

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.

A new version of the workflow is created. You can later revert the state of the workflow to this version.

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 run to make the workflow resume at the point at

which its run was interrupted when the server stopped.

Click Resume workflow run and select Do not resume workflow run (set as FAILED) to prevent

the workflow from restarting if the Orchestrator server restarts.

Prevent the workflow from restarting if the workflow depends on the environment in which it runs. For example, if a workflow requires a specific vCenter Server and you reconfigure Orchestrator to connect to a different vCenter Server, restarting the workflow after you restart the Orchestrator server causes the workflow to fail.

5 Type a detailed description of the workflow in the Description text box.

6 Click Save at the bottom of the workflow editor.

A green message at the bottom left of the workflow editor confirms that you saved your changes.

You defined aspects of the workflow behavior, set the version, and defined the operations that users can perform on the workflow.

What to do next

You must define the workflow attributes and parameters.

Defining Attributes and Parameters

After you create a workflow, you must define the global attributes, input parameters, and output parameters of the workflow.

Workflow attributes store data that workflows process internally. Workflow input parameters are data provided by an outside source, such as a user or another workflow. Workflow output parameters are data that the workflow delivers when it finishes its run.

Define Workflow Parameters on page 17

You can use input and output parameters to pass data into and out of the workflow.

Define Workflow Attributes on page 17

Workflow attributes are the data that workflows process.

Attribute and Parameter Naming Restrictions on page 18

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.

16 VMware, Inc.

Chapter 1 Developing Workflows

Define Workflow Parameters

You can use input and output parameters to pass data into and out of the workflow.

You can define the parameters of a workflow in the workflow editor. The input parameters are the initial data that the workflow requires to run. Users provide the values for the input parameters when they run the workflow. The output parameters are the data the workflow returns when it completes its run.

Prerequisites

Open a workflow for editing in the workflow editor.

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 inside the parameters tab and select Add parameter.

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 (Optional) To change the value of the parameter type, click the value and select one from the list of

available values.

The value for the parameter type is String by default.

5 Add a description for the parameter in the Description text box.

6 (Optional) If you 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.

Define Workflow Attributes

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

Open a workflow for editing in the workflow editor.

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.

VMware, Inc. 17

Developing with VMware vCenter Orchestrator

3 Click the attribute name to change it.

The default name is attX, 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.

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.

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.

IMPORTANT The use of OGNL expressions in workflow presentations is deprecated as of Orchestrator 4.1. Using OGNL expressions in workflow presentations is not supported in releases of Orchestrator later than

4.1.

You cannot use the following keywords in workflow attribute and parameter names.

18 VMware, Inc.

Chapter 1 Developing Workflows

Table 1‑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

View Workflow Schema on page 20

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

Building a Workflow in the Workflow Schema on page 20

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 23

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

Schema Element Properties on page 26

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

Links and Bindings on page 29

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 34

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

Exception Handling on page 37

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

Developing with VMware vCenter Orchestrator

Foreach Elements and Composite Types on page 38

You can insert a Foreach element in the workflow that you develop to run a subworkflow that iterates over arrays of parameters or attributes. To improve the understanding and readability of the workflow, you can group several workflow parameters of different types that are logically connected in a single type that is called a composite type.

View Workflow Schema

You view the schema of a workflow 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 that define the logical flow of the workflow.

By default, all elements in the workflow schema are linked. Links between the elements are represented as arrows. When you add a new element to the workflow schema, you must drag it onto an arrow or an existing workflow element that is not linked to a next element. After you add workflow elements to the schema, you can delete existing links and create new links to define the logical flow of the workflow.

You can copy an element or a selection of elements from the schema of an existing workflow to the schema of the workflow that you are editing. See “Copy Workflow Schema Elements,” on page 21.

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 Drag a schema element from the Generic menu in the left pane, to the workflow schema.

3 Double-click the element you dragged to the workflow schema, type an appropriate name, and press

Enter.

You must provide elements with unique names in the context of the workflow.

You cannot rename Waiting timer, Waiting event, End workflow, or Throw exception elements.

4 (Optional) Right-click an element in the schema and select Copy.

20 VMware, Inc.

Chapter 1 Developing Workflows

5 (Optional) 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.

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

7 Drag schema elements from the Generic menu to the workflow schema.

When you drag actions or workflows to the workflow schema, a dialog box in which you can search for the action or workflow to insert appears.

8 In the Filter text box, 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.

9 Double-click a workflow or action to select it.

You inserted the workflow or action in the workflow schema.

10 Repeat this procedure until you have added all of the required schema elements to 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.

Copy Workflow Schema Elements

You can copy an element or a selection of elements from the schema of an existing workflow to the schema of the workflow that you are editing.

Prerequisites

Open a workflow for editing in the workflow editor.

Procedure

1 Click the Schema tab in the workflow editor.

2 From the left pane, select the workflow from which you want to copy schema elements.

Click All Workflows and select the workflow from the hierarchical list of workflows.

Type the name of the workflow in the search text box and press Enter.

3 Right-click the selected workflow and select Open.

A window displaying the workflow's properties appears.

4 In the workflow's window, click the Schema tab.

5 Select one or more workflow schema elements, right-click the selection, and select Copy.

6 In the Schema tab of the workflow that you are editing, right-click and select Paste.

You copied workflow schema elements from one workflow to another.

What to do next

You must link and bind the copied schema elements to the existing workflow schema.

VMware, Inc. 21

Developing with VMware vCenter Orchestrator

Promote Input and Output Parameters

You can promote the input and output parameters of a child element to the parent workflow.

You can promote a custom attribute that you have defined on the General tab of the workflow editor. You can promote predefined attributes only by replacing an input parameter with an attribute of matching type.

NOTE If you promote a predefined attribute and assign a custom value to it, a duplicate attribute is created to avoid overwriting the value of the original attribute. The duplicate attribute retains the name of the original attribute and increments the numerical value at the end of the attribute's name.

Prerequisites

Open a workflow for editing in the workflow editor.

Procedure

1 Click the Schema tab in the workflow editor.

2 Add a workflow or an action element to the workflow schema.

The following notification appears at the top of the schema pane.

Do you want to add the activity's parameters as input/output to the current workflow?

3 On the notification, click Setup.

A pop-up window with the available options appears.

4 Select the mapping type for each input parameter.

Option Description

Input

Skip

Value

The argument is mapped to an input workflow parameter.

The argument is mapped to a NULL value.

The argument is mapped to an attribute with a value that you can set from the Value column.

5 Select the mapping type for each output parameter.

Option Description

Output

Skip

Local variable

The argument is mapped to an output workflow parameter.

The argument is mapped to a NULL value.

The argument is mapped to an attribute.

6 Click Promote.

You promoted parameters to the parent workflow.

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.

22 VMware, Inc.

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.

You can use the schema elements available in the Schema tab to build a workflow.

Table 1‑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.

Chapter 1 Developing Workflows

Location in Workflow Editor

Always present in the

Schema tab

Generic workflow palette

Decision Boolean function. Decision elements take

one input parameter and return either true or false. The type of decision that 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.

Custom decision Boolean function. Custom decisions can

take several input parameters and process them according to custom scripts. Returns either true or false.

Decision activity Boolean function. A decision activity runs a

workflow and binds its output parameters to a true or a false path.

Generic workflow palette

VMware, Inc. 23

Developing with VMware vCenter Orchestrator

Table 1‑3. Schema Elements and Icons (Continued)

Schema Element Name Description Icon

User interaction Allows users to pass new input parameters

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.

Waiting timer Used by long-running workflows. When a

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.

Waiting event Used in long-running workflows. When a

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.

End workflow The end point of the workflow. You can

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

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.

Location in Workflow Editor

Generic workflow palette

24 VMware, Inc.

Table 1‑3. Schema Elements and Icons (Continued)

Schema Element Name Description Icon

Action element Calls on an action from the Orchestrator

libraries of actions. When a workflow reaches an action element, it calls and runs that action.

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

Foreach element Runs a workflow on every element from an

array. For example, you can run the Raname Virtual Machine workflow on all virtual machines from a folder.

Asynchronous workflow

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.

Schedule workflow Creates a task to run the workflow at a set

time, then the workflow continues its run.

Chapter 1 Developing Workflows

Location in Workflow Editor

Generic workflow palette

VMware, Inc. 25

Developing with VMware vCenter Orchestrator

Table 1‑3. Schema Elements and Icons (Continued)

Schema Element Name Description Icon

Nested workflows Starts several workflows simultaneously.

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.

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

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

Location in Workflow Editor

Generic workflow palette

Basic, Log, and Network

workflow palette

Schema Element Properties

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

Edit the Global Properties of a Schema Element

You define the global properties of a schema element in the element's Info tab.

Prerequisites

Verify that the Schema tab of the workflow editor contains elements.

Procedure

1 Click the Schema tab in the workflow editor.

Select an element to edit by clicking the Edit icon ( ).

A dialog box that lists the properties of the element appears.

3 Click the Info tab.

26 VMware, Inc.

Chapter 1 Developing Workflows

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 From the Interaction drop-down menu, select a description.

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

7 (Optional) In the Description text box, type a description of the schema element.

Schema Element Properties Tabs

You access the properties of a schema element by clicking on an element that you have dragged into the workflow schema. The properties of the element appear in tabs at the bottom of the workflow editor.

Different schema elements have different properties tabs.

Table 1‑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.

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

VMware, Inc. 27

Developing with VMware vCenter Orchestrator

Table 1‑4. Properties Tabs per Schema Element (Continued)

Schema Element Property Tab Description Applies to Schema Element Type

IN The IN binding for this

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

element. The IN binding defines the way in which the schema element receives input from the element that precedes it in the workflow.

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

Predefined Task

Schedule Workflow

Scriptable Task

Workflow

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

28 VMware, Inc.

Chapter 1 Developing Workflows

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.

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 as expected. The exception path is the path that the workflow takes through the logical flow if an element does not run as expected.

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

A blue 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 red dashed arrow denotes the exception path that the workflow takes if a workflow element does not

run correctly.

The following figure shows an example workflow schema that demonstrates the different paths that workflows can take.

Figure 1‑1. Different Workflow Paths Through the Logical Flow of the Workflow

VMware, Inc. 29

Developing with VMware vCenter Orchestrator

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.

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

Standard path links determine the normal run of the workflow.

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

Open a workflow for editing in the workflow editor.

30 VMware, Inc.

+ 130 hidden pages