VMware vCenter Orchestrator - 4.2.1 User Manual

Developing with VMware vCenter

Orchestrator

vCenter Orchestrator 4.2.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-000854-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

Copyright © 2008–2012 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.

Developing with VMware vCenter Orchestrator 7

Developing Workflows 9

Principal Phases in the Workflow Development Process 10

Accessing the Orchestrator Client 11

Testing Workflows During Development 11

Workflow Editor 11

Create a Workflow 12

Edit a Workflow 12

Edit a Workflow from the Standard Library 12

Workflow Editor Tabs 13

Provide General Workflow Information 14

Defining Attributes and Parameters 15

Define Workflow Attributes 15

Define Workflow Parameters 16

Attribute and Parameter Naming Restrictions 16

Workflow Schema 17

View Workflow Schema 18

Building a Workflow in the Workflow Schema 18

Schema Elements 19

Schema Element Properties 22

Links and Bindings 24

Decisions 29

Exception Handling 31

Obtaining Input Parameters from Users When a Workflow Starts 33

Creating the Input Parameters Dialog Box In the Presentation Tab 33

Setting Parameter Properties 35

Requesting User Interactions While a Workflow Runs 38

Add a User Interaction to a Workflow 39

Set the User Interaction security.group Attribute 39

Set the timeout.date Attribute to an Absolute Date 40

Calculate a Relative Timeout for User Interactions 41

Set the timeout.date Attribute to a Relative Date 42

Define the External Inputs for a User Interaction 43

Define User Interaction Exception Behavior 44

Create the Input Parameters Dialog Box for the User Interaction 45

Respond to a Request for a User Interaction 46

Calling Workflows Within Workflows 46

Workflow Elements that Call Workflows 47

Call a Workflow Synchronously 49

Call a Workflow Asynchronously 50

Schedule a Workflow 50

VMware, Inc.

Developing with VMware vCenter Orchestrator

Prerequisites for Calling a Remote Workflow from Within Another Workflow 51

Call Several Workflows Simultaneously 52

Running a Workflow on a Selection of Objects 53

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

Developing Long-Running Workflows 55

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

Create a Timer-Based Long-Running Workflow 56

Create a Trigger Object 57

Create a Trigger-Based Long-Running Workflow 59

Configuration Elements 60

Create a Configuration Element 60

Workflow User Permissions 61

Set User Permissions on a Workflow 61

Validating Workflows 62

Validate a Workflow and Fix Validation Errors 62

Running Workflows 63

Run a Workflow 64

Develop a Simple Example Workflow 65

Create the Simple Workflow Example 66

Define the Simple Workflow Example Parameters 67

Create the Simple Workflow Example Schema 68

Link the Simple Workflow Example Elements 69

Create Workflow Zones 71

Define the Simple Workflow Example Decision Bindings 72

Bind the Simple Workflow Example Action Elements 73

Bind the Simple Workflow Example Scripted Task Elements 75

Define the Simple Example Workflow Exception Bindings 82

Set the Simple Workflow Example Attribute Read-Write Properties 82

Set the Simple Workflow Example Parameter Properties 83

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

Validate and Run the Simple Workflow Example 85

Develop a Complex Workflow 86

Create the Complex Workflow 87

Define the Complex Workflow Example Input Parameters 88

Create a Custom Action For the Complex Workflow Example 88

Create the Complex Workflow Example Schema 89

Link the Complex Workflow Example Schema Elements 90

Create the Complex Workflow Example Zones 91

Define the Complex Workflow Example Bindings 92

Set the Complex Workflow Example Attribute Properties 102

Create the Layout of the Complex Workflow Example Input Parameters 102

Validate and Run the Complex Workflow Example 103

Scripting 105

Orchestrator Elements that Require Scripting 105

Limitations of the Mozilla Rhino Implementation in Orchestrator 106

Using the Orchestrator API 106

Access the Scripting Engine from the Workflow Editor 107

Access the Scripting Engine from the Action or Policy Editor 107

4 VMware, Inc.

Access the Orchestrator API Explorer 108

Use the Orchestrator API Explorer to Find Objects 108

