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.
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.
Contents Developing with VMware vCenter Orchestrator 7 1 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 Namin
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
Contents 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 Scripti
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.
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. n Principal Phases in the Workflow Development Process on page 10 The process for developing a workflow involves a series of phases. n Accessing the Orchestrator Client on page 11 By default, all Orchestrator users can access the Orchestrator client.
Developing with VMware vCenter Orchestrator n 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.
Chapter 1 Developing Workflows Accessing the Orchestrator Client By default, all Orchestrator users can access the Orchestrator client. However, for security reasons, the Orchestrator administrator can limit access to the Orchestrator client to members of the Orchestrator administrator LDAP group. If the Orchestrator administrator has limited the access to the client and if you are not a member of the Orchestrator administrator group, you cannot log in to the Orchestrator client.
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.
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. No The version of the duplicate reverts to 0.0.0.
Developing with VMware vCenter Orchestrator Table 1-1. Workflow Editor Tabs (Continued) Tab Description Events Provides 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 Sets the permissions to interact with the workflow for users or groups of users.
Chapter 1 Developing Workflows 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.
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.
Chapter 1 Developing Workflows You cannot use the following keywords in workflow attribute and parameter names. Table 1-2.
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.
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.
Developing with VMware vCenter Orchestrator Table 1-3. Schema Elements and Icons (Continued) Schema Element Name 20 Description Icon Icon Location in Workflow editor 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.
Chapter 1 Developing Workflows Table 1-3. Schema Elements and Icons (Continued) Schema Element Name Description Icon Icon Location in Workflow editor 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.
Developing with VMware vCenter Orchestrator Table 1-3. Schema Elements and Icons (Continued) Schema Element Name Description Icon Icon Location in Workflow editor Asynchronous Workflows 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.
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.
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 properties and description. The information the Info tab displays depends on the type of schema element.
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.
Developing with VMware vCenter Orchestrator n n 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.
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.
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.
Chapter 1 Developing Workflows 2 Click the IN tab. The contents of the IN tab depend on the type of element you selected. 3 n 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.
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.
Chapter 1 Developing Workflows What to do next The decision element is linked to two other elements, but you did not define how the workflow determines which path to take. You must define the decision statement. Create Workflow Branches Using Decisions Decision elements are simple Boolean functions that you use to create branches in workflows. Decision elements determine whether or not the input received matches the decision statement you set.
Developing with VMware vCenter Orchestrator Exceptions act as a try and catch sequence within a workflow element. If you do not need to handle a given exception in an element, you do not have to bind that element's exception output parameter. The output parameter type for exceptions is always an errorCode object. Create Exception Bindings Elements can set bindings that define how the workflow behaves if it encounters an error in that element.
Chapter 1 Developing Workflows Obtaining Input Parameters from Users When a Workflow Starts 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.
Developing with VMware vCenter Orchestrator Create the Presentation of the Input Parameters Dialog Box You create the presentation of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab in the workflow editor. Prerequisites You must have created a workflow and a defined list of input parameters. Procedure 1 In the workflow editor, click the Presentation tab.
Chapter 1 Developing Workflows Setting Parameter Properties Orchestrator allows you to define properties to qualify the input parameter values that users provide when they run workflows. The parameter properties you define impose limits on the types and values of the input parameters the users provide. Every parameter can have several properties. You define an input parameter's properties in the Properties tab for a given parameter in the Presentation tab.
Developing with VMware vCenter Orchestrator 6 Under Value, make the property value either static or dynamic by selecting the corresponding symbol from the drop-down menu. Option Description Static property Dynamic property 7 If you set the property value to static, you select a property value according to the type of parameter for which you are setting the properties.
Chapter 1 Developing Workflows Table 1-5. Workflow Input Parameter Properties (Continued) Parameter Property Parameter Type Description Predefined answers All simple types Pre-defines a list of possible values for the property as an array of simple types. You either define the array manually or the property calls an action that returns an array of objects of the appropriate type.
Developing with VMware vCenter Orchestrator Table 1-6. Predefined OGNL Constant Values Constant Value Description ${#__current} Current value of the custom validation property or matching expression property ${#__username} User name of the user who started the workflow ${#__userdisplayname} Display name of the user who started the workflow ${#__serverurl} URL containing the IP address of the server from which the user starts the workflow.
Chapter 1 Developing Workflows 6 Define the External Inputs for a User Interaction on page 43 You specify the information that users must provide during a workflow run as the input parameters of a user interaction. 7 Define User Interaction Exception Behavior on page 44 If a user does not provide the input parameters within the timeout period, the user interaction returns an exception. You can define the exception behavior in a scripted function.
Developing with VMware vCenter Orchestrator n Identify an LDAP user group to respond to the user interaction request. Procedure 1 Click the User Interaction element in the workflow schema. 2 Click the Attributes tab for the user interaction. 3 Click Not set for the security.group source parameter to set which users can respond to the user interaction. 4 (Optional) Select NULL to allow all users to respond to the request for user interaction.
Chapter 1 Developing Workflows Procedure 1 Click the User Interaction element in the workflow schema. 2 Click the Attributes tab for the user interaction. 3 Click Not set for the timeout.date source parameter to set the timeout parameter value. 4 (Optional) Select NULL to allow the user interaction to set the workflow to wait indefinitely for the user to respond to the user interaction. 5 Click Create parameter/attribute in workflow to set the workflow to fail after a timeout period.
Developing with VMware vCenter Orchestrator 6 Click Create parameter/attribute in workflow to create a workflow attribute. a Name the attribute timerDate. b Select Date from the list of attribute types. c Select Create workflow ATTRIBUTE with the same name. d Leave the attribute value set to Not set, because a scripted function will provide this value. e Click OK. 7 Click the Scripting tab for the scripted workflow element.
Chapter 1 Developing Workflows 3 Click Not set for the timeout.date source parameter to set the timeout parameter value. 4 Select the Date object that encapsulates a relative time and date that you defined in a scripted function and click Select. You set the timeout.date attribute to a relative date and time that a scripted function calculates. What to do next Define the external input parameters that the user interaction requires from the user.
Developing with VMware vCenter Orchestrator Define User Interaction Exception Behavior If a user does not provide the input parameters within the timeout period, the user interaction returns an exception. You can define the exception behavior in a scripted function. If you do not define the action for the workflow to take if the user interaction times out, the workflow ends in the Failed state. Defining the exception behavior is a good workflow development practice.
Chapter 1 Developing Workflows What to do next Create the dialog box in which users provide input parameters. See “Create the Input Parameters Dialog Box for the User Interaction,” on page 45. Create the Input Parameters Dialog Box for the User Interaction Users provide input parameters during a workflow run in an input parameters dialog box, in the same way that they provide input parameters when a workflow first starts.
Developing with VMware vCenter Orchestrator Respond to a Request for a User Interaction Workflows that require interactions from users during their run suspend their run either until the user provides the required information or until the workflow times out. Workflows that require user interactions define which users can provide the required information and direct the requests for interaction. Prerequisites Log in to the Orchestrator client. At least one workflow in Waiting for User Interaction state.
Chapter 1 Developing Workflows n Prerequisites for Calling a Remote Workflow from Within Another Workflow on page 51 If the workflow that you develop calls another workflow that resides on a remote Orchestrator server, certain prerequisites must be fulfilled so that the remote workflow can run successfully. n Call Several Workflows Simultaneously on page 52 Calling several workflows simultaneously runs the called workflows synchronously as part of the run of the calling workflow.
Developing with VMware vCenter Orchestrator Scheduled workflows only run once. You can schedule a workflow to run recurrently by calling the Workflow.scheduleRecurrently method in a scriptable task element in a synchronous workflow. Nested Workflows A workflow can start several workflows simultaneously by nesting several workflows in a single schema element.
Chapter 1 Developing Workflows Propagate the Input Parameters and Presentation of a Child Workflow to the Parent Workflow If you develop a workflow that calls other workflows, you can propagate the input parameters and the presentation of the child workflows to the parent workflow. Procedure 1 Right-click the workflow that you want to modify and select Edit. The workflow editor opens. 2 Select the Schema tab.
Developing with VMware vCenter Orchestrator You called a workflow synchronously from another workflow. When the workflow reaches the synchronous workflow during its run, the synchronous workflow starts, and the initial workflow waits for it to complete before continuing its run. What to do next You can call a workflow asynchronously from a workflow. Call a Workflow Asynchronously Calling a workflow asynchronously runs the called workflow independently of the calling workflow.
Chapter 1 Developing Workflows Prerequisites Create a workflow, open it for editing in the workflow editor, and add some elements to the workflow schema. Procedure 1 Drag a Schedule Workflow element from the Action & Workflow menu to the appropriate position in the workflow schema. 2 Search for the workflow to call by typing part of its name in the text box. 3 Select the workflow from the list and click OK.
Developing with VMware vCenter Orchestrator Orchestrator server. Because the Rename virtual machine workflow runs on the remote Orchestrator server, the same virtual machine must be available in the inventory of that server. Otherwise, the Rename virtual machine workflow cannot resolve its vm input parameter. Therefore, the vCenter Server plug-in on the local and the remote Orchestrator servers must be connected to the same vCenter Server instance.
Chapter 1 Developing Workflows 11 Repeat Step 2 to Step 9 to define the settings for each of the workflows you add. 12 Click the nested workflow element in the workflow schema. The number of workflows nested in the element appears as a numeral on the nested workflows element. You called several workflows simultaneously from a workflow. What to do next You can define long-running workflows.
Developing with VMware vCenter Orchestrator Implement the Start Workflows in a Series and Start Workflows in Parallel Workflows You can use the Start workflows in a series and Start workflows in parallel workflows to run a workflow on a selection of objects. You cannot run the Start workflows in a series and Start workflows in parallel workflows directly. You must include them in another workflow that you create.
Chapter 1 Developing Workflows 7 Bind the wf input of the Start workflows in a series or Start workflows in parallel workflow to the workflow to run on the objects. For example, to remove any snapshots of all the virtual machines returned by the getAllVirtualMachinesByFolder action, select the Remove all snapshots workflow.
Developing with VMware vCenter Orchestrator 2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema. 3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab. 4 Provide a name and description for the scripted workflow element in the Info properties tab. 5 Right-click in the OUT properties tab, and select Bind to workflow parameter/attribute.
Chapter 1 Developing Workflows Procedure 1 Drag a Waiting Timer element from the Generic menu to the position in the workflow schema at which to suspend the workflow's run. 2 Link the Waiting Timer element to the elements that precede and follow it in the workflow schema. If you implement a scriptable task to calculate the time and date, this element must precede the Waiting Timer element. 3 Click the Waiting Timer element to show its properties tabs in the bottom half of the Schema tab.
Developing with VMware vCenter Orchestrator You create a Trigger object in a JavaScript function in a Scriptable Task element. This Scriptable Task element can be part of the trigger-based long-running workflow that waits for the trigger event. Alternatively, it can be part of a different workflow that provides input parameters to the trigger-based long-running workflow. The trigger function must implement the createEndOfTaskTrigger() method from the Orchestrator API.
Chapter 1 Developing Workflows You defined a workflow element that creates a trigger event for a trigger-based long-running workflow. The trigger element generates a Trigger object as its output parameter, to which a Waiting Event element can bind. What to do next You must bind this trigger event to a Waiting Event element in a trigger-based long-running workflow.
Developing with VMware vCenter Orchestrator Configuration Elements A configuration element is a list of attributes you can use to configure constants across a whole Orchestrator server deployment. All the workflows, actions, policies, and Web views running in a particular Orchestrator server can use the attributes you set in a configuration element.
Chapter 1 Developing Workflows 15 Check the appropriate check boxes to set the access rights for the selected user group. You can set the following permissions on the configuration element. 16 Permission Description View Users can view the configuration element, but cannot view the schemas or scripting. Inspect Users can view the configuration element, including the schemas and scripting. Execute Users can run the elements in the configuration element.
Developing with VMware vCenter Orchestrator 2 Click the Add access rights link to define permissions for a new user or user group. 3 Search for a user or user group. The search results show all of the users and user groups from the Orchestrator LDAP server that match the search. 4 Select a user or user group and click OK. 5 Right-click the user and select Add access rights. 6 Check the appropriate check boxes to set the level of permissions for this user and click OK.
Chapter 1 Developing Workflows 7 Click the Validate button in the Schema tab toolbar. If the workflow is valid, a confirmation message appears. If the workflow is invalid, a list of errors appears. 8 If the workflow is invalid, click on an error message. The validation tool highlights the schema element in which the error occurs by adding a red icon to it. Where possible, the validation tool proposes a Quick fix action. n If you agree with the proposed Quick fix action, click it to perform that action.
Developing with VMware vCenter Orchestrator Run a Workflow You can perform automated operations in vCenter Server by running workflows from the standard library or workflows that you create. For example, you can create a virtual machine by running the Create simple virtual machine workflow. Prerequisites You must have configured the vCenter plug-in. For details, see Installing and Configuring VMware vCenter Orchestrator. Procedure 1 Click the Workflows view in the Orchestrator client.
Chapter 1 Developing Workflows 9 Navigate through the vCenter Server infrastructure hierarchy to the resource pool you defined. If the virtual machine does not appear in the list, click the refresh button to reload the inventory. The orchestrator-test virtual machine is present in the resource pool. 10 (Optional) Right-click the orchestrator-test virtual machine in the Inventory view to see a contextual list of the workflows that you can run on the orchestrator-test virtual machine.
Developing with VMware vCenter Orchestrator 3 Create the Simple Workflow Example Schema on page 68 You create a workflow schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs. 4 Link the Simple Workflow Example Elements on page 69 You link a workflow's elements in the Schema tab of the workflow editor. The linking defines the flow of data through the workflow.
Chapter 1 Developing Workflows n A valid email address For information about how to install and configure vCenter, see vSphere Installation and Setup. For information about how to configure Orchestrator to use an SMTP server, see Installing and Configuring VMware vCenter Orchestrator. To write a workflow, you must have an Orchestrator user account with at least View, Execute, Inspect, Edit, and preferably Admin permissions on the server or on the workflow folder in which you are working.
Developing with VMware vCenter Orchestrator 3 Click arg_in_0. 4 Type the name vm in the Choose Attribute Name dialog box and click OK. 5 Click the Type text box and type vc:virtualm in the search text box in the parameter type dialog box. 6 Select VC:VirtualMachine from the proposed list of parameter types and click Accept. 7 Add a description of the parameter in the description text box. For example, type The virtual machine to power on.
Chapter 1 Developing Workflows 9 Click the Generic menu and drag a scriptable task element under the vim3WaitToolsStarted action element. 10 Double-click the scriptable task element and rename it OK. 11 Drag another scriptable task element to the left of the startVM action element. Name this scripted element Already started. 12 Drag more scripted elements into the schema, as follows. n Drag a scripted element to the right of startVM and name it startVM failed.
Developing with VMware vCenter Orchestrator 3 Link the remaining elements as described in the following table. Table 1-7.
Chapter 1 Developing Workflows Figure 1-4. Linking the Elements of the Start VM and Send Email Example Workflow What to do next You can highlight different zones in the workflow. Create Workflow Zones You can emphasize different zones in workflow by adding workflow notes of different colors. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.
Developing with VMware vCenter Orchestrator Figure 1-5. Start VM and Send Email Example Workflow Zones What to do next Define the bindings between the element parameters. Define the Simple Workflow Example Decision Bindings You bind a workflow's elements together in the Schema tab of the workflow editor.
Chapter 1 Developing Workflows Bind the Simple Workflow Example Action Elements You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the action elements process input parameters and generate output parameters. Prerequisites You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements together. Procedure 1 Click the startVM action element.
Developing with VMware vCenter Orchestrator The action elements' input and output parameters are bound to the appropriate parameter types and values. What to do next Bind the scriptable task elements and define their functions. Simple Workflow Example Action Element Bindings Bindings define how the simple workflow example's action elements process input and output parameters. When defining bindings, Orchestrator presents parameters you have already defined in the workflow as candidates for binding.
Chapter 1 Developing Workflows vim3WaitToolsStarted Action The vim3WaitToolsStarted action element waits until VMware Tools have installed on a virtual machine, and defines a polling rate and a timeout period. The following table shows the input parameter bindings the vim3WaitToolsStarted action requires. The vim3WaitToolsStarted action element has no output, so requires no output binding. Table 1-9.
Developing with VMware vCenter Orchestrator 2 Set the following general information in the Info tab. Interaction No external interaction Color None Business status Check the check box and add the text VM already powered on. Description Leave the text The VM is already powered on, bypassing startVM and waitTaskEnd, checking if the VM tools are up and running. 3 Click the IN tab in the schema element properties pane at the bottom of the Schema tab.
Chapter 1 Developing Workflows Table 1-10. Bindings of the Start VM Failed Scriptable Task Element Parameter Name Binding Type Bind to Existing or Create Parameter? vm IN Bind errorCode IN Create Binding Values n Local Parameter: vm n Source parameter: vm[inparameter] n Type: VC:VirtualMachine n Description: The virtual machine to power on. n Local Parameter: errorCode n Source parameter: errorCode[attribute] n Type: string Description: Catch any exceptions while powering on a VM.
Developing with VMware vCenter Orchestrator Table 1-11. Bindings of the Timeout 1 Scriptable Task Element Parameter Name Binding Type Bind to Existing or Create Parameter? vm IN Bind errorCode IN Bind Binding Values n Local Parameter: vm n Source parameter: vm[inparameter] n Type: VC:VirtualMachine n Description: The virtual machine to start. n Local Parameter: errorCode n Source parameter: errorCode[attribute] n Type: string Description: Catch any exceptions while powering on a VM.
Chapter 1 Developing Workflows Table 1-12. Bindings of the Timeout 2 Scriptable Task Element Parameter Name Binding Type Bind to Existing or Create Parameter? vm IN Bind errorCode IN Bind Binding Values n Local Parameter: vm n Source parameter: vm[inparameter] n Type: VC:VirtualMachine n Description: The virtual machine to power on. n Local Parameter: errorCode n Source parameter: errorCode[attribute] n Type: string Description: Catch any exceptions while powering on a VM.
Developing with VMware vCenter Orchestrator The OK scriptable task element requires the following scripted function. body = "The VM '"+vm.name+"' has started successfully and is ready for use"; //Writes the following event in the vCO database Server.log(body); Send Email Failed Scriptable Task Element The Send Email Failed scriptable task element receives notice that the sending of the email failed, and writes the event in the Orchestrator log.
Chapter 1 Developing Workflows Table 1-15. Bindings of the Send Email Scriptable Task Element Parameter Name Binding Type Bind to Existing or Create Parameter? vm IN Bind toAddress IN Bind Binding Values n Local Parameter: vm n Source parameter: vm[inparameter] n Type: VC:VirtualMachine n Description: The virtual machine to power on.
Developing with VMware vCenter Orchestrator //Apply the method that sends the email message myEmailMessage.sendMessage(); System.log("Sent email to '"+toAddress+"'"); Define the Simple Example Workflow Exception Bindings You define exception bindings in the Schema tab in the workflow editor. Exception bindings define how elements process errors. The following elements in the workflow return exceptions: startVM, vim3WaitTaskEnd, Send Email, and vim3WaitToolsStarted.
Chapter 1 Developing Workflows 2 Check the check boxes to make the following attributes read-only constants: n progress n pollRate n timeout n smtpHost n fromAddress n subject You have defined which of the workflow's attributes are constants and which are variables. What to do next You must set the parameter properties and place constraints on the possible values for that parameter.
Developing with VMware vCenter Orchestrator 12 Add a description in the Description tab in the bottom half of the screen. For example, type The email address of the person to notify. 13 Click the Properties tab for (string)toAddress. 14 Right-click the Properties tab and select Add Property > Mandatory input. 15 Set the value of the Mandatory input property to Yes. 16 Right-click the Properties tab and select Add Property > Matching regular expression.
Chapter 1 Developing Workflows 5 Provide a description of the Virtual Machine display group in the Description text box in the General tab at the bottom of the Presentation tab. For example, type Select the virtual machine to start. The text you enter here appears as a prompt in the input parameter dialog box when users start the workflow. 6 Drag the (VC:VirtualMachine)vm parameter under the Virtual Machine display group.
Developing with VMware vCenter Orchestrator 9 Click the workflow token to follow the progress of the workflow as it runs. If the workflow ran successfully, the virtual machine you identified is in the powered-on state, and the email recipient you defined receives a confirmation email. Develop a Complex Workflow Developing a complex example workflow demonstrates the most common steps in the workflow development process and more advanced scenarios, such as creating custom decisions and loops.
Chapter 1 Developing Workflows 6 Create the Complex Workflow Example Zones on page 91 Optionally, you can highlight different zones of the workflow by adding workflow notes. Creating different workflow zones helps to make complicated workflow schema easier to read and understand. 7 Define the Complex Workflow Example Bindings on page 92 You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define the data flow of the workflow.
Developing with VMware vCenter Orchestrator Define the Complex Workflow Example Input Parameters You define workflow input parameters in the workflow editor. The input parameters provide data for the workflow to process. Prerequisites You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, and opened it for editing in the workflow editor. Procedure 1 Click the Inputs tab in the workflow editor. 2 Define the following input parameter.
Chapter 1 Developing Workflows 9 Add the following description of the action in the General tab. This action returns an array containing the disk modes of all disks on a VM. The elements in the array each have one of the following string values: - persistent - independent-persistent - nonpersistent - independent-nonpersistent Legacy values: - undoable - append 10 Click the Scripting tab.
Developing with VMware vCenter Orchestrator 3 Add the following schema elements to the workflow schema. Table 1-16.
Chapter 1 Developing Workflows 2 Create the following links between the elements in the schema. Table 1-17.
Developing with VMware vCenter Orchestrator Procedure 1 2 Create the following workflow zones by using workflow notes. Elements in Zone Description Start element; Initialize scriptable task; VMs to Process? custom decision Get an array of virtual machines from a resource pool, initialize the counter of the Array and set the first virtual machine to be treated, if any. Pool has no VMs scriptable task. Resource pool contains no virtual machines of which to take snapshots.
Chapter 1 Developing Workflows All the elements' input and output parameters are bound to the appropriate parameter types and values. What to do next You must set the attribute properties. Complex Workflow Example Bindings Bindings define how the simple workflow example's action elements process input and output parameters. The Take Snapshots of All Virtual Machines in a Resource Pool workflow requires the following input and output parameter bindings.
Developing with VMware vCenter Orchestrator Table 1-18.
Chapter 1 Developing Workflows Pool Has No VMs Scriptable Task Element The Pool Has No VMs scriptable task element logs the fact that the resource pool contains no eligible virtual machines in the Orchestrator database. The following table shows the bindings that the Pool Has No VMs scriptable task element requires. Table 1-20.
Developing with VMware vCenter Orchestrator getVMDisksModes Action Element The getVMDisksModes action element obtains the modes of the disks running in a virtual machine. The following table shows the bindings that the getVMDisksModes action element requires. Table 1-22.
Chapter 1 Developing Workflows if (vmDisksModes[i].charAt(0)=="i") { containsIndependentDisks = true; } } } else { //if no disk found no need to try to snapshot the VM System.warn("Won't snapshot '"+vm.name+"', no disks found"); return false; } if (containsIndependentDisks) { System.warn("Won't snapshot '"+vm.name+"', independent disk(s) found"); return false; } else { System.log("Snapshoting '"+vm.
Developing with VMware vCenter Orchestrator Table 1-24. Bindings of the Create a snapshot Workflow Element (Continued) Parameter Name Binding Type Bind to Existing or Create Parameter? memory IN Create Binding Values n Local parameter: memory n Source parameter: snapshotMemory[attribute] n Type: Boolean Value: no Description: If TRUE, a dump of the internal state of the virtual machine (a memory dump) is included in the snapshot.
Chapter 1 Developing Workflows Table 1-25. Bindings of the VM Snapshots Scriptable Task Element Parameter Name Binding Type Bind to Existing or Create Parameter? vm IN Bind snapshotVmArray snapshotVmArray IN OUT Bind Bind Binding Values n Local parameter: vm n Source parameter: vm[attribute] n Type: VC:VirtualMachine n Description: An active virtual machine of which to take a snapshot.
Developing with VMware vCenter Orchestrator Table 1-26.
Chapter 1 Developing Workflows Table 1-27.
Developing with VMware vCenter Orchestrator The Set Output scriptable task element performs the following scripted function. //Passes the value of the internal attribute to a workflow output parameter snapshotVmArrayOut = snapshotVmArray; Set the Complex Workflow Example Attribute Properties You set the attribute properties in the General tab in the workflow editor. Prerequisites You must have created the workflow, created and linked its schema, and defined the IN and OUT bindings for all elements.
Chapter 1 Developing Workflows 6 Click the (VC:ResourcePool)resourcePool parameter. 7 Click the Properties tab for (VC:ResourcePool)resourcePool. 8 Right-click the Properties tab and select Add Property > Mandatory input. 9 Right-click the Properties tab again and select Select value as from the list of proposed properties. When you set this property, you set how the user selects the value of the (VC:ResourcePool)resourcePool input parameter.
Developing with VMware vCenter Orchestrator 104 VMware, Inc.
2 Scripting Orchestrator uses JavaScript to create building blocks from which you create actions, workflow elements, and policies that access the APIs of the technologies that you plug into Orchestrator. Orchestrator uses the Mozilla Rhino 1.6 JavaScript engine as its scripting engine. The scripting engine provides variable type checking, name space management, automatic completion, and exception handling.
Developing with VMware vCenter Orchestrator Limitations of the Mozilla Rhino Implementation in Orchestrator Orchestrator implements the Mozilla Rhino 1.6 JavaScripting engine. However, the implementation of Rhino in Orchestrator presents some limitations. When writing scripts for workflows, you must consider the following limitations of the Mozilla Rhino implementation in Orchestrator. n When a workflow runs, the objects that pass from one workflow element to another are not Javascript objects.
Chapter 2 Scripting 5 Writing Scripts on page 109 The Orchestrator scripting engine helps you to write scripts. Automatic insertion of functions and automatic completion of lines of scripting accelerates the scripting process and minimizes the potential for writing errors in scripts. 6 Add Parameters to Scripts on page 110 The Orchestrator scripting engine helps you to import available parameters into scripts.
Developing with VMware vCenter Orchestrator What to do next Search the Orchestrator API using the API Explorer. Access the Orchestrator API Explorer Orchestrator provides an API Explorer to allow you to search the Orchestrator API and see the documentation for JavaScript objects that you can use in scripted elements. You can consult an online version of the Scripting API for the vCenter Server plug-in on the Orchestrator documentation home page.
Chapter 2 Scripting Table 2-1.
Developing with VMware vCenter Orchestrator 5 Place the cursor at the end of an element you pasted into the script and press Ctrl+space to select from a contextual list of possible methods and attributes that the object can call. NOTE The automatic completion feature is currently experimental. You added object and functions to the script. What to do next Add parameters to the script.
Chapter 2 Scripting 3 Insert a parameter with a null value into the script. If you pass null values to primitive types such as integers, Booleans, and Strings, the Orchestrator scripting API automatically sets the default value for this argument. You added parameters to the script. What to do next Add access to Java classes in scripts.
Developing with VMware vCenter Orchestrator Accessing Operating System Commands from JavaScript The Orchestrator API provides a scripting class, Command, that runs commands in the Orchestrator server host operating system. To prevent unauthorized access to the Orchestrator server host, by default, Orchestrator applications do not have permission to run the Command class. The Orchestrator administrator can allow access to the Command scripting class by setting the com.vmware.js.
Chapter 2 Scripting n Simple string exception type checking, must use the following pattern in scripted elements in workflows. if (typeof(errorCode)=="string" && errorCode.indexOf("VMwareNoSpaceLeftOnDatastore:") == 0) { // Do something useful here } Orchestrator JavaScript Examples You can cut, paste, and adapt the Orchestrator JavaScript examples to help you write JavaScripts for common orchestration tasks.
Developing with VMware vCenter Orchestrator Larry ; System.log("'people' = " + people); // built-in XML type System.log("'people' is of type : " + typeof(people)); // list-like interface System.log("which contains a list of " + people.person.length() + " persons"); System.log("whose first element is : " + people.person[0]); // attribute 'id' is mapped to field '@id' people.person[0].
Chapter 2 Scripting Compare Types The following JavaScript example checks whether an object matches a given object type. var path = 'myurl/test'; if(typeof(path, string)){ throw("string"); else { throw("other"); } Run a Command in the Orchestrator Server The following JavaScript example allows you to run a command line on the Orchestrator server. Use the same credentials as those used to start the server. NOTE Access to the file system is limited by default.
Developing with VMware vCenter Orchestrator LDAP Scripting Examples Workflow scripted elements, actions, and policies require scripting of common LDAP tasks. You can cut, paste, and adapt these examples into your scripted elements. Convert LDAP Objects to Active Directory Objects The following JavaScript example converts LDAP group elements to Active Directory user group objects, and the reverse. var ldapGroup ; // convert from ldap element to Microsoft:UserGroup object var adGroup = ActiveDirectory.
Chapter 2 Scripting Workflow Scripting Examples Workflow scripted elements, actions, and policies require scripting examples of common workflow tasks. You can cut, paste, and adapt these examples into your scripted elements. Return All Workflows Run by the Current User The following JavaScript example obtains all workflow runs from the server and checks whether they belong to the current user. You can use this scripting with Webview components, for example. var allTokens = Server.
Developing with VMware vCenter Orchestrator if (workflowToLaunch == null) { throw "Workflow not found"; } var workflowParameters = new Properties(); workflowParameters.put("vm",VM); var wfToken = workflowToLaunch.execute(workflowParameters); System.log ("Ran workflow on " +VM.name); } 118 VMware, Inc.
Developing Actions 3 Orchestrator provides libraries of predefined actions. Actions represent individual functions that you use as building blocks in workflows, Web views, and scripts. Actions are JavaScript functions. They take multiple input parameters and have a single return value. They can call on any object in the Orchestrator API, or on objects in any API that you import into Orchestrator by using a plug-in. When a workflow runs, an action takes its input parameters from the workflow's attributes.
Developing with VMware vCenter Orchestrator You can use the Actions view to view information about the actions in the libraries and create and edit actions. Components of the Actions View When you click an action in the actions hierarchical list, information about that action appears in the Orchestrator client's right pane. The Actions view presents four tabs. General Displays general information about the action, including its name, its version number, the permissions, and a description.
Chapter 3 Developing Actions 8 Add the action input parameters by clicking the arrow icon. 9 Write the action script. 10 Set the action permissions. 11 Click Save and close. You created a custom action and added the action input parameters. What to do next You can use the new custom action in a workflow. Find Elements That Implement an Action If you edit an action and change its behavior, you might inadvertently break a workflow or application that implements that action.
Developing with VMware vCenter Orchestrator n Avoid writing loops in an action. Create loops in the workflow instead. If the server restarts, a running workflow resumes at its last check point, at the start of an element. If you write a loop inside an action and the server restarts while the workflow is running that action, the workflow resumes at the check point at the beginning of that action, and the loop starts again from the beginning.
Creating Resource Elements 4 Workflows and Web views can require as attributes objects that you create independently of Orchestrator. To use external objects as attributes in workflows or Web views, you import them into the Orchestrator server as resource elements. Objects that workflows and Web views can use as resource elements include image files, scripts, XML templates, HTML files, and so on.
Developing with VMware vCenter Orchestrator What to do next Import and edit a resource element. Import an External Object to Use as a Resource Element Workflows and Web views can require as attributes objects that you create independently of Orchestrator. To use external objects as attributes in workflows or Web views, you import them to the Orchestrator server as resource elements. Prerequisites An image file, script, XML template, HTML file, or other type of object to import.
Chapter 4 Creating Resource Elements What to do next Save the resource element to a file to update it, or add the resource element to a workflow or Web view. Save a Resource Element to a File You can save a resource element to a file on your local system. Saving the resource element as a file allows you to edit it. For example, if the resource element is an XML configuration file or a script, you must save it locally to modify it. You cannot edit a resource element in the Orchestrator client.
Developing with VMware vCenter Orchestrator n A workflow that requires this resource element as an attribute. Procedure 1 Click the Workflows view in the Orchestrator client. 2 Expand the hierarchical tree viewer to navigate to the workflow that requires the resource element as an attribute. 3 Right-click the workflow and select Edit. 4 On the General tab, right-click in the attributes pane and select Add attribute. 5 Click the attribute name and type a new name for the attribute.
Chapter 4 Creating Resource Elements 8 In the Select a type dialog box, type resource in the Filter box to search for an object type. Option Action Define a single resource element as an attribute Select ResourceElement from the list. Define a folder that contains multiple resource elements as an attribute Select ResourceElementCategory from the list. 9 Click Value and type the name of the resource element or category of resource elements in the Filter text box.
Developing with VMware vCenter Orchestrator 128 VMware, Inc.
Creating Packages 5 Packages are the vehicle for transporting content from one Orchestrator server to another. Packages can contain workflows, actions, policies, Web views, configurations, or resources. When you add an element to a package, Orchestrator checks for dependencies and adds any dependent elements to the package. For example, if you add a workflow that uses actions or other workflows, Orchestrator adds those actions and workflows to the package.
Developing with VMware vCenter Orchestrator Procedure 1 In the Orchestrator client, click the Packages view. 2 Click the menu button in the title bar of the Packages list and select Add package. 3 Name the new package and click OK. The syntax for package names is domain.your_company.folder.package_name. For example, com.vmware.myfolder.mypackage. 4 Right-click the package and select Edit. The package editor opens. 5 Add a description for the package in the General tab.
Chapter 5 Creating Packages 3 Search for a user or user group. The search results show all of the users and user groups from the Orchestrator LDAP server that match the search. 4 Select a user or user group and click OK. 5 Right-click the user and select Add access rights. 6 Check the appropriate check boxes to set the level of permissions for this user and click OK.
Developing with VMware vCenter Orchestrator 132 VMware, Inc.
Index A Action element 19 action elements, binding 73 Action view 119 actions adding 120 attributes 122 basic guidelines 121 binding 74 coding guidelines 121 creating 88, 120 finding elements that implement 121 naming 122 parameters 122 reusing 119 Actions 119 Actions view 120 API Explorer, accessing 108 attributes definition 15, 67 read-write properties 82, 102 audience 7 B binding action elements 73 decision elements 72 scriptable tasks 75 bindings action 74 defining 28, 92, 93 exception 32, 82 scriptab
Developing with VMware vCenter Orchestrator O Orchestrator API 106, 119 Orchestrator client, accessing 11 OS commands, accessing 112 OUT bindings 28 P packages create 129 digital rights management 129 permissions 130 signature 129 parameter properties dynamic 35 static 35 parameters definition 16, 67, 88 properties 83 read-write properties 82 presentation creating 84, 102 creating display groups 102 display groups 33 input steps 33 Presentation tab 33, 35, 102 Presentation Tab 35 presentations 13 properti
Index user interactions, input parameters dialog box 45 user interactions, responding 46 user interactions, security.group attribute 39 user interactions, timeout.
Developing with VMware vCenter Orchestrator 136 VMware, Inc.