Writing Scripts 109

Add Parameters to Scripts 110

Accessing the Orchestrator Server File System from JavaScript and Workflows 111

Accessing Java Classes from JavaScript 111

Accessing Operating System Commands from JavaScript 112

Exception Handling Guidelines 112

Orchestrator JavaScript Examples 113

Basic Scripting Examples 113

File System Scripting Examples 115

LDAP Scripting Examples 116

Logging Scripting Examples 116

Networking Scripting Examples 116

Workflow Scripting Examples 117

Contents

Developing Actions 119

Reusing Actions 119

Access the Actions View 119

Components of the Actions View 120

Creating Actions 120

Create an Action 120

Find Elements That Implement an Action 121

Action Coding Guidelines 121

Creating Resource Elements 123

View a Resource Element 123

Import an External Object to Use as a Resource Element 124

Edit the Resource Element Information and Access Rights 124

Save a Resource Element to a File 125

Update a Resource Element 125

Add a Resource Element to a Workflow 125

Add a Resource Element to a Web View 126

Creating Packages 129

Create a Package 129

Set User Permissions on a Package 130

Index 133

VMware, Inc. 5

Developing with VMware vCenter Orchestrator

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.

Principal Phases in the Workflow Development Process on page 10

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

Accessing the Orchestrator Client on page 11

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 11

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 11

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 14

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 15

After you create a workflow, you must determine the workflow's global attributes and input and output parameters.

Workflow Schema on page 17

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 33

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 38

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.

Developing with VMware vCenter Orchestrator

Calling Workflows Within Workflows on page 46

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 53

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 55

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 60

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 61

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 62

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 63

A workflow runs according to a logical flow of events.

Develop a Simple Example Workflow on page 65

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

Develop a Complex Workflow on page 86

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.

10 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 Administering VMware vCenter Orchestrator 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 1 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 Deselect the Validate workflow before running 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 12

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

Edit a Workflow on page 12

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

Edit a Workflow from the Standard Library on page 12

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 13

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

VMware, Inc. 11

Developing with VMware vCenter Orchestrator

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

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

12 VMware, Inc.

workflow_name

Chapter 1 Developing Workflows

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.

Workflow Editor Tabs

The workflow editor consists of tabs in 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 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.

Workflow Tokens 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. 13

Developing with VMware vCenter Orchestrator

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

14 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 15

Workflow attributes are the data that workflows process.

Define Workflow Parameters on page 16

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

Attribute and Parameter Naming Restrictions on page 16

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

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.

VMware, Inc. 15

Developing with VMware vCenter Orchestrator

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.

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.

16 VMware, Inc.

Chapter 1 Developing Workflows

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

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

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 18

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 18

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 19

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

Schema Element Properties on page 22

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

Links and Bindings on page 24

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 29

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

Exception Handling on page 31

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

Developing with VMware vCenter Orchestrator

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.

18 VMware, Inc.

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

The following table describes all of the schema elements from which you can build workflows.

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.

Icon Location in Workflow editor

Always present in the

Schema tab

Generic workflow palette

VMware, Inc. 19

Developing with VMware vCenter Orchestrator

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

Schema Element Name Description Icon

Decision Boolean function. Decision elements take

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.

Custom Decision Boolean function. Custom decisions can take

several input parameters and act upon them according to custom scripts. Returns either true or false.

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.

Icon Location in Workflow editor

Generic workflow palette

20 VMware, Inc.

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

Developing with VMware vCenter Orchestrator

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

22 VMware, Inc.

Chapter 1 Developing Workflows

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.

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

Developing with VMware vCenter Orchestrator

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

24 VMware, Inc.

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

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

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

Developing with VMware vCenter Orchestrator

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.

26 VMware, Inc.

Chapter 1 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 1-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 1-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. 27

Developing with VMware vCenter Orchestrator

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.

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.

28 VMware, Inc.

Chapter 1 Developing Workflows

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.

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.

VMware, Inc. 29

Developing with VMware vCenter Orchestrator

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.

if (

decision_statement

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.

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.

30 VMware, Inc.

+ 106 hidden pages