advertisement
vCenter Orchestrator Developer's Guide
vCenter Orchestrator 4.0.1
This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs .
EN-000228-03
vCenter Orchestrator Developer's Guide
You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to: [email protected]
Copyright
©
2009, 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents .
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304 www.vmware.com
2 VMware, Inc.
Contents
Updated Information 7
About This Book 9
1 Introduction to VMware vCenter Orchestrator 11
Key Features of the Orchestrator Platform 11
Orchestrator User Roles and Related Tasks 12
2 Developing Workflows 15
Principal Phases in the Workflow Development Process 16
Accessing the Orchestrator Client 17
Testing Workflows During Development 17
Provide General Workflow Information 20
Defining Attributes and Parameters 21
Obtaining Input Parameters from Users When a Workflow Starts 39
Requesting User Interactions While a Workflow Runs 44
Calling Workflows Within Workflows 52
Running a Workflow on a Selection of Objects 58
Developing Long-Running Workflows 60
Develop a Simple Example Workflow 70
3 Developing Actions 111
Components of the Actions View 112
4 Scripting 115
Orchestrator Elements that Require Scripting 115
Limitations of the Mozilla Rhino Implementation in Orchestrator 116
Using the Orchestrator API 116
Exception Handling Guidelines 122
Orchestrator JavaScript Examples 123
VMware, Inc. 3
vCenter Orchestrator Developer's Guide
5 Creating Resource Elements 131
Import an External Object to Use as a Resource Element 132
Edit the Resource Element Information and Access Rights 132
Save a Resource Element to a File 133
Add a Resource Element to a Workflow 133
Add a Resource Element to a Web View 134
6 Creating Packages 137
Set User Permissions on a Package 138
7 Developing Plug-Ins 141
Contents and Structure of a Plug-In 147
Create an Orchestrator Plug-In 151
Orchestrator Plug-In API Reference 216
Elements of the vso.xml Plug-In Definition File 230
8 Developing a Web Services Client 247
Writing a Web Service Client Application 247
Web Service API Object Reference 262
Web Service API Operation Reference 267
9 Developing Web Views 281
Web View Development Tasks to Perform in Orchestrator 283
File Structure of a Web View 293
Accessing Server Objects from URLs 309
Create a Simple Web View Using the Default Template 312
10 Refactoring Orchestrator Applications After Upgrading vCenter Server 329
When to Refactor Applications 329
Install the VMware Infrastructure 3.5 Plug-In 330
Refactoring Packages with the Basic Refactoring Workflow 330
Refactoring Packages with the Advanced Refactoring Workflows 333
Appendix: Workflow Name Changes 337
JDBC Workflow Name Changes 337
Locking Workflow Names Unchanged 338
Mail Workflow Name Changes 338
Refactoring Workflow Name Changes 338
4 VMware, Inc.
SSH Workflow Name Changes 339 vCenter Server Workflow Name Changes 339
Index 343
Contents
VMware, Inc. 5
vCenter Orchestrator Developer's Guide
6 VMware, Inc.
Updated Information
This VMware vCenter Orchestrator Developer's Guide is updated with each release of the product or when necessary.
This table provides the update history of the VMware vCenter Orchestrator Developer's Guide.
Revision Description
EN-000228-03 n
Added “Running a Workflow on a Selection of Objects,” on page 58,
workflow in a scripted loop in “Workflow Scripting Examples,” on page 129.
n n
Added managed object references and VcOptionValue examples in “Access Managed Object Reference
“Set vCenter Server Option Values,” on page 129.
Added Tapestry and Dojo versions in
“Web View Overview,” on page 282.
n n n
description of Execute permission in
“Set User Permissions on a Package,” on page 138.
Added “Limitations of the Mozilla Rhino Implementation in Orchestrator,” on page 116 and
Coding of Scripting Keywords,” on page 120.
Added more required JAR files to
EN-000228-02 n
Added links to third-party Web development standards in “Web View Overview,” on page 282.
n
Corrected description of Execute permission in “Set User Permissions on a Package,” on page 138.
n
Corrected OGNL syntax in “vmo:WorkflowLink Component,” on page 307.
EN-000228-01 n
n Corrected descriptions of the Pre-defined answers and Pre-defined list of elements
properties in “Workflow Input Parameter Properties,” on page 42.
n n
Improved definitions in
“Overview of Plug-Ins,” on page 141 and
“Contents and Structure of a Plug-
Complete revision of
“Create an Orchestrator Plug-In,” on page 151.
n n n n n
Added information about how to add a plug-in tab to the configuration interface in
Orchestrator Plug-In,” on page 151.
Added missing classes to “Orchestrator Plug-In API Reference,” on page 216 and improved
descriptions.
Removed erroneous references to Authorizations from “Import Web View Files from a Working
Folder,” on page 290, “Create a Web View Attribute,” on page 290, and
“hasRights Operation,” on page 278.
New Web view section, “Provide Unique Component Names,” on page 315, and reproduced the unique
component name change throughout the Web view example.
VMware, Inc. 7
vCenter Orchestrator Developer's Guide
Revision Description
EN-000228-00 Updated for the release of Orchestrator 4.0.1 with the following new information: n New procedure,
“Edit a Workflow from the Standard Library,” on page 18.
n New sections on
“Accessing the Orchestrator Client,” on page 17,
“Accessing the Orchestrator Server
“Accessing Operating System Commands from JavaScript,” on page 122, and
policy.
n n n
New Chapter 5, “Creating Resource Elements,” on page 131.
Major revision of Chapter 9, “Developing Web Views,” on page 281.
New “Appendix: Workflow Name Changes,” on page 337 to reflect changes between Orchestrator 4.0
and 4.0.1.
EN-000129-01 n
Packages with the Basic Refactoring Workflow,” on page 330 and
“Refactoring Packages with the
package.
n
Updated the filenames and paths of the solar system example plug-in in “Create an Orchestrator Plug-
In,” on page 151 to reflect changes in the file structure of the examples package.
EN-000129-00 Initial release of Orchestrator 4.0.
8 VMware, Inc.
About This Book
The VMware vCenter Orchestrator Developer's Guide provides information and instructions about how to use the
VMware vCenter Orchestrator platform to develop process-automation applications for virtual environments.
Intended Audience
This document is intended for developers who want to develop applications using the Orchestrator platform.
Specifically, this document is intended for the following types of developer.
n n
Application developers who want to create new extensions to the Orchestrator platform.
Scripting developers who want to create new building blocks to automate certain processes.
n n n
Web service application developers who want to access these processes across a network, through technologies such as simple object access protocol (SOAP) and Web services definition language (WSDL).
Web designers who want to create or customize Web front ends for these processes, using the Web 2.0
technologies.
IT staff who want to automate processes to save time, to reduce risk and cost, and to comply with regulations or standard practices.
Example Applications
The examples applications which this document describes are available to download. You can download a ZIP file of examples from the Orchestrator documentation home page .
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation, go to http://www.vmware.com/support/pubs .
Document Feedback
VMware welcomes your suggestions for improving our documentation. If you have comments, send your feedback to [email protected]
.
VMware, Inc. 9
vCenter Orchestrator Developer's Guide
Technical Support and Education Resources
The following technical support resources are available to you. To access the current version of this book and other books, go to http://www.vmware.com/support/pubs .
Online and Telephone
Support
To use online support to submit technical support requests, view your product and contract information, and register your products, go to http://www.vmware.com/support .
Customers with appropriate support contracts should use telephone support for the fastest response on priority 1 issues. Go to http://www.vmware.com/support/phone_support.html
.
Support Offerings To find out how VMware support offerings can help meet your business needs, go to http://www.vmware.com/support/services .
VMware Professional
Services
VMware Education Services courses offer extensive hands-on labs, case study examples, and course materials designed to be used as on-the-job reference tools. Courses are available onsite, in the classroom, and live online. For onsite pilot programs and implementation best practices, VMware Consulting
Services provides offerings to help you assess, plan, build, and manage your virtual environment. To access information about education classes, certification programs, and consulting services, go to http://www.vmware.com/services .
10 VMware, Inc.
Introduction to VMware vCenter
Orchestrator
1
VMware vCenter Orchestrator is a development and process-automation platform that provides a library of extensible workflows to allow you to create and run automated, configurable processes to manage the VMware vCenter infrastructure.
Orchestrator exposes every operation in the vCenter Server API, allowing you to integrate all of these operations into your automated processes. Orchestrator also allows you to integrate with other management and administration solutions through its open plug-in architecture.
This chapter includes the following topics: n
“Key Features of the Orchestrator Platform,” on page 11
n n
“Orchestrator User Roles and Related Tasks,” on page 12
“Orchestrator Architecture,” on page 13
Key Features of the Orchestrator Platform
Orchestrator is composed of three distinct layers: an orchestration platform that provides the common features required for an orchestration tool, a plug-in architecture to integrate control of subsystems, and a library of preexisting processes. Orchestrator is an open platform that can be extended with new plug-ins and libraries, and can be integrated into larger SOAP architectures through a set of APIs.
The following list presents the key Orchestrator features.
Persistence
Central management
Check-pointing
Versioning
Production grade external databases are used to store relevant information, such as processes, states, and configuration information.
Orchestrator provides a central way to manage your processes. The application server-based platform, with full version history, allows you to have scripts and process-related primitives in one place. This way, you can avoid scripts without versioning and proper change control spread on your servers.
Every step of a process is saved in the database, which allows you to restart the server without losing state and context. This feature is especially useful for long-running processes.
All Orchestrator Platform objects have an associated version history. This feature allows basic change management when distributing processes to different project stages or locations.
VMware, Inc. 11
vCenter Orchestrator Developer's Guide
Scripting engine
Workflow engine
Policy engine
Web 2.0 front end
Security
The Mozilla Rhino JavaScript engine provides a way to create new building blocks for Orchestrator Platform. The scripting engine is enhanced with basic version control, variable type checking, name space management and exception handling. It can be used in the following building blocks: n n n
Actions
Workflows
Policies
The workflow engine allows you to capture business processes. It uses one of the following methods to create a step-by-step automation: n n
Building blocks of the library
Building blocks provided by the customer n Plug-ins
Users, a schedule, or a policy can start workflows.
The policy engine allows monitoring and event generation to react to changing conditions. Policies can aggregate events from the platform or any of the plugins, which allows you to handle changing conditions on any of the integrated technologies.
The Web 2.0 front end allows new possibilities of expression and flexibility. It provides a library of user customizable components to access vCO orchestrated objects and uses Ajax technology to dynamically update content without reloading complete pages.
Orchestrator provides the following advanced security functions: n Public Key Infrastructure (PKI) to sign and encrypt content imported and exported between servers n n n
Digital Rights Management (DRM) to control how exported content might be viewed, edited and redistributed
Secure Sockets Layer (SSL) encrypted communications between the desktop client and the server and HTTPS access to the Web front end.
Advanced access rights management to provide control over access to processes and the objects manipulated by these processes.
Orchestrator User Roles and Related Tasks
vCenter Orchestrator provides different tools and interfaces based on the specific responsibilities of the two global user roles: Administrators and End Users.
Administrators This role has full access to all of the Orchestrator platform capabilities. Basic administrative tasks include the following items: n n
Installing and configuring Orchestrator
Managing access rights for Orchestrator and applications n n
Importing and exporting packages
Enabling and disabling Web views
12 VMware, Inc.
Chapter 1 Introduction to VMware vCenter Orchestrator
End Users n n
Running workflows and scheduling tasks
Managing version control of imported elements
Users in this role are granted access to only the Web front end. They can run and schedule workflows and policies.
Orchestrator Architecture
Orchestrator contains a workflow library and workflow engine to allow you to create and run workflows that automate orchestration processes. You run workflows on the objects of different technologies that Orchestrator accesses through a series of plug-ins.
Orchestrator provides a standard set of plug-ins, including a plug-in to VMware vCenter Server, to allow you to orchestrate tasks in the different environments that the plug-ins expose.
Orchestrator also presents an open architecture to allow you to plug in external third-party applications to the orchestration platform. You can run workflows on the objects of the plugged-in technologies that you define yourself. Orchestrator connects to a directory services server to manage user accounts, and to a database to store information from the workflows that it runs. You can access Orchestrator and the workflows and objects it exposes through the Orchestrator client interface, through a Web browser, or through Web services.
Figure 1-1 shows the architecture of Orchestrator.
Figure 1-1. VMware vCenter Orchestrator Architecture vCenter
Orchestrator
Client application browser access web service
workflow engine
workflow library vCenter VI3 WMI XML SSH JDBC SMTP
3rd-party plug-in directory services vCenter
Server Orchestrator database
N
OTE
The VMware Infrastructure 3 and Microsoft plug-ins are not installed by default.
VMware, Inc. 13
vCenter Orchestrator Developer's Guide
14 VMware, Inc.
Developing Workflows
2
You develop workflows in the Orchestrator client interface. Workflow development involves using the workflow editor, the built-in Mozilla Rhino JavaScript scripting engine, and the Orchestrator and vCenter
Server APIs.
n n
Principal Phases in the Workflow Development Process on page 16
The process for developing a workflow involves a series of phases.
Accessing the Orchestrator Client on page 17
By default, all Orchestrator users can access the Orchestrator client. However, for security reasons, the
Orchestrator administrator can limit access to the Orchestrator client to members of the Orchestrator administrator LDAP group.
n n n
Testing Workflows During Development on page 17
You can test workflows at any point during the development process, even if you have not completed the workflow or included an end element.
You create and edit workflows by using the workflow editor. The workflow editor is the Orchestrator client's IDE for developing workflows.
Provide General Workflow Information on page 20
You provide a workflow name and desription, define attributes and certain aspects of workflow behavior, set the version number, check the signature, and set user permissions in the General tab in the workflow editor.
n n n n
Defining Attributes and Parameters on page 21
After you create a workflow, you must determine the workflow's global attributes and input and output parameters.
A workflow schema is a graphical representation of a workflow that shows the workflow as a flow diagram of interconnected workflow elements.
Obtaining Input Parameters from Users When a Workflow Starts on page 39
If a workflow requires input parameters, it opens a dialog box in which users enter the required input parameter values when it runs. You can organize the content and layout, or presentation, of this dialog box in Presentation tab in the workflow editor.
Requesting User Interactions While a Workflow Runs on page 44
A workflow can sometimes require additional input parameters from an outside source while it runs.
These input parameters can come from another application or workflow, or the user can provide them directly.
VMware, Inc. 15
vCenter Orchestrator Developer's Guide n n n n n n n n n
Calling Workflows Within Workflows on page 52
Workflows can call on other workflows during their run. A workflow can start another workflow either because it requires the result of the other workflow as an input parameter for its own run, or it can start a workflow and let it continue its own run independently. Workflows can also start a workflow at a given time in the future, or start multiple workflows simultaneously.
Running a Workflow on a Selection of Objects on page 58
You can automate repetitive tasks by running a workflow on a selection of objects. For example, you can create a workflow that takes a snapshot of all the virtual machines in a virtual machine folder, or you can create a workflow that powers off all the virtual machines on a given host.
Developing Long-Running Workflows on page 60
A workflow in a waiting state consumes system resources because it constantly polls the object from which it requires a response. If you know that a workflow will potentially wait for a long time before it receives the response it requires, you can add long-running workflow elements to the workflow.
Configuration Elements on page 65
A configuration element is a list of attributes you can use to configure constants across a whole
Orchestrator server deployment.
Workflow User Permissions on page 66
Orchestrator defines levels of permissions that you can apply to users or groups to allow or deny them access to workflows.
Validating Workflows on page 67
Orchestrator provides a workflow validation tool. Validating a workflow helps identify errors in the workflow and checks that the data flows from one element to the next correctly.
A workflow runs according to a logical flow of events.
Develop a Simple Example Workflow on page 70
Developing a simple example workflow demonstrates the most common steps in the workflow development process.
Develop a Complex Workflow on page 92
Developing a complex example workflow demonstrates the most common steps in the workflow development process and more advanced scenarios, such as creating custom decisions and loops.
Principal Phases in the Workflow Development Process
The process for developing a workflow involves a series of phases.
The order in which you perform the tasks that developing a workflow involves generally conforms to the following sequence of phases.
1 Provide general information about the workflow.
2 Create the input parameters.
3 Create the logical flow of the workflow by laying out and linking the schema.
4 Bind the input and output parameters of each element to workflow attributes, creating the necessary parameters and attributes as you define each element.
5 Write any necessary scripts for scriptable task or custom decision elements.
6 Create the layout and behavior of the input parameters dialog box that the user sees when they run the workflow by creating the workflow presentation.
7 Validate the workflow.
16 VMware, Inc.
Chapter 2 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.
To allow you to access the Orchestrator client, the administrator must either add you to the Orchestrator administrator LDAP group, or enable all users to access the Orchestrator client.
See the VMware vCenter Orchestrator Administration Guide for information about setting LDAP groups and enabling and disabling access to the Orchestrator client.
Testing Workflows During Development
You can test workflows at any point during the development process, even if you have not completed the workflow or included an end element.
By default, Orchestrator checks that a workflow is valid before you can run it. You can deactivate automatic validation during workflow development, to run partial workflows for testing purposes.
N
OTE
Do not forget to reactivate automatic validation when you finish developing the workflow.
Procedure
1 In the Orchestrator client menu, click Tools > User Preferences.
2 Click the Workflows tab.
3 Uncheck the Validate workflow before executing it check box.
You deactivated automatic workflow validation.
Workflow Editor
You create and edit workflows by using the workflow editor. The workflow editor is the Orchestrator client's
IDE for developing workflows.
You open the workflow editor by editing an existing workflow.
n n n n
You can create workflows in the workflows hierarchical list in the Orchestrator client interface.
You edit a workflow by using the Orchestrator client's workflow editor.
Edit a Workflow from the Standard Library on page 18
Orchestrator provides a standard library of workflows that you can use to automate operations in the virtual infrastructure. The workflows in the standard library are locked in the read-only state.
Workflow Editor Tabs on page 19
The workflow editor consists of tabs in which you edit the components of the workflows.
VMware, Inc. 17
vCenter Orchestrator Developer's Guide
Create a Workflow
You can create workflows in the workflows hierarchical list in the Orchestrator client interface.
Procedure
1 In the Orchestrator client, click the Workflows view.
2 (Optional) Right-click the root of the workflows hierarchical list, or a folder in the list, and select Add
category to create a new workflow folder.
3 (Optional) Name the new folder.
4 Right-click the new folder or an existing folder and select New workflow.
5 Name the new workflow and click OK.
The new empty workflow is created in the folder you chose.
What to do next
You can edit the workflow.
Edit a Workflow
You edit a workflow by using the Orchestrator client's workflow editor.
Procedure
1 In the Orchestrator client, click the Workflows view.
2 Expand the workflows hierarchical list to navigate to the workflow to edit.
3 Click the workflow to edit.
4 Open the workflow for editing by right-clicking the workflow and selecting Edit.
The workflow editor opens, allowing you to edit the workflow.
Edit a Workflow from the Standard Library
Orchestrator provides a standard library of workflows that you can use to automate operations in the virtual infrastructure. The workflows in the standard library are locked in the read-only state.
To edit a workflow from the standard library, create a duplicate of that workflow. You can edit duplicate workflows or custom workflows.
Procedure
1 Click in the Workflows view in the Orchestrator client.
2 (Optional) Right-click the root of the hierarchical list of workflow folders and select New category to create a folder to contain the workflow to edit.
3 Expand the Library hierarchical list of standard workflows to navigate to the workflow to edit.
4 Right-click the workflow to edit.
The Edit option is dimmed. The workflow is read-only.
5 Right-click the workflow and select Duplicate workflow.
6 Provide a name for the duplicate workflow.
By default, Orchestrator names the duplicate workflow
Copy of workflow_name .
18 VMware, Inc.
Chapter 2 Developing Workflows
7 Click the Workflow category value to search for a folder in which to save the duplicate workflow.
Select the folder you created in Step 2
. If you did not create a folder, select a folder that is not in the library of standard workflows.
8 Click Yes or No to copy the workflow version history to the duplicate.
Option Description
Yes
No
The version history of the original workflow is replicated in the duplicate.
The version of the duplicate reverts to 0.0.0.
9 Click Duplicate to duplicate the workflow.
10 Right-click the duplicate workflow and select Edit.
The workflow editor opens. You can edit the duplicate workflow.
You duplicated a workflow from the standard library. You can edit the duplicate workflow.
Workflow Editor Tabs
The workflow editor consists of tabs in which you edit the components of the workflows.
Table 2-1. Workflow Editor Tabs
Tab
General
Inputs
Outputs
Schema
Presentation
Parameters Reference
Executions
Description
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.
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.
Define the values that the workflow generates when it completes its run. Other workflows or actions can use these values when they run.
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.
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.
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.
Provides details about each time a particular workflow runs.
This information includes the workflow's status, the user who ran it, the business status of the current element, and the time and date when the workflow started and ended.
VMware, Inc. 19
vCenter Orchestrator Developer's Guide
Table 2-1. Workflow Editor Tabs (Continued)
Tab
Events
Permissions
Description
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.
Sets the permissions to interact with the workflow for users or groups of users.
Provide General Workflow Information
You provide a workflow name and desription, define attributes and certain aspects of workflow behavior, set the version number, check the signature, and set user permissions in the General tab in the workflow editor.
Prerequisites
Create a workflow and open the workflow editor for that workflow.
Procedure
1 Click the General tab in the workflow editor.
2 Click the Version digits to set a version number for the workflow.
The Version Comment dialog box opens.
3 Type a comment for this version of the workflow and click OK.
For example, type Initial creation if you just created the workflow.
4 Define how the workflow behaves if the Orchestrator server restarts by setting the Server restart
behavior value.
n Leave the default value of Resume workflow execution to make the workflow resume at the point at which its run was interrupted when the server stopped.
n Click Resume workflow execution and select DON'T resume workflow execution (set as
FAILED) to prevent the workflow from restarting if the Orchestrator server restarts.
Prevent the workflow from restarting if the workflow depends on the environment in which it runs. For example, if a workflow requires a specific vCenter Server and you reconfigure Orchestrator to connect to a different vCenter Server, restarting the workflow after you restart the Orchestrator server causes the workflow to fail.
5 Type a detailed description of the workflow in the Description text box.
6 Click Save at the bottom of the workflow editor.
A green message at the bottom left of the workflow editor confirms that you saved your changes.
You defined aspects of the workflow behavior, set the version, and defined the operations that users can perform on the workflow.
What to do next
You must define the workflow attributes and parameters.
20 VMware, Inc.
Chapter 2 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.
n n n
Define Workflow Attributes on page 21
Workflow attributes are the data that workflows process.
Define Workflow Parameters on page 22
Input and output parameters allow you to pass information and data into and out of the workflow.
Attribute and Parameter Naming Restrictions on page 22
You can use OGNL expressions to determine input parameters dynamically when a workflow runs. The
Orchestrator OGNL parser uses certain keywords during OGNL processing that you cannot use in workflow attribute or parameter names.
Define Workflow Attributes
Workflow attributes are the data that workflows process.
N
OTE
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.
N
OTE
Workflow attributes must not have the same name as any of the workflow's parameters.
4 Click the attribute type to select a new type from a list of possible values.
The default attribute type is String.
5 Click the attribute value to set or select a value according to the attribute type.
6 Add a description of the attribute in the Description text box.
VMware, Inc. 21
vCenter Orchestrator Developer's Guide
7 If the attribute is a constant rather than a variable, click the check box to the left of the attribute name to make its value read-only.
The lock icon ( ) identifies the column of read-only check boxes.
8 (Optional) If you decide that the attribute should be an input or output parameter rather than an attribute, right-click the attribute and select Move as INPUT/OUTPUT parameter to change the attribute into a parameter.
You defined an attribute for the workflow.
What to do next
You can define the workflow's input and output parameters.
Define Workflow Parameters
Input and output parameters allow you to pass information and data into and out of the workflow.
You define a workflow's parameters in the workflow editor. The input parameters are the data upon which the workflow acts that the user provides when they run the workflow. The output parameters are the data the workflow returns when it completes.
Prerequisites
You must have created a workflow and opened the workflow editor for that workflow.
Procedure
1 Click the appropriate tab in the workflow editor.
n Click Inputs to create input parameters.
n Click Outputs to create output parameters.
2 Right-click in the parameters tab and select Add Parameter.
A new parameter appears in the attributes list, with String as its default type.
3 Click the parameter name to change it.
The default name is arg_in_ <X> for input parameters and arg_out_ <X> for output parameters, where
<X> is a number.
4 Click the parameter type value to change it from String to a different value from a list of possible values.
5 Add a description of the parameter in the Description text box.
6 (Optional) If you later decide that the parameter should be an attribute rather than a parameter, right-click the parameter and select Move as attribute to change the parameter into an attribute.
You have defined an input or output parameter for the workflow.
What to do next
After you define the workflow's parameters, build the workflow schema.
Attribute and Parameter Naming Restrictions
You can use OGNL expressions to determine input parameters dynamically when a workflow runs. The
Orchestrator OGNL parser uses certain keywords during OGNL processing that you cannot use in workflow attribute or parameter names.
Using a reserved OGNL keyword as a prefix to an attribute name does not break OGNL processing. For example, you can name a parameter trueParameter . Reserved keywords are not case-sensitive.
22 VMware, Inc.
Chapter 2 Developing Workflows
You cannot use the following keywords in workflow attribute and parameter names.
n n n n n n n n n n n n n n n n n n n n
Table 2-2. Forbidden Keywords in Attribute and Parameter Names
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 n n n n n n n n n n n n n n n n n n n n eof esc exponent export extends false final flt_literal flt_suff ident implements import in int int_literal interface
_keepLastEvaluation
_lastEvaluation letter long n n n n n n n n n n n n n n n n n n n n
Forbidden Keyword
_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.
n
View Workflow Schema on page 24
You view a workflow schema in the Schema tab for that workflow in the Orchestrator client.
n
Building a Workflow in the Workflow Schema on page 24
Workflow schemas consist of a sequence of schema elements. Workflow schema elements are the building blocks of the workflow, and can represent decisions, scripted tasks, actions, exception handlers, or even other workflows.
n n n n n
The workflow editor presents the workflow schema elements in menus in the Schema tab.
Schema Element Properties on page 28
Schema elements have properties that you can define and edit in the Schema tab of the workflow palette.
Links 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.
Workflows can implement decision functions that define different courses of action according to a
Boolean true or false statement.
Exception handling catches any errors that occur when a schema element runs. Exception handling defines how the schema element behaves when the error occurs.
VMware, Inc. 23
vCenter Orchestrator Developer's Guide
View Workflow Schema
You view a workflow schema in the Schema tab for that workflow in the Orchestrator client.
Procedure
1 Navigate to a workflow in the workflow hierarchical list.
2 Click the workflow.
Information about that workflow appears in the right pane.
3 Select the Schema tab in the right pane.
You see the graphical representation of the workflow.
Building a Workflow in the Workflow Schema
Workflow schemas consist of a sequence of schema elements. Workflow schema elements are the building blocks of the workflow, and can represent decisions, scripted tasks, actions, exception handlers, or even other workflows.
You build workflows in the workflow editor by dragging schema elements from the workflow palette on the left of the workflow editor into the workflow schema diagram.
Edit a Workflow Schema
You build a workflow by creating a sequence of schema elements in the workflow editor's Schema tab.
Repeat this procedure until you have added all of the required schema elements to the workflow schema. A workflow schema must have at least one End workflow element, but it can have several.
Prerequisites
Open a workflow for editing in the workflow editor.
Procedure
1 Click the Schema tab in the workflow editor.
2 Click the Generic menu on the left of the Schema tab.
3 Drag a schema element from the Generic menu to the workflow schema.
4 Double-click the element you dragged to the workflow schema.
Double-clicking an element allows you to name the element. You must provide elements with unique names in the context of the workflow.
a Type an appropriate element name in the schema element.
b Press the Enter key.
You cannot rename Waiting timer, Waiting event, End workflow, or Throw exception elements.
5 Right-click an element in the schema and select Copy.
6 Right-click at an appropriate position in the schema and select Paste.
Copying and pasting existing schema elements is a quick way of adding similar elements to the schema.
All of the settings of the copied element appear in the pasted element, except for the business state. Adjust the pasted element settings accordingly.
24 VMware, Inc.
Chapter 2 Developing Workflows
7 Drag schema elements from the Basic, Log, or Network menus to the workflow schema.
You can edit the names of the elements in the Basic, Log, or Network menus. You cannot edit their scripting.
8 Drag schema elements from the Action & Workflow menu to the workflow schema.
When you drag actions or workflows to the workflow schema, a dialog box appears that allows you to search for the action or workflow to insert.
9 Type the name or part of the name of the workflow or action to insert in the workflow.
The workflows or actions that match the search appear in the dialog box.
10 Double-click a workflow or action to select it.
You inserted the workflow or action in the workflow schema.
What to do next
Define the properties of the elements you added to the workflow schema and link and bind them all together.
Modify Search Results
You use the Search text box to find elements such as workflows or actions. If a search returns a partial result, you can modify the number of results that the search returns.
When you use the search for an element, a green message box indicates that the search lists all the results. A yellow message box indicates that the search lists only partial results.
Procedure
1 (Optional) If you are editing a workflow in the workflow editor, click Save and Close to exit the editor.
2 From the Orchestrator client menu, select Tools > User Preferences.
3 Click the General tab.
4 Type the number of results for searches to return in the Finder Maximum Size text box.
5 Click Save and Close in the User Preferences dialog box.
You modified the number of results that searches return.
Schema Elements
The workflow editor presents the workflow schema elements in menus in the Schema tab.
Table 2-3 describes all of the schema elements from which you can build workflows.
Table 2-3. Schema Elements and Icons
Schema Element
Name
Start Workflow
Scriptable Task
Description
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.
General purpose tasks you define. You write
JavaScript functions in this element.
Icon
Icon Location in Workflow editor
Always present in the
Schema tab
Generic workflow palette
VMware, Inc. 25
vCenter Orchestrator Developer's Guide
Table 2-3. Schema Elements and Icons (Continued)
Schema Element
Name
Decision
Custom Decision
User Interaction
Waiting Timer
Waiting Event
End Workflow
Description
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.
Boolean function. Custom decisions can take several input parameters and act upon them according to custom scripts. Returns either true or false.
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.
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 waitingsignal state.
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.
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
Icon Location in Workflow editor
Generic workflow palette
Generic workflow palette
Generic workflow palette
Generic workflow palette
Generic workflow palette
Generic workflow palette
26 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-3. Schema Elements and Icons (Continued)
Schema Element
Name
Thrown Exception
Workflow Note
Pre-Defined Task
Action
Workflow
Description
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.
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.
Noneditable scripted elements that perform standard tasks that workflows commonly use. The following tasks are predefined:
Basic n Sleep n n n n n n
Change credential
Wait until date
Wait for custom event
Increase counter
Decrease counter
Add hours to date
Log n n n n n n n n
System log
System warning
System error
Server log
Server warning
Server error
System+server log
System+server warning n System+server error
Network n n n
HTTP post
HTTP get
Send custom event
Calls on an action from the Orchestrator libraries of actions. When a workflow reaches an action element, it calls and runs that action.
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.
Icon
Icon Location in Workflow editor
Generic workflow palette
Generic workflow palette
Basic, Log, and Network workflow palette
Action & Workflow workflow palette
Action & Workflow workflow palette
VMware, Inc. 27
vCenter Orchestrator Developer's Guide
Table 2-3. Schema Elements and Icons (Continued)
Schema Element
Name
Asynchronous
Workflows
Schedule Workflow
Description
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.
Creates a task to run the workflow at a set time, then the workflow continues its run.
Nested Workflows Starts several workflows simultaneously.
You can choose to nest local workflows and remote workflows that are in a different
Orchestrator server. You can also run workflows with different credentials. The workflow waits until all the nested workflows complete before it continues its run.
Icon
Icon Location in Workflow editor
Action & Workflow workflow palette
Action & Workflow workflow palette
Action & Workflow workflow palette
Schema Element Properties
Schema elements have properties that you can define and edit in the Schema tab of the workflow palette.
Edit a Schema Element's Global Properties
You define a schema element's global properties in the schema element's Info tab.
Prerequisites
The Schema tab of the workflow editor must contain elements.
Procedure
1 Click the Schema tab in the workflow editor.
2 Select an element to edit by clicking a schema element in the workflow schema.
The schema element's properties tabs appear at the bottom of the workflow editor.
3 Click the Info tab.
4 Provide a name for the schema element in the Name text box.
This is the name that appears in the schema element in the workflow schema diagram.
5 Click the Interaction text box and select a description from the list.
The Interaction property allows you to select between standard descriptions of how this element interacts with objects outside of the workflow. This property is for information only.
6 (Optional) Click Color to change the background color of the schema element.
You can highlight certain sections of the schema by changing the color of individual workflow elements.
7 Provide a business status description in the Business Status text box.
The Business Status property is a brief description of what this element does. When a workflow is running, the workflow token shows the Business Status of each element as it runs. This feature is useful for tracking workflow status.
28 VMware, Inc.
Chapter 2 Developing Workflows
Schema Element Properties Tabs
You access a schema element's properties by clicking on a schema element that you have dragged into the workflow schema. The element properties appear in tabs at the bottom of the workflow editor.
Different element types present different properties tabs, as shown in Table 2-4
.
Table 2-4. Properties Tabs per Schema Element
Schema Element Property Tab Description
Attributes
Decision
End Workflow
Exception
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.
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.
Stops the workflow, either because the workflow completed successfully, or because it encountered an error and returned an exception.
How this schema element behaves in the event of an exception.
External Inputs n n n n n
Applies to Schema Element Type
User Interaction
Waiting Event
Waiting Timer
Decision
End
Exception n n n n n n n n n n n
Action
Asynchronous Workflow
Exception
Nested Workflows
Predefined Task
Schedule Workflow
Scriptable Task
User Interaction
Waiting Event
Waiting Timer
Workflow
User Interaction
IN
Input parameters that the user must provide at a certain moment while the workflow runs.
The IN binding for this element.
The IN binding defines the way in which the schema element receives input from the element that precedes it in the workflow.
n n n n n n n
Action
Asynchronous Workflow
Custom Decision
Predefined Task
Schedule Workflow
Scriptable Task
Workflow
VMware, Inc. 29
vCenter Orchestrator Developer's Guide
Table 2-4. Properties Tabs per Schema Element (Continued)
Schema Element Property Tab Description
Info The schema element's general properties and description. The information the Info tab displays depends on the type of schema element.
OUT
Presentation
Scripting
Visual Binding
Workflows
The OUT binding for this 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.
Defines the layout of the input parameters dialog box the user sees if the workflow needs user input while it is running.
Shows the JavaScript function 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.
Shows a graphical 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.
Selects the workflows to nest.
n n n n n n n n n n n n
Applies to Schema Element Type n n n n n n n n n n n n n
Action
Asynchronous Workflow
Custom Decision
Decision
Nested Workflows
Note
Predefined Task
Schedule Workflow
Scriptable Task
User Interaction
Waiting Event
Waiting Timer
Workflow n n n n n n
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
Nested Workflows
Links and Bindings
Links between elements determine the logical flow of the workflow. Bindings populate elements with data from other elements by binding input and output parameters to workflow attributes.
To understand links and bindings, you must understand the difference between the logical flow of a workflow and the data flow of a workflow.
30 VMware, Inc.
Chapter 2 Developing Workflows
Logical Flow of a Workflow
The logical flow of a workflow is the progression of the workflow from one element to the next in the schema as the workflow runs. You define the logical flow of the workflow by linking elements in the schema.
The standard path is the path that the workflow takes through the logical flow if all elements run normally.
The exception path is the path that the workflow takes through the logical flow if an element does not run normally.
Different styles of arrows in the workflow schema denote the different paths that the workflow can take through its logical flow.
n n n
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 .
n A thick red dotted arrow denotes the exception path that the workflow takes if a workflow element does not run correctly.
shows an example workflow schema that demonstrates the different paths that workflows can take.
Figure 2-1. Different Workflow Paths Through the Logical Flow of the Workflow
This example workflow can take the following paths through its logical flow.
n Standard path, true decision result, no exceptions.
a The decision element returns true .
b The
SnapVMsInResourcePool
workflow runs successfully.
n c The sendHtmlEmail action runs successfully.
d The workflow ends successfully in the completed state.
Standard path, false
decision result, no exceptions.
a The decision element returns false .
b The operation the scriptable task element defines runs successfully.
c The sendHtmlEmail action runs successfully.
d The workflow ends successfully in the completed state.
VMware, Inc. 31
vCenter Orchestrator Developer's Guide 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.
n 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.
n The Start Workflow element cannot receive incoming links and has no exception link.
n n n
Exception elements can receive multiple incoming exception links, and have no outgoing or exception links.
Decision elements have two outgoing links that define the paths the workflow takes depending on the decision's true or false result. Decisions have no exception link.
End Workflow elements cannot have outgoing links or exception links.
Create Standard Path Links
You link elements by connecting them using the connector tool in the Schema tab of the workflow editor.
When you link one element to another, you always link the elements in the order in which they run in the workflow. You always start from the element that runs first to create a link between two elements.
Prerequisites
To link elements, you must have the workflow editor open and the Schema must contain elements.
Procedure
1 Click the connector tool button in the toolbar at the top of the Schema tab to activate the connector tool.
2 Click an element to link to another element.
3 Move the pointer over the highlighted element to link to another element.
A black rectangle appears at the bottom of the element.
4 Left-click inside the element near the black rectangle, hold down the left mouse button, and move the pointer to the target element.
An arrow appears between the two elements and the target element turns green.
5 Release the left mouse button.
The arrow remains between the two elements.
A standard path now links the elements.
32 VMware, Inc.
Chapter 2 Developing Workflows
What to do next
The elements are joined, but you have not defined the data flow. You must define the IN and OUT bindings to bind incoming and outgoing data to workflow attributes.
Data Flow of a Workflow
The data flow of a workflow is the manner in which workflow element input and output parameters bind to workflow attributes as each element of the workflow runs. You define the data flow of a workflow by using schema element bindings.
When an element in the workflow schema runs, it requires data in the form of input parameters. It takes the data for its input parameters by binding to a workflow attribute that you set when you create the workflow, or by binding to an attribute that a preceding element in the workflow set when it ran.
The element processes the data, possibly transforms it, and generates the results of its run in the form of output parameters. The element binds its resulting output parameters to new workflow attributes that it creates. Other elements in the schema can bind to these new workflow attributes as their input parameters. The workflow can generate the attributes as its output parameters at the end of its run.
shows a very simple workflow. The black arrows represent the element linking and the logical flow of the workflow. The red lines show the data flow of the workflow.
Figure 2-2. Example of Workflow Data Flow
The data flows through the workflow as follows.
1 The workflow starts with input parameters a and b.
2 The first element processes parameter a and binds the result of the processing to workflow attribute c.
3 The first element processes parameter b and binds the result of the processing to workflow attribute d.
4 The second element takes workflow attribute c as an input parameter, processes it, and binds the resulting output parameter to workflow attribute e.
5 The second element takes workflow attribute d as an input parameter, processes it, and generates output parameter f.
6 The workflow ends and generates workflow attribute f as its output parameter, the result of its run.
VMware, Inc. 33
vCenter Orchestrator Developer's Guide
Element Bindings
You must bind all workflow element input and output parameters to workflow attributes. Bindings set data in the elements, and define the output and exception behavior of the elements. Links define the logical flow of the workflow, whereas bindings define the data flow.
To set data in an element, generate ouput parameters from the element after processing, and handle any errors that might occur when the element runs, you must set the element binding.
IN bindings
OUT bindings
Exception 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.
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.
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.
I
MPORTANT
When you add an element that requires input and output parameters of a type that you already defined in the workflow, Orchestrator sets the bindings to these parameters. You must check that the parameters Orchestrator binds are correct, in case the workflow defines different parameters of the same type to which the element could bind.
Define Element Bindings
After you link elements to create the logical flow of the workflow, you define element bindings to define how each element processes the data it receives and generates.
Prerequisites
You must have a workflow schema in the Schema tab of the workflow editor, and have created links between the elements.
34 VMware, Inc.
Chapter 2 Developing Workflows
Procedure
1 Click an element on which to set the bindings.
The element is highlighted and the element attributes tabs appear at the bottom of the Schema tab.
2 Click the IN tab.
The contents of the IN tab depend on the type of element you selected.
n 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.
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.
n 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.
n n n
If you selected a predefined task, workflow, or action element, the OUT tab lists the possible local output parameters for that type of element, but the binding is not set.
If you selected another type of element, you can select from a list of output parameters and attributes you defined for the workflow by right-clicking in the OUT tab and selecting Bind to workflow
attribute/parameter.
If the required attribute does not exist, you can create it by right-clicking in the IN tab and selecting
Bind to workflow attribute/parameter > Create attribute/parameter in workflow.
7 Choose a parameter to bind.
8 Click the Source Parameter > Not set button.
9 Choose a source parameter to bind to the input parameter.
10 (Optional) If you did not define the parameter to which to bind, you can create it by clicking the Create
attribute/parameter in workflow button in the parameter selection dialog box.
You defined the input parameters that the element receives and the output parameters that it generates, and bound them to workflow attributes and parameters.
What to do next
You can create forks in the path of the workflow by defining decisions.
VMware, Inc. 35
vCenter Orchestrator Developer's Guide
Decisions
Workflows can implement decision functions that define different courses of action according to a Boolean true
or false
statement.
Decisions are forks in the workflow. Workflow decisions are made according to inputs provided by you, by other workflows, by applications, or by the environment in which the workflow is running. The value of the input parameter that the decision element receives determines which branch of the fork the workflow takes.
For example, a workflow decision might receive the power status of a given virtual machine as its input. If the virtual machine is powered on, the workflow takes a certain path through its logical flow. If the virtual machine is powered off, the workflow takes a different path.
Decisions are always Boolean functions. The only possible outcomes for each decision are true or false .
Custom Decisions
Custom decisions differ from standard decisions in that you define the decision statement in a script. Custom decisions return true or false according to the statement you define, as the following example shows.
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.
n 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.
n If you hold the pointer over the right side of the decision element, a red arrow appears at the bottom of the element. The red arrow represents the false path the workflow takes if the input parameter or attribute received by the decision element does not match the decision statement.
4 Left-click inside the left side of the decision element, hold down the left mouse button, and move the pointer to the target element.
A green arrow appears between the two elements and the target element turns green.
5 Release the left mouse button.
The green arrow remains between the two elements. You have defined the path the workflow takes when the decision element receives the expected value.
36 VMware, Inc.
Chapter 2 Developing Workflows
6 Left-click inside the right side of the decision element, hold down the left mouse button, and move the pointer to the target element.
A dotted red arrow appears between the two elements and the target element turns green.
7 Release the left mouse button.
The dotted red arrow remains between the two elements. You have defined the path the workflow takes when the decision element receives unexpected input.
You have defined two possible true
or false
paths for the workflow to take, depending on the input parameter or attribute the decision element receives.
What to do next
The decision element is linked to two other elements, but you did not define how the workflow determines which path to take. You must define the decision statement.
Create Workflow Branches Using Decisions
Decision elements are simple Boolean functions that you use to create branches in workflows. Decision elements determine whether or not the input received matches the decision statement you set. As a function of this decision, the workflow continues its course along one of two possible paths.
Prerequisites
You must have a decision element linked to two other elements in the schema in the workflow editor before you define the decision.
Procedure
1 Click the decision element.
2 Click the Decision tab in the element properties tabs at the bottom of the Schema tab.
3 Click the Not Set (NULL) link to select the possible source input parameter for this decision.
A dialog box appears, which lists all the attributes and input parameters you defined in this workflow.
4 Select an input parameter from the list by double-clicking it.
5 (Optional) If you did not define the source parameter to which to bind, you can create it by clicking the
Create attribute/parameter in workflow link in the parameter selection dialog box.
6 Select a decision statement from the drop-down menu.
The statements the menu proposes are contextual, and differ according to the type of input parameter selected.
7 Add a value for the statement to match.
Depending on the input type and the statement you select, you might see a Not Set (NULL) link in the value text box. Clicking this link gives you a predefined choice of values. Otherwise, for example for
Strings, this is a text box in which you provide a value.
You defined a statement for the decision element. When the decision element receives the input parameter, it compares the value of the input parameter to the value in the statement and determines whether the statement is true or false.
What to do next
You must set up how the workflow handles exceptions.
VMware, Inc. 37
vCenter Orchestrator Developer's Guide
Exception Handling
Exception handling catches any errors that occur when a schema element runs. Exception handling defines how the schema element behaves when the error occurs.
All elements in a workflow, except for decisions and start and end elements, contain a specific output parameter type that serves only for handling exceptions. If an element encounters an error during its run, it can send an error signal to an exception handler. Exception handlers catch the error and react according to the errors they receive. If the exception handlers you define cannot handle a certain error, you can bind an element's exception output parameter to an Exception element, which ends the workflow run in the failed
state.
Exceptions act as a try and catch sequence within a workflow element. If you do not need to handle a given exception in an element, you do not have to bind that element's exception output parameter.
The output parameter type for exceptions is always an errorCode object.
Create Exception Bindings
Elements can set bindings that define how the workflow behaves if it encounters an error in that element.
Prerequisites
The Schema tab of the workflow editor must contain elements.
Procedure
1 Click the element on which to set the exception binding.
2 Click the connector tool button in the toolbar at the top of the Schema tab or hold down Ctrl and move the pointer over the right of the element for which to set the exception binding.
A red rectangle appears on the right of the element.
3 Left-click inside the element near the red rectangle, hold down the left mouse button, and move the pointer to the target element.
A thick dotted red arrow links the two elements. The target element defines the behavior of the workflow if the element that links to it encounters an error.
4 Click the element that links to the exception handling element.
5 Click the Exceptions tab in the schema element properties tabs at the bottom of the Schema tab.
6 Click the Not set button to set the Output Exception Binding value.
n Select a parameter to bind to the exception output parameter from the exception attribute binding dialog box.
n Click Create parameter/attribute in workflow to create an exception output parameter.
7 Click the target element that defines the exception handling behavior.
8 Click the IN tab in the schema element properties tabs at the bottom of the Schema tab.
9 Right-click in the IN tab and select Bind to workflow parameter/attribute.
10 Select the exception output parameter and click Select.
38 VMware, Inc.
Chapter 2 Developing Workflows
11 Click the OUT tab for the exception handling element in the schema element properties tabs at the bottom of the Schema tab
12 Define the behavior of the exception handling element.
n Right-click in the OUT tab and select Bind to workflow parameter/attribute to select an output parameter for the exception handling element to generate.
n Click the Scripting tab and use JavaScript to define the behavior of the exception handling element.
You defined how the element handles exceptions.
What to do next
You must define how to obtain input parameters from users when they run the workflow.
Obtaining Input Parameters from Users When a Workflow Starts
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.
The way you organize parameters in the Presentation tab translates into the input parameters dialog box when the workflow runs, and in the dialog box that opens when you run a workflow from a Web view.
The Presentation tab also allows you to add descriptions of the input parameters to help users when they provide input parameters. You can also set properties and constraints on parameters in the Presentation tab to limit the parameters that users provide. If the parameters the user provides do not meet the constraints you set in the Presentation tab, the workflow will not run.
n
Creating the Input Parameters Dialog Box In the Presentation Tab on page 39
You define the layout of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab of the workflow editor.
n
Setting Parameter Properties on page 41
Orchestrator allows you to define properties to qualify the input parameter values that users provide when they run workflows. The parameter properties you define impose limits on the types and values of the input parameters the users provide.
Creating the Input Parameters Dialog Box In the Presentation Tab
You define the layout of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab of the workflow editor.
The Presentation tab allows you to group input parameters into categories and to define the order in which these categories appear in the input parameters dialog box.
Presentation Descriptions
You can add an associated description for each parameter or group of parameters, which appears in the input parameters dialog box. The descriptions provide information to the users to help them provide the correct input parameters. You can enhance the layout of the description text by using HTML formatting.
Defining Presentation Input Steps
By default, the input parameters dialog box lists all the required input parameters in a single list. To help users enter input parameters, you can define nodes, called input steps, in the presentation tab. Input steps group input parameters of a similar nature. The input parameters under an input step appear in a distinct section in the input parameters dialog box when the workflow runs.
VMware, Inc. 39
vCenter Orchestrator Developer's Guide
Defining Presentation Display Groups
Each input step can have nodes of its own called display groups. The display groups define the order in which parameter input text boxes appear within their section of the input parameters dialog box. You can define display groups independently of input steps.
Create the Presentation of the Input Parameters Dialog Box
You create the presentation of the dialog box in which users provide input parameters when they run a workflow in the Presentation tab in the workflow editor.
Prerequisites
You must have created a workflow and a defined list of input parameters.
Procedure
1 In the workflow editor, click the Presentation tab.
By default, all of the workflow's parameters appear under the main Presentation node in the order in which you create them.
2 Right-click the Presentation node and select Create new step.
A New Step node appears under the Presentation node.
3 Double-click the New Step node to provide it with an appropriate name and press Enter.
This name appears as a section header in the input parameters dialog box when the workflow runs.
4 Click the input step and add a description in the General tab in the bottom half of the Presentation tab.
This description appears in the input parameters dialog box to provide information to the users to help them provide the correct input parameters. You can enhance the layout of the description text by using
HTML formatting.
5 Right-click the input step you created and select Create display group.
A New Group node appears under the input step node.
6 Double-click the New Group node and provide it with an appropriate name.
This name appears as a subsection header in the input parameters dialog box when the workflow runs.
7 Click the display group and add a description in the General tab in the bottom half of the Presentation tab.
This description appears in the input parameters dialog box. You can enhance the layout of the description text by using HTML formatting. You can add a parameter value to a group description by using an OGNL statement, such as
${#param}
.
8 Repeat the preceding steps until you have created all the input steps and display groups to appear in the input parameters dialog box when the workflow runs.
9 Drag parameters from under the Presentation node to the steps and groups of your choice.
You created the layout of the input parameters dialog box through which users provide input parameter values when the workflow runs.
What to do next
You must set the parameter properties.
40 VMware, Inc.
Chapter 2 Developing Workflows
Setting Parameter Properties
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.
Parameter properties validate the input parameters and modify the way that text boxes appear in the input parameters dialog box. Some parameter properties can create dependencies between parameters.
Static and Dynamic Parameter Property Values
A parameter property value can be either static or dynamic. Static property values remain constant. If you set a property value to static, you set or select the property's value from a list that the workflow editor generates according to the parameter type.
Dynamic property values depend on the value of another parameter or attribute. You define the functions by which dynamic properties obtain values by using an object graph navigation language (OGNL) expression. If a dynamic parameter property value depends on the value of another parameter property value and the other parameter property value changes, the OGNL expression recalculates and changes the dynamic property value.
Set Parameter Properties
When a workflow starts, it validates input parameter values from users against any parameter properties that you set.
Prerequisites
You must have a workflow and defined a list of input parameters before setting the parameter constraints.
Procedure
1 In the workflow editor, click the Presentation tab.
2 Click a parameter in the Presentation tab.
The parameter's General and Properties tabs appear at the bottom of the Presentation tab.
3 Click the parameter's Properties tab.
4 Right-click in the Properties tab and select Add property.
A dialog box opens, presenting a list of the possible properties for a parameter of the type selected.
5 Select a property from the list presented in the dialog box and click OK.
The property appears in the Properties tab.
6 Under Value, make the property value either static or dynamic by selecting the corresponding symbol from the drop-down menu.
Option Description
Static property
Dynamic property
VMware, Inc. 41
vCenter Orchestrator Developer's Guide
7 If you set the property value to static, you select a property value according to the type of parameter for which you are setting the properties.
8 If you set the property value to dynamic, you define the function to obtain the parameter property value by using an OGNL expression.
The workflow editor provides help writing the OGNL expression.
a
Click the icon to obtain a list of all the attributes and parameters defined by the workflow that this expression can call upon.
b
Click the icon to obtain a list of all the actions in the Orchestrator API that return an output parameter of the type for which you are defining the properties.
Clicking items in the proposed lists of parameters and actions adds them to the OGNL expression.
9 Click Save at the bottom of the workflow editor.
You defined the properties of the workflow's input parameters.
What to do next
Validate and debug the workflow.
Workflow Input Parameter Properties
You can set parameter properties to constrain the input parameters that users provide when they run workflows.
The possible properties for each type of parameter are listed in Table 2-5 .
Table 2-5. Workflow Input Parameter Properties
Parameter Property
Maximum string length
Parameter Type
String
Minimum string length
Matching regular expression
Maximum number value
Minimum number value
Number format
Mandatory
Predefined answers
Predefined list of elements
String
String
Number
Number
Number
Any
All simple types
Any simple or complex types
Description
Sets a maximum length for the parameter.
Sets a minimum length for the parameter.
Validates the input using a regular expression.
Sets a maximum value for the parameter.
Sets a minimum value for the parameter.
Formats the input for the parameter.
Makes the parameter mandatory.
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.
Pre-defines a list of possible values for the property as an array of simple or complex types. Calls an action that returns an array of objects of the appropriate type.
42 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-5. Workflow Input Parameter Properties (Continued)
Parameter Property
Show parameter input
Hide parameter input
Matching expression
Show in inventory
Specify a root object to be shown in the chooser. Root object is provided from a paramter or attribute.
Select as
Default value
Custom validation
Auto start
Mandatory input
Data binding
Authorized only
Multi-lines text input
Parameter Type
Any
Any
Any parameter type obtained from a plug-in
Any parameter type obtained from a plug-in
Any parameter type obtained from a plug-in
Any parameter type obtained from a plug-in
Any
OGNL scriptable validation
Boolean
Boolean
Any
Any parameter type obtained from a plug-in
Any
Description
Shows or hides a parameter text box in the presentation dialog box, depending on the value of a preceding Boolean parameter.
Similar to Show parameter input, but takes the negative value of a previous
Boolean parameter.
The input parameter matches a given expression.
If set, you can run the present workflow on any object of this type by rightclicking it in the inventory view and selecting Run workflow.
Specifies the root object if the selector for this parameter is a hierarchical list selector.
Use a list or hierarchical list selector to select the parameter.
Default value for this parameter.
If the OGNL expression returns a string, the validation shows this string as the text of the error result.
Starts the workflow automatically.
Makes this parameter mandatory. The workflow will not run without it.
Binds to a property that you have already defined in another parameter.
Only authorized users can access this parameter.
Allows users to enter multiple lines of text in the input parameters dialog box.
Predefined Constant Values for OGNL Expressions
You can use predefined constants when you create OGNL expressions to obtain dynamic parameter property values.
Orchestrator defines the following constants for use in OGNL expressions.
Table 2-6. Predefined OGNL Constant Values
Constant Value
${#__current}
${#__username}
${#__userDisplayName}
${#__serverUrl}
${#__datetime}
Description
Current value of the custom validation property or matching expression property
Username of the user who started the workflow
Display name of the user who started the workflow
URL containing the IP address of the server from which the user starts the workflow
Current date and time
VMware, Inc. 43
vCenter Orchestrator Developer's Guide
Table 2-6. Predefined OGNL Constant Values (Continued)
Constant Value
${#__date}
${#__timezone}
Description
Current date, with time set to 00:00:00
Current timezone
Requesting User Interactions While a Workflow Runs
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.
For example, if a certain event occurs while a workflow runs, the workflow can request human interaction to decide what course of action to take. The workflow waits before continuing, either until the user responds to the request for information, or until the waiting time exceeds a possible timeout period. If the waiting time exceeds the timeout period, the workflow returns an exception.
The default attributes for user interactions are security.group
and timeout.date
. When you set the security.group
attribute to a given LDAP user group, you limit the permission to respond to the user interaction request to members of that user group.
When you set the timeout.date
attribute, you set a time and date until which the workflow waits for the information from the user. You can set an absolute date, or you can create a scripted workflow element to calculate a time relative to the current time.
Procedure
1
Add a User Interaction to a Workflow on page 45
You request input parameters from users during a workflow run by adding a User Interaction schema element to the workflow. When a workflow encounters a User Interaction element, it suspends its run and waits for the user to provide the data that it requires.
2
Set the User Interaction security.group Attribute on page 45
The security.group
attribute of a user interaction element sets which users or groups of users have permission to respond to the user interaction.
3
Set the timeout.date Attribute to an Absolute Date on page 46
You set the timeout.date
attribute for a user interaction to set how long the workflow waits for a user to respond to a user interaction.
4
Calculate a Relative Timeout for User Interactions on page 47
You can calculate in a Date object a relative time and date at which a user interaction times out.
5
Set the timeout.date Attribute to a Relative Date on page 48
You can set the timeout.date
attribute of a User Interaction element to a relative time and date by binding it to a Date object. You define the object in a scripted function.
6
Define the External Inputs for a User Interaction on page 49
You specify the information that users must provide during a workflow run as the input parameters of a user interaction.
7
Define User Interaction Exception Behavior on page 49
If a user does not provide the input parameters within the timeout period, the user interaction returns an exception. You can define the exception behavior in a scripted function.
44 VMware, Inc.
Chapter 2 Developing Workflows
8
Create the Input Parameters Dialog Box for the User Interaction on page 51
Users provide input parameters during a workflow run in an input parameters dialog box, in the same way that they provide input parameters when a workflow first starts.
9
Respond to a Request for a User Interaction on page 52
Workflows that require interactions from users during their run suspend their run either until the user provides the required information or until the workflow times out.
Add a User Interaction to a Workflow
You request input parameters from users during a workflow run by adding a User Interaction schema element to the workflow. When a workflow encounters a User Interaction element, it suspends its run and waits for the user to provide the data that it requires.
Prerequisites n n n
Create a workflow
Open the workflow for editing in the workflow editor
Add some elements to the workflow schema
Procedure
1 Drag a User Interaction element to the appropriate position in the workflow schema.
2 Link the User Interaction element to the elements that precede and follow it.
3 Click the User Interaction element to display its properties tabs in the bottom half of the Schema tab.
4 Provide a name and a description for the user interaction in the Info tab.
5 Click Save.
You added a user interaction element to a workflow. When the workflow reaches this element, it waits for information from the user before continuing its run.
What to do next
Set the security.group attribute of the user interaction to limit permission to respond to the user interaction to a user or user group. See
“Set the User Interaction security.group Attribute,” on page 45.
Set the User Interaction security.group Attribute
The security.group
attribute of a user interaction element sets which users or groups of users have permission to respond to the user interaction.
Prerequisites n n n n
Create a workflow.
Open the workflow for editing in the workflow editor.
Add some elements and a user interaction to the workflow schema.
Identify an LDAP user group to respond to the user interaction request.
Procedure
1 Click the User Interaction element in the workflow schema.
2 Click the Attributes tab for the user interaction.
3 Click Not set for the security.group
source parameter to set which users can respond to the user interaction.
VMware, Inc. 45
vCenter Orchestrator Developer's Guide
4 (Optional) Select NULL to allow all users to respond to the request for user interaction.
5 To limit the permission to respond to a specific user or user group, click Create parameter/attribute in
workflow.
The Parameter information dialog box opens.
6 Name the parameter.
7 Select Create workflow ATTRIBUTE with the same name to create the
LdapGroup
attribute in the workflow.
8 Click Not set for the parameter value to open the LdapGroup selection box.
9 Type the name of the LDAP user group in the Filter text box.
10 Select the LDAP user group from the list and click Select.
For example, selecting the Administrators group means that only members of that group can respond to this request for user interaction.
You limited the permission to respond to the user interaction request.
11 Click OK to close the Parameter information dialog box.
You set the security.group
attribute for the user interaction.
What to do next
Set the timer.date
attribute to set the timeout period for the user interaction.
n
To set the timeout to an absolute date and time, see “Set the timeout.date Attribute to an Absolute
n
Relative Timeout for User Interactions,” on page 47.
Set the timeout.date Attribute to an Absolute Date
You set the timeout.date
attribute for a user interaction to set how long the workflow waits for a user to respond to a user interaction.
You set an absolute time and date in the Date object. When the time on the given date arrives, the workflow that is waiting for a user interaction times out and ends in the
Failed
state. For example, you can set the user interaction to timeout at midday on February 12th. To calculate a timeout that is relative to the current time
and date, see “Calculate a Relative Timeout for User Interactions,” on page 47.
Prerequisites n n n
Open a workflow for editing in the workflow editor.
Add a user interaction element to the workflow schema.
Set the security.group
attribute for the user interaction.
Procedure
1 Click the User Interaction element in the workflow schema.
2 Click the Attributes tab for the user interaction.
3 Click Not set for the timeout.date
source parameter to set the timeout parameter value.
4 (Optional) Select NULL to allow the user interaction to set the workflow to wait indefinitely for the user to respond to the user interaction.
46 VMware, Inc.
Chapter 2 Developing Workflows
5 Click Create parameter/attribute in workflow to set the workflow to fail after a timeout period.
The Parameter information dialog box opens.
6 Name the parameter.
7 Select Create workflow ATTRIBUTE with the same name to create a
Date
attribute in the workflow.
8 Click Not set for the parameter Value.
9 Use the calendar to select an absolute date and time until which the workflow waits for the user to respond.
10 Click OK to close the calendar.
11 Click OK to close the Parameter information dialog box.
You set the timeout.date
attribute to an absolute date. The workflow times out if the user does not respond to the user interaction before this time and date.
What to do next
Inputs for a User Interaction,” on page 49.
Calculate a Relative Timeout for User Interactions
You can calculate in a Date object a relative time and date at which a user interaction times out.
You can set an absolute time and date in a Date object. When the time on the given date arrives, the request for a user interaction times out. Alternatively, you can create a workflow element that calculates and generates a relative Date object according to a function that you define. For example, you can create a relative Date object that adds 24 hours to the current time.
Prerequisites n n n
Open a workflow for editing in the workflow editor.
Add a user interaction element to the workflow schema.
Set the security.group
attribute for the user interaction.
Procedure
1 Drag a Scriptable Task element from the Generic menu to the schema of a workflow, above the element that requires the relative Date object for its timeout.date
attribute.
2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema.
3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab.
4 Provide a name and description for the scripted workflow element in the Info properties tab.
5 Right-click in the OUT properties tab, and select Bind to workflow parameter/attribute.
6 Click Create parameter/attribute in workflow to create a workflow attribute.
a Name the attribute timerDate .
b Select
Date
from the list of attribute types.
c Select Create workflow ATTRIBUTE with the same name.
d Leave the attribute value set to Not set, because a scripted function will provide this value.
e Click OK.
7 Click the Scripting tab for the scripted workflow element.
VMware, Inc. 47
vCenter Orchestrator Developer's Guide
8 Define a function to calculate and generate a
Date
object named timerDate
in the scripting pad in the
Scripting tab.
For example, you can create a Date object by implementing the following JavaScript function, in which the timeout period is a relative delay in milliseconds.
timerDate = new Date();
System.log( "Current date : '" + timerDate + "'" ); timerDate.setTime( timerDate.getTime() + (86400 * 1000) );
System.log( "Timer will expire at '" + timerDate + "'" );
The preceding example JavaScript function defines a Date object that obtains the current date and time by using the getTime
method and adds 86,400,000 milliseconds, or 24 hours. The Scriptable Task element generates this value as its output parameter.
9 Click Save.
You created a function that calculates a time and date relative to the current time and date and generates a
Date object. A User Interaction element can receive this Date object as an input parameter to set the timeout period until which it waits for input from the user. When the workflow arrives at the User Interaction element, it suspends its run and waits either until the user provides the required information, or for 24 hours before it times out.
What to do next
You must bind the
Date
object to the User Interaction element's timeout.date
parameter. See
“Set the timeout.date Attribute to a Relative Date,” on page 48.
Set the timeout.date Attribute to a Relative Date
You can set the timeout.date
attribute of a User Interaction element to a relative time and date by binding it to a Date object. You define the object in a scripted function.
If you create a relative
Date
object in a scripted function, you can bind the timeout.date
attribute of a user interaction to this Date object. For example, if you bind the timeout.date
attribute to a Date object that adds 24 hours to the current time, the user interaction times out after waiting for 24 hours.
Prerequisites n n n
Add a user interaction element to the workflow schema.
Set the security.group
attribute for the user interaction.
Create a scripted function that calculates a relative time and date and encapsulates it in a Date object in
the workflow. See “Calculate a Relative Timeout for User Interactions,” on page 47.
Procedure
1 Click the User Interaction element in the workflow schema.
2 Click the Attributes tab for the user interaction.
3 Click Not set for the timeout.date
source parameter to set the timeout parameter value.
4 Select the Date object that encapsulates a relative time and date that you defined in a scripted function and click Select.
You set the timeout.date
attribute to a relative date and time that a scripted function calculates.
What to do next
Inputs for a User Interaction,” on page 49.
48 VMware, Inc.
Chapter 2 Developing Workflows
Define the External Inputs for a User Interaction
You specify the information that users must provide during a workflow run as the input parameters of a user interaction.
When a workflow reaches a user interaction element, it waits until a user provides the information that the user interaction requires as its input parameters.
Prerequisites n n n
Add a user interaction element to the workflow schema.
Set the security.group
attribute for the user interaction.
Set the timer.date
attribute for the user interaction
Procedure
1 Click the User Interaction element in the workflow schema.
2 Click the External Inputs tab.
3 Right-click in the External Inputs tab and select Bind to workflow parameter/attribute to define the parameters that the user must provide in the user interaction.
4 (Optional) If you already defined the input parameters in the workflow, select the parameters from the proposed list.
5 Click Create parameter/attribute in the workflow to create a workflow attribute to bind to the input parameter that the user provides.
6 Give the parameter an appropriate name.
7 Select the input parameter type from the list of types by searching for an object type in the Filter box.
For example, if the user interaction requires the user to provide a virtual machine as an input parameter, select VC:VirtualMachine .
8 Select Create workflow ATTRIBUTE with the same name to bind the input parameter that the user provides to a new attribute in the workflow.
9 Leave the input parameter value set to Not set.
The user provides this value when they respond to the user interaction during the workflow run.
10 Click OK to close the Parameter information dialog box.
You defined the input parameters that the user provides during a user interaction.
What to do next
Exception Behavior,” on page 49.
Define User Interaction Exception Behavior
If a user does not provide the input parameters within the timeout period, the user interaction returns an exception. You can define the exception behavior in a scripted function.
If you do not define the action for the workflow to take if the user interaction times out, the workflow ends in the Failed state. Defining the exception behavior is a good workflow development practice.
VMware, Inc. 49
vCenter Orchestrator Developer's Guide
Prerequisites n n n
Add a user interaction element to the workflow schema.
Set the security.group
and timer.date
attributes for the user interaction.
Define the external input parameters of the user interaction.
Procedure
1 Click the User Interaction element in the workflow schema.
2 Click the Exception tab.
3 Click Not set for the output exception binding.
4 Click Create parameter/attribute in workflow to create an exception attribute to which to bind the user interaction.
The Parameter information dialog box opens.
5 Create an errorCode attribute.
An errorCode attribute has the following default properties: n Name: errorCode n n
Type: string
Create: Create workflow ATTRIBUTE with the same name n Value: Type an appropriate error message.
6 Click OK to close the Parameter information dialog box.
7 Drag a scriptable task element next to the user interaction element in the workflow schema.
8 Link the exception output of the user interaction element to the scriptable task element.
A dotted red arrow between the two elements represents the exception link. The scriptable task element binds automatically to the errorCode attribute from the user interaction.
9 Double-click the scriptable task element and provide an appropriate name.
For example, Log timeout .
10 In the Scripting tab of the scriptable task element, write a JavaScript function to handle the exception.
For example, to record the timeout in the Orchestrator log, write the following function:
System.log("No response from user. Timed out.");
11 Link and bind the scriptable task element that handles exceptions to the element that follows it in the workflow.
For example, link and bind the scriptable task element to a Throw exception element to end the workflow with an error.
You defined the exception behavior if the user interaction times out.
What to do next
Create the dialog box in which users provide input parameters. See
“Create the Input Parameters Dialog Box for the User Interaction,” on page 51.
50 VMware, Inc.
Chapter 2 Developing Workflows
Create the Input Parameters Dialog Box for the User Interaction
Users provide input parameters during a workflow run in an input parameters dialog box, in the same way that they provide input parameters when a workflow first starts.
You create the layout of the dialog box in the Presentation tab of the user interaction element, not in the
Presentation tab for the whole workflow. The Presentation tab of the whole workflow creates the layout of the input parameters dialog box that appears when you start a workflow. The Presentation tab of the user interaction element creates the layout of the input parameters dialog box that opens when a workflow arrives at a user interaction element during its run.
Prerequisites n n n n
Add a user interaction element to the workflow schema.
Set the security.group
and timer.date
attributes for the user interaction.
Define the external input parameters of the user interaction.
Define the exception behavior.
Procedure
1 Click the User Interaction element in the workflow schema.
2 Click the Presentation tab of the user interaction element.
The Presentation tab shows the external input parameters that you created for the user interaction.
3 (Optional) Right-click the Presentation node in the Presentation tab and select Create new step.
Steps allow you to create sections in the dialog box, with descriptions and headings under which you can organize the input parameters.
4 (Optional) Right-click the Presentation node in the Presentation tab and select Create display group.
Display groups allow you to sort the order in which input parameters appear in the steps, and allow you to add sub-headers and instructions to the dialog box.
5 Click an input parameter in the list and add a description of the input parameter in the General tab for that parameter.
The description text that you type appears as a label in the input parameters dialog box to inform the user of the information they must provide when they respond to the user interaction.
6 Define input parameter properties.
Input parameter properties allow you to qualify the input parameter values that users can provide, and to determine parameter values dynamically by using OGNL expressions.
7 Click Save and close to close the workflow editor.
You created the input parameters dialog box in which users provide input parameters to respond to a user interaction during a workflow run.
What to do next
For information about creating the presentation steps and groups and setting input parameter properties, see
“Creating the Input Parameters Dialog Box In the Presentation Tab,” on page 39.
VMware, Inc. 51
vCenter Orchestrator Developer's Guide
Respond to a Request for a User Interaction
Workflows that require interactions from users during their run suspend their run either until the user provides the required information or until the workflow times out.
Workflows that require user interactions define which users can provide the required information and direct the requests for interaction.
Prerequisites
Log in to the Orchestrator client.
At least one workflow in Waiting for User Interaction state.
Procedure
1 Click the My Orchestrator view in the Orchestrator client.
2 Click the Waiting for Input tab.
The Waiting for Input tab lists the workflows that are waiting for user inputs that you or members of your user group have permission to provide.
3 Double-click a workflow that is waiting for input.
The workflow token that is waiting for input appears in the Workflows hierarchical list with the following symbol: .
4 Right-click the workflow token and select Answer.
5 Follow the instructions in the input parameters dialog box to provide the information that the workflow requires.
You provided information to a workflow that was waiting for user input during its run.
Calling Workflows Within Workflows
Workflows can call on other workflows during their run. A workflow can start another workflow either because it requires the result of the other workflow as an input parameter for its own run, or it can start a workflow and let it continue its own run independently. Workflows can also start a workflow at a given time in the future, or start multiple workflows simultaneously.
n n
Workflow Elements that Call Workflows on page 53
There are four ways to call other workflows from within a workflow. Each way of calling a workflow or workflows is represented by a different workflow schema element.
Call a Workflow Synchronously on page 55
Calling a workflow synchronously runs the called workflow as a part of the run of the calling workflow.
The calling workflow can use the called workflow's output parameters as input parameters when it runs its subsequent schema elements.
n
Call a Workflow Asynchronously on page 55
Calling a workflow asynchronously runs the called workflow independently of the calling workflow.
The calling workflow continues its run without waiting for the called workflow to complete.
52 VMware, Inc.
Chapter 2 Developing Workflows n n
Schedule a Workflow on page 56
You can call a workflow from a workflow and schedule it to start at a later time and date.
Call Several Workflows Simultaneously on page 57
Calling several workflows simultaneously runs the called workflows synchronously as part of the run of the calling workflow. The calling workflow waits for all of the called workflows to complete before it continues. The calling workflow can use the results of the called workflows as input parameters when it runs its subsequent schema elements.
Workflow Elements that Call Workflows
There are four ways to call other workflows from within a workflow. Each way of calling a workflow or workflows is represented by a different workflow schema element.
Synchronous Workflows A workflow can start another workflow synchronously. The called workflow runs as an integral part of the calling workflow's run, and runs in the same memory space as the calling workflow. The calling workflow starts another workflow, then waits until the end of the called workflow's run before it starts running the next element in its schema. Usually, you call a workflow synchronously because the calling workflow requires the output of the called workflow as an input parameter for a subsequent schema element. For example, a workflow can call the Start virtual machine and wait workflow to start a virtual machine, and then obtain the IP address of this virtual machine to pass to another element or to a user by email.
Asynchronous
Workflows
A workflow can start a workflow asynchronously. The calling workflow starts another workflow, but the calling workflow immediately continues running the next element in its schema, without waiting for the result of the called workflow. The called workflows run with input parameters that the calling workflow defines, but the lifecycle of the called workflow is independent from the lifecycle of the calling workflow. Asynchronous workflows allow you to create chains of workflows that pass input parameters from one workflow to the next. For example, a workflow can create various objects during its run. The workflow can then start asynchronous workflows that use these objects as input parameters in their own runs. When the original workflow has started all the required workflows and run its remaining elements, it ends. However, the asynchronous workflows it started continue their runs independently of the workflow that started them.
To make the calling workflow wait for the result of the called workflow, either use a nested workflow or create a scriptable task that retrieves the state of the workflow token of the called workflow and then retrieves the result of the workflow when it completes.
Scheduled Workflows A workflow can call a workflow but defer starting that workflow until a later time and date. The calling workflow then continues its run until it ends. Calling a scheduled workflow creates a task to start that workflow at the given time and date. When the calling workflow has run, you can view the scheduled workflow in the Scheduler and My Orchestrator views in the Orchestrator client.
VMware, Inc. 53
vCenter Orchestrator Developer's Guide
Nested Workflows
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.
A workflow can start several workflows simultaneously by nesting several workflows in a single schema element. All the workflows listed in the nested workflow element start simultaneously when the calling workflow arrives at the nested workflows element in its schema. Significantly, each nested workflow starts in a different memory space from the memory space of the calling workflow. The calling workflow waits until all the nested workflows have completed their runs before it starts running the next element in its schema. The calling workflow can thus use the results of the nested workflows as input parameters when it runs its remaining elements.
Propagate Workflow Changes to other Workflows
If you call a workflow from within another workflow, Orchestrator imports that workflow's input parameters into the calling workflow at the moment you add the workflow element to the schema, rather than referencing it.
As a consequence, if you change the called workflow after you have added it to another workflow, the calling workflow calls on the new version of the called workflow, but does not import any new input parameters. To prevent changes to workflows affecting the behavior of other workflows that call them, Orchestrator does not propagate the new input parameters automatically to the calling workflows.
To propagate parameters from one workflow to other workflows that call it, you must find the workflows that call the workflow, and synchronize the workflows manually.
Prerequisites
You need a workflow that another workflow or workflows call.
Procedure
1 Modify and save a workflow that other workflows call.
2 Close the workflow editor.
3 Navigate to the workflow you changed in the hierarchical list in the Workflows view in the Orchestrator client.
4 Right-click the workflow, and select References > Find Elements that Use this Element.
A list of workflows that call this workflow appears.
5 Double-click a workflow in the list to highlight it in the Workflows view in the Orchestrator client.
6 Right-click the workflow, and select Edit.
The workflow editor opens.
7 Click the Schema tab in the workflow editor.
8 Right-click the workflow element for the changed workflow from the workflow schema and select
Synchronize > Synchronize Parameters.
9 Click Continue in the confirmation dialog box.
10 Save and close the workflow editor.
to
Step 10 for all the workflows that use the modified workflow.
You propagated a changed workflow to other workflows that call it.
54 VMware, Inc.
Chapter 2 Developing Workflows
Call a Workflow Synchronously
Calling a workflow synchronously runs the called workflow as a part of the run of the calling workflow. The calling workflow can use the called workflow's output parameters as input parameters when it runs its subsequent schema elements.
You call workflows synchronously from another workflow by using the Workflow element.
Prerequisites n n
Open a workflow for editing in the workflow editor
Add some elements to the workflow schema
Procedure
1 Drag a Workflow element from the Action & Workflow menu to the appropriate position in the workflow schema.
The Choose workflow selection dialog box appears.
2 Search for ands select the workflow you want and click OK.
If the search returns a partial result, narrow your search criterion or increase the number of search results from the Tools > User preferences menu in the client.
3 Link the Workflow element to the elements that precede and follow it in the workflow schema.
4 Click the Workflow element to show its properties tabs in the bottom half of the Schema tab.
5 Bind the required input parameters to the workflow in the IN tab of the workflow schema element.
6 Bind the required output parameters to the workflow in the OUT tab of the workflow schema element's.
7 Define the exception behavior of the workflow in the Exceptions tab.
8 Click Save at the bottom of the workflow editor.
You called a workflow synchronously from another workflow. When the workflow reaches the synchronous workflow during its run, the synchronous workflow starts, and the initial workflow waits for it to complete before continuing its run.
What to do next
You can call a workflow asynchronously from a workflow.
Call a Workflow Asynchronously
Calling a workflow asynchronously runs the called workflow independently of the calling workflow. The calling workflow continues its run without waiting for the called workflow to complete.
You call workflows asynchronously from another workflow by using the Asynchronous Workflow element.
Prerequisites n n
Open a workflow for editing in the workflow editor
Add some elements to the workflow schema
VMware, Inc. 55
vCenter Orchestrator Developer's Guide
Procedure
1 Drag an Asynchronous Workflow element from the Action & Workflow menu to the appropriate position in the workflow schema.
The Choose workflow selection dialog box appears.
2 Search for and select the desired workflow from the list and click OK.
3 Link the Asynchronous Workflow element to the elements that precede and follow it in the workflow schema.
4 Click the Asynchronous Workflow element to show its properties tabs in the bottom half of the
Schema tab.
5 Bind the required input parameters to the workflow in IN tab of the asynchronous workflow element.
6 Bind the required output parameter in the OUT tab of the asynchronous workflow element.
You can bind the output parameter either to the called workflow, or to that workflow's result.
n Bind to the called workflow to return that workflow as an output parameter n Bind to the workflow token of the called workflow to return the result of running the called workflow.
7 Define the exception behavior of the asynchronous workflow element in the Exceptions tab.
8 Click Save at the bottom of the workflow editor.
You called a workflow asynchronously from another workflow. When the workflow reaches the asynchronous workflow during its run, the asynchronous workflow starts, and the initial workflow continues its run without waiting for the asynchronous workflow to finish.
What to do next
You can schedule a workflow to start at a later time and date.
Schedule a Workflow
You can call a workflow from a workflow and schedule it to start at a later time and date.
You schedule workflows in another workflow by using the Schedule Workflow element.
Prerequisites
Create a workflow, open it for editing in the workflow editor, and add some elements to the workflow schema.
Procedure
1 Drag a Schedule Workflow element from the Action & Workflow menu to the appropriate position in the workflow schema.
2 Search for the workflow to call by typing part of its name in the text box.
3 Select the workflow from the list and click OK.
4 Link the Schedule Workflow element to the elements that precede and follow it in the workflow schema.
5 Click the Schedule Workflow element to show its properties tabs in the bottom half of the Schema tab.
6 Click the IN property tab.
A parameter named workflowScheduleDate appears in the list of properties to define, together with the input parameters of the calling workflow.
7 Click Not set for the workflowScheduleDate parameter to set the parameter.
8 Click Create parameter/attribute in workflow to create the parameter and set the parameter value.
56 VMware, Inc.
Chapter 2 Developing Workflows
9 Click Not set for Value to set the parameter value.
10 Use the calendar that appears to set the date and time to start the scheduled workflow and click OK.
11 Bind the remaining input parameters to the scheduled workflow in the IN tab of the scheduled workflow element.
12 Bind the required output parameters to the
Task
object in the OUT tab of the scheduled workflow element.
13 Define the exception behavior of the scheduled workflow element in the Exceptions tab.
14 Click Save at the bottom of the workflow editor.
You scheduled a workflow to start at a given time and date from another workflow.
What to do next
You can call multiple workflows simultaneously from a workflow.
Call Several Workflows Simultaneously
Calling several workflows simultaneously runs the called workflows synchronously as part of the run of the calling workflow. The calling workflow waits for all of the called workflows to complete before it continues.
The calling workflow can use the results of the called workflows as input parameters when it runs its subsequent schema elements.
You call several workflows simultaneously from another workflow by using the Nested Workflows element.
You can use nested workflows to run workflows with user credentials that are different from the credentials of the user of the calling workflow.
Prerequisites n n
Open a workflow for editing in the workflow editor.
Add some elements to the workflow schema.
Procedure
1 Drag a Nested Workflows element from the Action & Workflow menu to the appropriate position in the workflow schema.
The Choose workflow selection dialog box appears.
2 Search for and select a workflow to start and click OK.
3 Link the Nested Workflows element to the elements that precede and follow it in the workflow schema.
4 Click the Nested Workflows element to show its properties tabs in the bottom half of the Schema tab.
5 Click the Workflows tab.
The workflow you selected in
appears in the tab.
6 Set the IN and OUT bindings for this workflow in the IN and OUT tabs in the right panel of the
Workflows schema element properties tab.
7 Click the Connection Info tab in the right panel of the Workflows schema element properties tab.
The Connection Info tab allows you to access workflows stored in a different server to the local one, using the appropriate credentials.
8 To access workflows on a remote server, select Remote and click Not set to provide a host name or IP address for the remote server.
VMware, Inc. 57
vCenter Orchestrator Developer's Guide
9 Define the credentials with which to access the remote server.
n Select Inherit to use the same credentials as the user who runs the calling workflow.
n Select Dynamic and click Not set to select a set of dynamic credentials that a parameter of the credentials
type defines elsewhere in the workflow.
n Select Static and click Not set to enter the credentials directly.
10 Click the Add Workflow button in the Workflows tab to select more workflows to add to the nested workflow element.
to
to define the settings for each of the workflows you add.
12 Click the nested workflow element in the workflow schema.
The number of workflows nested in the element appears as a numeral on the nested workflows element.
You called several workflows simultaneously from a workflow.
What to do next
You can define long-running workflows.
Running a Workflow on a Selection of Objects
You can 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.
You can use one of the following methods to run a workflow on a selection of objects.
n Run the Library > vCenter > Batch > Run a workflow on a selection of objects workflow.
n n n
Create a workflow that calls the Orchestrator > Start workflows in a series or Start workflows in
parallel workflows.
Create a workflow that obtains an array of objects and runs a workflow on each object in the array in a loop of workflow elements.
Run a workflow from JavaScript by calling the Workflow.execute() method in a For loop in a scripted element in a workflow.
Which method you choose to run a workflow on a selection of objects depends on the workflow to run and can affect the performance of the workflow. For example, running the Run a workflow on a selection of objects workflow is the simplest way to run a workflow on multiple objects and requires no workflow development, but it can only run workflows that take a single input parameter.
Creating a workflow that calls the Start workflows in a series or Start workflows in parallel workflows allows you to run on multiple objects workflows that take more than one input parameter. The calling workflow must create a properties array to pass the input parameters to the Start workflows in a series or Start workflows in parallel workflow. These workflows are only for use in other workflows. Do not run them directly.
Running a workflow in a For loop in a scripted element is faster than running a workflow in a loop of workflow elements, but it is less flexible and limits the potential for reuse. Most importantly, running a workflow in a scripted loop loses the checkpointing that Orchestrator performs when it starts each element in a workflow run. As a consequence, if the Orchestrator server stops while the scripted loop is running, when the server restarts, the workflow will resume at the beginning of the scripted element, repeating the whole loop. If the
Orchestrator server stops while running a workflow with a loop of workflow elements, the workflow will resume at the specific element in the loop that was running when the server stopped.
For more information about the Batch workflows, see the vCenter Orchestrator Administration Guide.
How to create a workflow that runs a workflow on an array of objects in a loop of workflow elements is
demonstrated in “Develop a Complex Workflow,” on page 92.
58 VMware, Inc.
Chapter 2 Developing Workflows
How to run a workflow in a scripted
For
loop is demonstrated in
“Workflow Scripting Examples,” on page 129.
Implement the Start Workflows in a Series and Start Workflows in Parallel
Workflows
You can use the Start workflows in a series and Start workflows in parallel workflows to run a workflow on a selection of objects.
You cannot run the Start workflows in a series and Start workflows in parallel workflows directly. You must include them in another workflow that you create. To use the Start workflows in a series and Start workflows in parallel workflows to run a workflow on a selection of objects, you must obtain the objects on which to run the workflow. You pass these objects and any other input parameters that the workflow requires to the workflow as an array of properties. The Start workflows in a series and Start workflows in parallel workflows emit the results of running the workflow on the selection of objects as an array of WorkflowToken objects.
You implement the Start workflows in a series and Start workflows in parallel workflows in the same way.
The Start workflows in a series workflow runs the workflow on each object sequentially. The Start workflows in parallel workflow runs the workflow on all the objects simultaneously.
Prerequisites
Open a workflow for editing in the workflow editor.
Procedure
1 In the workflow schema, add a scriptable task element or an action to obtain a list of objects on which to run the workflow.
For example, to run a workflow on all the virtual machines in a virtual machine folder, you can add the getAllVirtualMachinesByFolder action to the workflow.
2 Link the scripted element or action and bind the input and output of the scripted element or action to workflow inputs or attributes.
For example, you can bind the vmFolder
input of the getAllVirtualMachinesByFolder
action to a workflow input parameter and the actionResult output to a workflow attribute in the calling workflow.
3 Add a scriptable task element to cast the list of objects into a properties array.
For example, if the objects on which to run the workflow are an array of virtual machines, allVMs , returned by the actionResult output of the getAllVirtualMachinesByFolder action, you can write the following script to cast the objects into a properties array.
propsArray = new Array(); for each (var vm in allVMs) {
var prop = new Properties();
prop.put("vm", vm);
propsArray.push(prop);
}
4 Link the scriptable task element and bind its inputs and outputs to workflow attributes.
In the example scriptable task element in Step 3
, you bind the input to the allVMs array of virtual machines and you create the propsArray output attribute as an array of Properties objects.
5 Add a workflow element to the workflow schema.
6 Select either of the Start workflows in a series or Start workflows in parallel workflows and link the workflow element to the other elements.
VMware, Inc. 59
vCenter Orchestrator Developer's Guide
7 Bind the wf
input of the Start workflows in a series or Start workflows in parallel workflow to the workflow to run on the objects.
For example, to remove any snapshots of all the virtual machines returned by the getAllVirtualMachinesByFolder action, select the Remove all snapshots workflow.
8 Bind the parameters input of the Start workflows in a series or Start workflows in parallel workflow to the array of
Properties
objects that contains the objects on which to run the workflow.
For example, bind the parameters input to the propsArray
9 (Optional) Bind the workflowTokens output of the Start workflows in a series or Start workflows in parallel workflow to an attribute in the workflow.
10 Add and link an end element to the workflow, or continue adding more elements that use the results of running the Start workflows in a series or Start workflows in parallel workflow.
You created a workflow that uses either of the Start workflows in a series or Start workflows in parallel workflows to run a workflow on a selection of objects.
Developing Long-Running Workflows
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.
Every running workflow consumes a system thread. When a workflow reaches a long-running workflow element, the long-running workflow element sets the workflow into a passive state. The long-running workflow element then passes the workflow information to a single thread that polls the system for all longrunning workflow elements running in the server. Rather than each long-running workflow element constantly attempting to retrieve information from the system, long-running workflow elements remain passive for a set duration, while the long-running workflow thread polls the system on its behalf.
You set the duration of the wait in one of the following ways: n n
Set a timer, encapsulated in a Date object, that suspends the workflow until a certain time and date. You implement long-running workflow elements that are based on a timer by including a Waiting Timer element in the schema.
Define a trigger event, encapsulated in a Trigger object, that restarts the workflow after the trigger event occurs. You implement long-running workflow elements that are based on a trigger by adding a Waiting
Event element or a User Interaction element in the schema.
Set a Relative Time and Date for Timer-Based Workflows
You can set the timer.date
attribute of a Waiting Timer element to a relative time and date by binding it to a
Date object. You define the Date object in a scripted function.
When the time on the given date arrives, the long-running workflow that is based on a timer reactivates and continues its run. For example, you can set the workflow to reactivate at midday on February 12. Alternatively, you can create a workflow element that calculates and generates a relative Date object according to a function that you define. For example, you can create a relative Date object that adds 24 hours to the current time.
Prerequisites
You created a workflow, opened it for editing in the workflow editor, and added some elements to the workflow schema.
60 VMware, Inc.
Chapter 2 Developing Workflows
Procedure
1 Drag a Scriptable Task element from the Generic menu to the schema of a workflow, above the element that requires the relative
Date
object for its timeout.date
attribute.
2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema.
3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab.
4 Provide a name and description for the scripted workflow element in the Info properties tab.
5 Right-click in the OUT properties tab, and select Bind to workflow parameter/attribute.
6 Click Create parameter/attribute in workflow to create a workflow attribute.
a Name the attribute timerDate .
b Select Date from the list of attribute types.
c Select Create workflow ATTRIBUTE with the same name.
d Leave the attribute value set to Not set, because a scripted function will provide this value.
e Click OK.
7 Click the Scripting tab for the scripted workflow element.
8 Define a function to calculate and generate a
Date
object named timerDate
in the scripting pad in the
Scripting tab.
For example, you can create a Date object by implementing the following JavaScript function, in which the timeout period is a relative delay in milliseconds.
timerDate = new Date();
System.log( "Current date : '" + timerDate + "'" ); timerDate.setTime( timerDate.getTime() + (86400 * 1000) );
System.log( "Timer will expire at '" + timerDate + "'" );
The preceding example JavaScript function defines a Date object that obtains the current date and time by using the getTime method and adds 86,400,000 milliseconds, or 24 hours. The Scriptable Task element generates this value as its output parameter.
9 Click Save.
You created a function that calculates and generates a Date object. A Waiting Timer element can receive this
Date object as an input parameter, to suspend a long-running workflow until the date encapsulated in this object. When the workflow arrives at the Waiting Timer element, it suspends its run and waits for 24 hours before continuing.
What to do next
You must add a Waiting Timer element to a workflow to implement a long-running workflow that is based on a timer.
Create a Timer-Based Long-Running Workflow
If you know a workflow will have to wait for a response from an outside source for a predictable time, you can implement it as a timer-based long-running workflow. A timer-based long-running workflow waits until a given time and date before resuming.
You implement a workflow as a timer-based long-running workflow by using the Waiting Timer element.
Prerequisites
You must have created a workflow, opened it for editing in the workflow editor, and added some elements to the workflow schema.
VMware, Inc. 61
vCenter Orchestrator Developer's Guide
Procedure
1 Drag a Waiting Timer element from the Generic menu to the position in the workflow schema at which to suspend the workflow's run.
2 Link the Waiting Timer element to the elements that precede and follow it in the workflow schema.
If you implement a scriptable task to calculate the time and date, this element must precede the Waiting
Timer element.
3 Click the Waiting Timer element to show its properties tabs in the bottom half of the Schema tab.
4 Provide a description of the reason for implementing the timer in the Info properties tab.
5 Click the Attributes properties tab.
The timer.date
parameter appears in the list of attributes.
6 Click the timer.date
parameter's Not set button to bind the parameter to an appropriate Date object.
The Waiting Timer selection dialog box opens, presenting a list of possible bindings.
n n
Select a predefined Date object from the proposed list, for example one defined by a Scriptable
Task element elsewhere in the workflow.
Alternatively, create a
Date
object that sets a specific date and time for the workflow to await.
7 (Optional) Create a Date object that sets a specific date and time that the workflow awaits.
a Click Create parameter/attribute in workflow in the Waiting Timer selection dialog box.
The Parameter information dialog box appears.
b Give the parameter an appropriate name.
c Leave the type set to Date .
d Click Create workflow ATTRIBUTE with the same name.
e Click the Value property's Not set button to set the parameter value.
A calendar appears.
f Use the calendar to set a date and time at which to restart workflow.
g Click OK.
8 Click Save at the bottom of the workflow editor.
You defined a timer that suspends a timer-based long-running workflow until a set time and date.
What to do next
You can create a long-running workflow that waits for a trigger event before continuing.
Create a Trigger Object
Trigger objects monitor event triggers that plug-ins define. For example, the vCenter Server plug-in defines these events as Task objects. When the task ends, the trigger sends a message to a waiting trigger-based longrunning workflow element, to restart the workflow.
The time-consuming event for which a trigger-based long-running workflow waits must return a VC:Task object. For example, the startVM
action to start a virtual machine returns a
VC:Task
object, so that subsequent elements in a workflow can monitor its progress. A trigger-based long-running workflow's trigger event requires this VC:Task object as an input parameter.
62 VMware, Inc.
Chapter 2 Developing Workflows
You create a
Trigger
object in a JavaScript function in a Scriptable Task element. This Scriptable Task element can be part of the trigger-based long-running workflow that waits for the trigger event. Alternatively, it can be part of a different workflow that provides input parameters to the trigger-based long-running workflow.
The trigger function must implement the createEndOfTaskTrigger() method from the Orchestrator API.
I
MPORTANT
You must define a timeout period for all triggers, otherwise the workflow can wait indefinitely.
Prerequisites
You must have created a workflow, opened it for editing in the workflow editor, and added some elements to the workflow schema. The workflow must declare a VC:Task object as an attribute or input parameter, such as a VC:Task object from a workflow or workflow element that starts or clones a virtual machine.
Procedure
1 Drag a Scriptable Task element from the Generic menu into the schema of a workflow.
2 Link the Scriptable Task element to the elements that precede and follow it in the workflow schema.
One of the elements that precedes the Scriptable Task must generate a VC:Task object as its output parameter.
3 Click the Scriptable Task element to show its properties tabs in the bottom half of the Schema tab.
4 Provide a name and description for the trigger in Info properties tab.
5 Click the IN properties tab.
6 Right-click in the IN tab and select Bind to workflow parameter/attribute.
The input parameter selection dialog box opens.
7 Select or create an input parameter of the type VC:Task.
This VC:Task object represents the time-consuming event that another workflow or element launches.
8 (Optional) Select or create an input parameter of the Number type to define a timeout period in seconds.
9 Click the OUT properties tab.
10 Right-click in the OUT tab and select Bind to workflow parameter/attribute.
The output parameter selection dialog box opens.
11 Create an output parameter with the following properties.
a Create the Name property with the value trigger .
b Create the Type property with the value Trigger .
c Click Create ATTRIBUTE with same name to create the attribute.
d Leave the value as Not set.
12 Define any exception behavior in the Exceptions properties tab.
13 Define a function to generate a Trigger object in the Scripting tab.
For example, you could create a Trigger object by implementing the following JavaScript function.
trigger = task.createEndOfTaskTrigger(timeout);
The createEndOfTaskTrigger() method returns a Trigger object that monitors a VC:Task object named task .
14 Click Save at the bottom of the workflow editor.
You defined a workflow element that creates a trigger event for a trigger-based long-running workflow. The trigger element generates a Trigger object as its output parameter, to which a Waiting Event element can bind.
VMware, Inc. 63
vCenter Orchestrator Developer's Guide
What to do next
You must bind this trigger event to a Waiting Event element in a trigger-based long-running workflow.
Create a Trigger-Based Long-Running Workflow
If you know a workflow will have to wait for a response from an outside source during its run, but do not know how long that wait will last, you can implement it as a trigger-based long-running workflow. A triggerbased long-running workflow waits for a defined trigger event to occur before resuming.
You implement a workflow as a trigger-based long-running workflow by using the Waiting Event element.
When the trigger-based long-running workflow arrives at the Waiting Event element, it will suspend its run and wait in a passive state until it receives a message from the trigger. During the waiting period, the passive workflow does not consume a thread, but rather the long-running workflow element passes the workflow information to the single thread that monitors all long-running workflows in the server.
Prerequisites
You must have created a workflow, opened it for editing in the workflow editor, added some elements to the workflow schema, and defined a trigger event, encapsulated in a Trigger object.
Procedure
1 Drag a Waiting Event element from the Generic menu to the position in the workflow schema at which you want to suspend the workflow's run.
2 Link the Waiting Event element to the elements that precede and follow it in the workflow schema.
The scriptable task that declares the trigger must immediately precede the Waiting Event element.
3 Click the Waiting Event element to show its properties tabs in the bottom half of the Schema tab.
4 Provide a description of the reason for the wait in the Info properties tab.
5 Click the Attributes properties tab.
The trigger.ref
parameter appears in the list of attributes.
6 Click the trigger.ref
parameter's Not set link to bind the parameter to an appropriate Trigger object.
The Waiting Event selection dialog box opens, presenting a list of possible parameters to which to bind.
7 Select a predefined
Trigger
object from the proposed list.
This Trigger object represents a trigger event that another workflow or workflow element defines.
8 Define any exception behavior in the Exceptions properties tab.
9 Click Save at the bottom of the workflow editor.
You defined a workflow element that suspends a trigger-based long-running workflow, that waits for a specific trigger event before restarting.
What to do next
You can run a workflow.
64 VMware, Inc.
Chapter 2 Developing Workflows
Configuration Elements
A configuration element is a list of attributes you can use to configure constants across a whole Orchestrator server deployment.
All the workflows, actions, policies, and Web views running in a particular Orchestrator server can use the attributes you set in a configuration element. Setting attributes in configuration elements allows you to make the same attribute values available to all the workflows, actions, policies, and Web views running in the
Orchestrator server.
If you create a package containing a workflow, action, policy, or Web view that uses an attribute from a configuration element, Orchestrator automatically includes the configuration element in the package, but not its value. If you import a package containing a configuration element into another Orchestrator server, the configuration element attribute values are not set. You must set the attributes with values appropriate to the server in which you have imported the package. For example, if you create a workflow that requires attribute values that depend on the Orchestrator server on which it runs, setting those attributes in a configuration element allows you to export that workflow so that another Orchestrator server can use it. If you set the serverspecific attributes directly in the workflow, the workflow might not work if you import it into another server, because it might not find the attribute values it requires. Because the attribute values in an imported configuration element are not set, you have to set them with values appropriate to the new server.
Configuration elements therefore allow you to exchange workflows, actions, policies and Web views between servers more easily.
Create a Configuration Element
Configuration elements allow you to set common attributes across an Orchestrator server. All elements that are running in the server can call on the attributes you set in a configuration element. Creating configuration elements allows you to define common attributes once in the server, rather than individually in each element.
Procedure
1 Click the Configurations view in the Orchestrator client.
2 Right-click a folder in the hierarchical list of folders and select New category to create a new category.
3 Provide a name for the folder and click OK.
4 Right-click the folder you created and select New element.
5 Provide a name for the configuration element and click OK.
6 Right-click the element and select Edit.
The configuration element editor opens.
7 Increment the version number by clicking the version digits in the General tab and providing a version comment.
8 Provide a description of the configuration element in the Description text box in the General tab.
9 Click the Attributes tab.
10 Right-click in the tab and select Add attribute to create a new attribute.
11 Click the attribute values under Name, Type, Value, and Description to set the attribute name, type, value, and description.
12 Click the Permissions tab.
13 Click Add access rights to grant permission to access this configuration element to a group of users.
14 Search for a user group in the Filter text box and select the relevant user group from the proposed list.
VMware, Inc. 65
vCenter Orchestrator Developer's Guide
15 Check the appropriate check boxes to set the access rights for the selected user group.
You can set the following permissions on the configuration element.
Permission Description
View
Inspect
Execute
Users can view the configuration element, but cannot view the schemas or scripting.
Users can view the configuration element, including the schemas and scripting.
Users can run the elements in the configuration element.
Edit
Admin
Users can edit the elements in the configuration element.
Users can set permissions on the elements in the configuration element.
16 Click Save and Close to exit the configuration element editor.
You defined a configuration element that sets common attributes across an Orchestrator server.
What to do next
You can use the configuration element to provide attributes to workflows or actions.
Workflow User Permissions
Orchestrator defines levels of permissions that you can apply to users or groups to allow or deny them access to workflows.
View
Inspect
Execute
Edit
Admin
The user can view the elements in the workflow, but cannot view the schema or scripting.
The user can view the elements in the workflow, including the schema and scripting.
The user can run the workflow.
The user can edit the workflow.
The user can set permissions on the workflow.
Permissions are not cumulative. For example, to grant a user full permissions, you must set all the permissions, not just Admin. All the permissions require the View permission.
If you do not set any permissions on a workflow, the workflow inherits the permissions from the category that contains it. If you do set permissions on a workflow, those permissions override the permissions of the category that contains it, even if the permissions of the category are more restrictive.
Set User Permissions on a Workflow
You set levels of permission on a workflow to limit the access that users or user groups can have to that workflow.
You select the users and user groups for which to set permissions from the users and user groups in the
Orchestrator LDAP server.
Prerequisites
Create a workflow, open it for editing in the workflow editor, and add to it the necessary elements.
66 VMware, Inc.
Chapter 2 Developing Workflows
Procedure
1 Click the Permissions tab.
2 Click the Add access rights link to define permissions for a new user or user group.
3 Search for a user or user group.
The search results show all of the users and user groups from the Orchestrator LDAP server that match the search.
4 Select a user or user group and click OK.
5 Right-click the user and select Add access rights.
6 Check the appropriate check boxes to set the level of permissions for this user and click OK.
To allow a user to view the workflow, inspect the schema and scripting, run and edit the workflow, and change the permissions, you must check all check boxes.
7 Click Save and Close to exit the editor.
You set the appropriate user permissions on a workflow.
Validating Workflows
Orchestrator provides a workflow validation tool. Validating a workflow helps identify errors in the workflow and checks that the data flows from one element to the next correctly.
When you validate a workflow, the validation tool creates a list of any errors or warnings. Clicking an error in the list highlights the workflow element that contains the error.
If you run the validation tool in the workflow editor, the tool provides suggested quick fixes for the errors it detects. Some quick fixes require you to provide additional information or input parameters. Other quick fixes resolve the error for you.
Workflow validation checks the data bindings and connections between elements. Workflow validation does not check the data processing that each element in the workflow performs. Consequently, a valid workflow can run incorrectly and produce erroneous results if a function in a schema element is incorrect.
By default, Orchestrator always performs workflow validation when you run a workflow. You can change the default validation behavior in the Orchestrator client. See
know to be invalid, for testing purposes.
Validate a Workflow and Fix Validation Errors
You can validate workflows in either the Orchestrator client or in the workflow editor. However, you can only fix validation errors if you have opened the workflow for editing in the workflow editor.
Prerequisites
You must have a complete workflow to validate, with schema elements linked and bindings defined.
Procedure
1 Click the Workflows view.
2 Navigate to a workflow in the Workflows hierarchical list.
3 (Optional) Right-click the workflow and select Validate workflow.
If the workflow is valid, a confirmation message appears. If the workflow is invalid, a list of errors appears.
4 (Optional) Close the Workflow Validation dialog box.
VMware, Inc. 67
vCenter Orchestrator Developer's Guide
5 Right-click the workflow and select Edit to open the workflow editor.
6 Click the Schema tab.
7 Click the Validate button in the Schema tab toolbar.
If the workflow is valid, a confirmation message appears. If the workflow is invalid, a list of errors appears.
8 If the workflow is invalid, click on an error message.
The validation tool highlights the schema element in which the error occurs by adding a red icon to it.
Where possible, the validation tool proposes a Quick fix action.
n If you agree with the proposed Quick fix action, click it to perform that action.
n If you disagree with the proposed Quick fix action, close the Workflow Validation dialog box and fix the schema element manually.
Always check that the Quick Fix that Orchestrator proposes is appropriate. For example, the proposed action might be to delete an unused attribute, when in fact that attribute has not been correctly bound.
9 Repeat the preceding steps until you have eliminated all validation errors.
You validated a workflow, and possibly fixed any validation errors.
What to do next
You can run the workflow.
Running Workflows
A workflow runs according to a logical flow of events.
When you run a workflow, each schema element in the workflow runs according to the following sequence.
1 The workflow binds the workflow token attributes and input parameters to the schema element's input parameters.
2 The schema element runs.
3 The schema element's output parameters are copied to the workflow token attributes and workflow output parameters.
4 The workflow token attributes and output parameters are stored in the database.
5 The next schema element starts running.
This sequence repeats for each schema element until the end of the workflow.
Workflow Token Check Points
When a workflow runs, each schema element is a check point. After each schema element runs, Orchestrator stores workflow token attributes in the database, and the following schema element starts running. If the workflow stops unexpectedly, the next time the Orchestrator server restarts, the currently active schema element runs again, and the workflow continues from the start of the schema element that was running when the interruption happened. However, Orchestrator does not implement transaction management or a roll-back function.
End of Workflow
The workflow ends if the current active schema element is an end element or if an element has no outgoing connection. Validating a workflow with no end element returns a warning, but the workflow will run successfully. After the workflow reaches an end element, other workflows or applications can use the workflow's output parameters.
68 VMware, Inc.
Chapter 2 Developing Workflows
Run a Workflow
You can perform automated operations in vCenter Server by running workflows from the standard library or workflows that you create.
For example, you can create a virtual machine by running the Create simple virtual machine workflow.
Prerequisites
You must have configured the vCenter plug-in. For details, see vCenter Orchestrator Installation and Configuration
Guide.
Procedure
1 Click the Workflows view in the Orchestrator client.
2 In the workflows hierarchical list, open Library > vCenter > Virtual machine management > Basic to navigate to the Create simple virtual machine workflow.
3 Right-click the Create simple virtual machine workflow and select Execute workflow.
4 Provide the following information into the Execute workflow input parameters dialog box to create a virtual machine in a vCenter Server connected to Orchestrator.
Option
Virtual machine name
Virtual machine folder
Size of the new disk in GB
Memory size in MB
Number of virtual CPUs
Virtual machine guest OS
Host on which to create the virtual machine
Resource pool
The network to connect to
Datastore in which to store the virtual machine files
Action
Name the virtual machine orchestrator-test.
a Click Not set for the Virtual machine folder value.
b Select a virtual machine folder from the inventory.
The Select button is inactive until you select an object of the correct type, in this case, VC:VmFolder.
Type an appropriate numeric value.
Type an appropriate numeric value.
Select an appropriate number of CPUs from the Number of virtual CPUs drop-down menu.
Click the Not Set link and select a guest operating system from the list.
Click Not set for the Host on which to create the virtual machine value and navigate through the vCenter Server infrastructure hierarchy to a host machine.
Click Not set for the Resource pool value and navigate through the vCenter
Server infrastructure hierarchy to a resource pool.
Click Not set for the The network to connect to value and select a network.
Press Enter in the Filter text box to see all the available networks.
Click Not set for the Datastore in which to store the virtual machine value and navigate through the vCenter Server infrastructure hierarchy to a datastore.
5 Click Submit to run the workflow.
A workflow token appears under the Create simple virtual machine workflow, showing the workflow running icon.
6 Click the workflow token to view the status of the workflow as it runs.
7 Click the Events tab in the workflow token view to follow the progress of the workflow token until it completes.
8 Click the Inventory view in the Orchestrator client.
VMware, Inc. 69
vCenter Orchestrator Developer's Guide
9 Navigate through the vCenter Server infrastructure hierarchy to the resource pool you defined.
If the virtual machine does not appear in the list, click the refresh button to reload the inventory.
The orchestrator-test
virtual machine is present in the resource pool.
10 (Optional) Right-click the orchestrator-test virtual machine in the Inventory view to see a contextual list of the workflows that you can run on the orchestrator-test virtual machine.
The Create simple virtual machine workflow ran successfully.
What to do next
You can log in vSphere Client and manage the new virtual machine.
Develop a Simple Example Workflow
Developing a simple example workflow demonstrates the most common steps in the workflow development process.
The example workflow, named Start VM and Send Email, starts an existing virtual machine in the vCenter
Server and sends an email to the administrator to confirm that the virtual machine has started.
The example workflow performs the following tasks:
1 Prompts the user for a virtual machine to start.
2 Prompts the user for the email address of a person to inform that the virtual machine has started, or that an error occurred.
3 Checks whether or not the requested virtual machine is already powered on.
4 Sends the request to the vCenter Server to start the requested virtual machine.
5 Waits for vCenter Server to start up the requested virtual machine, and returns an error if the virtual machine fails to start or if starting the virtual machine takes too long.
6 Waits for vCenter Server to start up VMware Tools on the virtual machine. Returns an error if the virtual machine fails to start or if starting VMware Tools takes too long.
7 Verifies that the virtual machine is running.
8 Sends a notification email to the relevant person, to inform them that the machine has started or that an error occurred.
The ZIP file of Orchestrator examples that you can download from the Orchestrator documentation homepage contains a completed version of the Start VM and Send Email workflow. For details about where to download
the Orchestrator examples bundle, see “Example Applications,” on page 9.
The process for developing a simple workflow consists of the following tasks.
Prerequisites
“Developing Workflows,” on page 15.
Procedure
1
Create the Simple Workflow Example on page 72
The first step in the workflow development process is to create the workflow.
2
Define the Simple Workflow Example Parameters on page 73
You define workflow attributes and parameters in the workflow editor.
70 VMware, Inc.
Chapter 2 Developing Workflows
3
Create the Simple Workflow Example Schema on page 73
You create a workflow schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.
4
Link the Simple Workflow Example Elements on page 75
You link a workflow's elements in the Schema tab of the workflow editor. The linking defines the flow of data through the workflow.
5
Create Workflow Zones on page 76
You can emphasize different zones in workflow by adding workflow notes of different colors. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.
6
Define the Simple Workflow Example Decision Bindings on page 77
You bind a workflow's elements together in the Schema tab of the workflow editor. Decision bindings define how decision elements compare the input parameters received to the decision statement, and generate output parameters according to whether the input parameters match the decision statement.
7
Bind the Simple Workflow Example Action Elements on page 78
You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the action elements process input parameters and generate output parameters.
8
Bind the Simple Workflow Example Scripted Task Elements on page 81
You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the scripted task elements process input parameters and generate output parameters. You also bind the scriptable task elements to their JavaScript functions.
9
Define the Simple Example Workflow Exception Bindings on page 88
You define exception bindings in the Schema tab in the workflow editor. Exception bindings define how elements process errors.
10
Set the Simple Workflow Example Attribute Read-Write Properties on page 88
You can define whether parameters and attributes are read-only constants or writeable variables. You can also set limitations on the values that users can provide for input parameters.
11
Set the Simple Workflow Example Parameter Properties on page 89
You set the parameter properties in the Presentation tab in the workflow editor. Setting the parameter properties affects the behavior of the parameter, and places constraints on the possible values for that parameter.
12
Set the Layout of the Simple Workflow Example Input Parameters Dialog Box on page 90
You create the layout, or presentation, of the input parameters dialog box in the Presentation tab of the workflow editor. The input parameters dialog box opens when users run a workflow, and is the means by which users enter the input parameters with which the workflow runs.
13
Validate and Run the Simple Workflow Example on page 91
After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.
VMware, Inc. 71
vCenter Orchestrator Developer's Guide
Create the Simple Workflow Example
The first step in the workflow development process is to create the workflow.
Prerequisites
The following components are installed and configured on the system.
n vCenter Server, controlling some virtual machines, at least one of which is powered off n n
Access to an SMTP server
A valid email address
For information about how to install and configure vCenter, see the ESX and vCenter Server Installation Guide.
For information about how to configure Orchestrator to use an SMTP server, see the Orchestrator Installation
and Configuration Guide.
To write a workflow, you must have an Orchestrator user account with at least View, Execute, Inspect, Edit, and preferably Admin permissions on the server or on the workflow folder in which you are working.
Procedure
1 Start the Orchestrator client interface.
2 Log in using the Orchestrator username and password.
3 Click Workflows on the left side of the client interface.
4 Right-click the root of the workflows list and select Add category.
5 Name the new folder Workflow Examples and click OK.
6 Right-click the Workflow Examples folder and select New Workflow.
7 Name the new workflow Start VM and Send Email and click OK.
8 Right-click the Start VM and Send Email workflow and select Edit.
The workflow editor opens.
9 In the General tab, click the version number digits to increment the version number.
Because this is the initial creation of the workflow, set the version to 0.0.1.
10 Click the Server restart behavior value in the General tab to set whether the workflow resumes after a server restart.
11 Type a description of what the workflow does in the Description text box in the General tab.
For example, you can add the following description.
This workflow starts a virtual machine and sends a confirmation email to the Orchestrator administrator.
12 Click Save at the bottom of the General tab.
You created a workflow called Start VM and Send Email, but you did not define its functions.
What to do next
You must define the workflow's attributes and input and output parameters.
72 VMware, Inc.
Chapter 2 Developing Workflows
Define the Simple Workflow Example Parameters
You define workflow attributes and parameters in the workflow editor.
Prerequisites
You must have created the Start VM and Send Email workflow, and opened it for editing in the workflow editor.
Procedure
1 Click the Inputs tab in the workflow editor.
2 Right-click in the Inputs tab and select Add Parameter.
A parameter named arg_in_0 appears in the Inputs tab.
3 Click arg_in_0.
4 Type the name vm in the Choose Attribute Name dialog box and click OK.
5 Click the Type text box and type vc:virtualm in the search text box in the parameter type dialog box.
6 Select VC:VirtualMachine from the proposed list of parameter types and click Accept.
7 Add a description of the parameter in the description text box.
For example, type
The virtual machine to power on
.
8 Repeat the above process to create a second input parameter, with the following values.
n Name: toAddress n n
Type: String
Description: The email address of the person to inform of the result of this workflow
9 Click Save at the bottom of the Inputs tab.
You defined the workflow's input parameters.
What to do next
You must create the workflow's schema.
Create the Simple Workflow Example Schema
You create a workflow schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.
Prerequisites
You must created the Start VM and Send Email workflow and defined its parameters.
Procedure
1 Click the Schema tab in the workflow editor.
2 Click the Generic menu on the left of the Schema tab.
3 Drag a decision element to under the start element in the schema.
4 Double-click the decision element and change its name to VM powered on?
5 Click Action & Workflow and drag an action element to under the decision element.
The action selection dialog box appears.
VMware, Inc. 73
vCenter Orchestrator Developer's Guide
6 Type start in the Search text box.
7 Select the startVM action and click Select.
8 Drag the following action elements into the schema, one beneath the other under the startVM action element.
vim3WaitTaskEnd vim3WaitToolsStarted
Suspends the workflow run and polls an ongoing vCenter Server task at regular intervals, until that task is finished. In the present example, the startVM
action starts a virtual machine and the vim3WaitTaskEnd
action makes the workflow wait while the virtual machine starts up. After the virtual machine starts, the vim3WaitTaskEnd lets the workflow resume.
Suspends the workflow run and waits until VMware Tools start on the target virtual machine.
9 Click the Generic menu and drag a scriptable task element under the vim3WaitToolsStarted action element.
10 Double-click the scriptable task element and rename it OK .
11 Drag another scriptable task element to the left of the startVM action element.
Name this scripted element Already started .
12 Drag more scripted elements into the schema, as follows.
n Drag a scripted element to the right of startVM and name it startVM failed .
n n
Drag a scripted element to the right of vim3WaitTaskEnd and name it Timeout 1 .
Drag a scripted element to the right of vim3WaitToolsStarted and name it Timeout 2 .
n Drag a scripted element to the right of OK and name it Send Email .
n Drag a scripted element to the right of Timeout 2 and name it Send Email Failed .
13 Drag an end element to the right of Send Email .
14 Click Save at the bottom of the workflow editor Schema tab.
Figure 2-3 shows the layout of the Start VM and Send Email workflow schema elements.
Figure 2-3. Start VM and Send Email Example Workflow Schema Elements
74
What to do next
You must now link the workflow elements together.
VMware, Inc.
Chapter 2 Developing Workflows
Link the Simple Workflow Example Elements
You link a workflow's elements in the Schema tab of the workflow editor. The linking defines the flow of data through the workflow.
Prerequisites
You must have created the Start VM and Send Email workflow, defined its parameters, and laid out its schema.
Procedure
1 Click the connector tool button in the toolbar at the top of the Schema tab in the workflow editor.
2 Click the start element, and holding the left mouse button down, move the pointer to the
VM Powered
On?
decision element.
You have linked the start element to the decision element.
3 Link the remaining elements as described in the following table.
Table 2-7. Simple Workflow Example Links
Click
Left side of VM Powered
On?
decision element
Right side of VM Powered
On?
decision element
Middle of startVM action element
Middle of vim3WaitTaskEnd action element
Middle of vim3WaitToolsStarted action element
Middle of Already
Started scriptable task element
Right side of startVM action element
Right side of vim3WaitTaskEnd action element
Right side of vim3WaitToolsStarted action element
Middle of StartVM
Failed scriptable task element
Middle of both Timeout scripted elements
Middle of OK scriptable task element
Right side of Send Email scriptable task element
Link to
Already Started scriptable task element startVM action element vim3WaitTaskEnd action element vim3WaitToolsStarted action element
OK scriptable task element vim3WaitToolsStarted action element
StartVM Failed scriptable task element
Timeout 1 scriptable task element
Timeout 2 scriptable task element
Send Email scriptable task element
Send Email scriptable task element
Send Email scriptable task element
Send Email Failed scriptable task element
Type of Arrow
Green
Red dotted
Black
Black
Black
Black
Thick red dotted
Thick red dotted
Thick red dotted
Black
Black
Black
Thick red dotted
Description
Input matches decision statement
Input does not match decision statement
Normal workflow progression
Normal workflow progression
Normal workflow progression
Normal workflow progression
Exception handling
Exception handling
Exception handling
Normal workflow progression
Normal workflow progression
Normal workflow progression
Exception handling
VMware, Inc. 75
vCenter Orchestrator Developer's Guide
Table 2-7. Simple Workflow Example Links (Continued)
Click
Middle of Send Email scriptable task element
Middle of Send Email
Failed scriptable task element
Link to
End element
End element
Type of Arrow
Black
Black
Description
Normal workflow progression
Normal workflow progression
4 Click Save at the bottom of the workflow editor Schema tab.
Figure 2-4 shows what the linked elements of the Start VM and Send Email workflow should look like.
Figure 2-4. Linking the Elements of the Start VM and Send Email Example Workflow
76
What to do next
You can highlight different zones in the workflow.
Create Workflow Zones
You can emphasize different zones in workflow by adding workflow notes of different colors. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.
Prerequisites
You must have created the Start VM and Send Email workflow, laid out its schema, and linked the schema elements together.
Procedure
1 Drag a workflow note element from the Generic menu into the workflow editor.
2 Position the workflow note over the Already started scriptable task element.
3 Drag the edges of the workflow note to resize it so that it surrounds the Already started scriptable task element.
4 Double-click the text and add a description. For example,
Path if virtual machine is already powered on .
VMware, Inc.
Chapter 2 Developing Workflows
5 Click Color in the Info tab at the bottom of the workflow editor and select the background color.
6 Repeat the preceding steps to highlight other zones in the workflow.
n Place a note over the vertical sequence of elements from the
VM powered on?
decision element to the
OK element. Add the description Start VM path .
n Place a note over the startVM failed , both Timeout scriptable task elements and the Send Email
Failed scriptable task element. Add the description Error handling .
n Place a note over the Send Email scriptable task element. Add the description Send email .
Figure 2-5 shows what the example workflow zones should look like.
Figure 2-5. Start VM and Send Email Example Workflow Zones
What to do next
Define the bindings between the element parameters.
Define the Simple Workflow Example Decision Bindings
You bind a workflow's elements together in the Schema tab of the workflow editor. Decision bindings define how decision elements compare the input parameters received to the decision statement, and generate output parameters according to whether the input parameters match the decision statement.
Prerequisites
You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements together.
Procedure
1 Click the VM Powered On?
decision element.
2 Click the Decision tab in the schema element properties pane at the bottom of the Schema tab.
3 Click the Not set (NULL) button and select vm
as the decision element's input parameter from the list of proposed parameters.
4 Select the state equals statement from the list of decision statements proposed in the drop-down menu.
A Not set button appears in the value text box, which presents you with a limited choice of possible values.
5 Select poweredOn .
6 Click Save at the bottom of the workflow editor's Schema tab.
You have defined the true or false statement against which the decision element will compare the value of the input parameter it receives.
VMware, Inc. 77
vCenter Orchestrator Developer's Guide
What to do next
You must define the bindings for the other elements in the workflow.
Bind the Simple Workflow Example Action Elements
You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the action elements process input parameters and generate output parameters.
Prerequisites
You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements together.
Procedure
1 Click the startVM
action element.
2 Set the following general information in the Info tab.
Interaction
Color
Business status
Description
No external interaction
None
Check the check box and add the text Sending start VM .
Leave the text Start / Resume a VM. Return the start task
3 Click the IN tab in the schema element properties pane at the bottom of the Schema tab.
You will see the two possible input parameters available to the startVM
action, vm
and host
.
Orchestrator automatically binds the vm parameter to vm[in-parameter] because the startVM action can only take a VC:VirtualMachine as an input parameter. Orchestrator detected the vm parameter you defined when you set the workflow input parameters and so bound it to the action automatically.
4 Set host
to NULL.
This is an optional parameter, so you can set it to null. However, if you leave it set to Not set, the workflow will not validate.
5 Click the OUT tab in the schema element properties pane.
The default output parameter that all actions generate, actionResult , appears.
6 Click the actionResult parameter's Not set button.
7 Click the Create parameter/attribute in workflow button.
The Parameter Information dialog box opens, where you can define the values for this output parameter.
The output parameter type for the startVM
action is a
VC:Task
object.
8 Name the parameter powerOnTask .
9 Provide a description for this parameter.
For example, Contains the result of powering on a VM .
10 Click Create workflow ATTRIBUTE with the same name.
11 Click OK to exit the Parameter Information dialog box.
78 VMware, Inc.
Chapter 2 Developing Workflows
12 Repeat the preceding steps to bind the input and output parameters to the vim3WaitTaskEnd
and vim3WaitToolsStarted action elements.
“Simple Workflow Example Action Element Bindings,” on page 79 lists the bindings for the
vim3WaitTaskEnd and vim3WaitToolsStarted action elements.
13 Click Save at the bottom of the workflow editor's Schema tab.
The action elements' input and output parameters are bound to the appropriate parameter types and values.
What to do next
Bind the scriptable task elements and define their functions.
Simple Workflow Example Action Element Bindings
Bindings define how the simple workflow example's action elements process input and output parameters.
When defining bindings, Orchestrator presents parameters you have already defined in the workflow as candidates for binding. If you have not defined the required parameter in the workflow yet, the only parameter choice is
NULL
. Click Create parameter/attribute in workflow to create a new parameter.
vim3WaitTaskEnd Action
The vim3WaitTaskEnd action element declares constants to track the progress of a task and a polling rate.
Table 2-8 shows the input and output parameter bindings that the
vim3WaitTaskEnd
action requires.
Table 2-8. Binding Values of the vim3WaitTaskEnd Action
Parameter Name task
Binding Type
IN
Bind to Existing or
Create Parameter?
Create progress IN Create n n n n n n n n n
Binding Values
Local Parameter: task
Source parameter: task[attribute]
Type: VC:Task
Description:
The vCenter server task currently running.
Local Parameter: progress
Source parameter: progress[attribute]
Type: Boolean
Value: No (false)
Description:
Log progress while waiting for the vCenter Server task to complete.
VMware, Inc. 79
vCenter Orchestrator Developer's Guide
Table 2-8. Binding Values of the vim3WaitTaskEnd Action (Continued)
Parameter Name pollRate
Binding Type
IN
Bind to Existing or
Create Parameter?
Create actionResult OUT Create n n n n n n n
Binding Values n n
Local Parameter: pollRate
Source parameter: pollRate[attribute]
Type: number
Value: 2
Description:
Polling rate in seconds at which vim3WaitTaskEnd checks the advancement of the vCenter server task.
Local Parameter: actionResult[attribute]
Source parameter: returnedManagedObject[attri bute]
Type: Any
Description:
The returned managed object from the waitTaskEnd action.
vim3WaitToolsStarted Action
The vim3WaitToolsStarted action element waits until VMware Tools have installed on a virtual machine, and
defines a polling rate and a timeout period. Table 2-9
shows the input parameter bindings the vim3WaitToolsStarted action requires.
The vim3WaitToolsStarted action element has no output, so requires no output binding.
80 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-9. Binding Values of the vim3WaitToolsStarted Action
Parameter Name vm
Binding Type
IN
Bind to Existing or
Create Parameter?
Automatic binding pollingRate timeout
IN
IN
Bind
Create n n n n n n n n n n n n n
Binding Values n
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Value: Not editable, variable is not a workflow attribute.
Description:
The virtual machine to start.
Local Parameter: pollRate
Source parameter: pollRate[attribute]
Type: number
Description:
The polling rate in seconds at which vim3WaitTaskEnd checks the advancement of the vCenter server task.
Local Parameter: timeout
Source parameter: timeout[attribute]
Type: number
Value: 10
Description:
The timeout limit that vim
3WaitToolsStarted waits before throwing an exception.
Bind the Simple Workflow Example Scripted Task Elements
You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define how the scripted task elements process input parameters and generate output parameters. You also bind the scriptable task elements to their JavaScript functions.
Prerequisites
You must have created the Start VM and Send Email workflow, defined its parameters, laid out its schema, and linked the schema elements.
Procedure
1 Click the Already Started scriptable task element.
2 Set the following general information in the Info tab.
Interaction
Color
Business status
Description
No external interaction
None
Check the check box and add the text VM already powered on .
Leave the text
The VM is already powered on, bypassing startVM and waitTaskEnd, checking if the VM tools are up and running.
VMware, Inc. 81
vCenter Orchestrator Developer's Guide
3 Click the IN tab in the schema element properties pane at the bottom of the Schema tab.
Because this is a custom scriptable task element, no properties are predefined for you.
4 Right-click in the IN tab and select
Bind to workflow parameter/attribute
.
5 Select vm from the proposed list of parameters.
6 Leave the OUT and Exception tabs blank.
This element does not generate an output parameter or exception.
7 Click the Scripting tab.
8 Add the following JavaScript function.
//Writes the following event in the vCO database
Server.log("VM '"+ vm.name +"' already started");
9 Repeat the preceding steps to bind the remaining input parameters to the other scriptable task elements.
“Simple Workflow Example Scriptable Task Element Bindings,” on page 82 lists the bindings for the
Start VM failed, both Timeout or Error, Send Email Failed, and the OK scriptable task elements.
10 Click Save at the bottom of the workflow editor's Schema tab.
You have bound the scriptable task elements to their input and output parameters, and provided the scripting that defines their function.
What to do next
You must define the exception handling.
Simple Workflow Example Scriptable Task Element Bindings
Bindings define how the simple workflow example's scriptable task elements process input parameters. You also bind the scriptable task elements to their JavaScript functions.
When defining bindings, Orchestrator presents parameters you have already defined in the workflow as candidates for binding. If you have not defined the required parameter in the workflow yet, the only parameter choice is NULL . Click Create parameter/attribute in workflow to create a new parameter.
Start VM Failed Scriptable Task
The Start VM Failed scriptable task element handles any exceptions that the startVM action returns by setting the content of an email notification about the failure to start the virtual machine, and writing the event in the
Orchestrator log.
requires.
82 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-10. Bindings of the Start VM Failed Scriptable Task Element
Parameter Name vm errorCode body
Binding Type
IN
IN
OUT
Bind to Existing or
Create Parameter?
Bind
Create
Create n n n n n n n n n n n n
Binding Values
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Description:
The virtual machine to power on.
Local Parameter: errorCode
Source parameter: errorCode[attribute]
Type: string
Description:
Catch any exceptions while powering on a VM.
Local Parameter: body
Source parameter: body[attribute]
Type: string
Description: The email body
The Start VM Failed scriptable task element performs the following scripted function.
body = "Unable to execute powerOnVM_Task() on VM '"+vm.name+"', exception found: "+errorCode;
//Writes the following event in the vCO database
Server.error("Unable to execute powerOnVM_Task() on VM '"+vm.name, "Exception found: "+errorCode);
Timeout 1 Scriptable Task Element
The Timeout 1 scriptable task element handles any exceptions that the vim3WaitTaskEnd action returns by setting the content of an email notification about the failure of the task, and writing the event in the Orchestrator log.
VMware, Inc. 83
vCenter Orchestrator Developer's Guide
Table 2-11. Bindings of the Timeout 1 Scriptable Task Element
Parameter Name vm errorCode body
Binding Type
IN
IN
OUT
Bind to Existing or
Create Parameter?
Bind
Bind
Bind n n n n n n n n n n n n
Binding Values
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Description:
The virtual machine to start.
Local Parameter: errorCode
Source parameter: errorCode[attribute]
Type: string
Description:
Catch any exceptions while powering on a VM.
Local Parameter: body
Source parameter: body[attribute]
Type: string
Description: The email body
The Timeout 1 scriptable task element requires the following scripted function.
body = "Error while waiting for poweredOnVM_Task() to complete on VM '"+vm.name+"', exception found: "+errorCode;
//Writes the following event in the vCO database
Server.error("Error while waiting for poweredOnVM_Task() to complete on VM '"+vm.name, "Exception found: "+errorCode);
Timeout 2 Scriptable Task Element
The Timeout 2 scriptable task element handles any exceptions that the vim3WaitToolsStarted action returns by setting the content of an email notification about the failure of the task, and writing the event in the
Orchestrator log.
84 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-12. Bindings of the Timeout 2 Scriptable Task Element
Parameter Name vm errorCode body
Binding Type
IN
IN
OUT
Bind to Existing or
Create Parameter?
Bind
Bind
Bind n n n n n n n n n n n n
Binding Values
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Description:
The virtual machine to power on.
Local Parameter: errorCode
Source parameter: errorCode[attribute]
Type: string
Description:
Catch any exceptions while powering on a VM.
Local Parameter: body
Source parameter: body[attribute]
Type: string
Description: The email body
The Timeout 2 scriptable task element requires the following scripted function.
body = "Error while waiting for VMware tools to be up on VM '"+vm.name+"', exception found:
"+errorCode;
//Writes the following event in the vCO database
Server.error("Error while waiting for VMware tools to be up on VM '"+vm.name, "Exception found:
"+errorCode);
OK Scriptable Task Element
The OK scriptable task element receives notice that the virtual machine has started successfully, sets the content of an email notification about the successful start of the virtual machine, and writes the event in the Orchestrator log.
Table 2-13. Bindings of the OK Scriptable Task Element
Parameter Name vm
Binding Type
IN
Bind to Existing or
Create Parameter?
Bind body OUT Bind n n n n n n n n
Binding Values
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Description:
The virtual machine to power on.
Local Parameter: body
Source parameter: body[attribute]
Type: string
Description: The email body
VMware, Inc. 85
vCenter Orchestrator Developer's Guide
The OK scriptable task element requires the following scripted function.
body = "The VM '"+vm.name+"' has started successfully and is ready for use";
//Writes the following event in the vCO database
Server.log(body);
Send Email Failed Scriptable Task Element
The Send Email Failed scriptable task element receives notice that the sending of the email failed, and writes the event in the Orchestrator log.
Table 2-14. Bindings of the Send Email Failed Scriptable Task Element
Parameter Name vm
Binding Type
IN
Bind to Existing or
Create Parameter?
Bind toAddress emailErrorCode
IN
IN
Bind
Create n n n n n n n n n n
Binding Values n n
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Description:
The virtual machine to power on.
Local Parameter: toAddress
Source parameter: toAddress[in-parameter]
Type: string
Description:
The email address of the person to inform of the result of this workflow
Local Parameter: emailErrorCode
Source parameter: emailErrorCode[attrbute]
Type: string
Description:
Catch any exceptions while sending an email
The Send Email Failed scriptable task element requires the following scripted function.
//Writes the following event in the vCO database
Server.error("Couldn't send result email to '"+toAddress+"' for VM '"+vm.name, "Exception found:
"+emailErrorCode);
Send Email Scriptable Task Element
The purpose of the Start VM and Send Email workflow is to inform an administrator when it starts a virtual machine. To do so, you must define the scriptable task that sends an email. To send the email, the Send Email scriptable task element needs an SMTP server, addresses for the sender and recipient of the email, the email subject, and the email content.
shows the input and output parameter bindings that the Send Email scriptable task element requires.
86 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-15. Bindings of the Send Email Scriptable Task Element
Parameter Name vm toAddress body smtpHost fromAddress subject
Binding Type
IN
IN
IN
IN
IN
IN
Bind to Existing or
Create Parameter?
Bind
Bind
Bind
Create
Create
Create
The Send Email scriptable task element requires the following scripted function.
//Create an instance of EmailMessage var myEmailMessage = new EmailMessage() ;
//Apply methods on this instance that populate the email message myEmailMessage.smtpHost = smtpHost; myEmailMessage.fromAddress = fromAddress; myEmailMessage.toAddress = toAddress; myEmailMessage.subject = subject; myEmailMessage.addMimePart(body , "text/html"); n n n n n n n n n n n n n n n n n n n n n n n n
Binding Values
Local Parameter: vm
Source parameter: vm[inparameter]
Type: VC:VirtualMachine
Description:
The virtual machine to power on.
Local Parameter: toAddress
Source parameter: toAddress[in-parameter]
Type: string
Description:
The email address of the person to inform of the result of this workflow
Local Parameter: body
Source parameter: body[attribute]
Type: string
Description: The email body
Local Parameter: smtpHost
Source parameter: smtpHost[attribute]
Type: string
Description:
The email SMTP server
Local Parameter: fromAddress
Source parameter: fromAddress[attribute]
Type: string
Description:
The email address of the sender
Local Parameter: subject
Source parameter: subject[attribute]
Type: string
Description:
The email subject
VMware, Inc. 87
vCenter Orchestrator Developer's Guide
//Apply the method that sends the email message myEmailMessage.sendMessage();
System.log("Sent email to '"+toAddress+"'");
Define the Simple Example Workflow Exception Bindings
You define exception bindings in the Schema tab in the workflow editor. Exception bindings define how elements process errors.
The following elements in the workflow return exceptions: startVM
, vim3WaitTaskEnd
,
Send Email
, and vim3WaitToolsStarted .
Prerequisites
You must have created the Start VM and Send Email workflow, defined its parameters, and laid out its schema.
Procedure
1 Click the startVM action element.
2 Click the Exceptions tab at the bottom of the Schema tab.
3 Click the Not set button.
4 Select errorCode
from the proposed list.
5 Repeat the preceding steps to set the exception binding to errorCode for both vim3WaitTaskEnd and vim3WaitToolsStarted .
6 Click the Send Email scriptable task element.
7 Click the Exceptions tab at the bottom of the Schema tab.
8 Click the Not set button.
9 Select emailErrorCode from the proposed list.
10 Click Save at the bottom of the workflow editor's Schema tab.
You have defined the exception binding for the elements that return exceptions.
What to do next
You must set the read and write properties on the attributes and parameters.
Set the Simple Workflow Example Attribute Read-Write Properties
You can define whether parameters and attributes are read-only constants or writeable variables. You can also set limitations on the values that users can provide for input parameters.
Setting certain parameters to read-only allows other developers to adapt the workflow or to modify it without breaking the workflow's core function.
Prerequisites
You must have created a workflow, laid out and linked its schema, and defined the IN, OUT, and exception bindings for all elements.
88 VMware, Inc.
Chapter 2 Developing Workflows
Procedure
1 Click the General tab at the top of the workflow editor.
Under Attributes is a list of all the attributes you defined, with check boxes next to each attribute. When you check these checkboxes, you set attributes as read-only.
2 Check the check boxes to make the following attributes read-only constants: 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.
Set the Simple Workflow Example Parameter Properties
You set the parameter properties in the Presentation tab in the workflow editor. Setting the parameter properties affects the behavior of the parameter, and places constraints on the possible values for that parameter.
Prerequisites
You must have created a workflow, laid out and linked its schema, and defined the IN, OUT, and exception bindings for all elements.
Procedure
1 Click the Presentation tab.
The two input parameters you defined for this workflow are listed.
2 Click the (VC:VirtualMachine)vm parameter.
3 Add a description in the Description tab in the bottom half of the screen.
For example, type The virtual machine to start .
4 Click the Properties tab in the bottom half of the screen.
This tab allows you to set the properties of the (VC:VirtualMachine)vm parameter.
5 Right-click the Properties tab and select Add Property.
6 Select Mandatory input from the list of proposed properties.
When you select this property, users cannot run the Start VM and Send Email workflow without providing a virtual machine to start.
7 Set the value of the Mandatory input property to Yes.
8 Right-click on the Properties tab and select Add Property again.
9 Select Select value as from the list of proposed properties.
When you set this property, you set how the user selects the value of the (VC:VirtualMachine)vm input parameter.
VMware, Inc. 89
vCenter Orchestrator Developer's Guide
10 Select list from the list of possible values.
11 Click the
(string)toAddress
parameter in the top half of the Presentation tab.
12 Add a description in the Description tab in the bottom half of the screen.
For example, type The email address of the person to notify .
13 Click the Properties tab for (string)toAddress .
14 Right-click the Properties tab and select Add Property > Mandatory input.
15 Set the value of the Mandatory input property to Yes.
16 Right-click the Properties tab and select Add Property > Matching regular expression.
This property allows you to set constraints on what users can provide as input.
17 Click the Value text box for Matching regular expression and set the constraints to
[a-zA-Z0-9_%-+.]+@[a-zA-Z0-9-.]+\.[a-zA-Z]{2,4}
Setting these constraints limits user input to characters that are appropriate for email addresses. If the user tries to input any other character for the email address of the recipient when they start the workflow, the workflow will not start.
You have made both parameters mandatory, defined how the user can select the virtual machine to start, and limited the characters that can be input for the recipient's email address.
What to do next
You must create the layout, or presentation, of the input parameters dialog box in which users enter a workflow's input parameter values when they run it.
Set the Layout of the Simple Workflow Example Input Parameters Dialog Box
You create the layout, or presentation, of the input parameters dialog box in the Presentation tab of the workflow editor. The input parameters dialog box opens when users run a workflow, and is the means by which users enter the input parameters with which the workflow runs.
The layout you define in the Presentation tab also defines the layout of the input parameter dialog boxes for workflows you run using a Web view.
Prerequisites
You must have created a workflow, laid out and linked its schema, defined the IN, OUT, and exception bindings for all elements, and set the attribute and parameter properties.
Procedure
1 Click the Presentation tab in the workflow editor.
2 Right-click the Presentation node in the presentation hierarchical list and select Create display group.
A New Step node and a New Group sub-node appear under the Presentation node.
3 Right-click New Step and select Delete.
Because this workflow only has two parameters, you do not need multiple layers of display sections in the input parameters dialog box.
4 Double-click New Group to edit the group name and press Enter.
For example, name the display group Virtual Machine .
The text you enter here appears as a heading in the input parameter dialog box when users start the workflow.
90 VMware, Inc.
Chapter 2 Developing Workflows
5 Provide a description of the Virtual Machine display group in the Description text box in the General tab at the bottom of the Presentation tab.
For example, type Select the virtual machine to start .
The text you enter here appears as a prompt in the input parameter dialog box when users start the workflow.
6 Drag the (VC:VirtualMachine)vm parameter under the Virtual Machine display group.
The text box in the input parameters dialog box in which the user enters the virtual machine to start will appear under the heading Virtual Machine.
7 Repeat the preceding steps to create a display group for the toAddress parameter, setting the following properties: a Create a display group named Recipient's Email Address .
b Add a description for the display group, for example,
Enter the email address of the person to notify when this virtual machines is powered-on .
c Drag the toAddress property under the Recipient's Email Address display group.
You have set up the layout of the input parameters dialog box that appears when users run the workflow.
What to do next
You have completed the development of the simple workflow example. You can now validate and run the workflow.
Validate and Run the Simple Workflow Example
After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.
Prerequisites
Create a workflow, lay out its schema, define the links and bindings, define the parameter properties, and create the presentation of the input parameters dialog box.
Procedure
1 Click Validate in the Schema tab of the workflow editor.
The validation tool locates any errors in the definition of the workflow.
2 When you have eliminated any errors, click Save and Close at the bottom of the workflow editor.
You return to the Orchestrator client.
3 Click the Workflows view.
4 Select Workflow Examples > Start VM and Send Email in the workflow hierarchical list.
5 Right-click the Start VM and Send Email workflow and select Execute workflow.
The input parameters dialog box opens and prompts you for a virtual machine to start and an email address of a person to inform.
6 Select a virtual machine to start in the vCenter Server from the proposed list.
7 Enter an email address to which to send email notifications.
VMware, Inc. 91
vCenter Orchestrator Developer's Guide
8 Click Submit to start the workflow.
A workflow token appears under the Start VM and Send Email workflow.
9 Click the workflow token to follow the progress of the workflow as it runs.
If the workflow ran successfully, the virtual machine you identified is in the powered-on state, and the email recipient you defined receives a confirmation email.
Develop a Complex Workflow
Developing a complex example workflow demonstrates the most common steps in the workflow development process and more advanced scenarios, such as creating custom decisions and loops.
In the complex workflow exercise, you develop a workflow that takes a snapshot of all the virtual machines contained in a given resource pool. The workflow you create will perform the following tasks:
1 Prompts the user for a resource pool that contains the virtual machines of which to take snapshots.
2 Determines whether the resource pool contains running virtual machines.
3 Determines how many running virtual machines the resource contains.
4 Verifies whether an individual virtual machine running in the pool meets specific criteria for a snapshot to be taken.
5 Takes the snapshot of the virtual machine.
6 Determines whether more virtual machines exist in the pool of which to take snapshots.
7 Repeats the verification and snapshot process until the workflow has taken snapshots of all eligible virtual machines in the resource pool.
The ZIP file of Orchestrator examples that you can download from the Orchestrator documentation homepage contains a completed version of the Take a Snapshot of All Virtual Machines in a Resource Pool workflow. For details about where to download the Orchestrator examples bundle, see
“Example Applications,” on page 9.
Prerequisites
Workflow,” on page 70. The procedures to develop a complex workflow provide the broad steps of the
development process, but are not as detailed as the simple workflow exercises.
Procedure
1
Create the Complex Workflow on page 93
The first step in the workflow development process is to create the workflow in the Orchestrator client.
2
Define the Complex Workflow Example Input Parameters on page 94
You define workflow input parameters in the workflow editor. The input parameters provide data for the workflow to process.
3
Create a Custom Action For the Complex Workflow Example on page 94
The Check VM scriptable element calls on an actions that does not exist in the Orchestrator API. You must create the getVMDiskModes action.
4
Create the Complex Workflow Example Schema on page 95
You create a workflow's schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.
5
Link the Complex Workflow Example Schema Elements on page 96
You link a workflow's elements together in the Schema tab of the workflow editor. The linking defines the logical flow the workflow.
92 VMware, Inc.
Chapter 2 Developing Workflows
6
Create the Complex Workflow Example Zones on page 98
Optionally, you can highlight different zones of the workflow by adding workflow notes. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.
7
Define the Complex Workflow Example Bindings on page 99
You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define the data flow of the workflow. You also bind the scriptable task elements to their JavaScript functions.
8
Set the Complex Workflow Example Attribute Properties on page 108
You set the attribute properties in the General tab in the workflow editor.
9
Create the Layout of the Complex Workflow Example Input Parameters on page 108
You create the layout, or presentation, of the input parameters dialog box in the Presentation tab of the workflow editor. The input parameters dialog box opens when users run a workflow, and is the means by which users enter the input parameters with which the workflow runs.
10
Validate and Run the Complex Workflow Example on page 109
After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.
Create the Complex Workflow
The first step in the workflow development process is to create the workflow in the Orchestrator client.
Prerequisites
The following components are installed and configured on the system.
n vCenter Server, controlling a resource pool that contains some virtual machines n
Workflow Example,” on page 72.
For information about how to install and configure vCenter, see the ESX and vCenter Server Installation Guide.
For information about how to configure Orchestrator, see the Orchestrator Installation and Configuration Guide.
Procedure
1 Select Workflows > Workflow Examples.
2 Create a workflow called Take a Snapshot of All Virtual Machines in a Resource Pool.
3 Open the workflow editor by right-clicking the new workflow and selecting Edit.
4 In the General tab of the workflow editor, click the version number digits to increment the version number.
Because this is the initial creation of the workflow, set the version to 0.0.1.
5 Click the Server restart behavior value in the General tab to set whether the workflow resumes after a server restart.
6 Type a description of what the workflow does in the Description text box in the General tab.
7 Click Save at the bottom of the General tab.
You created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.
What to do next
You can now continue editing the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.
VMware, Inc. 93
vCenter Orchestrator Developer's Guide
Define the Complex Workflow Example Input Parameters
You define workflow input parameters in the workflow editor. The input parameters provide data for the workflow to process.
Prerequisites
You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, and opened it for editing in the workflow editor.
Procedure
1 Click the Inputs tab in the workflow editor.
2 Define the following input parameter.
n Name: resourcePool n n
Type: VC:ResourcePool
Description: The resource pool containing the virtual machines of which to take snapshots.
3 Click the Outputs tab in the workflow editor.
4 Define the following output parameter.
n n
Name: snapshotVmArrayOut
Type: Array/VC:VirtualMachine n Description: The Array of virtual machines of which snapshots have been taken.
You have defined the workflow input parameter.
What to do next
You can create a workflow schema.
Create a Custom Action For the Complex Workflow Example
The Check VM scriptable element calls on an actions that does not exist in the Orchestrator API. You must create the getVMDiskModes action.
For more detail about creating actions, see
Chapter 3, “Developing Actions,” on page 111.
Prerequisites
You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.
Procedure
1 Close the workflow editor by clicking Save and Close.
2 Click the Actions view in the Orchestrator client.
3 Right-click the root of the actions hierarchical list and select New Module.
4 Name the new module com.vmware.example
.
5 Right-click the com.vmware.example module and select Add Action.
6 Create an action called getVMDiskModes .
7 Right-click getVMDiskModes
and select Edit.
8 Increment the version number in the General tab in the actions editor by clicking the version digits.
94 VMware, Inc.
Chapter 2 Developing Workflows
9 Add the following description of the action in the General tab.
This action returns an array containing the disk modes of all disks on a VM.
The elements in the array each have one of the following string values:
- persistent
- independent-persistent
- nonpersistent
- independent-nonpersistent
Legacy values:
- undoable
- append
10 Click the Scripting tab.
11 Right-click in the top pane of the Scripting tab and select Add Parameter to create the following input parameter.
n Name: vm n n
Value: VC:VirtualMachine
Description: The virtual machine for which to return the Disk Modes
12 Add the following scripting in the bottom of the Scripting tab.
The following code returns an array of disk modes for the disks of the virtual machine.
var devicesArray = vm.config.hardware.device; var retArray = new Array(); if (devicesArray!=null && devicesArray.length!=0) {
for (i in devicesArray) {
if (devicesArray[i] instanceof VcVirtualDisk) {
retArray.push(devicesArray[i].backing.diskMode);
}
}
} return retArray;
13 Click Save and Close to exit the Actions palette.
You have defined the custom action the Take a Snapshot of All Virtual Machines in a Resource Pool workflow requires.
What to do next
You must create the workflow schema.
Create the Complex Workflow Example Schema
You create a workflow's schema in the Schema tab of the workflow editor. The workflow schema contains the elements that the workflow runs.
Prerequisites
You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, defined its input parameter, and created the getVMDiskModes action.
Procedure
1 Right-click the Take a Snapshot of All Virtual Machines in a Resource Pool workflow to open the workflow editor.
2 Click the Schema tab in the workflow editor.
VMware, Inc. 95
vCenter Orchestrator Developer's Guide
3 Add the following schema elements to the workflow schema.
Table 2-16. Complex Workflow Example Schema Elements
Element Type
Scriptable task
Decision
Scriptable task
Custom decision
Action
Custom decision
Workflow
Scriptable task
Scriptable task
Scriptable task
Scriptable task
End element
Element Name
Initializing
VMs to Process?
Pool Has No VMs
Remaining VMs?
getVMDiskModes
Create snapshot?
Create a snapshot
VM Snapshots
Increment
Log Exception
Set Output
No name
Position in Schema
Below start element
Below Initializing scriptable task
Below Virtual Machines to Process?
custom decision
Right of Virtual Machines to Process?
custom decision
Right of Virtual Machines Remaining?
custom decision
Right of getVMDiskModes action
Above Create snapshot? decision
Left of Create a snapshot workflow
Left of VM Snapshots scriptable task
Above VM Snapshots scriptable task
Below Remaining VMs? custom decision
Right of Set Output scriptable task
4 Click Save at the bottom of the Schema tab.
You have created the structure of the workflow.
Figure 2-6. Layout of the Take a Snapshot of All Virtual Machines in a Resource Pool Schema Elements
96
What to do next
You can now link the workflow elements together.
Link the Complex Workflow Example Schema Elements
You link a workflow's elements together in the Schema tab of the workflow editor. The linking defines the logical flow the workflow.
Prerequisites
You must have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, defined its input parameter, and created its schema.
VMware, Inc.
Chapter 2 Developing Workflows
Procedure
1 Click the connector tool button in the toolbar at the top of the Schema tab in the workflow editor.
2 Create the following links between the elements in the schema.
Table 2-17. Complex Workflow Example Links
Starting Element
Start element
Initializing scripted element
VMs to Process? decision's true result
VMs to Process? decision's false result
Has No VMs scriptable task
VMs Remaining? custom decision's true result
VMs Remaining? custom decision's false result getVMDisksModes action getVMDisksModes action exception link
Create Snapshot? custom decision's true result
Create Snapshot? custom decision's false result
Create a snapshot workflow
Create a snapshot workflow exception link
VM Snapshots scriptable task
Increment scriptable task
Log Exception scriptable task
Set Output scriptable task
Target Element
Initializing scripted element
VMs to Process? custom decision
VMs Remaining? custom decision
Has No VMs scriptable task
Set Output scriptable task getVMDisksModes action
Set Output scriptable task
Create Snapshot? decision
Log Exception scriptable task
Create a snapshot workflow
Increment scriptable task
VM Snapshots scriptable task
Log Exception scriptable task
Increment scriptable task
VMs Remaining? custom decision
Increment scriptable task
End element
3 Click Save at the bottom of the workflow editor's Schema tab.
workflow should look like.
Figure 2-7. Linking of the Take a Snapshot of All Virtual Machines in a Resource Pool Example Workflow
What to do next
You can optionally define workflow zones by using workflow notes.
VMware, Inc. 97
vCenter Orchestrator Developer's Guide
Create the Complex Workflow Example Zones
Optionally, you can highlight different zones of the workflow by adding workflow notes. Creating different workflow zones helps to make complicated workflow schema easier to read and understand.
Prerequisites
You must have created the workflow, created its schema, and linked the schema elements .
Procedure
1 Create the following workflow zones by using workflow notes.
Elements in Zone Description
Start element; Initialize scriptable task; VMs to Process? custom decision
Pool has no VMs scriptable task.
VMs remaining? custom decision; getVMDisksModes action, Create
Snapshot? decision; Create a snapshot workflow; VM Snapshots scriptable task; Increment scriptable task; Log Exception scriptable task
Get an array of virtual machines from a resource pool, initialize the counter of the Array and set the first virtual machine to be treated, if any.
Resource pool contains no virtual machines of which to take snapshots.
Check whether any virtual machines remain in the resource pool, check that a virtual machine meets the snapshot criteria, take a snapshot, then loop until a snapshot has been taken of all the virtual machines.
Set Output scriptable task; End element
Generates the resulting array of virtual machines of which snapshots have been taken.
2 Click Save at the bottom of the workflow editor Schema tab.
Your workflow zones should look like the following diagram.
Figure 2-8. Schema Diagram for Take Snapshot of all Virtual Machines in a Resource Pool Example Workflow
98
What to do next
You must define the bindings between the element parameters.
VMware, Inc.
Chapter 2 Developing Workflows
Define the Complex Workflow Example Bindings
You bind a workflow's elements together in the Schema tab of the workflow editor. Bindings define the data flow of the workflow. You also bind the scriptable task elements to their JavaScript functions.
Prerequisites
You must already have created the Take a Snapshot of All Virtual Machines in a Resource Pool workflow, defined its input parameter, created its schema, and linked the schema elements together.
Procedure
1 Click the Schema tab in the workflow editor.
2
Define the bindings shown in “Complex Workflow Example Bindings,” on page 99.
3 Click Save at the bottom of the workflow editor Schema tab.
All the elements' input and output parameters are bound to the appropriate parameter types and values.
What to do next
You must set the attribute properties.
Complex Workflow Example Bindings
Bindings define how the simple workflow example's action elements process input and output parameters.
The Take Snapshots of All Virtual Machines in a Resource Pool workflow requires the following input and output parameter bindings. You also define the JavaScript functions for the scriptable task elements.
In cases in which you bind to existing parameters, the binding inherits the type and description values from the original parameter.
Initializing Scriptable Task
The Initializing scriptable task element initializes the attributes of the workflow. Table 2-18
shows the input and output parameter bindings that the Initializing scriptable task element requires.
Table 2-18. Bindings of the Initializing Scriptable Task Element
Parameter Name resourcePool
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind allVMs OUT Create n n n n n n
Binding Values n n
Local parameter: resourcePool
Source parameter: resourcePool[in-parameter]
Type: VC:ResourcePool
Description:
The resource pool containing the virtual machines of which to take snapshots
Local parameter: allVMs
Source parameter: allVMs[attribute]
Type:
Array/VC:VirtualMachine
Description:
The virtual machines in the resource pool.
VMware, Inc. 99
vCenter Orchestrator Developer's Guide
Table 2-18. Bindings of the Initializing Scriptable Task Element (Continued)
Parameter Name numberOfVMs vmCounter vm snapshotVmArray
Binding Type
OUT
OUT
OUT
OUT
Bind to Existing or Create
Parameter?
Create
Create
Create
Create n n n n n n n n n n n n
Binding Values n n n n
Local parameter: numberOfVMs
Source parameter: numberOfVMs[attribute]
Type: number
Description:
The number of virtual machines found in the resourcePool
Local parameter: vmCounter
Source parameter: vmCounter[attribute]
Type: number
Description:
The counter of the virtual machines inside the array
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
The current virtual machine having a snapshot taken
Local parameter: snapshotVmArray
Source parameter: snapshotVmArray[attribute]
Type:
Array/VC:VirtualMachine
Description:
The Array of virtual machines of which snapshots have been taken
The Initialize scriptable task element performs the following scripted function.
//Retrieve an array of virtual machines contained in the specified Resource Pool allVMs = resourcePool.vm;
//Initialize the size of the Array and the first VM to snapshot if (allVMs!=null && allVMs.length!=0) {
numberOfVms = allVMs.length;
vm = allVMs[0];
} else {
numberOfVms = 0;
}
//Initialize the VM counter vmCounter = 0;
//Initializing the array of VM snapshots snapshotVmArray = new Array();
VMs to Process? Decision Element
The VMs to Process? decision element determines whether any virtual machines of which to take snapshots
exist in the resource pool. Table 2-19
shows the bindings that the VMs to Process? decision element requires.
100 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-19. Bindings of the VMs to Process? Decision Element
Parameter Name numberOfVMs
Binding Type
Decision
Bind to Existing or Create
Parameter?
Bind n n n
Binding Values n
Source parameter: numberOfVMs[attribute]
Decision statement: Greater than
Value: 0.0
Description:
The number of virtual machines found in the resourcePool
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.
Table 2-20 shows the bindings that the Pool Has No VMs scriptable
task element requires.
Table 2-20. Bindings of the Pool Has No VMs Scriptable Task Element
Parameter Name resourcePool
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind n n n n
Binding Values
Local parameter: resourcePool
Source parameter: resourcePool[in-parameter]
Type: VC:ResourcePool
Description:
The resource pool containing the virtual machines of which to take snapshots.
The Pool Has No VMs scriptable task element performs the following scripted function.
//Writes the following event in the vCO database
Server.warn("The specified ResourcePool "+resourcePool.name+" does not contain any VMs.");
Remaining VMs? Custom Decision Element
The Remaining VMs? custom decision element determines whether any virtual machines of which to take
element requires.
VMware, Inc. 101
vCenter Orchestrator Developer's Guide
Table 2-21. Bindings of the Remaining VMs? Custom Decision Element
Parameter Name numberOfVMs
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind vmCounter IN Bind n n n n n n n
Binding Values n
Source parameter: numberOfVMs[attribute]
Decision statement: Greater than
Value: 0.0
Description:
The number of virtual machines found in the resourcePool
Local parameter: vmCounter
Source parameter: vmCounter[attribute]
Type: number
Description:
The counter of the virtual machines inside the array
The Remaining VMs? custom decision element performs the following scripted function.
//Checks if the workflow has reached the end of the array of VMs if (vmCounter < numberOfVms) {
return true;
} else {
return false;
} getVMDisksModes Action Element
The getVMDisksModes
action element obtains the modes of the disks running in a virtual machine. Table 2-22
shows the bindings that the getVMDisksModes action element requires.
Table 2-22. Bindings of the getVMDisksModes Action Element
Parameter Name vm
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind actionResult errorCode
OUT
Exception
Create
Create
Binding Values n n n n n n n n
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
The current virtual machine having a snapshot taken
Local parameter: actionResult
Source parameter: vmDisksModes[attribute]
Type: Array/String
Description:
The current Disks Modes of the virtual machine
Local parameter: errorCode
102 VMware, Inc.
Chapter 2 Developing Workflows
Create Snapshot? Custom Decision Element
The Create Snapshot? custom decision element determines whether to take snapshots of virtual machines,
custom decision element requires.
Table 2-23. Bindings of the Create Snapshot? Decision Element
Parameter Name vmDisksMode
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind vm IN Bind n n n n n n n n
Binding Values
Local parameter: vmDisksMode
Source parameter: vmDisksMode[attribute]
Type: Array/String
Description:
The current Disks Modes of the virtual machine
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
The current virtual machine having a snapshot taken
The Create Snapshot? custom decision element custom decision element performs the following scripted function.
//A snapshot cannot be taken if one of its disks is in independent mode
// (independent-persistent or independent-nonpersistent) var containsIndependentDisks = false; if (vmDisksModes!=null && vmDisksModes.length>0) {
for (i in vmDisksModes) {
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.name+"'");
return true;
}
Create a snapshot Workflow Element
The Create a snapshot workflow element takes snapshots of virtual machines. Table 2-24
shows the bindings that the Create a snapshot workflow element requires.
VMware, Inc. 103
vCenter Orchestrator Developer's Guide
Table 2-24. Bindings of the Create a snapshot Workflow Element
Parameter Name vm
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind name description memory quiesce snapshot errorCode
IN
IN
IN
IN
OUT
Exception
Create
Create
Create
Create
Create
Create
Binding Values n n n n n n n n n n n n
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
An active virtual machine of which to take a snapshot.
Local parameter: name
Source parameter: snapshotName[attribute]
Type: string
Description:
The name for this snapshot.
The name does not need to be unique for this virtual machine.
Local parameter: description
Source parameter: snapshotDescription[attribute]
Type: string
Description:
A description for this snapshot.
n n n n n n n n n n
Local parameter: memory
Source parameter: snapshotMemory[attribute]
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.
Local parameter: quiesce
Source parameter: snapshotQuiesce[attribute]
Type: Boolean
Value: yes
Description:
If TRUE and the virtual machine is powered on when the snapshot is taken, the
VMware Tools are used to quiesce the file system in the virtual machine.
n n n n
Local parameter: snapshot
Source parameter: NULL
Type:
VC:VirtualMachineSnapshot
Description:
The snapshot taken.
Local parameter: errorCode
104 VMware, Inc.
Chapter 2 Developing Workflows
VM Snapshots Scriptable Task Element
The VM Snapshots scriptable task element adds the snapshots to an array.
shows the bindings that the VM Snapshots scriptable task element requires.
Table 2-25. Bindings of the VM Snapshots Scriptable Task Element
Parameter Name vm
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind snapshotVmArray snapshotVmArray
IN
OUT
Bind
Bind n n n n n n n n
Binding Values n n n n
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
An active virtual machine of which to take a snapshot.
Local parameter: snapshotVmArray
Source parameter: snapshotVmArray[attribute]
Type: Array/VC:VirtualMachine
Description:
The Array of virtual machines of which snapshots have been taken
Local parameter: snapshotVmArray
Source parameter: snapshotVmArray[attribute]
Type: Array/VC:VirtualMachine
Description:
The Array of virtual machines of which snapshots have been taken
The VM Snapshots scriptable task element performs the following scripted function.
//Writes the following event in the vCO database
Server.log("Successfully took snapshot of the VM '"+vm.name);
//Inserts the VM snapshot in an array snapshotVmArray.push(vm);
Increment Scriptable Task Element
The Increment scriptable task element increments the counter that counts the number of virtual machines in
shows the bindings that the Increment scriptable task element requires.
VMware, Inc. 105
vCenter Orchestrator Developer's Guide
Table 2-26. Bindings of the Increment Scriptable Task Element
Parameter Name vmCounter
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind allVMs vmCounter vm
IN
OUT
OUT
Bind
Bind
Bind n n n n n n n n n n n n n n
Binding Values n n
Local parameter: vmCounter
Source parameter: vmCounter[attribute]
Type: number
Description:
The counter of the virtual machines inside the array
Local parameter: allVMs
Source parameter: allVMs[attribute]
Type:
Array/VC:VirtualMachine
Description:
The virtual machines in the resource pool.
Local parameter: vmCounter
Source parameter: vmCounter[attribute]
Type: number
Description:
The counter of the virtual machines inside the array
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
The current virtual machine having a snapshot taken
The Increment scriptable task element performs the following scripted function.
//Increases the array VM counter vmCounter++;
//Sets the next VM to be snapshot in the attribute vm vm = allVMs[vmCounter];
Log Exception Scriptable Task Element
The Log Exception scriptable task element handles exceptions from the workflow and action elements.
Table 2-27 shows the bindings that the Log Exception scriptable task element requires.
106 VMware, Inc.
Chapter 2 Developing Workflows
Table 2-27. Bindings of the Log Exception Task Element
Parameter Name vm
Binding Type
IN
Bind to Existing or Create
Parameter?
Bind errorCode IN Bind n n n n n n n n
Binding Values
Local parameter: vm
Source parameter: vm[attribute]
Type: VC:VirtualMachine
Description:
The current virtual machine having a snapshot taken
Local parameter: errorCode
Source parameter: errorCode[attribute]
Type: string
Description:
An exception caught while taking a snapshot of a virtual machine
The Log Exception scriptable task element performs the following scripted function.
//Writes the following event in the vCO database
Server.error("Coudln't snapshot the VM '"+vm.name+"', exception: "+errorCode);
Set Output Scriptable Task Element
The Set Output scriptable generates the workflow's output parameter, that contains the array of virtual
machines of which snapshots have been taken. Table 2-28
shows the bindings that the Set Output scriptable task element requires.
Table 2-28. Bindings of the Set Output Task Element
Parameter Name snapshotVmArray snapshotVmArrayOut
Binding Type
IN
OUT
Bind to Existing or Create
Parameter?
Bind
Bind
Binding Values n n n n n n n n
Local parameter: snapshotVmArray
Source parameter: snapshotVmArray[attribute]
Type:
Array/VC:VirtualMachine
Description:
The Array of virtual machines of which snapshots have been taken
Local parameter: snapshotVmArrayOut
Source parameter: snapshotVmArrayOut[outparameter]
Type:
Array/VC:VirtualMachine
Description:
The Array of virtual machines of which snapshots have been
VMware, Inc. 107
vCenter Orchestrator Developer's Guide
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.
Procedure
1 Click the General tab.
2 Check the read-only check box of the following attributes to make them read-only constants: n snapshotName n snapshotDescription n snapshotMemory n snapshotQuiesce
You have defined which of the workflow's attributes are constants and which are variables.
What to do next
You must create the workflow presentation, which creates the layout of the input parameters dialog box in which users enter a workflow's input parameter values when they run it.
Create the Layout of the Complex Workflow Example Input Parameters
You create the layout, or presentation, of the input parameters dialog box in the Presentation tab of the workflow editor. The input parameters dialog box opens when users run a workflow, and is the means by which users enter the input parameters with which the workflow runs.
Prerequisites
You must have created the workflow, created and linked its schema, defined the IN, OUT, and exception bindings for all elements, and set the attribute and parameter properties.
Procedure
1 Click the Presentation tab in the workflow editor.
This workflow has only one input parameter, so creating the presentation is straightforward.
2 Right-click the Presentation node in the presentation hierarchical list and select New Group.
3 Delete the New Step that appears above the New Group.
4 Double-click the New Group and change the group name to Resource Pool .
5 Provide a description of the Resource Pool display group in the Description text box in the General tab at the bottom of the Presentation tab.
For example,
Enter the name of the resource pool that contains the virtual machines of which to take a snapshot.
6 Click the (VC:ResourcePool)resourcePool parameter.
108 VMware, Inc.
Chapter 2 Developing Workflows
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.
10 Drag the (VC:ResourcePool)resourcePool parameter under the Resource Pool display group.
You have created the layout of the input parameters dialog box that appears when users run the workflow.
What to do next
You have completed the development of the more complex workflow example. You can now validate and run the workflow.
Validate and Run the Complex Workflow Example
After you create a workflow, you can validate it to discover any possible errors. If the workflow contains no errors, you can run it.
Prerequisites
Create a workflow, lay out its schema, define the links and bindings, define the parameter properties, and create the presentation of the input parameters dialog box.
Procedure
1 Click Validation in the Schema tab of the workflow editor.
The validation tool detects any errors in the definition of the workflow.
2 When you have eliminated any errors, click Save and Close at the bottom of the workflow editor.
You return to the Orchestrator client.
3 Click the Workflows view.
4 In the workflow hierarchical list, select Workflow Examples > Take a Snapshot of All Virtual Machines
in a Resource Pool.
5 Right-click the Take a Snapshot of All Virtual Machines in a Resource Pool workflow and select Execute
workflow.
The input parameters dialog box opens and prompts you for a resource pool that contains the virtual machines of which to take a snapshot.
6 Click Submit to run the workflow.
A workflow token appears under the Take a Snapshot of All Virtual Machines in a Resource Pool workflow.
7 Click the workflow token to follow the progress of the workflow as it runs.
If the workflow ran successfully, the workflow takes a snapshot of all of the virtual machines in the chosen resource pool.
VMware, Inc. 109
vCenter Orchestrator Developer's Guide
110 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. These attributes can be either the workflow's initial input parameters, or attributes that other elements in the workflow set when they run.
This chapter includes the following topics: n
“Reusing Actions,” on page 111
n n n
“Access the Actions View,” on page 111
“Components of the Actions View,” on page 112
“Creating Actions,” on page 112
Reusing Actions
When you define an individual function as an action instead of coding it directly into a scriptable task workflow element, you expose it in the library. When an action is visible in the library, other workflows can use it.
When you define actions independently from the workflows that call on them, you can update or optimize the actions more easily. Defining individual actions also allows other workflows to reuse actions. When a workflow runs, Orchestrator caches each action only the first time that the workflow runs it. Orchestrator can then reuse the cached action. Caching actions is useful for recursive calls in a workflow, or fast loops.
You can duplicate actions, export them to other workflows or packages, or move them to a different module in the actions hierarchical list.
Access the Actions View
The Orchestrator client interface features an Actions view that provides access to the Orchestrator server's libraries of actions.
The Actions view on the left side of the Orchestrator client interface presents you with a hierarchical list of all the actions available in the Orchestrator server.
VMware, Inc. 111
vCenter Orchestrator Developer's Guide
Procedure
1 Click Actions on the left side of the client interface.
2 Browse the libraries of actions by expanding the nodes of the actions hierarchical list.
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
Scripting
Events
Permissions
Displays general information about the action, including its name, its version number, the permissions, and a description.
Shows the action's return types, input parameters, and the JavaScript code that defines the action's function.
Shows all the events that this action encountered or triggered.
Shows which users and user groups have permission to access this action.
Creating Actions
You can define individual functions as actions that other elements, such as workflows, can use. Actions are
JavaScript functions with defined input and output parameters and permissions.
n n
When you define an individual function as an action, instead of coding it directly into a scriptable task workflow element, you can expose it in the library for other workflows to use.
Find Elements That Implement an Action on page 113
If you edit an action and change its behavior, you might inadvertently break a workflow or application that implements that action. Orchestrator provides a function to find all of the actions, workflows, or packages that implement a given element. You can check whether modifying the element affects the operation of other elements.
n
Action Coding Guidelines on page 113
To optimize the performance of workflows and to maximize the potential to reuse actions, you should follow some basic coding guidelines when creating actions.
Create an Action
When you define an individual function as an action, instead of coding it directly into a scriptable task workflow element, you can expose it in the library for other workflows to use.
Procedure
1 Click the Actions view in the Orchestrator client.
2 Expand the root of the actions hierarchical list and navigate to the module in which you want to create the action.
3 Right-click the module and select Add action.
4 Type a name for the action in the text box and click OK.
Your custom action is added to the library of actions.
112 VMware, Inc.
Chapter 3 Developing Actions
5 Right-click the action and select Edit.
6 Click the Scripting tab.
7 To change the default return type, click the void link.
8 Add the action input parameters by clicking the arrow icon.
9 Write the action script.
10 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. Orchestrator provides a function to find all of the actions, workflows, or packages that implement a given element. You can check whether modifying the element affects the operation of other elements.
I
MPORTANT
The Find Elements that Use this Element function checks all packages, workflows, and policies, but it does not check in scripts. Consequently, modifying an action might affect an element that calls this action in a script that the Find Elements that Use this Element function did not identify.
Procedure
1 Click the Actions view in the Orchestrator client.
2 Expand the nodes of the actions hierarchical list to navigate to a given action.
3 Right-click the action and select Find Elements that Use this Element.
A dialog box shows all of the elements, such as workflows or packages, that implement this action.
4 Double-click an element in the list of results to show that element in the Orchestrator client.
You located all of the elements that implement an action.
What to do next
You can check whether modifying this element affects any other elements.
Action Coding Guidelines
To optimize the performance of workflows and to maximize the potential to reuse actions, you should follow some basic coding guidelines when creating actions.
Basic Action Guidelines
When you create an action, you must use basic guidelines.
n Every action must include a description of its role and function.
n n n
Write short, elementary actions and combine them in a workflow.
Avoid writing actions that perform multiple functions, because this limits the potential for reusing the action.
Avoid actions that run for long periods of time. Instead, create a loop in the workflow and include a
Waiting Event or Waiting Timer element after the action element.
VMware, Inc. 113
vCenter Orchestrator Developer's Guide n n
Do not write check points in actions. Workflows set a check point at the start and end of each element's run.
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.
Action Naming Guidelines
Use basic guidelines when you name actions.
n Write action names in English.
n n
Start action names with a lowercase letter. Use an uppercase letter at the beginning of each conjoined word in the name. For example, myAction .
Make action names as explicit as possible, so that the function of the action is clear. For example, backupAllVMsInPool .
n n n
Make module names as explicit as possible.
Make module names unique.
Use the inverse Internet address format for module names. For example, com.vmware.myactions.myAction
.
Action Parameter Guidelines
Use basic guidelines when you write action parameter definitions.
n Write parameter names in English.
n n n
Start parameter names with a lowercase letter.
Make parameter names as explicit as possible.
Preferably limit parameter names to a single word. If a name must contain more than one word, use an uppercase letter at the beginning of each conjoined word in the name. For example, myParameter
.
n n n n
Use the plural form for parameters that represent an array of objects.
Make variable names unambiguous, for example, displayName .
Include a description for each parameter to describe its purpose.
Do not use an excessive number of parameters in a single action.
114 VMware, Inc.
Scripting
4
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.
The Orchestrator workflow engine allows you to use basic JavaScript language features, such as if, loops, arrays, and strings. You can use objects in scripting that the Orchestrator API provides, or objects from any other API that you import into Orchestrator through a plug-in and that you map to JavaScript objects. For information about Rhino, see the Mozilla Rhino Web site at http://www.mozilla.org/rhino/ .
This chapter includes the following topics: n
“Orchestrator Elements that Require Scripting,” on page 115
n n n n
“Limitations of the Mozilla Rhino Implementation in Orchestrator,” on page 116
“Using the Orchestrator API,” on page 116
“Exception Handling Guidelines,” on page 122
“Orchestrator JavaScript Examples,” on page 123
Orchestrator Elements that Require Scripting
Not all Orchestrator elements require you to write scripts. To provide maximum flexibility to your applications, you can customize certain elements by adding JavaScript functions.
You can add scripts in the following Orchestrator elements.
Actions
Policies
Workflows
Actions are scripted functions. You can limit the scripting you write for an action to a single operation, to maximize the potential for action reuse by other elements, such as other workflows. Alternatively, an action can contain many operations, to limit the complexity of workflows, although this does reduce the capacity for reusing the action.
You set policies by using scripts that watch for trigger events. When the trigger events occur, policies launch orchestration operations that you define in scripts.
The Scriptable Task workflow element allows you to write a custom scripted operation or sequence of operations that you can use in the workflows. You also define the Boolean decision statement for custom decision elements in scripts that return either true or false .
VMware, Inc. 115
vCenter Orchestrator Developer's Guide
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 n n n
When a workflow runs, the objects that pass from one workflow element to another are not Javascript objects. What is passed from one element to the next is the serialization of a Java object that has a Javascript image. As a consequence, you cannot use the whole Javascript language, but only those classes that are present in the API Explorer. You cannot pass function objects from one workflow element to another.
Orchestrator runs the code in scriptable task elements in a context that is not the Rhino root context.
Orchestrator transparently wraps scriptable task elements and actions into Javascript functions, which it then runs. A scriptable task element that contains
System.log(this);
does not display the global object this in the same way as a standard Rhino implementation.
You can only call actions that return nonserializable objects from scripting, and not from workflows. To call an action that returns a nonserializable object, you must write a scriptable task element that calls the action by using the System.getModule
ModuleName.action() method.
Workflow validation does not check whether a workflow attribute type is different to an input type of an action or subworkflow. If you change the type of a workflow input parameter, for example from
VIM3:VirtualMachine
to
VC:VirtualMachine
, but you do not update any scriptable tasks or actions that use the original input type, the workflow validates but does not run.
Using the Orchestrator API
The Orchestrator API exposes as JavaScript objects and methods all of the objects and functions of the technologies that Orchestrator accesses through its plug-ins.
For example, you can access JavaScript implementations of the vCenter Server API through the Orchestrator
API, to include vCenter operations in scripted elements that you create. You can also access JavaScript implementations of objects from all of the other plug-ins you install in the Orchestrator server. If you create a custom plug-in to a third-party application, you map the objects from its API to JavaScript objects that the
Orchestrator API then exposes.
Procedure
1
Access the Scripting Engine from the Workflow Editor on page 117
The Orchestrator scripting engine uses the Mozilla Rhino 1.6 JavaScript engine to help you write scripts for scripted elements in workflows. You access the scripting engine for scripted workflow elements from the Scripting tab in the workflow editor.
2
Access the Scripting Engine from the Action or Policy Editor on page 117
The Orchestrator scripting engine uses the Mozilla Rhino JavaScript engine to help you write scripts for actions or policies. You access the scripting engine for actions and policies from the Scripting tabs in the action and policy editors.
3
Access the Orchestrator API Explorer on page 118
Orchestrator provides an API Explorer to allow you to search the Orchestrator API and see the documentation of JavaScript objects that you can use in scripted elements.
4
Use the Orchestrator API Explorer to Find Objects on page 118
The Orchestrator API exposes the API of all plugged-in technologies, including the entire vCenter Server
API. The Orchestrator API Explorer helps you find the objects you need to add to scripts.
116 VMware, Inc.
Chapter 4 Scripting
5
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 120
The Orchestrator scripting engine helps you to import available parameters into scripts.
7
Accessing the Orchestrator Server File System from JavaScript and Workflows on page 121
Orchestrator limits access to the Orchestrator server file system from JavaScript and Workflows to specific directories.
8
Accessing Java Classes from JavaScript on page 121
By default, Orchestrator restricts JavaScript access to a limited set of Java classes. If you require JavaScript access to a wider range of Java classes, you must set an Orchestrator system property to allow this access.
9
Accessing Operating System Commands from JavaScript on page 122
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.
Access the Scripting Engine from the Workflow Editor
The Orchestrator scripting engine uses the Mozilla Rhino 1.6 JavaScript engine to help you write scripts for scripted elements in workflows. You access the scripting engine for scripted workflow elements from the
Scripting tab in the workflow editor.
Procedure
1 Right-click a workflow in the Workflows view of the Orchestrator client and select Edit.
2 Click the Schema tab in the workflows editor.
3 Add a Scriptable Task element or a Custom Decision element to the workflow schema.
4 Click on the scriptable element's Scripting tab.
You accessed the scripting engine to define the scripted functions of workflow elements. The Scripting tab allows you to navigate through the API, consult documentation about the objects, search for objects, and write
JavaScript.
What to do next
Search the Orchestrator API using the API Explorer.
Access the Scripting Engine from the Action or Policy Editor
The Orchestrator scripting engine uses the Mozilla Rhino JavaScript engine to help you write scripts for actions or policies. You access the scripting engine for actions and policies from the Scripting tabs in the action and policy editors.
Procedure
1 Right-click an action or policy in the Actions or Policies views of the Orchestrator client and select Edit.
2 Click the Scripting tab in the action or policy editor.
You accessed the scripting engine to define the scripted functions of action or policy elements. The Scripting tab allows you to navigate through the API, consult documentation about the objects, search for objects, and write JavaScript.
VMware, Inc. 117
vCenter Orchestrator Developer's Guide
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 of JavaScript objects that you can use in scripted elements.
Procedure u You can access the API Explorer from either the Orchestrator client or from the Scripting tabs of the workflow, policy, and action editors.
n To access the API Explorer from the Orchestrator client, click Tools > API Explorer in the Orchestrator client tool bar.
n To access the API Explorer from the Scripting tabs of the workflow, policy, and action editors, click
Search API on the left.
The API Explorer appears, allowing you to search all the objects and functions of the Orchestrator API.
What to do next
Use the API Explorer to write scripts for scriptable elements.
Use the Orchestrator API Explorer to Find Objects
The Orchestrator API exposes the API of all plugged-in technologies, including the entire vCenter Server API.
The Orchestrator API Explorer helps you find the objects you need to add to scripts.
Prerequisites
The API Explorer is open.
Procedure
1 Enter the name or part of a name of an object in the API Explorer Search text box and click Search.
To limit your search to a particular object type, uncheck or check the Scripting Class, Attributes &
Methods and Types & Enumerations check boxes.
2 Double-click the element in the proposed list.
The object is highlighted in the hierarchical list on the left. A documentation pane under the hierarchical list presents information about the object.
You found the object you were looking for.
What to do next
Use the objects you find in scripts.
JavaScript Objects in the API Explorer
The Orchestrator API Explorer identifies and groups together the different kinds of JavaScript objects in the hierarchical tree on the left of the Scripting tab or API Explorer dialog box. The API Explorer uses icons to help you identify the different kinds of object.
Table 4-1 describes the objects of the Orchestrator API and shows their icon.
118 VMware, Inc.
Chapter 4 Scripting
Table 4-1. JavaScript Objects in the Orchestrator API
Object
Type
Icon in Hierarchical List
Function set
Primitive
Object
Attribute
Method
Constructor
Enumeration
String set
Module
Plug-in Image that plug-in defines
Description
Types
Internal type that contains a set of static methods
Primitive types
Standard Orchestrator scripting objects
JavaScript attributes
JavaScript methods
JavaScript constructors
JavaScript enumerations
String set, default values
A collection of actions
The APIs that plug-ins expose to
Orchestrator
Writing Scripts
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.
Prerequisites
A scripted element is open for editing and its Scripting tab is open.
Procedure
1 Navigate through the hierarchical list of objects on the left of the Scripting tab, or use the API Explorer search function, to select a type, class, or method to add to the script.
2 Right-click the type, class, or method and select Copy.
If the scripting engine does not allow you to copy the element you selected, this object is not possible in the context of the script.
3 Right-click in the scripting pad, and paste the element you copied into the appropriate place in the script.
The scripting engine enters the element into the script, complete with its constructor and an instance name.
For example, if you copied the
Date
object, the scripting engine pastes the following code into the script.
var myDate = new Date();
VMware, Inc. 119
vCenter Orchestrator Developer's Guide
4 Copy and paste a method to add to the script.
The scripting engine completes the method call, adding the required attributes.
For example, if you copied the cloneVM()
method from the com.vmware.library.vc.vm
module, the scripting engine pastes the following code into the script.
System.getModule("com.vmware.library.vc.vm").cloneVM(vm,folder,name,spec)
The scripting engine highlights those parameters that you already defined in the element. Any undefined parameters remain unhighlighted.
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.
N
OTE
The automatic completion feature is currently experimental.
You added object and functions to the script.
What to do next
Add parameters to the script.
Color Coding of Scripting Keywords
When you add scripts on the Scripting tab of a scripted workflow element, certain types of keywords appear in different colors to enhance the readability of the code.
All scripting appears in standard black font unless stated otherwise.
Table 4-2. Color Coding of Scripting Keywords
Keyword Type
Standard JavaScript keywords, for example if, else, for, and new
Variable declarations, namely var
Modifiers in loops, for example in
Null variable values
Non-null variable values
Code comments
Orchestrator plug-in object types, for example
VC:VirtualMachine or VC:Host
Output text
Workflow attributes
Workflow inputs
Workflow outputs
Text Color in Scripting Tab
Bold black
Green
Red
Purple
Green
Italic gray
Green
Green
Pink
Pink
Pink
Add Parameters to Scripts
The Orchestrator scripting engine helps you to import available parameters into scripts.
If you have already defined parameters for the element you are editing, they appear as links in the Scripting tab toolbar.
Prerequisites
A scripted element is open for editing and its Scripting tab is open.
120 VMware, Inc.
Chapter 4 Scripting
Procedure
1 Move the cursor to the appropriate position in a script in the scripting pad of the Scripting tab.
2 Click the parameter link in the Scripting tab toolbar.
Orchestrator inserts the parameter at the position of the cursor.
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.
Accessing the Orchestrator Server File System from JavaScript and Workflows
Orchestrator limits access to the Orchestrator server file system from JavaScript and Workflows to specific directories.
Javascript functions and workflows only have read, write, and execute permission in the permanent directory c:\orchestrator .
The Orchestrator administrator can modify the folders to which JavaScript functions and workflows have read, write, and execute access by setting a system property. See the VMware vCenter Orchestrator Administration
Guide for information about setting system properties.
JavaScript functions and workflows also have read, write, and execute permission in the server system default temporary I/O folder. Writing to the default temporary I/O folder is the only portable, guaranteed, and configuration-independent means of accessing the file system with full permissions. However, files that you write to the temporary I/O folder are lost when you reboot the server.
You obtain the default temporary I/O folder by calling the System.getTempDirectory
method in JavaScript functions.
Access the Server File System Using the System.getTempDirectory Method
As an alternative to writing to the folders on the Orchestrator server system in which the administrator has set the appropriate permissions, you can write to the default temporary I/O folder.
Orchestrator has full read, write, and execute rights in the default temporary I/O folder by default. You obtain the default temporary I/O folder by using the System.getTempDirectory
method in JavaScript functions
Procedure u Include the following code line in JavaScript functions to access the java.io.temp-dir folder.
var tempDir = System.getTempDirectory()
Accessing Java Classes from JavaScript
By default, Orchestrator restricts JavaScript access to a limited set of Java classes. If you require JavaScript access to a wider range of Java classes, you must set an Orchestrator system property to allow this access.
By default, the Orchestrator JavaScript engine can access only the classes in the java.util.* package.
The Orchestrator administrator can allow access to other Java classes from JavaScript functions by setting a system property. See the VMware vCenter Orchestrator Administration Guide for information about setting system properties.
VMware, Inc. 121
vCenter Orchestrator Developer's Guide
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.allow-local-process=true
system property.
For information about setting system properties, see the VMware vCenter Orchestrator Administration Guide.
Exception Handling Guidelines
The Orchestrator implementation of the Mozilla Rhina JavaScript Engine supports exception handling, to allow you to process errors. You must use the following guidelines when writing exception handlers in scripts.
n Use the following European Computer Manufacturers Association (ECMA) error types. Use Error as a generic exception that plug-in functions return, and the following specific error types.
n TypeError n RangeError n EvalError n ReferenceError n URIError n SyntaxError
The following example shows a URIError definition.
try {
...
throw new URIError("VirtualMachine with ID 'vm-0056'
not found on 'vcenter-test-1'") ;
...
} catch ( e if e instanceof URIError ) { n n
}
All exceptions that scripts do not catch must be simple string objects of the form <type>:SPACE<human readable message>
, as the following example shows.
throw "ValidationError: The input parameter 'myParam' of type 'string' is too short."
Write human readable messages as clearly as possible.
122 VMware, Inc.
Chapter 4 Scripting n n
Simple string exception type checking must use the following pattern.
try {
throw "VMwareNoSpaceLeftOnDatastore: Datastore 'myDatastore' has no space left" ;
} catch ( e if (typeof(e)=="string" && e.indexOf("VMwareNoSpaceLeftOnDatastore:") == 0) ) {
System.log("No space left on device") ;
// Do something useful here
}
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.
n n
Basic Scripting Examples on page 124
Workflow scripted elements, actions, and policies require basic scripting of common tasks. You can cut, paste, and adapt these examples into your scripted elements.
Email Scripting Examples on page 125
Workflow scripted elements, actions, and policies require scripting of common email-related tasks. You can cut, paste, and adapt these examples into your scripted elements.
n n
File System Scripting Examples on page 126
Workflow scripted elements, actions, and policies require scripting of common file system tasks. You can cut, paste, and adapt these examples into your scripted elements.
LDAP Scripting Examples on page 126
Workflow scripted elements, actions, and policies require scripting of common LDAP tasks. You can cut, paste, and adapt these examples into your scripted elements.
n n n n
Logging Scripting Examples on page 127
Workflow scripted elements, actions, and policies require scripting of common logging tasks. You can cut, paste, and adapt these examples into your scripted elements.
Networking Scripting Examples on page 127
Workflow scripted elements, actions, and policies require scripting of common networking tasks. You can cut, paste, and adapt these examples into your scripted elements.
vCenter Server Scripting Examples on page 127
Workflow scripted elements, actions, and policies require scripting of common vCenter Server tasks.
You can cut, paste, and adapt these examples into your scripted elements.
Workflow Scripting Examples on page 129
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.
VMware, Inc. 123
vCenter Orchestrator Developer's Guide
Basic Scripting Examples
Workflow scripted elements, actions, and policies require basic scripting of common tasks. You can cut, paste, and adapt these examples into your scripted elements.
Access XML Documents
The following JavaScript example allows you to access XML documents from JavaScript by using the
ECMAScript for XML (E4X) implementation in the Orchestrator JavaScript API.
N
OTE
In addition to implementing E4X in the JavaScript API, Orchestrator also provides a Document Object
Model (DOM) XML implementation in the XML plug-in. For information about the XML plug-in and its sample workflows, see the vCenter Orchestrator Admninistration Guide.
var people = <people>
<person id="1">
<name>Moe</name>
</person>
<person id="2">
<name>Larry</name>
</person>
</people>;
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].@id='47';
// change Moe's id to 47
// also supports search by constraints
System.log("Moe's id is now : " + people.person.(name=='Moe').@id);
// suppress Moe from the list delete people.person[0];
System.log("Moe is now removed.");
// new (sub-)document can be built from a string people.person[1] = new XML("<person id=\"3\"><name>James</name></person>");
System.log("Added James to the list, which is now :"); for each(var person in people..person) for each(var person in people..person){
System.log("- " + person.name + " (id=" + person.@id + ")");
}
124 VMware, Inc.
Chapter 4 Scripting
Setting and Obtaining Properties from a Hashtable
The following JavaScript example sets properties in a hashtable and obtains the properties from the hashtable.
In the following example, the key is always a String and the value is an object, a number, a Boolean, or a String.
var table = new Properties() ; table.put("myKey",new Date()) ;
// get the object back var myDate= table.get("myKey") ;
System.log("Date is : "+myDate) ;
Replace the Contents of a String
The following JavaScript example replaces the content of a String and replaces it with new content.
var str1 = "'hello'" ; var reg = new RegExp("(')", "g"); var str2 = str1.replace(reg,"\\'") ;
System.log(""+str2) ; // result : \'hello\'
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.
N
OTE
var cmd = new Command("ls -al") ; cmd.execute(true) ;
System.log(cmd.output) ;
Email Scripting Examples
Workflow scripted elements, actions, and policies require scripting of common email-related tasks. You can cut, paste, and adapt these examples into your scripted elements.
Obtain an Email Address
The following JavaScript example obtains the email address of the current owner of a running script.
var emailAddress = Server.getRunningUser().emailAddress ;
VMware, Inc. 125
vCenter Orchestrator Developer's Guide
Send an Email
The following JavaScript example sends an email to the defined recipient, through an SMTP server, with the defined content.
var message = new EmailMessage() ; message.smtpHost = "smtpHost" ; message.subject= "my subject" ; message.toAddress = "[email protected]" ; message.fromAddress = "[email protected]" ; message.addMimePart("This is a simple message","text/html") ; message.sendMessage() ;
File System Scripting Examples
Workflow scripted elements, actions, and policies require scripting of common file system tasks. You can cut, paste, and adapt these examples into your scripted elements.
N
OTE
Add Content to a Simple Text File
The following JavaScript example adds content to a text file.
var tempDir = System.getTempDirectory() ; var fileWriter = new FileWriter(tempDir + "/readme.txt") ; fileWriter.open() ; fileWriter.writeLine("File written at : "+new Date()) ; fileWriter.writeLine("Another line") ; fileWriter.close() ;
Obtain the Contents of a File
The following JavaScript example obtains the contents of a file from the Orchestrator server host machine.
var tempDir = System.getTempDirectory() ; var fileReader = new FileReader(tempDir + "/readme.txt") ; fileReader.open() ; var fileContentAsString = fileReader.readAll(); fileReader.close() ;
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.search("UserGroup",ldapGroup.commonName) ;
// convert back to LdapGroup element var ldapElement = Server.getLdapElement(adGroup.distinguishedName) ;
126 VMware, Inc.
Chapter 4 Scripting
Logging Scripting Examples
Workflow scripted elements, actions, and policies require scripting of common logging tasks. You can cut, paste, and adapt these examples into your scripted elements.
Persistent Logging
The following JavaScript example creates persistent log entries.
Server.log("This is a persistant message", "enter a long description here");
Server.warn("This is a persistant warning", "enter a long description here");
Server.error("This is a persistant error", "enter a long description here");
Non-Persistent Logging
The following JavaScript example creates non-persistent log entries.
System.log("This is a non-persistant log message");
System.warn("This is a non-persistant log warning");
System.error("This is a non-persistant log error");
Networking Scripting Examples
Workflow scripted elements, actions, and policies require scripting of common networking tasks. You can cut, paste, and adapt these examples into your scripted elements.
Obtain Text from a URL
The following JavaScript example accesses a URL, obtains text, and converts it to a string.
var url = new URL("http://www.vmware.com") ; var htmlContentAsString = url.getContent() ;
vCenter Server Scripting Examples
Workflow scripted elements, actions, and policies require scripting of common vCenter Server tasks. You can cut, paste, and adapt these examples into your scripted elements.
Access Managed Object Types
The following JavaScript example allows Orchestrator to use scripting to access vCenter Server managed objects through the vCenter Server plug-in.
var vm = ...;
// Get the property 'name' var name = vm.name; // returns a string
// return a VcEnvironmentBrowser managed object var environmentBrowser = vm.environmentBrowser;
Access Managed Object Reference Types
The following JavaScript example allows Orchestrator to access data objects with the return type
ManagedObjectReference . You must use the toManagedObject() method to convert workflow input parameter objects to managed objects.
// VcVirtualMachineSnapshotInfo data object var virtualMachineSnapshotInfo = virtualMachine.snapshot;
// There is no automatic conversion between ManagedObjectReference and VimManagedObject
VMware, Inc. 127
vCenter Orchestrator Developer's Guide
// in a 'Data Object Type'. virtualMachineSnapshotRef is only the reference to the
// 'Managed Object Type' not the object itself var virtualMachineSnapshotRef = virtualMachineSnapshotInfo.currentSnapshot;
// Convert from ManagedObjectReference to a VimManagedObject.
// The concrete class is VcVirtualMachineSnapshot.
var virtualMachineSnapshot = VcPlugin.toManagedObject(
virtualMachine, virtualMachineSnapshotRef);
// The reverse operation, if required.
//virtualMachineSnapshotInfo.currentSnapshot =virtualMachineSnapshot.reference;
Handle Enumeration Types
The following JavaScript example allows Orchestrator to use scripting to handle vCenter Server enumerations through the vCenter Server plug-in.
// a VcSharesLevel FINDER ENUMERATION TYPE, for example
// received from an input parameter var sharesLevel = ...
// get the String value of the FINDER ENUMERATION TYPE var sharesLevelString = sharesLevel.name;
// Convert from the String value to a static value of VcSharesLevel
// SCRIPTING TYPE var level = VcSharesLevel.fromString(sharesLevel.name);
// Assign to a DataObject var sharesInfo = new VcSharesInfo(); sharesInfo.level = level;
Discover Host Machines and Virtual Machines
The following JavaScript example allows Orchestrator to use scripting to find host machines and virtual machines through the vCenter Server plug-in.
var vimHosts = VcPlugin.allSdkConnections();
System.log(vimHosts.length + " Vim hosts found"); for (var i = 0; i < vimHosts.length; i++) {
var vimHost = vimHosts[i];
System.log("Vim host '" + vimHost.id + "'");
// Hierarchy entry point
var rootFolder = vimHost.rootFolder;
// Get the property 'name'
var name = rootFolder.name;
System.log("--- Root folder '" + name + "'");
// Get the folder's data centers
var datacenters = rootFolder.datacenter;
if (datacenters != null) {
for (var j = 0; j < datacenters.length; j++) {
var datacenter = datacenters[j];
System.log("--- Datacenter '" + datacenter.id + "'");
}
128 VMware, Inc.
Chapter 4 Scripting
}
// Method to get all the host systems in a vCenter Server host
var hostSystems = vimHost.getAllHostSystems();
if (hostSystems != null) {
for (var j = 0; j < hostSystems.length; j++) {
var hostSystem = hostSystems[j];
System.log("--- HostSystem '" + hostSystem.id + "'");
}
}
// Method to get all the virtual machines in a vCenter Server host
var vms = vimHost.getAllVirtualMachines();
if (vms != null) {
for (var j = 0; j < vms.length; j++) {
var vm = vms[j];
System.log("--- VM '" + vm.id + "'");
System.log("--- VM '" + vm.getName() + "'");
var guestInfo = vm.guest;
System.log("--- VM guestInfo '" + guestInfo + "'");
if (guestInfo != null) {
System.log("--- VM guestInfo.guestFamily '" + guestInfo.guestFamily + "'");
}
}
}
}
Set vCenter Server Option Values
The following JavaScript example allows Orchestrator to set vCenter VcOptionManager option values.
var myVcOptionValue = new VcOptionValue(); myVcOptionValue.key = VimAdvancedOptionKey; myVcOptionValue.value_LongValue = VimAdvancedOptionValue;
You can set the following optional value types as VcOptionValue attributes.
value value_FloatValue value_IntValue value_LongValue
Attribute is a string value.
Attribute value is a float value.
Attribute value is an integer value.
Attribute value is a long value.
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.findAllForType('WorkflowToken'); var currentUser = Server.getCredential().username; var res = []; for(var i = 0; i<res.length; i++){
VMware, Inc. 129
vCenter Orchestrator Developer's Guide
if(allTokens[i].runningUserName == currentUser){
res.push(allTokens[i]);
}
} return res;
Schedule a Workflow
The following JavaScript example starts a workflow with a given set of properties, then schedules it to start one hour later.
var workflowToLaunch = myWorkflow ;
// create parameters var workflowParameters = new Properties() ; workflowParameters.put("name","John Doe") ;
// change the task name workflowParameters.put("__taskName","Workflow for John Doe") ;
// create scheduling date one hour in the future var workflowScheduleDate = new Date() ; var time = workflowScheduleDate.getTime() + (60*60*1000) ; workflowScheduleDate.setTime(time) ; var scheduledTask = workflowToLaunch.schedule(workflowParameters,workflowScheduleDate);
Run a Workflow on a Selection of Objects in a Loop
The following JavaScript example takes the array of virtual machines and runs a workflow on each one in a
For
loop.
VMs
and workflowToRun
are workflow inputs.
var len=VMs.length; for (var i=0; i < len; i++ )
{
var VM = VMs[i];
//var workflowToLaunch = Server.getWorkflowWithId(" workflowId");
var workflowToLaunch = workflowToRun;
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);
}
130 VMware, Inc.
Creating Resource Elements
5
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. Any workflows or Web views that run in the Orchestrator server can use any resource elements that you import into Orchestrator.
Importing an object into Orchestrator as a resource element allows you to make changes to the object in a single location, and to propagate those changes automatically to all the workflows or Web views that use this resource element.
You can organize resource elements into categories. The maximum size for a resource element is 16MB.
This chapter includes the following topics: n n n n n n n
“View a Resource Element,” on page 131
“Import an External Object to Use as a Resource Element,” on page 132
“Edit the Resource Element Information and Access Rights,” on page 132
“Save a Resource Element to a File,” on page 133
“Update a Resource Element,” on page 133
“Add a Resource Element to a Workflow,” on page 133
“Add a Resource Element to a Web View,” on page 134
View a Resource Element
You can view existing resource elements in the Orchestrator client, to examine their contents and discover which workflows or Web views use this resource element.
Procedure
1 Click the Resources view in the Orchestrator client.
2 Expand the hierarchical tree viewer to navigate to a resource element.
3 Click a resource element to show information about it in the right pane.
4 Click the Viewer tab to display the contents of the resource element.
5 Right-click the resource element and select Find Elements that Use this Element.
Orchestrator lists all the workflows and Web views that use this resource element.
VMware, Inc. 131
vCenter Orchestrator Developer's Guide
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.
Procedure
1 Click the Resources view in the Orchestrator client.
2 Right-click a resource folder in the hierarchical list and select New category to create a folder in which to store the resource element.
3 Right-click the resource folder in which to import the resource element and select Import resource(s).
4 Select the resource to import and click Open.
Orchestrator adds the resource element to the folder you selected.
You imported a resource element into the Orchestrator server.
What to do next
Edit the general information of the resource element and set the user access permissions.
Edit the Resource Element Information and Access Rights
After you import an object into the Orchestrator server as a resource element, you can edit the resource element's details and permissions.
Prerequisites
An image, script, XML, or HTML file, or any other type of object that you imported into Orchestrator as a resource element.
Procedure
1 Right-click the resource element and select Edit.
2 Click the General tab and set the resource element name, version, and description.
3 Click the Permissions tab and click the Add access rights link to define permissions for a user group.
4 Type a user group name in the Search text box.
5 Select a user group and click OK.
6 Right-click the user group and select Add access rights.
7 Check the appropriate check boxes to set the level of permissions for this user group and click OK.
Permissions are not cumulative. To allow a user to view the resource element, use it in their workflows or Web views, and change the permissions, you must check all check boxes.
8 Click Save and Close to exit the editor.
You edited the general information about the resource element and set the user access rights.
132 VMware, Inc.
Chapter 5 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.
Prerequisites
You must have a resource element in the Orchestrator server to save to a file.
Procedure
1 Right-click the resource element and select Save to file.
2 Make the required modifications to the file.
You saved a resource element to a file.
What to do next
Update the resource element in the Orchestrator server.
Update a Resource Element
If a file or object that you have defined as a resource element changes, you can update the resource element in the Orchestrator server.
Prerequisites
An image, script, XML, or HTML file, or any other type of object that you imported into Orchestrator as a resource element.
Procedure
1 Modify the source file of the resource element in your local system.
2 Click the Resources view in the Orchestrator client.
3 Navigate through the hierarchical list to the resource element that you have updated.
4 Right-click the resource element and select Update resource.
5 (Optional) Click the Viewer tab to check that Orchestrator has updated the resource element.
You updated a resource element that the Orchestrator server contains.
Add a Resource Element to a Workflow
Resource elements are external objects that you can import to the Orchestrator server for workflows to use as attributes when they run. For example, a workflow can use an imported XML file that defines a map to convert one type of data to another, or a script that defines a function, when it runs.
Prerequisites
You must have the following objects in your Orchestrator server: n n
An image, script, XML, or HTML file, or any other type of object that you imported into Orchestrator as a resource element.
A workflow that requires this resource element as an attribute.
VMware, Inc. 133
vCenter Orchestrator Developer's Guide
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.
6 Click Type to set the attribute type.
7 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 category that contains multiple resource elements as an attribute
Select ResourceElementCategory from the list.
8 Click Value and type the name of the resource element or category of resource elements in the Search text box.
9 Select the resource element or category of resource elements from the proposed list and click Select.
10 Click Save and Close to exit the editor.
You added a resource element or category of resource elements as an attribute in a workflow.
Add a Resource Element to a Web View
Resource elements are external objects that you can import into the Orchestrator server for Web views to use as Web view attributes. Web view attributes identify objects with which Web view components interact.
Prerequisites
You must have the following objects in your Orchestrator server: n n
An image, script, XML, or HTML file, or any other type of object that you imported into Orchestrator as a resource element.
A Web view that requires this resource element as an attribute.
Procedure
1 Click the Web views view in the Orchestrator client.
2 If the Web view is running, right-click the Web view to which to add the resource element and select
Unpublish.
3 Right-click the Web view and select Edit.
4 Click the Attributes tab.
5 Right-click in the Attributes tab and select Add attribute.
6 Click the attribute name and type a new name for the attribute.
7 Click Type to set the attribute type.
134 VMware, Inc.
Chapter 5 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 category 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 Search text box.
10 Select the resource element or category of resource elements from the proposed list and click Select.
11 Click Save and Close to exit the editor.
You added a resource element or category of resource elements as an attribute in a Web view.
VMware, Inc. 135
vCenter Orchestrator Developer's Guide
136 VMware, Inc.
Creating Packages
6
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.
When you import a package, the server compares the versions of the different elements of its contents to matching local elements. The comparison shows the differences in versions between the local and imported elements. The administrator can decide whether to import the package, or choose specific elements to import.
Packages use digital rights management to control how the receiving server can use the content of the package.
Orchestrator signs packages and encrypts the packages for data protection. Packages can track which users export and redistribute elements by using X509 certificates.
I
MPORTANT
Packages that Orchestrator 3.2 generates are upwardly compatible with Orchestrator 4.x. You can import a package from an Orchestrator 3.2 server into an Orchestrator 4.x server. Packages from Orchestrator
4.x are not backwards compatible with Orchestrator 3.2. You cannot import into an Orchestrator 3.2 server a package that an Orchestrator 4.x server generates.
For more information about using packages, see VCenter Orchestrator Administration Guide.
n n
You export workflows, policies, actions, plug-in references, resources, Web views, and configuration elements in packages. All elements that an element implements are added to the package automatically, to ensure compatibility between versions. If you don't want to add the referenced elements, you can delete them in the package editor.
Set User Permissions on a Package on page 138
You set different levels of permission on a package to limit the access that different users or user groups can have to the contents of that package.
Create a Package
You export workflows, policies, actions, plug-in references, resources, Web views, and configuration elements in packages. All elements that an element implements are added to the package automatically, to ensure compatibility between versions. If you don't want to add the referenced elements, you can delete them in the package editor.
Prerequisites
Elements such as workflows, actions, and policies to add to a package.
VMware, Inc. 137
vCenter Orchestrator Developer's Guide
Procedure
1 Click the Packages view in the Orchestrator client.
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.
6 Click the Workflows tab to add workflows to the package.
n n
Click Insert Workflows (list search) to search for and select workflows in a selection dialog box.
Click Insert Workflows (tree browsing) to browse and select workflows in a hierarchical list.
7 (Optional) Click the Policies, Actions, Web View, Configurations, Resources, and Used Plug-Ins tabs to add policy templates, actions, Web views, configuration elements, resource elements, and plug-ins to the package.
You created a package and added elements to it.
What to do next
You must set the user permissions for this package.
Set User Permissions on a Package
You set different levels of permission on a package to limit the access that different users or user groups can have to the contents of that package.
You select the different users and user groups for which to set permissions from the users and user groups in the Orchestrator LDAP server. Orchestrator defines levels of permissions that you can apply to users or groups.
View
Inspect
Execute
Edit
Admin
The user can view the elements in the package, but cannot view the schemas or scripting.
The user can view the elements in the package, including the schemas and scripting.
Not used.
The user can edit the elements in the package.
The user can set permissions on the elements in the package.
Prerequisites
You must have created a package, opened it for editing in the package editor, and added to it the necessary elements.
Procedure
1 Click the Permissions tab in the package editor.
2 Click the Add access rights link to define permissions for a new user or user group.
138 VMware, Inc.
Chapter 6 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.
To allow a user to view the elements, inspect the schema and scripting, run and edit the elements, and change the permissions, you must check all check boxes.
7 Click Save and Close to exit the package editor.
You created a package and set the appropriate user permissions.
VMware, Inc. 139
vCenter Orchestrator Developer's Guide
140 VMware, Inc.
Developing Plug-Ins
7
Plug-ins allow you to use Orchestrator to access and control external technologies and applications. Exposing an external technology in an Orchestrator plug-in allows you to incorporate objects and functions in workflows that access the objects and functions of that external technology.
Plug-ins allow you to extend the Orchestrator scripting API with scripting types, classes, and methods that you can use in workflows to perform operations in the plugged-in technology. Plug-ins also allow you to represent objects from the plugged-in technology in the Orchestrator inventory. Plug-ins publish notification events from the external system that trigger events in both Orchestrator and in the plugged-in technology.
Each plug-in can provide one or more packages of workflows and actions that you can run on the objects in the inventory to automate the typical use cases of the integrated product.
The external technologies that you can access by using plug-ins can include virtualization management tools, email systems, databases, directory services, and remote control interfaces.
Orchestrator provides a set of standard plug-ins to allow you to incorporate such technologies as the VMware vCenter Server API and email capabilities into workflows. In addition, the Orchestrator open plug-in architecture allows you to develop plug-ins to access other applications. Orchestrator implements open standards, to simplify integration with external systems.
This chapter includes the following topics: n
“Overview of Plug-Ins,” on page 141
n n
“Contents and Structure of a Plug-In,” on page 147
“Create an Orchestrator Plug-In,” on page 151
n n
“Orchestrator Plug-In API Reference,” on page 216
“Elements of the vso.xml Plug-In Definition File,” on page 230
Overview of Plug-Ins
Orchestrator plug-ins must include a standard set of parts and must adhere to a standard architecture. These practices help you to create plug-ins for the widest possible variety of external technologies.
n n
Exposing an External API to Orchestrator on page 142
You expose an API from an external product to the Orchestrator platform by creating an Orchestrator plug-in. You can create a plug-in for any technology that exposes an API that you can map into JavaScript objects that Orchestrator can use.
Parts of a Plug-In on page 142
Plug-ins are composed of a standard set of parts that expose the objects in the plugged-in technology to the Orchestrator platform.
VMware, Inc. 141
vCenter Orchestrator Developer's Guide n n n n n n
Role of the vso.xml File on page 144
You use the vso.xml
file to map the objects, classes, methods, and attributes of the plugged-in technology to Orchestrator inventory objects, scripting types, scripting classes, scripting methods, and attributes.
The vso.xml
file also defines the configuration and start-up behavior of the plug-in.
Roles of the Plug-In Adapter on page 144
The plug-in adapter is the entry point of the plug-in to the Orchestrator server. The plug-in adapter serves as the datastore for the plugged-in technology in the Orchestrator server, creates the plug-in factory, and manages events that occur in the plugged-in technology.
Roles of the Plug-In Factory on page 145
The plug-in factory defines how Orchestrator finds objects in the plugged-in technology and performs operations on the objects.
Role of Finder Objects on page 146
Finder objects identify and locate specific instances of managed object types in the plugged-in technology.
Orchestrator can modify and interact with objects that it finds in the plugged-in technology by running workflows on the finder objects.
Role of Scripting Objects on page 146
Scripting objects are JavaScript representations of objects from the plugged-in technology. Scripting objects from plug-ins appear in the Orchestrator Javascript API and you can use them in scripted elements in workflows and actions.
Role of Event Handlers on page 147
Events are changes in the states or attributes of the objects that Orchestrator finds in the plugged-in technology. Orchestrator monitors events by implementing event handlers.
Exposing an External API to Orchestrator
You expose an API from an external product to the Orchestrator platform by creating an Orchestrator plugin. You can create a plug-in for any technology that exposes an API that you can map into JavaScript objects that Orchestrator can use.
Plug-ins map Java objects and methods to JavaScript objects that they add to the Orchestrator scripting API.
If an external technology exposes a Java API, you can map the API directly to JavaScript for Orchestrator to use in workflows and actions.
You can create plug-ins for applications that expose an API in a language other than Java by using a Web service definition language (WSDL) or messaging service to integrate the exposed API with Java objects. You then map the integrated Java objects to JavaScript for Orchestrator to use.
The plugged-in technology is independent from Orchestrator. You can create Orchestrator plug-ins for external products even if you only have access to binary code, for example in Java archives (JAR files), rather than source code.
Parts of a Plug-In
Plug-ins are composed of a standard set of parts that expose the objects in the plugged-in technology to the
Orchestrator platform.
The main parts of a plug-in are the plug-in adapter, factory, and event implementations. You map the objects and operations defined in the adapter, factory, and event implementations to Orchestrator objects in an XML definition file named vso.xml
. The vso.xml
file maps objects and functions from the plugged in technology to
JavaScript scripting objects that appear in the Orchestrator JavaScript API. The vso.xml
file also maps object types from the plugged-in technology to finders, that appear in the Orchestrator Inventory tab.
142 VMware, Inc.
Chapter 7 Developing Plug-Ins
Plug-ins are composed of the following parts.
Plug-In Module
Plug-In Adapter
Plug-In Factory
Configuration
Finders
Scripting Objects
Inventory
Events
The plug-in itself, as defined by a collection of Java classes, a vso.xml
file, and packages of the workflows and actions that interact with the objects that you access through the plug-in. The plug-in module is mandatory.
Defines the interface between the plugged-in technology and the Orchestrator server. The adapter is the point of entry of the plug-in to the orchestration platform. The adapter creates the plug-in factory, manages the loading and unloading of the plug-in, and manages the events that occur on the objects in the plugged-in technology. The plug-in adapter is mandatory.
Defines how Orchestrator finds objects in the plugged-in technology and performs operations on them. The adapter creates a factory for the client session that opens between Orchestrator and a plugged-in technology. The factory allows you either to share a session between all client connections or to open one session per client connection. The plug-in factory is mandatory.
You can add a tab to the Orchestrator configuration interface in which you can configure the plug-in after you install it. For example, you can add a tab to the
Orchestrator configuration interface in which users provide information about the environment in which the plugged-in technology is running. Orchestrator does not define a standard way for the plug-in to store its configuration. You can store configuration information by using Windows Registries, static configuration files, storing information in a database, or in XML files. The plugin configuration tab is optional.
Interaction rules that define how Orchestrator locates and represents the objects in the plugged-in technology. Finders retrieve objects from the network of objects that the plugged-in technology exposes to Orchestrator. You define in the vso.xml
file the relations between objects to allow you to navigate through the network of objects. Orchestrator represents the object model of the plugged-in technology in the Inventory tab. Finders are mandatory if you want to expose objects in the plugged-in technology to Orchestrator.
JavaScript object types that provide access to the objects, operations, and attributes in the plugged-in technology. Scripting objects define how
Orchestrator accesses the object model of the plugged-in technology through
JavaScript. You map the classes and methods of the plugged-in technology to
JavaScript objects in the vso.xml
file. You can access the JavaScript objects in the Orchestrator scripting API and integrate them into Orchestrator scripted tasks, actions, and workflows. Scripting objects are mandatory if you want to add scripting types, classes, and methods to the Orchestrator JavaScript API.
Instances of objects in the plugged-in technology that Orchestrator locates by using finders appear in the Inventory view in the Orchestrator client. You can perform operations on the objects in the inventory by running workflows on them. The inventory is optional. You can create a plug-in that only adds scripting types and classes to the Orchestrator JavaScript API and does not expose any instances of objects in the inventory.
Changes in the state of an object in the plugged-in technology. Orchestrator can listen passively for events that occur in the plugged-in technology.
Orchestrator can also actively trigger events in the plugged-in technology.
Events are optional.
VMware, Inc. 143
vCenter Orchestrator Developer's Guide
Role of the vso.xml File
You use the vso.xml
file to map the objects, classes, methods, and attributes of the plugged-in technology to
Orchestrator inventory objects, scripting types, scripting classes, scripting methods, and attributes. The vso.xml
file also defines the configuration and start-up behavior of the plug-in.
The vso.xml
file performs the following principal roles.
Start-Up and
Configuration Behavior
Inventory Objects
Scripting Types
Scripting Classes
Scripting Methods
Scripting Attributes
Defines the manner in which the plug-in starts and locates any configuration implementations that the plug-in defines. Loads the plug-in adapter.
Defines the types of objects that the plug-in accesses in the plugged-in technology. The finder methods of the plug-in factory implementation locate instances of these objects and display them in the Orchestrator inventory.
Adds scripting types to the Orchestrator JavaScript API to represent the different types of object in the inventory. You can use these scripting types as input parameters in workflows.
Adds classes to the Orchestrator JavaScript API that you can use in scripted elements in workflows, actions, policies, and so on.
Adds methods to the Orchestrator JavaScript API that you can use in scripted elements in workflows, actions, policies, and so on.
Adds the attributes of the objects in the plugged-in technology to the
Orchestrator JavaScript API that you can use in scripted elements in workflows, actions, policies, and so on.
Roles of the Plug-In Adapter
The plug-in adapter is the entry point of the plug-in to the Orchestrator server. The plug-in adapter serves as the datastore for the plugged-in technology in the Orchestrator server, creates the plug-in factory, and manages events that occur in the plugged-in technology.
To create a plug-in adapter, you create a Java class that implements the
IPluginAdaptor
interface.
The plug-in adapter class that you create manages the plug-in factory, events, and triggers in the plugged-in technology. The IPluginAdaptor interface provides methods that you use to perform these tasks.
The plug-in adapter performs the following principal roles.
Creates a factory
Manages events
The most important role of the plug-in adapter is to load and unload one plugin factory instance for every connection from Orchestrator to the plugged-in technology. The plug-in adapter class calls the
IPluginAdaptor.createPluginFactory()
method to create an instance of a class that implements the IPluginFactory interface.
The plug-in adapter is the interface between the Orchestrator server and the plugged-in technology. The plug-in adapter manages the events that
Orchestrator performs or watches for on the objects in the plugged-in technology. The adapter manages events through event publishers. Event publishers are instances of the IPluginEventPublisher interface that the adapter creates by calling the IPluginAdaptor.registerEventPublisher() method. Event publishers set triggers and gauges on objects in the plugged-in
144 VMware, Inc.
Chapter 7 Developing Plug-Ins
Sets the plug-in name
Installs licenses technology, to allow Orchestrator to launch defined actions if certain events occur on the object, or if the object's values pass certain thresholds. Similarly, you can define PluginTrigger and PluginWatcher instances that define events that Wait Event elements in long-running workflows await.
You provide a name for the plug-in in the vso.xml
file. The plug-in adapter gets this name from the vso.xml
file and publishes it in the Orchestrator client
Inventory view.
You can call methods to install any license files that the plugged-in technology requires in the adapter implement.
For full details of the IPluginAdaptor interface, all of its methods, and all of the other classes of the plug-in
of the IPluginAdaptor interface, see
“Create a Plug-In Adapter,” on page 186.
Roles of the Plug-In Factory
The plug-in factory defines how Orchestrator finds objects in the plugged-in technology and performs operations on the objects.
To create the plug-in factory, you must implement and extend the
IPluginFactory
interface from the
Orchestrator plug-in API. The plug-in factory class that you create defines the finder functions that Orchestrator uses to access objects in the plugged-in technology. The factory allows the Orchestrator server to find objects by their ID, by their relation to other objects, or by searching for a query string.
The plug-in factory performs the following principal tasks.
Finds objects
Finds objects related to other objects
Define queries to find objects according to your own criteria
You can create functions that find objects according to their name and type.
You find objects by name and type by using the IPluginFactory.find() method.
You can create functions to find objects that relate to a given object by a given relation type. You define relations in the vso.xml
file. You can also create finders to find dependent child objects that relate to all parents by a given relation type.
You implement the
IPluginFactory.findRelation()
method to find any objects that are related to a given parent object by a given relation type. You implement the IPluginFactory.hasChildrenInRelation() method to discover whether at least one child object exists for a parent instance.
You can create object finders that implement query rules that you define. You implement the IPluginFactory.findAll() method to find all objects that satisfy query rules you define when the factory calls this method. You obtain the results of the findAll() method in a QueryResult object that contains a list of all of the objects found that match the query rules you define.
For more information about the IPluginFactory interface, all of its methods, and all of the other classes of the plug-in API, see
“Orchestrator Plug-In API Reference,” on page 216. For an examination of an example
implementation of the
IPluginFactory
interface, see
“Create a Plug-In Factory,” on page 158.
VMware, Inc. 145
vCenter Orchestrator Developer's Guide
Role of Finder Objects
Finder objects identify and locate specific instances of managed object types in the plugged-in technology.
Orchestrator can modify and interact with objects that it finds in the plugged-in technology by running workflows on the finder objects.
Every instance of a given managed object type in the plugged-in technology must have a unique identifier so that Orchestrator finder objects can find them. The plugged-in technology provides the unique identifiers for the object instances as strings. When a workflow runs, Orchestrator sets the unique identifiers of the objects that it finds as workflow attribute values. Workflows that require an object of a given type as an input parameter run on a specific instance of that type of object.
Finder objects that plug-ins add to the Orchestrator JavaScript API have the plug-in name as a prefix. For example, the
VirtualMachine
managed object type from the vCenter Server API appears in Orchestrator as the
VC:VirtualMachine JavaScript type.
For example, Orchestrator accesses a specific VC:VirtualMachine instance through the vCenter Server plug-in by implementing a finder object that uses the id
attribute of the virtual machine as its unique identifier. You can pass this object instance to workflow elements as attribute values.
An Orchestrator plug-in maps the objects from the plugged-in technology to equivalent Orchestrator finder objects in the <finder> elements in the vso.xml
file. The <finder> elements identify the method or function from the plugged-in technology that obtains the unique identifier for a specific instance of an object. The
<finder> elements also define relations between objects, to find objects by the manner in which they relate to other objects.
Finder objects appear in the Orchestrator Inventory tab under the plug-in that contains them.
Role of Scripting Objects
Scripting objects are JavaScript representations of objects from the plugged-in technology. Scripting objects from plug-ins appear in the Orchestrator Javascript API and you can use them in scripted elements in workflows and actions.
Scripting objects from plug-ins appear in the Orchestrator JavaScript API as JavaScript modules, types, and classes. Most finder objects have a scripting object representation. The JavaScript classes can add methods and attributes to the Orchestrator JavaScript API that represent the methods and attributes from objects from the
API of the plugged-in technology. The plugged-in technology provides the implementations of the objects, types, classes, attributes, and methods independently of Orchestrator. For example, the vCenter Server plugin represents all the objects from the vCenter Server API as JavaScript objects in the Orchestrator JavaScript
API, with JavaScript representations of all the classes, methods and attributes that the vCenter Server API defines. You can use the vCenter Server scripting classes and the methods and attributes they define in
Orchestrator scripted functions.
For example, the VirtualMachine managed object type from the vCenter Server API is found by the
VC:VirtualMachine finder and appears in the Orchestrator JavaScript API as the VcVirtualMachine JavaScript class. The VcVirtualMachine JavaScript class in the Orchestrator JavaScript API defines all of the same methods and attributes as the VirtualMachine managed object from the vCenter Server API.
An Orchestrator plug-in maps the objects, types, classes, attributes, and methods from the plugged-in technology to equivalent Orchestrator JavaScript objects, types, classes, attributes, and methods in the
<scripting-objects> element in the vso.xml
file.
146 VMware, Inc.
Chapter 7 Developing Plug-Ins
Role of Event Handlers
Events are changes in the states or attributes of the objects that Orchestrator finds in the plugged-in technology.
Orchestrator monitors events by implementing event handlers.
Orchestrator plug-ins allow you to monitor events in a plugged-in technology in different ways. The
Orchestrator plug-in API allows you to create the following types of event handlers to monitor events in a plugged-in technology.
Listeners
Policies
Workflow triggers
Watchers
Passively monitor objects in the plugged-in technology for changes in their state. The plugged-in technology or the plug-in implementation defines the events that listeners monitor. Listeners do not initiate events, but notify
Orchestrator when the events occur. Listeners detect events either by polling the plugged-in technology or by receiving notifications from the plugged-in technology. When events occur, Orchestrator policies or workflows that are waiting for the event can react by starting operations in the Orchestrator server.
Listener components are optional.
Monitor certain events in the plugged-in technology and start operations in the
Orchestrator server if the events occur. Policies can monitor policy triggers and policy gauges. Policy triggers define an event in the plugged-in technology that, when it occurs, causes a running policy to start an operation in the
Orchestrator server, for example running a workflow. Policy gauges define ranges of values for the attributes of an object in the plugged-in technology that, when exceeded, cause Orchestrator to start an operation. Policies are optional.
If a running workflow contains a Wait Event element, when it reaches that element it suspends its run and waits for an event to occur in a plugged-in technology. Workflow triggers define the events in the plugged-in technology that Waiting Event elements in workflows await. You register workflow triggers with watchers. Workflow triggers are optional.
Watch workflow triggers for a certain event in the plugged-in technology, on behalf of a Waiting Event element in a workflow. When the event occurs, the watchers notify any worklows that are waiting for that event. Watchers are optional.
Contents and Structure of a Plug-In
Plug-ins contain a standard set of components and conform to a standard structure.
n n
Defining the Application Mapping in the vso.xml File on page 148
To create a plug-in, you must define how Orchestrator accesses and interacts with the objects in the plugged-in technology. You map all of the objects and functions of the plugged-in technology to corresponding Orchestrator objects and functions in the vso.xml
file.
Format of the vso.xml Plug-In Definition File on page 148
The vso.xml
file defines how the Orchestrator server interacts with the plugged-in technology. You must include a reference to every type of object or operation to expose to Orchestrator in the vso.xml
file.
VMware, Inc. 147
vCenter Orchestrator Developer's Guide n n
Naming Plug-In Objects on page 149
You must provide a unique identifier for every object that the plug-in finds in the plugged-in technology.
You define the object names in the <finder> elements and in the <object> elements in the vso.xml
file.
File Structure of the Plug-In on page 150
A plug-in must conform to a standard file structure and must include certain specific folders and files.
You deliver a plug-in as a standard Java archive (JAR) or ZIP file, that you must rename with the .dar
extension.
Defining the Application Mapping in the vso.xml File
To create a plug-in, you must define how Orchestrator accesses and interacts with the objects in the pluggedin technology. You map all of the objects and functions of the plugged-in technology to corresponding
Orchestrator objects and functions in the vso.xml
file.
The vso.xml
file provides the following information to the Orchestrator server: n n n n n n
A version, name, and description for the plug-in
References to the classes of the plugged-in technology and to the associated plug-in adapter
Initializes the plug-in when the Orchestrator server starts
Scripting types to represent the types of objects in the plugged-in technology
The relationships between object types to define how the objects display in the Orchestrator Inventory
Scripting classes that map the objects and operations in the plugged-in technology to functions and object types in the Orchestrator JavaSCript API n n
Enumerations to define a list of constant values that apply to all objects of a certain type
Events that Orchestrator monitors in the plugged-in technology
The vso.xml
file must conform to the Orchestrator plug-in XML schema definition. You can access the schema definition at the VMware support site.
http://www.vmware.com/support/orchestrator/plugin-4-0.xsd
For descriptions of all of the elements of the vso.xml file , see
“Elements of the vso.xml Plug-In Definition
Format of the vso.xml Plug-In Definition File
The vso.xml
file defines how the Orchestrator server interacts with the plugged-in technology. You must include a reference to every type of object or operation to expose to Orchestrator in the vso.xml
file.
Objects that you include in the vso.xml
file appear as scripting objects in the Orchestrator scripting API, or as finder objects in the Orchestrator Inventory tab.
As part of the open architecture and standardized implementation of plug-ins, the vso.xml
file must adhere to a standard format.
shows the format of the vso.xml
plug-in definition file and how the elements nest within each other.
148 VMware, Inc.
Chapter 7 Developing Plug-Ins
Figure 7-1. Format of the vso.xml Plug-In Definition File inventory header installation version scripts packages adaptor module datasource finders scripting objects classes objects factories relations properties events constructors methods attributes
XML
DB finders parameters parameters enumerations configuration static dynamic configuration adaptor configuration
WAR
Naming Plug-In Objects
You must provide a unique identifier for every object that the plug-in finds in the plugged-in technology. You define the object names in the <finder> elements and in the <object> elements in the vso.xml
file.
The finder operations that you define in the factory implementation find objects in the plugged-in technology.
When the plug-in finds objects, you can use them in Orchestrator workflows and pass them from one workflow element to another. The unique identifiers that you provide for the objects allows them to pass between the elements in a workflow.
The Orchestrator server stores only the type and identifier of each object that it processes, and stores no information about where or how Orchestrator obtained the object. You must name objects consistently in the plug-in implementation so that you can track the objects you obtain from plug-ins.
If the Orchestrator server stops while workflows are running, when you restart the server the workflows resume at the workflow element that was running when the server stopped. The workflow uses the identifiers to retrieve objects that the element was processing when the server stopped.
VMware, Inc. 149
vCenter Orchestrator Developer's Guide
Plug-In Object Naming Conventions
You must follow Java class naming conventions when you name all objects in plug-ins.
I
MPORTANT
Because of the way in which the workflow engine performs data serialization, do not use the following string sequences in object names. Using these character sequences in object identifiers causes the workflow engine to parse workflows incorrectly, which can cause unexpected behavior when you run the workflows.
n #;# n #,# n #=#
Use these guidelines when you name objects in plug-ins.
n Use an initial uppercase letter for each word in the name.
n n
Do not use spaces to separate words.
For letters, only use the standard characters
A
to
Z
and a
to z
.
n n
Do not use special characters, such as accents.
Do not use a number as the first character of a name.
n Where possible, use fewer than 10 characters.
Table 7-1 shows rules that apply to individual object types.
Table 7-1. Plug-In Object Naming Rules
Object Type
Plug-In
Finder object
Scripting object
Naming Rules n n n n n n n
Defined in the <module> element in the vso.xml file.
Must adhere to Java class naming conventions.
Must be unique. You cannot run two plug-ins with the same name in an Orchestrator server.
n n
Defined in the <finder> elements in the vso.xml file.
Must adhere to Java class naming conventions.
n Must be unique in the plug-in.
Orchestrator adds the plug-in name and a colon to the finder object names in the finder object types in the Orchestrator scripting API. For example, the VirtualMachine object type from the vCenter Server plug-in appears in the Orchestrator scripting API as VC:VirtualMachine.
Defined in the <scripting-object> elements in the vso.xml file.
Must adhere to Java class naming conventions.
Must be unique in the Orchestrator server.
To avoid confusing scripting objects with finder objects of the same name or with scripting objects from other plug-ins, always prefix the scripting object name with the name of the plug-in, but do not add a colon. For example, the VirtualMachine class from the vCenter
Server plug-in appears in the Orchestrator scripting API as the VcVirtualMachine class.
File Structure of the Plug-In
A plug-in must conform to a standard file structure and must include certain specific folders and files. You deliver a plug-in as a standard Java archive (JAR) or ZIP file, that you must rename with the .dar
extension.
150 VMware, Inc.
Chapter 7 Developing Plug-Ins
Table 7-2. Structure of the DAR Archive
Folders plug-in_name\VSO-INF\ plug-in_name\lib\ plug-in_name\resources\ plug-in_name\webapps\
Description
Contains the vso.xml file that defines the mapping of the objects in the plugged-in technology to Orchestrator objects.
The VSO-INF folder and the vso.xml file are mandatory.
Contains the JAR files that contain the binaries of the plugged-in technology. Also contains JAR files that contain the implementations of the adapter, factory, notification handlers, and other interfaces in the plug-in.
The lib folder and JAR files are mandatory.
Contains resource files that the plug-in requires. The resources folder can include the following types of element: n Image files, to represent the objects of the plug-in in the
Orchestrator Inventory tab.
n n
Scripts, to define initialization behavior when the plugin starts.
Orchestrator packages, that can contain custom workflows, actions, Web views, and other resources that interact with the objects that you access by using the plug-in.
You can organize resources in subfolders. For example, resources\images\ , resources\scripts\, or resources\packages\ .
The resources folder is optional.
Contains the WAR file of the Web application that adds a tab for the plug-in to the Orchestrator configuration interface or the files of a Web view for the plug-in.
The webapps folder is optional.
You use the Orchestrator configuration interface to import a DAR file to the Orchestrator server.
Create an Orchestrator Plug-In
To create a plug-in to use Orchestrator to manage an external application, you must create a plug-in adapter and a plug-in factory, create any event handlers, and map the objects from the plugged-in application to
Orchestrator objects in the vso.xml
file.
The procedure to create a plug-in consists of several subprocedures. These procedures demonstrate the plugin creation process by examining the Java classes, resources, and vso.xml
file for a plug-in to an example Java application. The example application that these procedures examine represents the solar system. The example contains Java objects to represent the Sun, the planets, and their moons. The Java objects also define operations that you can perform on the objects. The Orchestrator plug-in for this application allows you to use Orchestrator to manage the solar system application. When you install the example plug-in, you can use Orchestrator to perform the operations on the objects of the solar system application by running workflows and setting policies.
Procedure
1
Accessing the Orchestrator Plug-In API on page 153
The Orchestrator plug-in API provides Java interfaces that you implement to create the plug-in adapter and plug-in factory. The plug-in adapter and factory expose the objects and operations of the pluggedin technology to the Orchestrator server.
2
Obtain an Application to Plug in to Orchestrator on page 153
To create a plug-in, you must have an application to expose for Orchestrator to manage.
VMware, Inc. 151
vCenter Orchestrator Developer's Guide
3
Components of the Solar System Application on page 154
The solar system application replicates a solar system and includes objects to represent stars, planets, and moons. The solar system application also defines operations that you can perform on these objects.
4
Components of the Solar System Plug-In on page 157
The solar system plug-in implements a plug-in adapter, plug-in factory, and event handlers to expose the objects and functions of the solar system application to Orchestrator.
5
Create a Plug-In Factory on page 158
To create a plug-in factory, you create a Java class that implements the IPluginFactory interface from the Orchestrator plug-in API.
6
Create a Plug-In Event Listener on page 166
Plug-in event listeners allow Orchestrator to monitor events that occur in the plugged-in technology. To create a plug-in event listener, you create a Java class that implements the
IPluginNotificationHandler interface from the Orchestrator plug-in API.
7
Create a Plug-In Event Generator on page 170
You can create one or more event generators in a plug-in to perform operations on the objects in the plugged-in technology. The event generator generates events that the Orchestrator plug-in, rather than the plugged-in technology, defines.
8
Create a Plug-In Workflow Trigger on page 175
You can create plug-in workflow triggers to monitor events in the plugged-in technology on behalf of a
Wait Event element in a workflow. To create a workflow trigger, you create a Java class that implements the PluginTrigger class from the Orchestrator plug-in API.
9
Create Plug-In Watchers on page 179
Plug-in watchers watch triggers on behalf of workflows that are waiting for the event that the trigger starts. To create a plug-in watcher, you create a Java class that implements the PluginWatcher class from the Orchestrator plug-in API. You publish the watcher on the Orchestrator notification server by implementing the IPluginPublisher interface.
10
Define Objects and Methods to Map to the Orchestrator JavaScript API on page 185
You can map the object types, classes, and methods of the plugged-in technology and the plug-in itself to JavaScript types, classes, and methods that you add to the Orchestrator JavaScript API.
11
Create a Plug-In Adapter on page 186
To create a plug-in adapter, you create a Java class that implements the
IPluginAdaptor
interface from the Orchestrator plug-in API. The adapter instantiates the plug-in factory and event management implementations.
12
Add a Tab to the Configuration Interface on page 191
You can add a tab to the Orchestrator configuration interface to allow users to provide information to the plug-in configuration that is specific to their environment or preferences.
13
Map the Application in the vso.xml File on page 201
The vso.xml
file defines how Orchestrator accesses and interacts with the plugged-in technology. The vso.xml
file maps objects and operations in the plugged-in technology and in the plug-in implementation to Orchestrator objects and operations.
14
Create the Plug-In DAR Archive on page 209
The final stage in the creation of a plug-in is to create the DAR archive that you import to Orchestrator.
152 VMware, Inc.
Chapter 7 Developing Plug-Ins
15
Install a Plug-In in the Orchestrator Server on page 211
After you create the plug-in DAR file, you must install it in the Orchestrator server. You install plug-ins in the Orchestrator configuration interface.
16
Interact with the Solar System Application by Using Orchestrator on page 212
After you install a plug-in in the Orchestrator server, you can use the objects that it adds to the
Orchestrator JavaScript API to create workflows, actions, policies, Web views, and so on. You use these items to interact with the plugged-in technology using Orchestrator.
Accessing the Orchestrator Plug-In API
The Orchestrator plug-in API provides Java interfaces that you implement to create the plug-in adapter and plug-in factory. The plug-in adapter and factory expose the objects and operations of the plugged-in technology to the Orchestrator server.
The plug-in API includes interfaces, classes, and annotations that you can use when you create the plug-in adapter, factory, and event management implementations. For the full list of the classes in the Orchestrator plug-in API, see
“Orchestrator Plug-In API Reference,” on page 216.
Locating the Plug-In API Java Archives
Orchestrator provides the classes of the plug-in API in the Orchestrator plug-in API Java archive (JAR) file, vmware-vmo-sdkapi.jar
. To develop the plug-in adapter and factory implementations, you must include the vmware-vmo-sdkapi.jar
file in your classpath. You might also need the utility classes that the vmware-vmoutil.jar
archive provides.
Table 7-3. Locations of JAR File and Utility Class Archive
Option
If you installed the standalone version of Orchestrator.
Location
If the vCenter Server installer installed Orchestrator.
install-directory\VMware\Orchestrator\appserver\server\vmo\lib installdirectory\VMware\Infrastructure\Orchestrator\ap p-server\server\vmo\lib
If you develop a plug-in that requires a tab in the Orchestrator configuration interface, you must include the vmware-vmo-webconfiguration-commons.jar
file in your classpath.
Table 7-4. Location of the Orchestrator Configuration Tab JAR File
Option
If you installed the standalone version of Orchestrator.
Location
If the vCenter Server installer installed Orchestrator.
installdirectory\VMware\Orchestrator\configuration\jet ty\lib\ext installdirectory\VMware\Infrastructure\Orchestrator\co nfiguration\jetty\lib\ext
Obtain an Application to Plug in to Orchestrator
To create a plug-in, you must have an application to expose for Orchestrator to manage.
The solar system example application demonstrates how to create a plug-in. The ZIP file of Orchestrator examples that you can download from the Orchestrator documentation homepage contains a DAR file for the solar system plug-in, the source files for the solar system application, and the source files for its plug-in
implementation. For details about where to download the Orchestrator examples bundle, see “Example
VMware, Inc. 153
vCenter Orchestrator Developer's Guide
You can install the solar system DAR file to experiment with the solar system plug-in in the Orchestrator client.
Alternatively, you can examine the source files of the solar system application and solar system plug-in. You can modify the source files to adapt and extend the solar system application and solar system plug-in, and rebuild the DAR file to incorporate your modifications in the plug-in.
Procedure
1 Download the ZIP file of Orchestrator examples from the Orchestrator documentation home page.
2 Unzip the bundle to an appropriate location.
3 Navigate to the following location to view the files of the solar system application and the solar system plug-in.
install-directory\vco-samples_4_0_1_build_number\Plug-Ins
The \Plug-Ins folder contains the following file and folders: vmware-vmosdksolarsystem.dar
SolarSystem
VSOSDK-
SolarSystem\context
VSOSDK-SolarSystem\src
VSOSDK-
SolarSystem\webapp
DAR archive that contains a ready-made version of the solar system plugin.
Contains the source files for the solar system application for you to inspect.
Contains the vso.xml
file for the solar system plug-in, image files, a solar system Web view, a package of workflows, and the Web application that processes configuration information.
Contains the implementations of the Orchestrator plug-in API interfaces for the solar system application.
Contains the files that add a tab for the solar system plug-in to the
Orchestrator configuration interface.
4 (Optional) To recreate the solar system plug-in from the beginning, you must add the VSOSDK-
SolarSystem\webapp\WEB-INF\lib\vmware-solarsystem.jar
Java archive to your classpath.
Components of the Solar System Application
The solar system application replicates a solar system and includes objects to represent stars, planets, and moons. The solar system application also defines operations that you can perform on these objects.
You find the source files of the solar system application in the
Plug-
Ins\SolarSystem\src\com\vmware\solarsystem folder in the Orchestrator examples bundle.
For simplicity, the solar system application runs in the JVM of the Orchestrator server when you install the solar system plug-in. You can create plug-ins for technologies that run independently of Orchestrator by defining how Orchestrator connects to the application in a function in the plug-in. For example, you can add connection information in a tab for the plug-in in the Orchestrator configuration interface.
N
OTE
The source files of the solar system example application and solar system plug-in are provided for reference purposes, so that you can see the details of the application that the solar system plug-in exposes and of the plug-in implementation. If you import the ready-made vmware-vmosdk-solarsystem.dar
file to
Orchestrator, you do not need to build solar system application code or build the plug-in from the sources.
However, if you adapt the code of the solar system application or the solar system plug-in, you can rebuild
154 VMware, Inc.
Chapter 7 Developing Plug-Ins
CelestialBody.java Class
The CelestialBody.java
class is a serializable class that defines a generic celestial body, that can be a star, a planet, or a moon.
The CelestialBody class declares the following constructor and methods: n CelestialBody() constructor, to create a generic celestial body instance n getId() method, to return an object identifier n setId() method, to set an object identifier n getName()
method, to return an object name n setName() method, to set an object name
Star.java Class
The Star.java
class extends CelestialBody to create star objects.
The Star class adds the following constructor and methods: n Star() constructor, to create star instances n getCircumference() method, to return the circumference of a star n setCircumference() method, to set the circumference of a star n getSurfaceTemp() method, to return the surface temperature of a star n setSurfaceTemp()
method, to set the surface temperature of a star n getPlanets() method, to return a list of planets that orbit a star n setPlanets() method, to set the list of planets that orbit a star n addPlanet()
method, to add a planet to the list of planets that orbit a star n removePlanet() method, to remove a planet from the list of planets that orbit a star
Planet.java Class
The Planet.java
class extends CelestialBody to create planet objects.
The Planet class declares the following constructor and methods: n Planet() constructor, to create planet instances n getCircumference()
method, to return the circumference of a planet n setCircumference() method, to set the circumference of a planet n getGravity() method, to return the gravity of a planet n setGravity()
method, to set the gravity of a planet n getMoons() method, to return a list of moons that orbit a planet n setMoons() method, to set the list of moons that orbit a planet n addMoon()
method, to add a moon to the list of moons that orbit a planet n removeMoon() method, to remove a moon from the list of moons that orbit a planet n getStarId() method, to return the identifier of the star that the planet orbits n setStarId() method, to set the identifier of the star that the planet orbits
VMware, Inc. 155
vCenter Orchestrator Developer's Guide
Moon.java Class
The Moon.java
class extends CelestialBody to create moon objects.
The Moon class declares the following constructor and methods: n Moon() constructor, to create moon instances n getVolume() method, to return the volume of a moon n setVolume() method, to set the volume of a moon n getPlanetId()
method, to return the identifier of the planet that this moon orbits n setPlanetId() method, to set the identifier of the planet that this moon orbits
ISolarSystemListener.java Class
The ISolarSystemListener.java class extends java.util.EventListener
to create a listener that monitors events in the solar system application.
The ISolarSystemListener class declares the following methods: n circumferenceChanged() , to monitor changes in the circumference of a planet n gravityChanged() , to monitor changes in the gravity of a planet n planetAdded() , to monitor the creation of new planets n planetRemoved() , to monitor the destruction of planets
SolarSystemEventHandler.java Class
The SolarSystemEventHandler.java
class creates an array of ISolarSystemListener instances and defines methods to handle the events that the ISolarSystemListener instances observe.
The SolarSystemEventHandler defines the following methods: n registerListener() , to add a listener to the array of ISolarSystemListener instances n unregisterListener() , to remove a listener from the array of ISolarSystemListener instances n fireCircumferenceChanged() , to register a change in the circumference of a planet n fireGravityChanged() , to register a change in the gravity of a planet n firePlanetAdded() , to register the creation of a planet n firePlanetRemoved()
, to register the destruction of a planet
SolarSystemRepository.java Class
The SolarSystemRepository.java
class implements all of the classes of the solar system application to create an instance of a solar system.
When the solar system application runs, it creates a unique SolarSystemRepository instance that represents
Earth's solar system. The SolarSystemRepository starts a SolarSystemEventHandler instance to monitor events in the solar system, and creates instances of the Star , Planet , and Moon classes that represent the Sun, Earth,
Mars, Titan, and so on. The SolarSystemRepository constructor calls the Star.addPlanet() and
Planet.addMoon() methods to add the planets to the Sun and the moons to the planets, and sets their respective names, identifiers, and attributes.
156 VMware, Inc.
Chapter 7 Developing Plug-Ins
The
SolarSystemRepository
class defines the following constructor and methods: n SolarSystemRepository() constructor, to create a unique SolarSystemRepository instance and a
SolarSystemEventHandler instance n getUniqueInstance()
, to return a unique
SolarSystemRepository
instance n getStar() , to return the star of this solar system instance n setStar() , to set the star of this solar system instance n getAllPlanets() , to return a list of the planets that orbit the star n getPlanetById() , to return a planet by its unique identifier n getAllMoons() , to return a list of the moons that orbit a planet n getMoonById() , to return a moon by its unique identifier
Components of the Solar System Plug-In
The solar system plug-in implements a plug-in adapter, plug-in factory, and event handlers to expose the objects and functions of the solar system application to Orchestrator.
You find the source files of the solar system plug-in in the \Plug-Ins\solarsystem\VSOSDK-
SolarSystem\src\com\vmware\orchestrator\api\sample\solarsystem directory after you unzip the examples bundle.
N
OTE
The source files of the solar system example application and solar system plug-in are provided for reference purposes, so that you can see the details of the application that the solar system plug-in exposes and of the plug-in implementation. If you import the ready-made vmware-vmosdk-solarsystem.dar
file to
Orchestrator, you do not need to build solar system application code or build the plug-in from the sources.
However, if you adapt the code of the solar system application or the solar system plug-in, you can rebuild
Table 7-5 lists the Java files of the solar system application.
Table 7-5. Source Files for the Solar System Plug-In Implementation
Class Name Description
SolarSystemAdapter.java
SolarSystemFactory.java
SolarSystemEventGenerator.java
SolarSystemEventListener.java
SolarSystemTriggerGenerator.java
Implements the IPluginAdaptor interface that defines for
Orchestrator the entry point of the solar system application.
Instantiates the solar system factory and creates instances of event generators, publishers, and watchers.
Implements the IPluginFactory interface that defines how
Orchestrator uses the plug-in to find solar system objects, and how to perform operations on those objects.
Defines methods to publish events to Orchestrator and a method to generate solar flares on Star objects in the solar system application. Creates a StarFlareEventListener object that listens for solar flare events on Star objects in the solar system application.
Implements the IPluginNotificationHandler interface, registers listeners with the notification handler to listen for events in the solar system application, and sends notifications of the events to Orchestrator.
Creates triggers that allow you to start solar flare events in the solar system application from Orchestrator.
VMware, Inc. 157
vCenter Orchestrator Developer's Guide
Table 7-5. Source Files for the Solar System Plug-In Implementation (Continued)
Class Name
SolarSystemWatchersManager.java
\config\SolarSystemConfigurationAdaptor.java
\config\SolarSystemConfigureAction.java
Description
Implements StarFlareEventListener to monitor solar flare events in the solar system application and performs functions in Orchestrator if the solar flare exceeds a certain magnitude.
Implements the IConfigurationAdaptor interface and
SDKHelper class to load and save configuration information in the Orchestrator configuration server.
Defines methods to obtain configuration information from the user in the Orchestrator configuration interface. The solar system configuration tab in the Orchestrator configuration interface allows the user to configure their home planet and to specify whether Pluto is a planet or a dwarf planet.
This information examines the Java code of each of the files in the solar system plug-in.
Create a Plug-In Factory
To create a plug-in factory, you create a Java class that implements the IPluginFactory interface from the
Orchestrator plug-in API.
These procedures present the steps involved in creating a plug-in factory. To illustrate the process, they present code from the SolarSystemFactory class from the solar system plug-in.
You can download the Orchestrator examples ZIP file from the Orchestrator documentation home page to obtain the sources of the solar system example application and plug-in.
“IPluginFactory Interface,” on page 219.
Procedure
1
Set Up the Plug-In Factory Implementation on page 159
To create a plug-in factory, you create an implementation of the
IPluginFactory
interface from the
Orchestrator plug-in API.
2
Set Up Event Listeners and Notification Handlers on page 159
You activate event listeners and notification handlers for a plug-in in the factory implementation.
3
Find Objects By Identifier in the Plugged-In Technology on page 160
You can find objects by their identifier in the plugged-in technology by using the
IPluginFactory.find() method.
4
Find Objects in the Plugged-In Technology By a Query on page 161
You can find objects in the plugged-in technology by defining a query in the
IPluginFactory.findAll()
method.
5
Find Objects By Relation Type in the Plugged-In Technology on page 163
You can find objects by their relationship to other objects in the plugged-in technology by using the
IPluginFactory.findRelation() method. You can also determine whether an object has any dependent child objects by using the IPluginFactory.hasChildrenInRelation() method.
6
Discover Whether an Object has Children of a Given Relation Type on page 165
You implement the
IPluginFactory.hasChildrenInRelation()
method to discover whether an object relates to any children by a given type of relation.
158 VMware, Inc.
Chapter 7 Developing Plug-Ins
Set Up the Plug-In Factory Implementation
To create a plug-in factory, you create an implementation of the IPluginFactory interface from the Orchestrator plug-in API.
Prerequisites n n
You have an application to plug in to Orchestrator.
You have access to the Orchestrator plug-in API JAR file.
Procedure
1 Create and save a Java file for the plug-in factory implementation named
YourApplicationNameFactory.java
.
In the solar system example, the factory class is named SolarSystemFactory.java
.
2 Declare the package that contains the Java classes of the plug-in implementation.
The solar system example declares the following package: package com.vmware.orchestrator.api.sample.solarsystem;
3 Import the Orchestrator plug-in API classes with a Java import statement.
import ch.dunes.vso.sdk.api.*;
4 Import the classes of the application to plug in with a Java import statement.
import com.vmware.solarsystem.*;
5 Import any other classes that the factory implementation requires.
In the solar system example, the factory implementation requires the following classes: import java.util.*; import org.apache.log4j.Logger;
6 Declare a public class that implements the
IPluginFactory
interface from the Orchestrator plug-in API.
The solar system example factory declares the SolarSystemFactory class.
public class SolarSystemFactory implements IPluginFactory {
}
You set up the IPluginFactory implementation.
What to do next
Set up event listeners and notifications in the plug-in factory.
Set Up Event Listeners and Notification Handlers
You activate event listeners and notification handlers for a plug-in in the factory implementation.
The plug-in adapter creates one plug-in factory for each connection between Orchestrator and the plugged-in technology. Consequently, you set up event listeners and notification handlers in the plug-in factory to listen for events through the connection and to send notifications about the events that the listeners discover.
Prerequisites n n
Set up the factory implementation class.
Declare a public class that implements the IPluginFactory interface.
VMware, Inc. 159
vCenter Orchestrator Developer's Guide
Procedure
1 Set up logging so that Orchestrator can record in the logs the events that occur in the plugged-in technology.
The solar system example uses an instance of org.apache.log4j.Logger
to log events.
public class SolarSystemFactory implements IPluginFactory {
private Logger log = Logger.getLogger(this.getClass());
}
2 Set up a notification handler by implementing the IPluginNotificationHandler interface from the
Orchestrator API.
The SolarSystemFactory constructor gets an instance of IPluginNotificationHandler named notificationHandler
.
public class SolarSystemFactory implements IPluginFactory {
private Logger log = Logger.getLogger(this.getClass());
public SolarSystemFactory(IPluginNotificationHandler notificationHandler) {
}
}
3 Create an instance of an event listener that implements the java.util.EventListener
class.
The solar system plug-in factory creates an instance of the SolarSystemEventListener class. The
SolarSystemEventListener instance monitors an instance of the SolarSystemRepository class from the solar system application.
public class SolarSystemFactory implements IPluginFactory {
private Logger log = Logger.getLogger(this.getClass());
public SolarSystemFactory(IPluginNotificationHandler notificationHandler) {
super();
new SolarSystemEventListener(
SolarSystemRepository.getUniqueInstance(), notificationHandler);
}
}
N
OTE
The SolarSystemEventListener class is an implementation of the ISolarSystemListener listener that the solar system application defines. ISolarSystemListener implements java.util.EventListener
.
For information about the implementation of
SolarSystemEventListener
, see
You set up the event listeners and notification handlers in the plug-in factory, to listen for events in the pluggedin technology and to send notifications about the events.
What to do next
Define methods in the plug-in factory to find objects in the plugged-in technology by name, type, and by their relation to other objects.
Find Objects By Identifier in the Plugged-In Technology
You can find objects by their identifier in the plugged-in technology by using the IPluginFactory.find() method.
All instances of objects in the plugged-in technology must have a unique name or identifier for Orchestrator to find them. The IPluginFactory.find() method uses the type and identifier to find an object in the pluggedin technology and returns objects of the type java.lang.Object
.
160 VMware, Inc.
Chapter 7 Developing Plug-Ins
Prerequisites n n
Set up the factory implementation class.
Create a public constructor that implements the
IPluginFactory
interface.
Procedure
1 Declare the IPluginFactory.find() method to find objects of the type java.lang.Object
.
public Object find(String type, String id) {
}
2 Write in the logs the type and identifier of the objects that the plug-in factory finds.
public Object find(String type, String id) {
log.debug("find: " + type + ", " + id);
}
3 Call the appropriate methods from the plugged-in technology to obtain the identifiers of objects of each different type.
The SolarSystemFactory class uses an if-else statement to call the SolarSystemRepository.getStar() , getPlanetById() , and getMoonById() methods.
public Object find(String type, String id) {
log.debug("find: " + type + ", " + id);
if (type.equals("Star")) {
return SolarSystemRepository.getUniqueInstance().getStar();
}
else if (type.equals("Planet")) {
return SolarSystemRepository.getUniqueInstance().getPlanetById(id);
}
else if (type.equals("Moon")) {
return SolarSystemRepository.getUniqueInstance().getMoonById(id);
}
else if (type.equals("Galaxy")) {
return null; // No object for galaxy defined yet
}
else {
throw new IndexOutOfBoundsException("Type " + type + "
+ unknown for plugin SolarSystem");
}
}
You implemented the IPluginFactory.find() method to find objects by identifier in the plugged-in technology.
What to do next
Define methods in the plug-in factory to find all objects of a certain type.
Find Objects in the Plugged-In Technology By a Query
You can find objects in the plugged-in technology by defining a query in the
IPluginFactory.findAll() method.
The findAll() method takes the object type and a query as parameters. You can define the syntax of the query in the IPluginFactory implementation to narrow the search. If you do not define query syntax, findAll() returns all objects of the specified type. You can ignore the query and find objects by type, ignore the type and find objects by query, or find objects by both query and type.
VMware, Inc. 161
vCenter Orchestrator Developer's Guide
The findAll()
method returns a
QueryResult
object that contains a list of the objects of the corresponding type that the plugged-in technology contains. For information about QueryResult objects, see
Prerequisites n n
Set up the factory implementation class.
Create a public constructor that implements the IPluginFactory interface.
Procedure
1 Declare the
IPluginFactory.findAll()
method to obtain a
QueryResult
object.
public QueryResult findAll(String type, String query) {
}
2 Write in the logs the type of the objects that the plug-in factory finds and any additional query that narrows the search.
public QueryResult findAll(String type, String query) {
log.debug("findAll: " + type + ", " + query);
}
3 Call the appropriate methods from the plugged-in technology to obtain objects of each different type.
The SolarSystemFactory class uses an if-else statement to call the SolarSystemRepository.getStar() , getAllPlanets() , and getAllMoons() methods.
public QueryResult findAll(String type, String query) {
log.debug("findAll: " + type + ", " + query);
List list; // The list can contain any element from the plug-in
if (type.equals("Star")) {
list = new Vector();
list.add(SolarSystemRepository.getUniqueInstance().getStar());
}
else if (type.equals("Planet")) {
list = SolarSystemRepository.getUniqueInstance().getAllPlanets();
}
else if (type.equals("Moon")) {
list = SolarSystemRepository.getUniqueInstance().getAllMoons();
}
else if (type.equals("Galaxy")) {
list = new Vector();
}
else {
throw new IndexOutOfBoundsException("Type " + type +
" unknown for SolarSystem plug-in ");
}
return new QueryResult(list);
}
The SolarSystemFactory implementation of the findAll() method does not define a custom query to narrow the search, so it returns a list of all the objects of each given type in the QueryResult object.
You defined methods to find objects by their type in the plugged-in technology.
What to do next
Define methods in the plug-in factory to find all objects that relate to other objects by a certain relation type.
162 VMware, Inc.
Chapter 7 Developing Plug-Ins
Find Objects By Relation Type in the Plugged-In Technology
You can find objects by their relationship to other objects in the plugged-in technology by using the
IPluginFactory.findRelation() method. You can also determine whether an object has any dependent child objects by using the IPluginFactory.hasChildrenInRelation() method.
The IPluginFactory.findRelation() returns all of the dependent child objects that relate to a parent object by a certain relation type.
The IPluginFactory.hasChildrenInRelation() method returns HasChildrenResult objects to confirm whether a parent object has any dependent child objects that relate to it by a given relation type. The possible values of a HasChildrenResult object are yes , no , or unknown . For information about HasChildrenResult objects, see
“HasChildrenResult Enumeration,” on page 228.
You define the relations between the objects in the plugged-in technology in the vso.xml
file for the plug-in.
Prerequisites n n
Set up the factory implementation class.
Create a public constructor that implements the IPluginFactory interface.
VMware, Inc. 163
vCenter Orchestrator Developer's Guide
Procedure
1 Declare the
IPluginFactory.findRelation()
method to return a java.util.List
instance that lists all the child objects that relate to a parent object by a given relation.
public List findRelation(String parentType, String parentId, String relationName) {
}
2 Write in the logs the type and identifier of the parent object and the name of the relationship that the child objects have to the parent.
public List findRelation(String parentType, String parentId, String relationName) {
log.debug("findRelation: " + parentType + ", " + parentId + ", " + relationName);
}
164 VMware, Inc.
Chapter 7 Developing Plug-Ins
3 Call the appropriate methods from the plugged-in technology to obtain lists of child objects that relate to their parent objects by different types of relations.
The
SolarSystemFactory
class uses an if-else
statement to call the
SolarSystemRepository.getAllPlanets() method to return a list of all of the planets that relate to a particular star by the OrbitingPlanets relation. The if-else statement also calls Planet.getMoons() to return a list of all of the moons that relate to a particular planet by the
OrbitingMoons
relation.
public List findRelation(String parentType, String parentId, String relationName) {
log.debug("findRelation: " + parentType + ", " + parentId + ", " + relationName);
if (parentId == null) {
List<Star> list = new Vector<Star>();
list.add(SolarSystemRepository.getUniqueInstance().getStar());
return list;
}
if (parentType.equals("Star")) {
if (relationName.equals("OrbitingPlanets")) {
return SolarSystemRepository.getUniqueInstance().getAllPlanets();
}
else {
throw new IndexOutOfBoundsException("Unknown relation name: "
+ relationName);
}
}
if (parentType.equals("Planet")) {
if (relationName.equals("OrbitingMoons")) {
Planet parentPlanet =
SolarSystemRepository.getUniqueInstance().getPlanetById(parentId);
if (parentPlanet != null) {
return parentPlanet.getMoons();
}
return null;
}
else {
throw new IndexOutOfBoundsException("Unknown relation name: "
+ relationName);
}
}
else {
return null;
}
}
You defined methods in the IPluginFactory implementation to find objects in the plugged-in technology that relate to other objects by a certain relation type.
What to do next
Discover whether an object relates to any child objects by a given type of relation.
Discover Whether an Object has Children of a Given Relation Type
You implement the IPluginFactory.hasChildrenInRelation() method to discover whether an object relates to any children by a given type of relation.
You can implement an if-else statement in the hasChildrenInRelation() method to check for child objects that relate to a parent by a certain relation type. For example, you can implement a function that uses the hasChildrenInRelation() method in the solar system example to check whether a Planet object has any moons.
VMware, Inc. 165
vCenter Orchestrator Developer's Guide
The possible return values of the hasChildrenInRelation()
method are
Yes
,
No
, and
Unknown
. If you do not implement the hasChildrenInRelation() method, it returns Unknown .
Prerequisites n n
Set up the factory implementation class.
Create a public constructor that implements the IPluginFactory interface.
Procedure u Declare the
IPluginFactory.hasChildrenInRelation()
method to discover whether an object has any children of a certain relation type.
The SolarSystemFactory example does not fully implement the hasChildrenInRelation() method and returns unknown in all cases.
public HasChildrenResult hasChildrenInRelation(String parentType,
String parentId, String relationName) {
return HasChildrenResult.Unknown;
}
You called the IPluginFactory.hasChildrenInRelation() method to discover whether an object has any children of a certain relation type.
What to do next
Create an event listener object to allow Orchestrator to monitor events in the plugged-in technology.
Create a Plug-In Event Listener
Plug-in event listeners allow Orchestrator to monitor events that occur in the plugged-in technology. To create a plug-in event listener, you create a Java class that implements the IPluginNotificationHandler interface from the Orchestrator plug-in API.
These procedures present the steps involved in creating a plug-in event listener. To illustrate the process, they present code from the
SolarSystemEventListener
class from the solar system example application.
You can download the Orchestrator examples ZIP file from the Orchestrator documentation home page to obtain the sources of the solar system example application and plug-in.
IPluginNotificationHandler interface, see
“IPluginNotificationHandler Interface,” on page 220.
Procedure
1
Set Up the Event Listener Implementation on page 167
To create a plug-in event listener, you implement the java.util.Eventlistener
interface and create an instance of the
IPluginNotification
interface from the Orchestrator plug-in API.
2
Register the Event Listener with the Plugged-In Technology on page 168
To monitor events in a plugged-in technology, you must register the event listener from the plug-in with the plugged-in technology and implement a notification handler.
3
Notify Orchestrator of Events in the Plugged-In Technology on page 169
Event listeners implement the IPluginNotificationHandler interface from the Orchestrator plug-in API to notify Orchestrator of events in the plugged-in technology.
166 VMware, Inc.
Chapter 7 Developing Plug-Ins
Set Up the Event Listener Implementation
To create a plug-in event listener, you implement the java.util.Eventlistener
interface and create an instance of the IPluginNotification interface from the Orchestrator plug-in API.
Prerequisites n n
Download the bundle of Orchestrator examples.
Unzip the examples bundle to an appropriate location.
Procedure
1 Create and save a Java file for the plug-in event listener implementation named
<YourApplicationName>EventListener.java
.
In the solar system example, the event listener class is named SolarSystemEventListener.java
.
2 Declare the package that contains the Java classes of the plug-in implementation.
The solar system example declares the following package: package com.vmware.orchestrator.api.sample.solarsystem;
3 Import the Orchestrator plug-in API classes with a Java import statement.
In the solar system example, the event listener requires the following class: import ch.dunes.vso.sdk.api.IPluginNotificationHandler;
4 Import any other classes that the event listener implementation requires.
In the solar system example, the event listener requires the following classes from the solar system application: import com.vmware.solarsystem.ISolarSystemListener; import com.vmware.solarsystem.Planet; import com.vmware.solarsystem.SolarSystemRepository;
5 Declare a public class for the event listener that implements the java.util.Eventlistener
interface.
In the solar system example, the event listener declares the following class: public class SolarSystemEventListener implements ISolarSystemListener {
}
The
ISolarSystemListener
class from the solar system application is a subclass of java.util.Eventlistener
.
6 Create an instance of the IPluginNotificationHandler interface.
The solar system event listener creates an
IPluginNotificationHandler
instance named notficationHandler .
public class SolarSystemEventListener implements ISolarSystemListener {
IPluginNotificationHandler notficationHandler;
}
You set up the plug-in event listener class.
What to do next
Register the plug-in event listener with the plugged-in technology.
VMware, Inc. 167
vCenter Orchestrator Developer's Guide
Register the Event Listener with the Plugged-In Technology
To monitor events in a plugged-in technology, you must register the event listener from the plug-in with the plugged-in technology and implement a notification handler.
An event listener requires access to the main class of the application to which it listens for events. An event listener also requires an instance of the IPluginNotificationHandler interface from the Orchestrator plug-in
API, to send notifications to Orchestrator if the events occur.
Prerequisites n n n
Set up the event listener implementation class.
Declare a public class that implements the java.util.EventListener
interface.
Create an instance of the IPluginNotificationHandler interface.
Procedure
1 Create a public constructor to create event listener instances.
The solar system example creates a constructor that takes as parameters an instance of the
SolarSystemRepository class from the solar system application and an instance of the
IPluginNotificationHandler interface.
public SolarSystemEventListener(SolarSystemRepository solarSystemRepository,
IPluginNotificationHandler notificationHandler) {
}
2 Register an instance of the event listener with the plugged-in technology.
You register the event listener by using the listener registration mechanism that the plugged-in technology defines.
The
SolarSystemEventListener()
constructor registers the event listener with the solar system application by calling the SolarSystemRepository.registerListener() method.
public SolarSystemEventListener(SolarSystemRepository solarSystemRepository,
IPluginNotificationHandler notificationHandler) {
solarSystemRepository.registerListener(this);
}
3 Associate an instance of the IPluginNotificiationHandler interface to the event listener.
The
SolarSystemEventListener()
constructor uses the this
Java keyword to add an instance of
IPluginNotificiationHandler to the event listener.
public SolarSystemEventListener(SolarSystemRepository solarSystemRepository,
IPluginNotificationHandler notificationHandler) {
solarSystemRepository.registerListener(this);
this.notificationHandler = notificationHandler;
}
You created an event listener that registers an event listener and a notification handler with the plugged-in technology. The event listener listens for events in the plugged-in technology and sends notifications to
Orchestrator.
What to do next
Call the methods of the IPluginNotificationHandler interface to notify Orchestrator of events in the pluggedin technology.
168 VMware, Inc.
Chapter 7 Developing Plug-Ins
Notify Orchestrator of Events in the Plugged-In Technology
Event listeners implement the IPluginNotificationHandler interface from the Orchestrator plug-in API to notify Orchestrator of events in the plugged-in technology.
The IPluginNotificationHandler interface defines methods that you implement in the event listener to notify
Orchestrator of changes in state of the objects that the event listener monitors in the plugged-in technology.
The SolarSystemEventListener class monitors objects in a SolarSystemRepository instance for changes in state that the following methods cause: n Planet.setCircumference() , that changes the circumference of a planet.
n Planet.setGravity() , that changes the gravity of a planet.
n Star.addPlanet()
, that adds a planet to a star.
n Star.removePlanet() , that removes a planet from a star.
The events that the SolarSystemEventListener class monitors are all events that the solar system application defines.
Prerequisites n n n n
Set up the event listener implementation class.
Declare a public class that implements the java.util.EventListener
interface.
Create an instance of the IPluginNotificationHandler interface.
Register the event listener and the notification handler instances with the plugged-in technology.
VMware, Inc. 169
vCenter Orchestrator Developer's Guide
Procedure
1 Create methods that implement the
IPluginNotificationHandler.notifyElementUpdated()
method to notify Orchestrator of changes to an existing object.
The SolarSystemEventListener class creates the following methods to inform Orchestrator of changes to the circumference and gravity of a particular Planet object: public void circumferenceChanged(Planet planet) {
notificationHandler.notifyElementUpdated("Planet", planet.getId());
} public void gravityChanged(Planet planet) {
notificationHandler.notifyElementUpdated("Planet", planet.getId());
}
2 Create methods that implement the
IPluginNotificationHandler.notifyElementInvalidate()
method to notify Orchestrator of changes in relations between objects.
The SolarSystemEventListener class creates the following method to notify Orchestrator that a child
Planet object is added to a parent Star object.
public void planetAdded(Planet planet) {
notificationHandler.notifyElementInvalidate("Star", "sol");
}
3 Create methods that implement the IPluginNotificationHandler.notifyElementDeleted() method to notify Orchestrator of the removal of an object.
The SolarSystemEventListener class creates the following method to notify Orchestrator that a child
Planet object is deleted from its parent Star .
public void planetRemoved(Planet planet) {
notificationHandler.notifyElementDeleted("Planet", planet.getId());
}
You implemented the methods of the IPluginNotificationHandler interface to notify Orchestrator of events that occur on the objects in the plugged-in technology.
What to do next
Create an event generator to push to the plugged-in technology events that the Orchestrator plug-in defines.
Create a Plug-In Event Generator
You can create one or more event generators in a plug-in to perform operations on the objects in the pluggedin technology. The event generator generates events that the Orchestrator plug-in, rather than the plugged-in technology, defines.
You can implement the IPluginEventPublisher interface to publish events in the plugged-in technology to the
Orchestrator policy engine. You create methods to set policy triggers and gauges on objects in the plugged-in technology and event listeners to listen for events on those objects.
The solar system plug-in features an event generator that implements an event publisher and creates a method to generate solar flares on a
Star
object in a
SolarSystemRepository
instance. These procedures present the steps involved in creating a plug-in event generator. To illustrate the process, they present code from the
SolarSystemEventGenerator class. The package of workflows, actions, and resources that accompany the solar system example contains a policy template that monitors a gauge that the SolarSystemEventGenerator class publishes to the policy engine.
You can download the Orchestrator examples ZIP file from the Orchestrator documentation home page to obtain the sources of the solar system example application and plug-in.
170 VMware, Inc.
Chapter 7 Developing Plug-Ins
interface, see
“IPluginEventPublisher Interface,” on page 218.
Procedure
1
Set Up the Event Generator on page 171
You can create
IPluginEventPublisher
instances and methods to generate events directly in the plug-in adaptor implementation. However, the solar system class creates these objects in a separate class.
2
Create Event Publishers on page 172
You can create IPluginEventPublisher instances to publish event gauges and event triggers to the
Orchestrator policy engine. Policies run in the Orchestrator server and monitor objects through plug-ins.
3
Define and Publish Events to Orchestrator on page 174
The IPluginEventPublisher interface allows you to publish to the Orchestrator policy engine events that you define in the plug-in that occur in the plugged-in technology.
Set Up the Event Generator
You can create IPluginEventPublisher instances and methods to generate events directly in the plug-in adaptor implementation. However, the solar system class creates these objects in a separate class.
Prerequisites n n
You have an application to plug in to Orchestrator.
You have access to the Orchestrator plug-in API JAR file.
Procedure
1 Create and save a Java file for the plug-in event generator class named
YourApplicationNameEventGenerator.java
.
In the solar system example, the event generator class is named
SolarSystemEventGenerator.java
.
2 Declare the package that contains the Java classes of the plug-in implementation.
The solar system example declares the following package: package com.vmware.orchestrator.api.sample.solarsystem;
3 Import the Orchestrator plug-in API classes with a Java import statement.
import ch.dunes.vso.sdk.api.*;
4 Import any other classes that the event generator requires.
In the solar system example, the event generator requires the following classes: import java.util.*; import org.apache.log4j.Logger;
5 Declare a public class for the event generator implementation.
The solar system example factory declares the SolarSystemEventGenerator class.
public class SolarSystemEventGenerator {
}
VMware, Inc. 171
vCenter Orchestrator Developer's Guide
6 Set up logging so that Orchestrator can record in the logs the events that the event generator generates.
The solar system example uses an instance of org.apache.log4j.Logger
to log events.
public class SolarSystemEventGenerator {
private static final Logger log = Logger.getLogger(SolarSystemEventGenerator.class);
}
7 Create an instance of the event generator class for other classes in the plug-in implementation to use.
The SolarSystemEventGenerator declares a static instance of itself named _solarSystemEventGenerator that the plug-in adapter class instantiates when it runs.
public class SolarSystemEventGenerator {
private static final Logger log = Logger.getLogger(SolarSystemEventGenerator.class);
public final static SolarSystemEventGenerator _solarSystemEventGenerator =
new SolarSystemEventGenerator();
}
You set up and instantiated a plug-in event generator class.
What to do next
Create instances of the IPluginEventPublisher interface to monitor objects in the plugged-in technology.
Create Event Publishers
You can create
IPluginEventPublisher
instances to publish event gauges and event triggers to the Orchestrator policy engine. Policies run in the Orchestrator server and monitor objects through plug-ins.
Policies can implement either gauges or triggers to monitor objects in the plugged-in technology. Policy gauges monitor the attributes of objects and push an event in the Orchestrator server if the values of the objects exceed certain limits. Policy triggers monitor objects and push an event in the Orchestrator server if a defined event occurs on the object. You register policy gauges and triggers with IPluginEventPublisher instances so that
Orchestrator policies can monitor them.
The SolarSystemEventGenerator class creates IPluginEventPublisher instances. The
SolarSystemEventGenerator class defines methods to add and remove the IPluginEventPublisher instances in the Orchestrator policy engine.
Prerequisites
Set up the event generator class to create event generator instances.
172 VMware, Inc.
Chapter 7 Developing Plug-Ins
Procedure
1 Create one or more instances of the
IPluginEventPublisher
interface with which to register the objects to monitor.
The SolarSystemEventGenerator class creates a hashtable to contain all of the IPluginEventPublisher instances.
private Hashtable<String, Vector<IPluginEventPublisher>> policyElements =
new Hashtable<String, Vector<IPluginEventPublisher>>();
2 Define a method to register the objects to monitor with the IPluginEventPublisher instances.
The
SolarSystemEventGenerator
class defines a method that takes as parameters the type and identifier of the object to monitor and an IPluginEventPublisher instance with which to monitor the object. The addPolicyElement() method adds an IPluginEventPublisher instance for each object to the hashtable of
IPluginEventPublisher instances.
public void addPolicyElement(String sdkType, String id, IPluginEventPublisher publisher) {
String key = sdkType + "' / '" + id;
log.info("Registering element to watch : '" + key + "'");
Vector<IPluginEventPublisher> publishers = policyElements.get(key);
if (publishers == null) {
publishers = new Vector<IPluginEventPublisher>();
policyElements.put(key, publishers);
}
publishers.add(publisher);
}
3 (Optional) Define a method to remove objects from the list of objects to monitor.
The SolarSystemEventGenerator class defines a method that takes as parameters the type and identifier of the object to monitor and an IPluginEventPublisher instance with which the objects are registered. The removePolicyElement() method removes an IPluginEventPublisher instance for the identified object from the hashtable of IPluginEventPublisher instances.
public boolean removePolicyElement(
String sdkType, String id, IPluginEventPublisher publisher) {
String key = sdkType + "' / '" + id;
log.info("Unregistering element to watch : '" + key + "'");
Vector<IPluginEventPublisher> publishers = policyElements.get(key);
publishers.remove(publisher);
if (publishers.size() == 0) {
policyElements.remove(key);
}
return (policyElements.size() > 0);
}
You created IPluginEventPublisher instances that publish to Orchestrator policies the events that occur on objects in the plugged-in technology.
What to do next
Define an event to push from Orchestrator to the plugged-in technology.
VMware, Inc. 173
vCenter Orchestrator Developer's Guide
Define and Publish Events to Orchestrator
The IPluginEventPublisher interface allows you to publish to the Orchestrator policy engine events that you define in the plug-in that occur in the plugged-in technology.
You can use the methods of the IPluginEventPublisher interface to set gauges and triggers that Orchestrator policies monitor.
The SolarSystemEventGenerator class defines a method that generates solar flares of a given magnitude on
Star objects in the solar system application. By implementing a method to create solar flares in the solar system plug-in, the plug-in adds a function that does not exist in the solar system application. The generateFlareEvent() method that the plug-in defines registers a policy gauge with the Orchestrator policy engine. An Orchestrator policy can watch this gauge for solar flares that exceed a certain magnitude.
Prerequisites n n
Set up the event generator class to create event generator instances.
Create instances of the IPluginEventPublisher interface.
Procedure
1 Create functions that define event listeners and the events that the event listeners monitor.
The SolarSystemEventGenerator class declares an interface from which to create listener instances, and adds a method to the interface to create flare events of a certain magnitude on a given Star object.
public interface StarFlareEventListener{
void starFlareEvent(String starid, double magnitude);
}
2 Create listener instances to listen for the events that the plug-in defines.
The
SolarSystemEventGenerator
instantiates the
StarFlareEventListener
interface to create a listener named starFlareEventListener .
private StarFlareEventListener starFlareEventListener;
3 Create functions to generate events in the plugged-in technology.
The SolarSystemEventGenerator defines the generateFlareEvent() method that takes an object type, identifier, and a magnitude value as parameters. The method writes in the logs that the plug-in generated a flare event on a given object.
public void generateFlareEvent(String sdkType, String id, double magnitude) {
String key = sdkType + "' / '" + id;
log.info("Generate Flare Event for : '" + key + "'");
}
4 Register the objects to monitor with
IPluginEventPublisher
instances.
The SolarSystemEventGenerator.generateFlareEvent() method adds IPluginEventPublisher instances for each object to the policyElements hashtable of publishers that the SolarSystemEventGenerator class creates.
public void generateFlareEvent(String sdkType, String id, double magnitude) {
String key = sdkType + "' / '" + id;
log.info("Generate Flare Event for : '" + key + "'");
Vector<IPluginEventPublisher> publishers = policyElements.get(key);
}
174 VMware, Inc.
Chapter 7 Developing Plug-Ins
5 Call the
IPluginEventPublisher.pushGauge()
or
IPluginEventPublisher.pushTrigger()
methods to publish gauges or triggers to the Orchestrator policy engine.
The SolarSystemEventGenerator.generateFlareEvent() method calls the pushGauge() method to publish a gauge with the Orchestrator policy engine. The generateFlareEvent() method passes the object type, identifier, and magnitude value to the pushGauge()
method, sets the gauge name to
Flare
and the type of value that the gauge monitors to magnitude .
public void generateFlareEvent(String sdkType, String id, double magnitude) {
String key = sdkType + "' / '" + id;
log.info("Generate Flare Event for : '" + key + "'");
Vector<IPluginEventPublisher> publishers = policyElements.get(key);
if (publishers != null) {
for (IPluginEventPublisher publisher : publishers) {
publisher.pushGauge(sdkType, id, "Flare", "magnitude", magnitude);
}
}
6 Call the functions that define the events to generate and monitor.
To generate flare events, the SolarSystemEventGenerator.generateFlareEvent() method calls the
StarFlareEventListener.starFlareEvent() method that the SolarSystemEventGenerator class defines.
public void generateFlareEvent(String sdkType, String id, double magnitude) {
String key = sdkType + "' / '" + id;
log.info("Generate Flare Event for : '" + key + "'");
Vector<IPluginEventPublisher> publishers = policyElements.get(key);
if (publishers != null) {
for (IPluginEventPublisher publisher : publishers) {
publisher.pushGauge(sdkType, id, "Flare", "magnitude", magnitude);
}
if (sdkType.equals("Star")) {
starFlareEventListener.starFlareEvent(id, magnitude);
}
}
You registered a policy gauge or a trigger that an Orchestrator policy can watch for events in the plugged-in technology. If the events occur, the policy starts an operation in the Orchestrator server.
What to do next
Create plug-in triggers to start operations in the Orchestrator server when certain events occur in the pluggedin technology.
Create a Plug-In Workflow Trigger
You can create plug-in workflow triggers to monitor events in the plugged-in technology on behalf of a Wait
Event element in a workflow. To create a workflow trigger, you create a Java class that implements the
PluginTrigger class from the Orchestrator plug-in API.
When a workflow trigger detects a change in the properties of an object that it is monitoring, it sends a notification to any Orchestrator workflows that are waiting for the event. When the workflow receives the notification from the workflow trigger, it stops waiting and resumes its run.
The
PluginTrigger
class defines methods to obtain or set the type and name of the object to monitor, the nature of the event, and a timeout period.
You create implementations of the PluginTrigger class exclusively for use by Wait Event elements in workflows. You define policy triggers for Orchestrator policies in classes that define events and implement the IPluginEventPublisher.pushTrigger() method.
VMware, Inc. 175
vCenter Orchestrator Developer's Guide
The solar system plug-in features a workflow trigger that creates an instance of the
PluginTrigger
class to monitor solar flare events on a Star object in a SolarSystemRepository instance. These procedures present the steps involved in creating a workflow trigger. To illustrate the process, they present code from the
SolarSystemTriggerGenerator class. The package of workflows, actions, and resources that accompany the solar system example provides a workflow that contains a Wait Event element that monitors the workflow trigger for solar flare events.
For a description of the role of the plug-in triggers and the other components of a plug-in, see
“PluginTrigger Class,” on page 222.
Procedure
1
Set Up the Workflow Trigger on page 176
To create a workflow trigger, you create an implementation of the
PluginTrigger
class from the
Orchestrator plug-in API.
2
Create Instances of the PluginTrigger Class on page 177
You create a workflow trigger by instantiating the PluginTrigger class.
3
Set the Properties that a Workflow Trigger Monitors on page 178
Workflow triggers monitor changes in the properties of an object in the plugged-in technology. When workflow triggers detect a change in the properties of an object, they notify any workflows in the
Orchestrator server that are waiting for this event.
Set Up the Workflow Trigger
To create a workflow trigger, you create an implementation of the
PluginTrigger
class from the Orchestrator plug-in API.
Prerequisites n n
You have an application to plug in to Orchestrator.
You have access to the Orchestrator plug-in API JAR file.
Procedure
1 Create and save a Java file for the workflow trigger implementation.
In the solar system example, the workflow trigger class is named SolarSystemTriggerGenerator .
2 Declare the package that contains the Java classes of the plug-in implementation.
The solar system example declares the following package: package com.vmware.orchestrator.api.sample.solarsystem;
3 Import the Orchestrator plug-in API classes with a Java import statement.
The
SolarSystemTriggerGenerator
class requires the following classes: import ch.dunes.vso.sdk.api.IPluginFactory; import ch.dunes.vso.sdk.api.PluginTrigger;
4 Import the classes of the application to plug in with a Java import statement.
The SolarSystemTriggerGenerator class requires the following class: import com.vmware.solarsystem.Star;
176 VMware, Inc.
Chapter 7 Developing Plug-Ins
5 Import any other classes that the workflow trigger implementation requires.
The
SolarSystemTriggerGenerator
class requires the following class: import java.util.Properties;
6 Declare a public class to contain the workflow trigger implementation.
The SolarSystemTriggerGenerator class declares the following class: public class SolarSystemTriggerGenerator {
}
You set up the workflow trigger implementation.
What to do next
Implement the PluginTrigger class from the Orchestrator plug-in API to create workflow trigger instances.
Create Instances of the PluginTrigger Class
You create a workflow trigger by instantiating the
PluginTrigger
class.
The PluginTrigger class defines a constructor that you can use to create workflow trigger instances. The
PluginTrigger constructor can define properties such as the name of the workflow trigger, a timeout period, and the type and identifier of the object that the workflow trigger monitors.
Prerequisites n n
Set up the workflow trigger implementation class.
Declare a public class to contain the workflow trigger implementation.
Procedure
1 Create an instance of the PluginTrigger class by calling the PluginTrigger() constructor.
The SolarSystemTriggerGenerator class defines the newTrigger() method to create a workflow trigger named trigger .
private PluginTrigger newTrigger() {
PluginTrigger trigger = new PluginTrigger();
return trigger;
}
2 Call the methods of the PluginTrigger class to set the basic properties of the workflow trigger.
The SolarSystemTriggerGenerator class calls the PluginTrigger.setModuleName() method to set the name of the workflow trigger to the same name as the plug-in itself and calls PluginTrigger.setTimeout() to deactivate the timeout period.
private PluginTrigger newTrigger() {
PluginTrigger trigger = new PluginTrigger();
trigger.setModuleName(SolarSystemAdapter.pluginName);
trigger.setTimeout( -1 );
return trigger;
}
N
OTE
If you find objects by their type or identifier, you implement the setSdkType()
and setSdkId() methods to set triggers on objects.
You used the
PluginTrigger()
constructor to create workflow trigger instances to notify waiting workflows when defined events occur.
VMware, Inc. 177
vCenter Orchestrator Developer's Guide
What to do next
Set the properties that the workflow trigger monitors in the objects in the plugged-in technology.
Set the Properties that a Workflow Trigger Monitors
Workflow triggers monitor changes in the properties of an object in the plugged-in technology. When workflow triggers detect a change in the properties of an object, they notify any workflows in the Orchestrator server that are waiting for this event.
You set the properties that a workflow trigger monitors by passing a java.util.Properties
list to a
PluginTrigger instance.
Prerequisites n n
Set up the workflow trigger class.
Create PluginTrigger instances.
Procedure
1 Declare variables for the object and object properties that the workflow trigger monitors.
The SolarSystemTriggerGenerator class declares variables for the Star object that it monitors and for the magnitude of any solar flare events that occur on that star.
public static final String STAR_ID = "star_id"; public static final String MAGNITUDE = "magnitude";
2 Create an instance of the PluginTrigger class in which to set the properties to monitor.
The
SolarSystemTriggerGenerator
class calls the
SolarSystemTriggerGenerator.newTrigger()
method to create a trigger instance.
public PluginTrigger createStarFlareTrigger(Star star, double magnitude) {
PluginTrigger trigger = newTrigger();
return trigger;
}
3 Create an instance of a java.util.Properties
list to contain the properties to monitor.
The SolarSystemTriggerGenerator class create a properties list named props .
public PluginTrigger createStarFlareTrigger(Star star, double magnitude){
PluginTrigger trigger = newTrigger();
Properties props = new Properties();
return trigger;
}
178 VMware, Inc.
Chapter 7 Developing Plug-Ins
4 Call the
Properties.setProperty()
method to add the properties to monitor to the properties list.
The SolarSystemTriggerGenerator class adds the identifier of the star object and the value of the magnitude of the solar flare event to the properties list props .
public PluginTrigger createStarFlareTrigger(Star star, double magnitude){
PluginTrigger trigger = newTrigger();
Properties props = new Properties();
props.setProperty(STAR_ID, star.getId());
props.setProperty(MAGNITUDE, Double.toString(magnitude));
return trigger;
}
5 Call the
PluginTrigger.setProperties()
method to add the properties list to the workflow trigger instance.
The SolarSystemTriggerGenerator class adds the properties list props to the workflow trigger, to provide the identifier of the star object and the value of the flare event to monitor.
public PluginTrigger createStarFlareTrigger(Star star, double magnitude){
PluginTrigger trigger = newTrigger();
Properties props = new Properties();
props.setProperty(STAR_ID, star.getId() );
props.setProperty(MAGNITUDE, Double.toString(magnitude));
trigger.setProperties( props );
return trigger;
}
You added a list of properties to a workflow trigger so that it can monitor the value of a given property in an object. If the properties of the object change, the workflow trigger notifies any workflows that are waiting for that event.
What to do next
Create plug-in watchers to watch the triggers for events.
Create Plug-In Watchers
Plug-in watchers watch triggers on behalf of workflows that are waiting for the event that the trigger starts.
To create a plug-in watcher, you create a Java class that implements the
PluginWatcher
class from the
Orchestrator plug-in API. You publish the watcher on the Orchestrator notification server by implementing the IPluginPublisher interface.
These procedures present the steps involved in creating a plug-in watcher. To illustrate the process, they present code from the SolarSystemWatchersManager class from the solar system plug-in.
You can download the Orchestrator examples ZIP file from the Orchestrator documentation home page to obtain the sources of the solar system example application and plug-in.
class and publisher interface, see “PluginWatcher Class,” on page 223 and
“IPluginPublisher Interface,” on page 220.
Procedure
1
Set Up the Watcher Implementation on page 180
You can create
PluginWatcher
instances and methods to generate events directly in the plug-in adaptor.
However, the solar system example creates the watcher instances in a separate class named
SolarSystemWatchersManager .
VMware, Inc. 179
vCenter Orchestrator Developer's Guide
2
Create Instances of the PluginWatcher Class on page 181
You create a plug-in watcher to watch a workflow trigger by instantiating the PluginWatcher class. When the event that the workflow trigger defines occurs, the plug-in watcher notifies any workflows that are waiting for that event.
3
Publish Plug-In Watchers on page 182
You implement the IPluginPublisher interface to publish plug-in watchers to the Orchestrator notification mechanism.
Set Up the Watcher Implementation
You can create PluginWatcher instances and methods to generate events directly in the plug-in adaptor.
However, the solar system example creates the watcher instances in a separate class named
SolarSystemWatchersManager .
Prerequisites n n
Download the bundle of Orchestrator examples.
Unzip the examples bundle to an appropriate location.
Procedure
1 Create and save a Java file for the plug-in watcher class.
In the solar system example, the watcher class is named SolarSystemWatchersManager.java
.
2 Declare the package that contains the Java classes of the plug-in implementation.
The solar system example declares the following package: package com.vmware.orchestrator.api.sample.solarsystem;
3 Import the Orchestrator plug-in API classes with a Java import statement.
In the solar system example, the event watcher requires the following classes: import ch.dunes.vso.sdk.api.IPluginPublisher; import ch.dunes.vso.sdk.api.PluginWatcher;
4 Import any classes that the plug-in implementation or plugged-in technology defines.
In the solar system example, the watcher requires the following class that the
SolarSystemEventGenerator
class defines: import com.vmware.orchestrator.api.sample.solarsystem.
SolarSystemEventGenerator.StarFlareEventListener;
5 Import any other classes that the watcher implementation requires.
In the solar system example, the event watcher requires the following classes: import java.util.Hashtable; import java.util.List; import java.util.Map; import java.util.Properties; import java.util.Vector; import org.apache.log4j.Logger;
180 VMware, Inc.
Chapter 7 Developing Plug-Ins
6 Declare a public class for the event generator implementation.
The solar system example watcher declares the
SolarSystemWatchersManager
class, that implements the
StarFlareEventListener class.
public class SolarSystemWatchersManager implements StarFlareEventListener {
}
The StarFlareEventListener class listens for solar flare events of a certain magnitude.
7 Set up logging so that Orchestrator can record in the logs the events that the watcher observes.
The solar system example uses an instance of org.apache.log4j.Logger
to log events.
public class SolarSystemWatchersManager implements StarFlareEventListener {
private static final Logger log = Logger.getLogger(SolarSystemWatchersManager.class);
}
8 Declare a public constructor to create instances of the watcher implementation class.
The SolarSystemWatchersManager class creates a constructor that creates instances of
SolarSystemWatchersManager . The SolarSystemWatchersManager instances contain the starFlareEventListener event listener that the SolarSystemEventGenerator class defines.
public SolarSystemWatchersManager() {
SolarSystemEventGenerator._solarSystemEventGenerator.
addStarFlareUniqueEventListener(this);
}
You set up a plug-in event watcher class to create watcher instances to watch for events from triggers.
What to do next
Create instances of the PluginWatcher class.
Create Instances of the PluginWatcher Class
You create a plug-in watcher to watch a workflow trigger by instantiating the PluginWatcher class. When the event that the workflow trigger defines occurs, the plug-in watcher notifies any workflows that are waiting for that event.
The PluginWatcher class defines a constructor that you can use to create plug-in watcher instances. The
PluginWatcher class defines methods to obtain or set the name of the workflow trigger to watch and a timeout period.
Prerequisites n n
Set up the plug-in watcher implementation class.
Declare a public constructor to instantiate the plug-in watcher implementation.
VMware, Inc. 181
vCenter Orchestrator Developer's Guide
Procedure
1 Create one or more instances of the
PluginWatcher
class with which to register the workflow triggers to monitor.
The SolarSystemWatchersManager class creates a hashtable to contain all of the PluginWatcher instances.
private final Map<String, PluginWatcher> watchers = new Hashtable<String, PluginWatcher>();
2 Obtain watcher instances by calling the PluginWatcher.getId() method.
The
SolarSystemWatchersManager
class defines a method that adds a
PluginWatcher
instance to the hashtable of PluginWatcher instances.
public void addWatcher(PluginWatcher watcher) {
synchronized (watchers) {
watchers.put(watcher.getId(), watcher);
}
}
3 (Optional) Remove watcher instances after an event occurs.
The SolarSystemWatchersManager class defines a method that removes a PluginWatcher instance from the hashtable of PluginWatcher instances.
public void removeWatcher(String watcherId) {
synchronized (watchers) {
watchers.remove(watcherId);
}
}
You created instances of the PluginWatcher class to watch workflow triggers for events.
What to do next
Register the watcher instances with
IPluginPublisher
instances to publish the watchers to the Orchestrator notification mechanism.
Publish Plug-In Watchers
You implement the IPluginPublisher interface to publish plug-in watchers to the Orchestrator notification mechanism.
When a workflow trigger starts an event in the plugged-in technology, a plug-in watcher that watches that trigger and that is registered with an IPluginPublisher instance notifies any waiting workflows that the event has occurred.
Prerequisites n n n
Set up the plug-in watcher implementation class.
Declare a public constructor to instantiate the plug-in watcher implementation.
Create instances of the
PluginWatcher
class.
182 VMware, Inc.
Chapter 7 Developing Plug-Ins
Procedure
1 Create an instance of the
IPluginPublisher
interface.
The SolarSystemWatchersManager class declares the following variable for the IPluginPublisher instance.
private IPluginPublisher pluginPublisher;
2 Define a method to add the IPluginPublisher instance to the plug-in adapter implementation.
The
SolarSystemWatchersManager
class declares the following method that the
SolarSystemAdapter
class calls.
public void setPluginPublisher(IPluginPublisher pluginPublisher) {
this.pluginPublisher = pluginPublisher;
}
3 Define the event for which the watcher watches and that the publisher publishes to the Orchestrator notification mechanism.
The SolarSystemWatchersManager class defines the starFlareEvent() method that takes a Star object and a magnitude value as parameters. The starFlareEvent() method also gets the hashtable of watchers and creates a list of watchers to remove from the hashtable after the event occurs.
public void starFlareEvent(String starid, double magnitude) {
synchronized (watchers) {
List<String> watchersToRemove = new Vector<String>();
}
}
4 Call the PluginWatcher.getTrigger() and PluginTrigger.getProperties() methods to obtain the properties to watch in the trigger.
The SolarSystemWatchersManager.starFlareEvent() method extracts the STAR_ID and MAGNITUDE properties from the trigger and adds them to a PluginWatcher instance in the hashtable.
public void starFlareEvent(String starid, double magnitude) {
synchronized (watchers) {
List<String> watchersToRemove = new Vector<String>();
for (PluginWatcher watcher : watchers.values()) {
Properties props = watcher.getTrigger().getProperties();
String wStarId = props.getProperty(SolarSystemTriggerGenerator.STAR_ID);
String wMagnitude = props.getProperty(SolarSystemTriggerGenerator.MAGNITUDE);
}
}
}
VMware, Inc. 183
vCenter Orchestrator Developer's Guide
5 Define the event and publish it to the Orchestrator notification mechanism by calling the
IPluginPublisher.pushWatcherEvent()
method.
The SolarSystemWatchersManager.starFlareEvent() method checks whether the magnitude value exceeds a maximum magnitude value. If the maximum magnitude value is exceeded, the starFlareEvent() method writes the flare event in the logs and publishes the event to the Orchestrator notification mechanism.
public void starFlareEvent(String starid, double magnitude) {
synchronized (watchers) {
List<String> watchersToRemove = new Vector<String>();
for (PluginWatcher watcher : watchers.values()) {
Properties props = watcher.getTrigger().getProperties();
String wStarId = props.getProperty(SolarSystemTriggerGenerator.STAR_ID);
String wMagnitude = props.getProperty(SolarSystemTriggerGenerator.MAGNITUDE);
if (wStarId != null && wStarId.equals(starid)) {
double wMagnLimit = Double.parseDouble(wMagnitude);
if (magnitude >= wMagnLimit) {
log.info("pushWatcherEvent() for id '" + watcher.getId() + "'");
pluginPublisher.pushWatcherEvent(watcher.getId(), null);
}
}
}
}
}
6 (Optional) Remove the watchers from the notification mechanism after the events occur.
The
SolarSystemWatchersManager.starFlareEvent()
method adds the watcher to the list of watchers to remove and defines a method to remove that list of watchers from the hashtable.
public void starFlareEvent(String starid, double magnitude) {
synchronized (watchers) {
List<String> watchersToRemove = new Vector<String>();
for (PluginWatcher watcher : watchers.values()) {
Properties props = watcher.getTrigger().getProperties();
String wStarId = props.getProperty(SolarSystemTriggerGenerator.STAR_ID);
String wMagnitude = props.getProperty(SolarSystemTriggerGenerator.MAGNITUDE);
if (wStarId != null && wStarId.equals(starid)) {
double wMagnLimit = Double.parseDouble(wMagnitude);
if (magnitude >= wMagnLimit) {
log.info("pushWatcherEvent() for id '" + watcher.getId() + "'");
pluginPublisher.pushWatcherEvent(watcher.getId(), null);
watchersToRemove.add(watcher.getId());
}
}
}
for (String toRemove : watchersToRemove) {
watchers.remove(toRemove);
}
}
}
You defined an event for a watcher to watch and published the event to the Orchestrator notification mechanism. Orchestrator notifies any workflows that are waiting for that event that it has occurred.
What to do next
Define objects and methods to add to the Orchestrator JavaScript API.
184 VMware, Inc.
Chapter 7 Developing Plug-Ins
Define Objects and Methods to Map to the Orchestrator JavaScript API
You can map the object types, classes, and methods of the plugged-in technology and the plug-in itself to
JavaScript types, classes, and methods that you add to the Orchestrator JavaScript API.
You can add objects and functions to the JavaScript API that do not exist in the plugged-in technology by defining them in the plug-in implementation. Adding objects and functions to the JavaScript API allows you to include the objects and functions in Orchestrator actions and workflows, to perform operations on objects in the plugged-in technology.
You map the objects and functions that you define in the plug-in implementation in
<scripting-object> elements in the vso.xml
file. For information about how to map objects and functions to the JavaScript API in the vso.xml
file, see “Map the Application in the vso.xml File,” on page 201.
The vso.xml
file in the solar system example maps to JavaScript objects all of the objects and methods that the solar system application defines. The vso.xml
file also maps the following objects and methods from the solar system plug-in implementation to the Orchestrator JavaScript API.
n SolarSystemEventGenerator scripting class n SolarSystemEventGenerator.generateFlareEvent() scripting method n SolarSystemTriggerGenerator scripting class n SolarSystemTriggerGenerator.createStarFlareTrigger() scripting method
To create a class to map to the Orchestrator JavaScript API, you add an instance of that class to an instance of the IPluginFactory implementation by defining a method named createScriptingSingleton() . When the plug-in adaptor instantiates the factory, it also instantiates the class to add to the JavaScript API.
Prerequisites
You created at least one class of the plug-in implementation, for example the adaptor, the factory, or an event generator implementation.
Procedure
1 Create an instance of a class to map to the Orchestrator JavaScript API in one of the classes of the plug-in implementation.
The SolarSystemEventGenerator class defines the following constructor to create instances of itself: public final static SolarSystemEventGenerator _solarSystemEventGenerator =
new SolarSystemEventGenerator();
2 Define a method named createScriptingSingleton() that accesses the IPluginFactory implementation of the plug-in.
The SolarSystemEventGenerator class creates the following instance of that class: public static SolarSystemEventGenerator createScriptingSingleton(IPluginFactory factory) {
}
3 Implement the createScriptingSingleton()
method to return to the factory an instance of the class to map to the JavaScript API.
The SolarSystemEventGenerator class returns the _solarSystemEventGenerator instance.
public static SolarSystemEventGenerator createScriptingSingleton(IPluginFactory factory) {
return _solarSystemEventGenerator;
}
VMware, Inc. 185
vCenter Orchestrator Developer's Guide
You created an instance of a class that the vso.xml
file can map to a scripting class in the Orchestrator JavaScript
API. The vso.xml
file of the solar system example maps the _solarSystemEventGenerator instance to the
SolarSystemEventGenerator scripting class in the JavaScript API.
What to do next
Implement the plug-in adapter to instantiate all of the classes and objects that you defined in the plug-in.
Create a Plug-In Adapter
To create a plug-in adapter, you create a Java class that implements the IPluginAdaptor interface from the
Orchestrator plug-in API. The adapter instantiates the plug-in factory and event management implementations.
These procedures present the steps involved in creating a plug-in adapter. To illustrate the process, they present code from the SolarSystemAdapter class from the solar system example application. You can download the
Orchestrator examples ZIP file from the Orchestrator documentation home page to obtain the sources of the solar system example application.
For a description of the role of the plug-in adapter and the other components of a plug-in, see
“IPluginAdaptor Interface,” on page 218.
Procedure
1
Set Up the Plug-In Adapter Implementation on page 186
To create a plug-in adapter, you create an implementation of the
IPluginAdaptor
interface from the
Orchestrator plug-in API.
2
Instantiate the Plug-In Factory on page 187
You instantiate the plug-in factory in the plug-in adapter. The adapter creates one factory instance for every connection between Orchestrator and the plugged-in technology.
3
Manage Plug-In Events on page 189
The plug-in adapter manages the events that occur in the plugged-in technology by defining event generators and event publishers.
4
Add Plug-In Watchers on page 190
Plug-in watchers monitor the events that workflow triggers define. When an event occurs, Orchestrator notifies any workflows that are waiting for that event.
Set Up the Plug-In Adapter Implementation
To create a plug-in adapter, you create an implementation of the IPluginAdaptor interface from the
Orchestrator plug-in API.
Procedure
1 Create and save a Java file for the plug-in adapter implementation named
YourApplicationNameAdapter.java
.
In the solar system example, the adapter class is SolarSystemAdapter.java
.
2 Declare a package to contain the plug-in implementation.
The solar system example declares the following package to contain the adapter, factory, and event handler implementations: package com.vmware.orchestrator.api.sample.solarsystem;
186 VMware, Inc.
Chapter 7 Developing Plug-Ins
3 Import the Orchestrator plug-in API interfaces, classes, and enumerations with a Java import
statement.
import ch.dunes.vso.sdk.api.*;
4 Import any other classes that the adapter implementation requires.
In the solar system example, the adapter implementation requires the following classes: import javax.security.auth.login.LoginException; import org.jboss.logging.Logger;
5 Declare a public constructor that implements the IPluginAdaptor interface from the Orchestrator plug-in
API.
The solar system adapter declares the SolarSystemAdapter constructor.
public class SolarSystemAdapter implements IPluginAdaptor {
}
6 Set up a logger to write to the logs the events that occur in the adapter.
The solar system adapter uses an instance of org.jboss.logging.Logger
to log events.
private static final Logger log = Logger.getLogger(SolarSystemAdapter.class);
You set up the IPluginAdaptor implementation.
What to do next
Create an instance of the
IPluginFactory
implementation.
Instantiate the Plug-In Factory
You instantiate the plug-in factory in the plug-in adapter. The adapter creates one factory instance for every connection between Orchestrator and the plugged-in technology.
Prerequisites n n n
Create an implementation of the IPluginFactory interface.
Set up the adapter implementation class.
Create a public constructor that implements the IPluginAdaptor interface.
VMware, Inc. 187
vCenter Orchestrator Developer's Guide
Procedure
1 Declare the variables that the adapter class uses in its method calls.
The solar system adapter declares variables for the plug-in factory and plug-in name.
public class SolarSystemAdapter implements IPluginAdaptor {
private SolarSystemFactory factory;
static String pluginName;
}
2 Create an instance of the plug-in factory class that implements the
IPluginFactory
interface.
The solar system adapter calls the IPluginAdaptor.createPluginFactory() method to create an instance of the SolarSystemFactory interface, if one does not exist already.
public IPluginFactory createPluginFactory(String sessionID, String username,
String password, IPluginNotificationHandler notificationHandler)
throws SecurityException, LoginException, PluginLicenseException {
if (factory == null) {
factory = new SolarSystemFactory();
}
return factory;
}
3 Set the plug-in name.
The
IPluginAdaptor.setPluginName()
method gets the name from the vso.xml
file.
The solar system adapter uses the pluginName variable to set the name of the plug-in.
public void setPluginName(String pluginName) {
SolarSystemAdapter.pluginName = pluginName;
}
4 (Optional) Install any licenses that Orchestrator requires to access the plugged-in technology.
You obtain licenses by calling the IPluginAdaptor.installLicenses() method to instantiate an array of
PluginLicense objects.
public void installLicenses(PluginLicense[] licenses) throws
PluginLicenseException {
}
5 (Optional) Uninstall an existing plug-in factory.
A plug-in creates a factory instance for every client session that opens between Orchestrator and a pluggedin technology. You can remove unnecessary plug-in factories to clean up the Orchestrator server by calling the IPluginAdaptor.uninstallPluginFactory() method.
The solar system plug-in does not implement the IPluginAdaptor.uninstallPluginFactory() method.
You can uninstall factories by implementing a function in the uninstallPluginFactory() method declaration.
public void uninstallPluginFactory(IPluginFactory plugin) {
}
You instantiated the IPluginFactory implementation, set the name for the plug-in, obtained any licenses that the plug-in connection requires, and potentially defined a function to remove old factory instances from the server.
What to do next
Instantiate event generators and publishers.
188 VMware, Inc.
Chapter 7 Developing Plug-Ins
Manage Plug-In Events
The plug-in adapter manages the events that occur in the plugged-in technology by defining event generators and event publishers.
Prerequisites n Create a public constructor that implements the
IPluginAdaptor
interface.
n Instantiate the plug-in factory.
Procedure
1 Define the method to generate plug-in events.
You can define the events to manage directly in the adapter implementation. However, the solar system plug-in implementation defines the events in a separate class, SolarSystemEventGenerator .
SolarSystemAdapter defines the following getEventGenerator() method to obtain an instance of the
SolarSystemEventGenerator class.
private SolarSystemEventGenerator getEventGenerator() {
return SolarSystemEventGenerator._solarSystemEventGenerator;
}
2 (Optional) If Orchestrator monitors the plugged-in application for events, you can register an instance of the IPluginEventPublisher interface with the Orchestrator policy engine by calling the
IPluginAdaptor.registerEventPublisher()
method.
The solar system example adapter creates the following IPluginEventPublisher instance and registers it with the Orchestrator policy engine by calling the SolarSystemEventGenerator.addPolicyElement() method.
public void registerEventPublisher(
String type, String id, IPluginEventPublisher publisher) {
getEventGenerator().addPolicyElement(type, id, publisher);
}
3 (Optional) Unregister an
IPluginEventPublisher
from the Orchestrator policy engine.
The solar system example adapter unregisters an IPluginEventPublisher instance and removes it from the Orchestrator policy engine by calling the SolarSystemEventGenerator.removePolicyElement() method.
public void unregisterEventPublisher(
String type, String id, IPluginEventPublisher publisher) {
getEventGenerator().removePolicyElement(type, id, publisher);
}
You instantiated an event generator and optionally defined methods to register and unregister an event publisher with the Orchestrator policy engine.
What to do next
Add and remove watchers that monitor workflow triggers. When the events that the workflow triggers define occur, Orchestrator notifies any workflows that are waiting for that event.
VMware, Inc. 189
vCenter Orchestrator Developer's Guide
Add Plug-In Watchers
Plug-in watchers monitor the events that workflow triggers define. When an event occurs, Orchestrator notifies any workflows that are waiting for that event.
Prerequisites n Create a public constructor that implements the
IPluginAdaptor
interface.
n n
Instantiate the plug-in factory.
Create event generators and publishers.
Procedure
1 Create an instance of the plug-in watcher implementation.
The SolarSystemAdapter class creates an instance of the SolarSystemWatchersManager class.
private static final SolarSystemWatchersManager watchersManager =
new SolarSystemWatchersManager();
2 Add a watcher instance to the plug-in adaptor.
You add a watcher to the adapter by calling the IPluginAdaptor.addWatcher() method.
The solar system example defines a method to add the SolarSystemWatchersManager instance.
public void addWatcher(PluginWatcher watcher) {
log.info( "Adding watcher '" + watcher + "'" );
watchersManager.addWatcher(watcher);
}
3 Remove a watcher from the plug-in adaptor.
You remove a watcher by calling the IPluginAdaptor.removeWatcher() method.
The solar system example defines a method to remove a
SolarSystemWatchersManager
instance.
public void removeWatcher(String watcherId) {
log.info( "Removing watcher '" + watcherId + "'" );
watchersManager.removeWatcher( watcherId );
}
4 Instantiate the plug-in publisher that publishes events from the watchers to the Orchestrator notification mechanism.
The solar system example defines a method that calls the
SolarSystemWatchersManager.setPluginPublisher() method to instantiate a plug-in publisher.
public void setPluginPublisher(IPluginPublisher pluginPublisher) {
watchersManager.setPluginPublisher( pluginPublisher );
}
You added watchers to the plug-in adapter implementation to monitor the events that workflow triggers generate.
What to do next
Add a tab for the plug-in to the Orchestrator configuration interface.
190 VMware, Inc.
Chapter 7 Developing Plug-Ins
Add a Tab to the Configuration Interface
You can add a tab to the Orchestrator configuration interface to allow users to provide information to the plugin configuration that is specific to their environment or preferences.
To add a configuration tab for a plug-in to the configuration interface, you implement the
IConfigurationAdaptor
interface. You can also use the
SDKHelper
and extend the
BaseAction
classes from the
Orchestrator plug-in API. You create a configuration adapter that accesses the classes of the plug-in and the plugged-in technology for the Orchestrator configuration server. You define configuration actions to obtain and save the configuration information that the user provides by using the configuration tab.
You must create an Apache Struts-based Web application to create the layout of the tab in the configuration interface. The Struts Web application uses the methods that you define in the IConfigurationAdaptor implementation to add configuration operations for the users to perform in the configuration tab for the plugin. The Struts Web application submits to the Orchestrator server the information that the user enters in the configuration tab.
Creating a plug-in configuration tab requires several steps. Code from the
SolarSystemConfigurationAdapter and SolarSystemConfigureAction classes from the solar system plug-in is included in the steps.
You can download the Orchestrator examples ZIP file from the Orchestrator documentation home page to obtain the sources of the solar system example application and plug-in.
For information about all of the methods and parameters of the configuration adapter interface, see
SDKHelper
class provides, see
“SDKHelper Class,” on page 225.
Procedure
1
Set Up the Configuration Adapter on page 192
To create a tab in the configuration interface for a plug-in, you create an implementation of the
IConfigurationAdaptor interface from the Orchestrator plug-in API. You also call the methods of the
SDKHelper class.
2
Load and Save Configuration Information in the Configuration Server on page 193
The IConfigurationAdaptor interface provides methods to load and save configuration information in the Orchestrator configuration server. The configuration adapter uses these methods to locate and update the configuration information for a plug-in by setting plug-in properties.
3
Create a Configuration Action to Obtain Configuration Information from the User on page 196
Orchestrator uses the Apache Struts framework to pass to the Orchestrator server the configuration information that the user provides in the configuration interface.
4
Create a Struts-Based Web Application to Add to the Configuration Interface on page 198
The tab that you add to the Orchestrator configuration interface is an Apache Struts-based Web application. You define the layout of the page by using HTML or JavaServer Pages (JSP) and add actions to the page by implementing the Struts framework.
VMware, Inc. 191
vCenter Orchestrator Developer's Guide
Set Up the Configuration Adapter
To create a tab in the configuration interface for a plug-in, you create an implementation of the
IConfigurationAdaptor interface from the Orchestrator plug-in API. You also call the methods of the
SDKHelper class.
Prerequisites n n n
You have an application to plug in to Orchestrator.
You have access to the Orchestrator plug-in API JAR file.
Implement the plug-in adapter and factory interfaces.
Procedure
1 Create and save a Java file for the plug-in configuration adapter implementation.
In the solar system example, the configuration adapter class is named
SolarSystemConfigurationAdaptor.java
.
2 Declare the package that contains the Java classes of the plug-in configuration implementation.
The solar system example declares the following package: com.vmware.orchestrator.api.sample.solarsystem.config;
3 Import the classes of the plug-in configuration API with a Java import statement.
import ch.dunes.util.Localizator; import ch.dunes.vso.sdk.conf.ConfigurationError; import ch.dunes.vso.sdk.conf.WebConfigurationAdaptor; import ch.dunes.vso.sdk.helper.SDKHelper;
4 Import the classes of the application to plug in with a Java import statement.
import com.vmware.solarsystem.*;
5 Import any other classes that the configuration adapter implementation requires.
In the solar system example, the configuration adapter implementation requires the following classes: import java.awt.Component; import java.io.File; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Hashtable; import java.util.List; import java.util.Map; import java.util.Properties;
6 Declare a public class that implements the IConfigurationAdaptor interface.
public class SolarSystemConfigurationAdaptor implements WebConfigurationAdaptor {
}
The
WebConfigurationAdaptor
class extends the
IConfigurationAdaptor
interface.
You set up the plug-in configuration adapter implementation.
What to do next
Define methods to load and save plug-in configuration information.
192 VMware, Inc.
Chapter 7 Developing Plug-Ins
Load and Save Configuration Information in the Configuration Server
The IConfigurationAdaptor interface provides methods to load and save configuration information in the
Orchestrator configuration server. The configuration adapter uses these methods to locate and update the configuration information for a plug-in by setting plug-in properties.
You also create methods in the configuration adapter to define the values that the user can configure.
Orchestrator reloads this information each time this user connects to the Orchestrator server. You can validate the information that the user provides.
In the solar system example, the SolarSystemConfigurationAdaptor class defines methods to allow users to select their home planet and to define Pluto as either a planet or as a dwarf planet. The
SolarSystemConfigurationAdaptor class implements the methods of the IConfigurationAdaptor interface to load and save configuration information and to validate the information that the users provide. The methods that SolarSystemConfigurationAdaptor defines are implemented by the SolarSystemConfigureAction class.
Prerequisites n n
Implement the plug-in adapter and factory interfaces.
Set up the configuration adapter implementation class.
Procedure
1 Declare variables for the plug-in name and for the configurable values.
The SolarSystemConfigurationAdaptor class declares the following variables: private String pluginName = "SolarSystem"; private String homePlanet; private String plutoClassifiedAsAPlanet = "yes";
2 Create a class loader to load the configuration adapter classes into the configuration server.
Orchestrator defines a utility class named
Localizator
to locate packages of classes.
The SolarSystemConfigurationAdaptor class creates an instance of Localizator that calls the java.lang.Class.getClassLoader() method and directs it to the package of configuration classes.
private static Localizator local =
new Localizator(SolarSystemConfigurationAdaptor.class.getClassLoader(),
"com/vmware/orchestrator/api/sample/solarsystem/config/package");
VMware, Inc. 193
vCenter Orchestrator Developer's Guide
3 Define methods to obtain and set the configurable values.
The
SolarSystemConfigurationAdaptor
class uses the
Localizator.getResourceString()
method to get the properties of Pluto from the plug-in configuration server and adds them to a hashtable. The
SolarSystemConfigurationAdaptor class also defines methods to set whether Pluto is a planet and to set the user's home planet.
public Map<String, String> getPlutoClassifyList(){
Map<String, String> ret = new Hashtable<String, String>();
ret.put("no", local.getResourceString("select.pluto.classify.dwarfPlanet"));
ret.put("yes", local.getResourceString("select.pluto.classify.planet"));
return ret;
} public List<Planet> getAllPlanets(){
return SolarSystemRepository.getUniqueInstance().getAllPlanets();
} public String getHomePlanet() {
return homePlanet;
} public void setHomePlanet(String homePlanet) {
this.homePlanet = homePlanet;
} public void setPlutoClassifiedAsAPlanet(String plutoClassifiedAsAPlanet) {
this.plutoClassifiedAsAPlanet = plutoClassifiedAsAPlanet;
} public String getPlutoClassifiedAsAPlanet() {
return plutoClassifiedAsAPlanet;
}
4 Implement the IConfigurationAdaptor.saveConfiguration() method to save configuration information to the configuration server by setting plug-in properties.
The
SolarSystemConfigurationAdaptor.loadConfiguration()
method creates a
Properties
list to contain the configurable properties. The values that SolarSystemConfigurationAdaptor.saveConfiguration() method adds to the list are the values that the methods defined in
SolarSystemConfigurationAdaptor.saveConfiguration() method calls the
SDKHelper.savePropertiesForPluginName() to save the Properties list to the configuration server.
public void saveConfiguration(OutputStream stream) throws IOException {
System.out.println("home planet: " + homePlanet);
System.out.println("is pluto classified as a planet: " + plutoClassifiedAsAPlanet);
Properties prop = new Properties();
prop.setProperty("solar.system.home.planet", homePlanet);
prop.setProperty("solar.system.isPlutoClassifiedAsAPlanet", plutoClassifiedAsAPlanet);
if (stream == null) {
SDKHelper.savePropertiesForPluginName(prop, pluginName);
}
}
194 VMware, Inc.
Chapter 7 Developing Plug-Ins
5 Implement the
IConfigurationAdaptor.loadConfiguration()
method to load configuration information from the configuration server into the Orchestrator server.
The SolarSystemConfigurationAdaptor.loadConfiguration() method creates a Properties list to contain the configurable properties. The SolarSystemConfigurationAdaptor.loadConfiguration() method calls the
SDKHelper.getConfigurationPathForPluginName()
and
SDKHelper.loadPropertiesForPluginName() methods to get the properties from the plug-in and adds them to the Properties list.
public void loadConfiguration(InputStream stream) throws IOException {
Properties prop = new Properties();
String path = SDKHelper.getConfigurationPathForPluginName(pluginName);
if (new File(path).exists()) {
prop = SDKHelper.loadPropertiesForPluginName(pluginName);
}
if (prop.getProperty("solar.system.home.planet") != null) {
homePlanet = prop.getProperty("solar.system.home.planet");
}
if (prop.getProperty("solar.system.isPlutoClassifiedAsAPlanet") != null){
plutoClassifiedAsAPlanet = prop.getProperty("solar.system.isPlutoClassifiedAsAPlanet");
}
}
6 Implement the IConfigurationAdaptor.setPluginName() method to set the name of the plug-in in the configuration server.
The SolarSystemConfigurationAdaptor class does not add any additional code to the
IConfigurationAdaptor.setPluginName() method.
public void setPluginName(String name) {
}
7 Implement the IConfigurationAdaptor.validateConfiguration() method to validate the configuration information.
The IConfigurationAdaptor.validateConfiguration() method returns a ConfigurationError instance for each validation error. The SolarSystemConfigurationAdaptor class returns null in the event of an invalid configuration property. You can implement more sophisticated code to perform more stringent validation of the values that the user provides in the configuration interface.
public ConfigurationError[] validateConfiguration() {
return null;
}
8 Implement the WebConfigurationAdaptor.getWebAppContext() and
WebConfigurationAdaptor.setWebConfiguration() methods to locate the WAR file of a Struts-based Web application Web application that defines the actions to perform in the configuration tab.
The
SolarSystemConfigurationAdaptor
class points the getWebAppContext()
method to the solarsystem
WAR file in the DAR file.
public String getWebAppContext() {
return "/solarsystem";
} public void setWebConfiguration(boolean webConfiguration) {
}
You implemented the methods of the IConfigurationAdaptor and SDKHelper classes to load and save configuration information in the configuration server and defined methods to obtain and set the configurable values.
VMware, Inc. 195
vCenter Orchestrator Developer's Guide
What to do next
Obtain configuration information that the user sets in the configuration interface by implementing the Apache
Struts framework.
Create a Configuration Action to Obtain Configuration Information from the User
Orchestrator uses the Apache Struts framework to pass to the Orchestrator server the configuration information that the user provides in the configuration interface.
You can implement the action that passes configuration information from the Orchestrator configuration interface to the configuration server directly in the configuration adapter implementation. However, the solar system example defines this action in a separate class named SolarSystemConfigureAction . The
SolarSystemConfigureAction class uses the methods that the SolarSystemConfigurationAdaptor class defines to load and save configuration information. The SolarSystemConfigureAction class implements the Apache
Struts framework to obtain the configuration information from the configuration interface and pass it to the
Orchestrator configuration server. The tab that you add to the configuration interface is a Struts Web application.
Prerequisites n n n
Implement the plug-in adapter and factory interfaces.
Set up the configuration adapter implementation class.
Implement the methods of the
IConfigurationAdaptor
interface to load, save, and validate configuration information.
Procedure
1 Create and save a Java file for the plug-in configuration action implementation.
In the solar system example, the configuration action class is named SolarSystemConfigureAction.java
.
2 Declare the package that contains the Java classes of the plug-in configuration implementation.
The solar system example declares the following package: com.vmware.orchestrator.api.sample.solarsystem.config;
3 Import the classes of the Orchestrator API with a Java import statement.
The
SolarSystemConfigureAction
class requires the following classes: import ch.dunes.vso.configuration.web.commons.BaseAction; import ch.dunes.vso.sdk.conf.ConfigurationError;
4 Import the third-party Java classes that the configuration action requires.
The SolarSystemConfigureAction class requires the following classes: import org.apache.log4j.Logger; import com.opensymphony.xwork2.ModelDriven;
5 Declare a public class that implements the BaseAction and ModelDriven classes.
The Orchestrator
BaseAction
class defines how Orchestrator interacts with the Struts framework. The
OpenSymphony XWork2 ModelDriven class pushes objects to the Struts framework.
The SolarSystemConfigureAction class implements these classes and creates a generic instance of the
SolarSystemConfigurationAdaptor
class.
public class SolarSystemConfigureAction extends BaseAction
implements ModelDriven<SolarSystemConfigurationAdaptor> {
}
196 VMware, Inc.
Chapter 7 Developing Plug-Ins
6 Define the variables that the
BaseAction
implementation requires.
The SolarSystemConfigureAction class declares variables for the unique identifier of each instance of the serializable BaseAction class, a logger, an array of ConfigurationError instances, and the configuration adapter instance.
private static final long serialVersionUID = 1L; private static Logger log = Logger.getLogger(SolarSystemConfigureAction.class); private ConfigurationError[] configErrors; private SolarSystemConfigurationAdaptor solarSystemConfigurationAdaptor;
7 Implement the
BaseAction.prepare()
method to instantiate the configuration adapter and load the configuration information.
The SolarSystemConfigureAction class creates an instance of the SolarSystemConfigurationAdaptor class and calls the SolarSystemConfigurationAdaptor.loadConfiguration() method.
public void prepare() throws Exception {
solarSystemConfigurationAdaptor = new SolarSystemConfigurationAdaptor();
solarSystemConfigurationAdaptor.loadConfiguration(null);
}
8 Implement the BaseAction.execute() method to log and validate the configuration information.
The SolarSystemConfigureAction class implements the BaseAction.execute() method to record in the logs the result of calling the SolarSystemConfigurationAdaptor.validateConfiguration() method.
public String execute() throws Exception {
log.debug("SolarSystemConfigureAction execute method");
configErrors = solarSystemConfigurationAdaptor.validateConfiguration();
return SUCCESS;
}
9 Implement a save() method to save the configuration information.
The SolarSystemConfigureAction class implements the save() method to record in the logs the result of calling the SolarSystemConfigurationAdaptor.saveConfiguration() method.
public String save() throws Exception {
log.debug("SolarSystemConfigureAction save method");
solarSystemConfigurationAdaptor.saveConfiguration(null);
configErrors = solarSystemConfigurationAdaptor.validateConfiguration();
return SUCCESS;
}
VMware, Inc. 197
vCenter Orchestrator Developer's Guide
10 Add error handling to the implementation of the configuration action.
The
SolarSystemConfigureAction
class returns an array of errors if the configuration is invalid.
public ConfigurationError[] getConfigErrors() {
return configErrors;
} public void setConfigErrors(ConfigurationError[] configErrors) {
this.configErrors = configErrors;
} public int getConfigErrorsSize() {
return configErrors.length;
}
11 Add the configuration adapter to the Struts Web application in the configuration interface by implementing the ModelDriven.getModel() class from the OpenSymphony XWork2 framework.
The SolarSystemConfigureAction class passes an instance of the SolarSystemConfigurationAdaptor to the
Struts framework.
public SolarSystemConfigurationAdaptor getModel() {
return solarSystemConfigurationAdaptor;
}
You created the configuration action that instantiates the configuration adapter and implements the
Orchestrator
BaseAction
and OpenSymphony
ModelDriven
classes. The
BaseAction
and
ModelDriven
classes pass configuration information from the Orchestrator configuration interface to the Orchestrator server through the Struts framework.
What to do next
Create a Struts-based Web application to add a tab to the Orchestrator configuration interface.
Create a Struts-Based Web Application to Add to the Configuration Interface
The tab that you add to the Orchestrator configuration interface is an Apache Struts-based Web application.
You define the layout of the page by using HTML or JavaServer Pages (JSP) and add actions to the page by implementing the Struts framework.
To add a configuration tab to the Orchestrator configuration interface, you must include a Web application archive (WAR) file in the DAR file of the plug-in.
The DAR file of the solar system plug-in contains a built WAR file for the solar system configuration tab. You can also examine the files of the solar system configuration Web application in the bundle of source files of the solar system plug-in.
n VSOSDK-SolarSystem\webapp\index.jsp
n VSOSDK-SolarSystem\webapp\WEB-INF\web.xml
n VSOSDK-SolarSystem\webapp\WEB-INF\pages\configure.jsp
n VSOSDK-SolarSystem\src\struts.xml
You must be familiar with Web application development technologies, including the Struts framework and
JSP. See the Apache Struts documentation for information about Struts. For details of all the directories and files that the WAR file contains, see
“Contents of the Solar System Configuration WAR File,” on page 200.
Prerequisites n n
Implement the plug-in adapter and factory interfaces.
Create the configuration adapter and configuration action implementations.
198 VMware, Inc.
Chapter 7 Developing Plug-Ins
Procedure
1 Create an index page for the configuration tab that implements the JavaServer Pages Standard Tag Library
(JSTL).
The index page must refer to the JSTL definition.
<%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %>
2 Create a Web application definition XML file that provides information about the plug-in to the
Orchestrator configuration server.
The Web application definition file references the XML schemas, locates the index page, accesses resource files, and implements security.
3 Create a JSP page that defines the layout and contents of the configuration tab.
The configuration tab can include any types of buttons, forms, lists, or menus that JSP provides.
The solar system configuration tab includes a button that the user can use to set the plutoClassifiedAsAPlanet
property to designate Pluto as a planet or a dwarf planet, a list from which they can select their home planet from the allPlanets properties list, and a save button that calls a Struts action named ConfigureSave .
<div id="c_content">
<s:form action="ConfigureSave" method="POST" validate="true">
<s:radio key="select.pluto.classify.text" name="plutoClassifiedAsAPlanet"
list="plutoClassifyList"/>
<s:select key="select.home.planet" list="allPlanets" listValue="name" listKey="id"
name="homePlanet"/>
<s:submit type="input" key="save.button"/>
</s:form>
</div>
4 Create a Struts configuration file that implements the Struts framework to pass to the configuration server the configuration information that the user enters.
The Struts configuration file in the solar system example implements the OpenSymphoyOpenSymphony
XWork2
ActionSupport
class to pass the results of the
ConfigureSave
action to the Struts framework. The
ConfigureSave action calls the SolarSystemConfigureAction.save() method.
<action name="Default" class="com.opensymphony.xwork2.ActionSupport">
<result name="success" type="chain">Configure</result>
</action>
<action name="Configure"
class="com.vmware.orchestrator.api.sample.solarsystem.config.SolarSystemConfigureAction">
<result name="success">/WEB-INF/pages/configure.jsp</result>
</action>
<action name="ConfigureSave"
class="com.vmware.orchestrator.api.sample.solarsystem.config.SolarSystemConfigureAction"
method="save">
<result name="success">/WEB-INF/pages/configure.jsp</result>
</action>
VMware, Inc. 199
vCenter Orchestrator Developer's Guide
5 Copy all of the required JAR files in a directory named lib
in the Web application directory.
You must include the JAR files that contain the implementations of the configuration adapter and actions, and JAR files for any other technologies that configuration implementation uses.
6 Create a Web application archive to contain the Web application files.
A WAR file is a JAR file that you rename to .war
.
In the solar system example, the configuration Web application files are stored in WAR file named solarsystem.war
.
You created a Struts-based Web application that contains all of the Web application files and the Java implementations of the configuration adapter and action.
What to do next
Map the application and the plug-in implementation to Orchestrator objects in the vso.xml
file.
Contents of the Solar System Configuration WAR File
You add a configuration tab to the Orchestrator configuration interface by creating a Web application archive
(WAR) file that contains the implementations of the configuration adapter and configuration actions, the layout of the tab, and the Struts configuration files.
The DAR file of the solar system plug-in contains a built WAR file for the solar system configuration tab. You can also examine the files of the solar system configuration Web application in the bundle of source files of the solar system plug-in.
The solar system DAR file contains a WAR file named solarsystem.war
.
If you modify the source files of the solar system configuration WAR file, you must rebuild the DAR file of the solar system plug-in by using the Ant build tool. Rebuilding the plug-in DAR file rebuilds the WAR file of the
solar system configuration tab. See “Build the Solar System Application and Plug-In,” on page 210.
Table 7-6. Contents of the Solar System Configuration WAR File
Directory Filename
\Plug-Ins\VSOSDK-
SolarSystem\src\ solarsystem\ solarsystem\WEB-INF\ struts.xml
index.jsp
web.xml
Description
Struts framework configuration file that references the Java classes and methods of the configuration actions. The struts.xml
is located in the source files of the solar system plug-in rather than in the WAR file.
JSP file that defines the layout of the configuration tab for the plug-in.
Sets up the configuration tab by implementing the appropriate XML schemas, locating the index page, accessing resource files, and implementing security.
200 VMware, Inc.
Chapter 7 Developing Plug-Ins
Table 7-6. Contents of the Solar System Configuration WAR File (Continued)
Directory solarsystem\WEB-INF\lib\ solarsystem\WEB-INF\pages\
Filename n n n n n n n n jaxb-api.jar
jaxb-impl.jar
jsr173_api.jar
vmware-solarsystem.jar
vmware-vmo-model.jar
vmware-vmo-sdkapi.jar
vmware-vmosdkwebsolarsystem.jar
vmware-vmo-util.jar
configure.jsp
Description
JAR files that contain the binaries of the solar system plug-in implementation, the solar system application, the
Orchestrator APIs, and other required applications.
JSP file that adds buttons and a dropdown list to the configuration tab. The buttons and list implement the configuration actions that the
SolarSystemConfigureAction class defines and that struts.xml maps to the Struts framework.
Map the Application in the vso.xml File
The vso.xml
file defines how Orchestrator accesses and interacts with the plugged-in technology. The vso.xml
file maps objects and operations in the plugged-in technology and in the plug-in implementation to
Orchestrator objects and operations.
You can use the objects and operations that you map to create Orchestrator workflows, policies, and actions to interact with the plugged-in technology by using Orchestrator.
You find the vso.xml
file for the solar system example in the following location in the solar system source files in the Orchestrator examples bundle:
VSOSDK-SolarSystem\context\VSO-INF\
For full descriptions of all of the elements of a vso.xml
file and all of their attributes, see
“Elements of the vso.xml Plug-In Definition File,” on page 230.
Prerequisites n n n
You have an application to plug in to Orchestrator.
Implement the plug-in adapter and factory interfaces.
Implement the configuration adapter interface and create the configuration Web application.
Procedure
1
Set Up the Global Plug-In Information on page 202
To create a plug-in, you must point Orchestrator to the relevant XML schema definition and the source files for the application and plug-in. You must also define the behavior of the plug-in when Orchestrator starts and provide a root object for the hierarchy of objects that the plug-in exposes.
2
Map Objects in the Plugged-In Technology to Scripting Types and Inventory Objects on page 203
To allow Orchestrator to access objects in a plugged-in application, you must define how and where the plug-in finds those objects.
VMware, Inc. 201
vCenter Orchestrator Developer's Guide
3
Define Enumerations on page 206
You can define enumerations in the vso.xml
file to set global values that apply to all objects of a certain category.
4
Map Classes and Methods to Classes and Methods in the JavaScript API on page 206
Orchestrator monitors objects in the plugged-in application and performs operations on them by running workflows, policies, and actions. You map in the vso.xml
file the classes and methods from the pluggedin technology and from the plug-in implementation to JavaScript classes and methods in the Orchestrator
JavaScript API.
Set Up the Global Plug-In Information
To create a plug-in, you must point Orchestrator to the relevant XML schema definition and the source files for the application and plug-in. You must also define the behavior of the plug-in when Orchestrator starts and provide a root object for the hierarchy of objects that the plug-in exposes.
Procedure
1 Create a file named vso.xml
.
2 Set up the
<module>
element to provide basic information about the plug-in, including a pointer to the
Orchestrator plug-in XML schema definition.
The <module> element in the vso.xml
file for the solar system example sets the plug-in name to
SolarSystem , sets the version number, and provides the path in the DAR archive to the icon that represents this plug-in in the Orchestrator Inventory view and selection dialog boxes.
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.vmware.com/support/orchestrator/plugin-4-0.xsd"
name="SolarSystem" version="1.0.0" build-number="4" image="images/solarSystem-16x16.png">
3 Provide a description of the plug-in in the <description> element.
The following example shows a <description> element for the solar system.
<description>Example plug-in to a solar system application.</description>
4 Add a tab for the plug-in to the configuration interface by referencing the configuration adapter in the
<configuration> element.
The <configuration> element in the vso.xml
file for the solar system example identifies an icon for the solar system plug-in tab in the file structure of the DAR file, references the configuration adapter implementation, and activates validation of the information that the user provides.
<configuration
icon="images/solarSystem_32x32.png"
adaptor-class=
"com.vmware.orchestrator.api.sample.solarsystem.config.SolarSystemConfigurationAdaptor"
configuration-war="o11nplugin-solarsystem-config.war"
validation="enabled" />
202 VMware, Inc.
Chapter 7 Developing Plug-Ins
5 Set the
<installation>
and
<action>
elements to define the behavior of the plug-in when the Orchestrator server starts.
The solar system example sets the version mode to restart the plug-in whenever a new version is detected, and provides the path to a package of Orchestrator workflows, policies, and a Web view in the file structure of the DAR file. Orchestrator installs this package when the plug-in starts.
<installation mode="version">
<action type="install-package" resource="packages/com.vmware.solarsystem.package" />
</installation>
6 Set the root of the hierarchy of object types in the <inventory> element.
The solar system plug-in defines the root of the hierarchy that represents the plug-in in the Orchestrator scripting API as an object of the type
Galaxy
. All of the other solar system objects relate to the
Galaxy
object.
<inventory type="Galaxy"/>
You set up the elements that identify the plug-in to Orchestrator, added a tab to the configuration interface, defined the start-up behavior, and defined the root scripting object type for the objects in the plug-in.
What to do next
Define the types of objects that Orchestrator finds through the plug-in by mapping the finder objects that the plug-in factory implementation defines to <finder> elements in the vso.xml
file.
Map Objects in the Plugged-In Technology to Scripting Types and Inventory Objects
To allow Orchestrator to access objects in a plugged-in application, you must define how and where the plugin finds those objects.
The objects you map in the vso.xml
file appear as scripting types in the Orchestrator JavaScript API. Instances of these objects appear in the Orchestrator inventory.
Prerequisites
You must have created the vso.xml
file, defined how Orchestrator identifies the plug-in, and referenced the configuration adapter.
VMware, Inc. 203
vCenter Orchestrator Developer's Guide
Procedure
1 Set the data sources for the plug-in
<finder>
elements in the
<finder-datasources>
element.
The plug-in adapter implementation is the point of access to all the classes of the plug-in.
The solar system plug-in vso.xml
file sets the name of the data source to solar-datasource and points the
<finder> elements to the SolarSystemAdapter class that instantiates the SolarSystemFactory and the other classes of the plug-in.
<finder-datasources>
<finder-datasource name="solar-datasource"
adaptor-class=
"com.vmware.orchestrator.api.sample.solarsystem.SolarSystemAdapter"
anonymous-login-mode="internal"/>
</finder-datasources>
2 Define how the plug-in finds objects in the plugged-in technology in
<finder>
elements.
The following extract from the solar system vso.xml
file shows the <finder> element for objects of the type
Star .
<finders>
<finder type="Star" datasource="solar-datasource"
java-class="com.vmware.solarsystem.Star"
script-object="Star" image="images/sun_16x16.png">
[...]
</finder>
[...]
</finders>
The <finder> element for Star objects obtains their data from the data source that the <finderdatasource> element defines. The Star finder type represents instances of the com.vmware.solarsystem.Star
class in the Orchestrator inventory. The finder element for Star objects defines a Star scripting type that appears in the Orchestrator JavaScript API.
3 Obtain the identifier of the object in the <id> element.
The solar system example obtains the identifier of the object by calling the getId() method that the solar system application's CelestialBody class defines.
<id accessor="getId()" />
4 Define the object's relations in the
<relations>
element.
The solar system example defines a relation named OrbitingPlanets to relate objects of the type Planet to the Star object that this <finder> element finds.
<relations>
<relation type="Planet" name="OrbitingPlanets"/>
</relations>
5 Set the hierarchy of objects in the Orchestrator inventory tab according to their relation to the parent.
The solar system example places all objects related to
Star
objects type by the
OrbitingPlanets
relation immediately beneath the star in the inventory hierarchy.
<inventory-children>
<relation-link name="OrbitingPlanets"></relation-link>
</inventory-children>
204 VMware, Inc.
Chapter 7 Developing Plug-Ins
6 Set the object's properties in the
<properties>
element.
The solar system example defines name , circumference , and surfaceTemp properties for all Star objects.
The bean-property property allows Orchestrator to create get and set methods in the scripting API to obtain and set these properties.
<properties>
<property display-name="Name" name="name"
bean-property="name"/>
<property display-name="Circumference" name="circumference"
bean-property="circumference"/>
<property display-name="Surface Temperature" name="surfaceTemp"
bean-property="surfaceTemp"/>
</properties>
7 Set the events that can occur on the object in the
<events>
element.
Events can be either gauges or triggers.
In the solar system example, the SolarSystemEventGenerator class defines a generateFlareEvent() method to generate solar flares on Star objects. The <gauge> element monitors the values of the flare events that occur on Star objects.
<events>
<gauge min-value="0" name="Flare" unit="number">
<description>Magnitude of the flare</description>
</gauge>
</events>
You defined a <finder> element to find objects of a certain type in the plugged-in application. The objects that the finder finds appear as scripting types in the Orchestrator JavaScript API and instances of these types appear in the Orchestrator inventory.
What to do next
Define enumerations to set values that apply to all objects of a certain type.
Solar System Finder Mappings
The vso.xml
file for the solar system example maps objects from the solar system application to objects that appear as scripting types in the Orchestrator JavaScript API. Instances of these objects appear in the
Orchestrator inventory.
Table 7-7 lists the mappings that the
vso.xml
file defines for each type of object that the solar system application defines.
Table 7-7. Solar System Finder Mappings
Scripting
Type
Galaxy
Star
Source Class Inventory Children
None Stars
Star , defined by application OrbitingPlanets
Planet
Moon
Planet , defined by application
OrbitingMoons
Moon , defined by application None n n n n n
Properties n n n
None name circumference surfaceTemp name circumference gravity name volume
Events
None
Flare
None
None
VMware, Inc. 205
vCenter Orchestrator Developer's Guide
Define Enumerations
You can define enumerations in the vso.xml
file to set global values that apply to all objects of a certain category.
The categories that you set in the vso.xml
file appear as enumerations in the Orchestrator JavaScript API.
Prerequisites
You must have set up the plug-in and defined <finder> elements in the vso.xml
file.
Procedure
1 Define an enumeration for a certain object type in the <enumerations> element.
The solar system example defines enumerations to set a PlanetCategory enumeration on Planet objects.
<enumerations>
<enumeration type="PlanetCategory">
<description>Define the category of a Planet</description>
[...]
</enumeration>
2 Define entries for the enumerations that apply values to objects in the given object category.
The solar system example defines values that represent different types of planet.
<entries>
<entry id="gaz"
name="Huge Gaz">Huge planet with only gaz atmosphere.
No Physical core.</entry>
<entry id="earth"
name="Earth">You could live on this planet.</entry>
<entry id="desert"
name="Desert">Planet without water.</entry>
<entry id="ice"
name="Ice">Planet with water but completely frozen.</entry>
<entry id="other"
name="Other">Does not fit into any category.</entry>
</entries>
The vso.xml
file of the solar system example also defines a
StarCategory
enumeration that allows you to define a Star object as a blue dwarf, a nova, or a yellow sun.
You defined enumerations that can apply to all objects in a certain category.
What to do next
Map the classes and methods of the plugged-in technology and the plug-in implementation to JavaScript classes and methods in the Orchestrator JavaScript API.
Map Classes and Methods to Classes and Methods in the JavaScript API
Orchestrator monitors objects in the plugged-in application and performs operations on them by running workflows, policies, and actions. You map in the vso.xml
file the classes and methods from the plugged-in technology and from the plug-in implementation to JavaScript classes and methods in the Orchestrator
JavaScript API.
You identify in
<scripting-objects><object>
elements the classes and methods to map to classes and methods in the JavaScript API.
206 VMware, Inc.
Chapter 7 Developing Plug-Ins
Prerequisites
You must have set up the plug-in, and defined
<finder>
elements and enumerations.
Procedure
1 Map a Java class from the plugged-in technology or from the plug-in implementation to a JavaScript class.
The SolarSystemEventGenerator class defines the events that Orchestrator can invoke in the solar system application. The solar system vso.xml
file maps the event generator class to a JavaScript class named
_SolarSystemEventGenerator . By setting the strict attribute to true , Orchestrator can only call the methods from the SolarSystemEventGenerator class that are mapped in the vso.xml
file. To allow scripting to instantiate a class you use the create
attribute.
<scripting-objects>
<object script-name="_SolarSystemEventGenerator"
java-class="com.vmware.orchestrator.api.sample.solarsystem.SolarSystemEventGenerator"
strict="true">
<description>The entry point to generate events</description>
[...]
</object>
[...]
</scripting-objects>
2 (Optional) If necessary, denote the JavaScript object as a singleton object.
In the solar system example, SolarSystemEventGenerator is a singleton object. The plug-in adaptor can only create a single instance of the SolarSystemEventGenerator class. You can only call the methods of the
SolarSystemEventGenerator
JavaScript object and cannot instantiate the class in Orchestrator scripts.
<singleton script-name="SolarSystemEventGenerator"
datasource="solar-datasource"/>
VMware, Inc. 207
vCenter Orchestrator Developer's Guide
3 Map the methods in the Java class to methods in the Orchestrator JavaScript API in the
<object><methods>
element.
The SolarSystemEventGenerator class defines a generateFlareEvent() method to generate solar flare events. The solar system vso.xml
maps this method to a JavaScript method of the same name, and sets its parameters in the JavaScript method.
<methods>
<method script-name="generateFlareEvent" java-name="generateFlareEvent">
<description>Start a Solar Flare</description>
<parameters>
<parameter name="star" type="Star">The star which generates the event</parameter>
<parameter name="magnitude" type="number">The magnitude of the flare</parameter>
</parameters>
</method>
</methods>
4 Map the attributes of a Java class to JavaScript attributes in
<object><attributes>
elements.
The solar system vso.xml
file maps the Java attributes of the Star object to attributes of the same name in the Star JavaScript class in the Orchestrator JavaScript API.
<object script-name="Star" java-class="com.vmware.solarsystem.Star"
create="false" strict="true">
[...]
<attributes>
<attribute script-name="id" java-name="id" return-type="string">
The unique Id of the star</attribute>
<attribute script-name="name" java-name="name" return-type="string">
The name of the star</attribute>
<attribute script-name="circumference" java-name="circumference" return-type="number">
Circumference of the star</attribute>
<attribute script-name="temperature" java-name="surfaceTemp" return-type="number">
The temperature on the star's surface</attribute>
</attributes>
[...]
</object>
You mapped classes and their methods and attributes from the classes in the plugged-in technology and plugin implementation to a JavaScript class and methods in the Orchestrator JavaScript API.
What to do next
Create or rebuild the DAR file for the plug-in.
Solar System JavaScript API Mappings
The vso.xml
file for the solar system example maps objects, classes, methods, and attributes from the solar system application to scripting types, classes, methods, and attributes in the Orchestrator JavaScript API.
that the vso.xml
file maps to the Orchestrator JavaScript API.
Table 7-8. Solar System JavaScript API Mappings
Scripting Class Source Class
SolarSystemEventGenerator SolarSystemEventGenerator , defined by plug-in
SolarSystemTriggerGenerat or
SolarSystemTriggerGenerator , defined by plug-in
Attributes
None
None
Methods generateFlareEvent( st ar, magnitude) createStarFlareTrigger
( star, minMagnitude)
208 VMware, Inc.
Chapter 7 Developing Plug-Ins
Table 7-8. Solar System JavaScript API Mappings (Continued)
Scripting Class
Star
Source Class
Star , defined by application
Planet
Moon
Planet , defined by application
Moon , defined by application n n n n n n n n n n n n
Attributes n id name circumferen ce temperature id name circumferen ce gravity starId id name volume planetId n n
Methods addPlanet(planet) removePlanet(planet
) n n addMoon(moon) removeMoon(moon)
None
Create the Plug-In DAR Archive
The final stage in the creation of a plug-in is to create the DAR archive that you import to Orchestrator.
The DAR archive is a standard ZIP file that you rename to .dar
. The DAR archive contains all of the elements of the plug-in implementation and must adhere to a standard file and folder structure.
N
OTE
The source files of the solar system example application and solar system plug-in are provided for reference purposes, so that you can see the details of the application that the solar system plug-in exposes and of the plug-in implementation. If you import the ready-made vmware-vmosdk-solarsystem.dar
file to
Orchestrator, you do not need to build solar system application code or build the plug-in from the sources.
However, if you adapt the code of the solar system application or the solar system plug-in, you can rebuild
Prerequisites n n n
Implement the plug-in adapter and factory interfaces.
Implement the configuration adapter interface and create the configuration Web application.
Map the application to Orchestrator objects in the vso.xml
file.
Procedure
1 Create a working directory in which to create the DAR archive.
For example, create a directory named plugin_name.
2 Create a directory named VSO-INF at the root of the working directory.
3 Copy the vso.xml
file to
VSO-INF
.
4 Create a directory named lib at the root of the working directory.
5 Add the JAR files containing the classes of the application to plug in and the classes of the plug-in adapter and factory implementations to lib .
6 (Optional) Create a directory named webapps
at the root of the working directory.
The webapps contains the WAR file of the configuration tab Web application.
VMware, Inc. 209
vCenter Orchestrator Developer's Guide
7 Create a directory named resources
at the root of the working directory.
8 (Optional) Create a directory named images in the resources directory.
The resources\images directory can contain icons to represent the different objects of the plugged-in application in the Orchestrator Inventory view and selection dialog boxes.
9 (Optional) Create a directory named packages
in the resources
directory.
The resources\packages directory can contain packages of workflows, actions, policies, Web views, and so on, that interact with the plugged-in application.
10 Create a ZIP archive that contains all of the preceding directories and files.
11 Rename the ZIP archive to plugin_name.dar
.
You created the DAR archive that contains a plug-in, and imported it to Orchestrator.
What to do next
You can access the objects of the plugged-in application in the Orchestrator inventory to perform operations on them. You can also use the objects and methods that you mapped to the Orchestrator scripting API to create workflows, actions, policies, Web views, and so on, to interact with the objects through the plug-in.
Build the Solar System Application and Plug-In
If you adapt the solar system application or the solar system plug-in, you can rebuild the DAR file by using the Apache Ant building tool.
The Orchestrator examples bundle contains the scripts and build.xml
file that allow you to rebuild the solar system DAR file and the JAR files that it contains. If you add new files to the solar system plug-in, you must update the build.xml
file.
N
OTE
If you did not adapt the solar system application or plug-in, you do not need to build the solar system
DAR file. You can install the ready-made DAR file directly.
Prerequisites
You must have Apache Ant 1.7.1 or later installed and configured on your system.
Procedure
1 Navigate to the folder that contains the solar system application and plug-in.
install-directory\vco-samples_4_0_1_build_number\Plug-Ins\SolarSystem\
2 Open a terminal window and navigate to the install-directory\vco-samples_4_0_1_build_number\Plug-
Ins\SolarSystem\ folder.
3 Type the ant command in the terminal window.
You rebuilt the solar system DAR file to incorporate any modifications that you made to the application or to the plug-in.
What to do next
Install the solar system DAR file in the Orchestrator server.
210 VMware, Inc.
Chapter 7 Developing Plug-Ins
Contents of the Solar System DAR File
The DAR file is a ZIP file that you rename to DAR. You can unzip the solar system DAR file to view the contents and file structure of the solar system plug-in.
The solar system example vmware-vmosdk-solarsystem.dar
file contains the following directories and files.
n \lib , that contains the following JAR archives: n vmware-solarsystem.jar
, that contains the classes of the solar system application.
n vmware-vmosdk-solarsystem.jar
, that contains the classes of the plug-in adapter and factory implementations for the solar system application.
n \resources , that contains the following directories: n \images
, that contains icons that represent the different objects of the solar system application on the
Orchestrator Inventory tab.
n \packages , that contains an Orchestrator package named com.vmware.solarsystem.package
. The package contains workflows, policies, actions, and the Web view that allow Orchestrator to interact with the solar system application.
n \VSO-INF\vso.xml
, the XML file that maps the solar system application to Orchestrator objects.
n \webapps
, that contains the solarsystem.war
file for the Web application of the solar system configuration tab.
n \web-content , that contains the files of the solar system Web view.
Install a Plug-In in the Orchestrator Server
After you create the plug-in DAR file, you must install it in the Orchestrator server. You install plug-ins in the
Orchestrator configuration interface.
Prerequisites
You have a completed DAR file for a plug-in.
Procedure
1 Open the Orchestrator configuration interface in a Web browser and log in.
http:// orchestrator_server_DNS_name_or_IP_address:8282
2 Click Plug-ins.
3 Type the credentials for a user who is a member of the Orchestrator Administration group.
When the Orchestrator server starts, the system uses these credentials to set up the plug-ins. The system checks the enabled plug-ins and performs any necessary internal installations such as package import, policy run, script launch, and so on.
4 Click the magnifying glass icon and select the DAR file to install.
5 Click Open.
6 Click Upload and install.
The installed plug-in file is stored in the install_directory\app-server\server\vmo\plugins folder.
7 Click Apply changes.
Depending on the plug-in, the configuration server might restart.
VMware, Inc. 211
vCenter Orchestrator Developer's Guide
8 (Optional) If the plug-in adds a configuration tab to the configuration interface, click the tab for the plugin.
For example, if you install the solar system plug-in, click Solar System.
9 (Optional) Configure the plug-in in its configuration tab.
For example, if you install the solar system plug-in, select your home planet and select whether Pluto is a planet or a dwarf planet.
10 Click Apply changes.
11 Restart the Orchestrator server.
You installed and configured a plug-in.
What to do next
Use Orchestrator to interact with the plugged-in technology.
Interact with the Solar System Application by Using Orchestrator
After you install a plug-in in the Orchestrator server, you can use the objects that it adds to the Orchestrator
JavaScript API to create workflows, actions, policies, Web views, and so on. You use these items to interact with the plugged-in technology using Orchestrator.
The solar system plug-in includes the com.vmware.samples.solarsystem
package that contains workflows, actions, a policy, and a Web view that implement the API objects that the solar system plug-in adds to the
Orchestrator JavaScript API.
Procedure
1
View Plug-In Scripting Objects in the JavaScript API on page 212
The objects of a plugged-in technology that you map to Orchestrator scripting objects appear in the
Orchestrator JavaScript API.
2
Run Workflows on Plug-In Objects in the Inventory on page 213
You can use the scripting objects that a plug-in adds to the Orchestrator JavaScript API to write workflows and actions to interact with the plugged-in technology.
3
Monitor Plug-In Events by Using Policies on page 214
You can use policies to monitor events in a plugged-in technology and perform defined operations when the events occur.
4
Monitor Plug-In Events by Using Workflows on page 215
Workflows can include a Wait Event element that suspends the workflow and waits for an event to occur in a plugged-in technology. Plug-ins can implement triggers and watchers to notify waiting workflows of the events that occur.
5
Access Plug-In Objects and Operations by Using a Web View on page 216
With Web views, you can run workflows on objects from the Orchestrator inventory from a Web browser instead of from the Orchestrator client.
View Plug-In Scripting Objects in the JavaScript API
The objects of a plugged-in technology that you map to Orchestrator scripting objects appear in the
Orchestrator JavaScript API.
The solar system vso.xml
file maps objects from the solar system application and plug-in to classes, methods, attributes, and enumerations in the Orchestrator JavaScript API.
212 VMware, Inc.
Chapter 7 Developing Plug-Ins
Prerequisites n n
Install the solar system plug-in in the Orchestrator server.
Start the Orchestrator client.
Procedure
1 Select Tools > Api explorer in the Orchestrator menus.
2 Expand the SolarSystem node in the hierarchical list of scripting objects.
You see the scripting types for the different types of celestial bodies, scripting classes for the Star ,
Planet , Moon , SolarSystemEventGenerator , and SolarSystemTriggersManager objects, and enumerations to define categories of stars and planets.
3 Expand a scripting class in the hierarchical list to see the scripting methods and attributes that it defines.
The scripting methods and attributes are those that the vso.xml
file maps for each object.
You can use the scripting objects from the plug-in to create workflows, actions, policies, and so on.
What to do next
Run a workflow on a solar system object in the Inventory tab.
Run Workflows on Plug-In Objects in the Inventory
You can use the scripting objects that a plug-in adds to the Orchestrator JavaScript API to write workflows and actions to interact with the plugged-in technology.
The solar system plug-in includes a package of workflows that you can use to perform operations on the objects that the plug-in adds to the Orchestrator inventory.
Prerequisites n n
Install the solar system plug-in in the Orchestrator server.
Start the Orchestrator client.
Procedure
1 Click Workflows in the Orchestrator client.
2 Expand the Samples > SolarSystem nodes in the hierarchical list of workflows to see the list of workflows that the solar system plug-in adds to the library.
3 Click the Add Planet workflow.
4 Click the Schema tab and click the scripted element in the schema.
5 Click the Scripting tab for the scripted element.
You see that Add Planet workflow calls the Star.addPlanet() method from the solar system application.
6 Click Inventory.
7 Expand the SolarSystem node in the hierarchical list of plug-ins and select the Helios star object.
You see objects that represent the planets of Earth's solar system. The planets are the instances of the
Planet object that the SolarSystemRepository class from the solar system application creates.
8 Expand a planet node to see its moons.
The vso.xml
file defines the hierarchy of planets to stars and moons to planets by setting the
OrbitingPlanets and OrbitingMoons relations.
VMware, Inc. 213
vCenter Orchestrator Developer's Guide
9 Click the sun, a planet, or a moon to display its properties on the right.
10 Right-click the sun, a planet, or a moon to and select Execute operation to run a workflow on that object.
You can select a workflow to run from a contextual list of workflows that take that type of object as an input parameter.
You can run workflows on the solar system objects in the inventory. You can add a planet to the sun's orbit or generate or wait for a solar flare. You can modify the circumference of planets or split or destroy them.
What to do next
Monitor events in the solar system application by setting a policy.
Monitor Plug-In Events by Using Policies
You can use policies to monitor events in a plugged-in technology and perform defined operations when the events occur.
The solar system plug-in includes a policy that monitors a star object for solar flares. When flares occur, the policy records the magnitude of the flares in the logs.
Prerequisites n n
Install the solar system plug-in in the Orchestrator server.
Start the Orchestrator client.
Procedure
1 Click Policy Templates in the Orchestrator client.
2 Expand the Samples > SolarSystem nodes in the hierarchical list of policies.
3 Right-click the Star policy and select Apply Policy.
4 Add a policy description and select a
Star
object on which to apply the policy in the Apply Policy dialog box and click Submit.
The Star policy opens in the Policies tab.
5 Click the Star policy and open the Scripting tab.
In the scripting tab you see that the policy is monitoring a threshold named Flare .
6 Right-click the Star policy and select Start policy.
7 Click the Inventory tab.
8 Right-click the Helios star and select Execute operation.
9 Run the Generate Flare Event workflow, setting the magnitude of the flare to 100 .
The Generate Flare Event workflow includes a script that calls the
SolarSystemEventGenerator.generateFlareEvent() method. The gauge that the
SolarSystemEventGenerator class implements pushes an event object named Flare to the Orchestrator policy engine.
10 Click the Policies tab.
11 Click the Star policy.
12 Click the Logs tab.
The policy has recorded the magnitude of the solar flare event in the logs.
214 VMware, Inc.
Chapter 7 Developing Plug-Ins
The
Star
policy implements the solar system scripting API to monitor star objects for solar flare events and records their magnitude. The policy keeps on running until you stop it. If you run the Generate Flare Event again, the policy continues to record the magnitudes of the flares in the logs.
What to do next
Monitor events on objects in the plugged-in technology by running workflows.
Monitor Plug-In Events by Using Workflows
Workflows can include a Wait Event element that suspends the workflow and waits for an event to occur in a plugged-in technology. Plug-ins can implement triggers and watchers to notify waiting workflows of the events that occur.
The solar system example includes a workflow that implements a Wait Event element to wait for solar flares.
When a flare occurs, the waiting workflow resumes its run, records the magnitude of the flare in the logs, then ends.
Prerequisites n n
Install the solar system plug-in in the Orchestrator server.
Start the Orchestrator client.
Procedure
1 Click Workflows in the Orchestrator client.
2 Expand the Samples > SolarSystem nodes in the hierarchical list of workflows to see the list of workflows that the solar system plug-in adds to the library.
3 Right-click the Wait On Flare Event workflow, select Execute workflow, and click Submit.
The Wait On Flare Event workflow calls the SolarSystemTriggerGenerator.createStarFlareTrigger() method to create an event trigger.
4 Click the workflow token for this run of the Wait On Flare Event workflow.
In the workflow schema, you can see that the workflow has suspended its run at the Waiting Event element. In the Logs tab you can see that the workflow is waiting for a flare of at least magnitude 10.
5 Click Inventory.
6 Expand the SolarSystem node in the hierarchical list of plug-ins.
7 Right-click Helios and select Execute operation > Generate Flare Event.
Set the magnitude of the flare to a value greater than 10 when you run the workflow.
8 Click Workflows.
9 Click the workflow token for Wait On Flare Event workflow.
The workflow is no longer waiting and has ended its run. In the Logs tab for this token you can see that the workflow has recorded a flare of at least magnitude 10.
The Wait On Flare Event workflow implements the solar system scripting API to create a plug-in trigger that waits for solar flares of a given magnitude. When a flare event occurs, the workflow ends, but you can create a loop in the workflow to record the event and wait for the next event.
What to do next
Access the solar system objects and workflows by using the solar system Web view.
VMware, Inc. 215
vCenter Orchestrator Developer's Guide
Access Plug-In Objects and Operations by Using a Web View
With Web views, you can run workflows on objects from the Orchestrator inventory from a Web browser instead of from the Orchestrator client.
The solar system example includes a Web view that you can use to access the objects and workflows of the solar system plug-in from a Web browser.
Prerequisites n n
Install the solar system plug-in in the Orchestrator server.
Start the Orchestrator client.
Procedure
1 Click Web views in the Orchestrator client.
2 Right-click the SolarSystem Web view and select Publish.
3 Open a browser and go to http:// orchestrator_server:8280 .
In the URL, orchestrator_server is the DNS name or IP address of the Orchestrator server, and 8280 is the default port number where Orchestrator publishes Web views.
4 On the Orchestrator home page, click Web View List.
5 Click Solar System.
6 Log in using your Orchestrator user name and password.
7 Click the buttons in the Web view to run workflows on the objects in the solar system application.
You can run workflows to add a planet to the Sun, modify, split, or remove planets from a Web browser. You can examine the structure and files of the solar system Web view in the source files of the solar system plugin or exporting the Web view to a directory in Web views in the Orchestrator client.
What to do next
You can adapt the classes of the solar system application and the plug-in implementation to experiment with plug-in development. You can use the solar system scripting API to develop more workflows that perform operations in the solar system application.
Orchestrator Plug-In API Reference
The Orchestrator plug-in API defines Java interfaces and classes to implement and extend when you develop the IPluginAdaptor and IPluginFactory implementations to create a plug-in.
All classes are contained in the ch.dunes.vso.sdk.api
package, unless stated otherwise.
IAop Interface
The
IAop
interface provides methods to obtain and set properties on objects in the plugged-in technology.
public interface IAop
The IAop interface defines the following methods:
216 VMware, Inc.
Chapter 7 Developing Plug-Ins
Method get(java.lang.String propertyName, java.lang.Object object, java.lang.Object sdkObject) set(java.lang.String propertyName, java.lang.String propertyValue, java.lang.Object object)
Returns Description java.lang.Object
Obtains a property from a given object in the plugin.
Void Sets a property on a given object in the plug-in.
IConfigurationAdaptor Interface
The IConfigurationAdaptor interface allows you to add a tab in the Orchestrator configuration interface. You can use the tab to configure a plug-in.
You can extend the IConfigurationAdaptor interface to pass to the plug-in configuration information that is specific to your environment. The
SDKHelper
class defines further methods to pass configuration information from the configuration interface to the Orchestrator server.
The IConfigurationAdaptor interface is contained in the ch.dunes.vso.sdk.conf
package.
The IConfigurationAdaptor interface defines the following methods.
Method loadConfiguration(java.io.InputStream
stream) saveConfiguration(java.io.OutputStream
stream) setPluginName(java.lang.String name) validateConfiguration()
Returns Description
Void Loads or reloads the configuration. If the stream property is null, the plug-in loads its default configuration.
Returns java.io.IOException if it encounters an error.
Void Saves the configuration details. If the stream property is null, the plug-in saves the configuration details in the default location when you click Apply Changes in the configuration interface.
Returns java.io.IOException if it encounters an error.
Void Sets the plug-in name as it appears in the plug-in tab in the configuration interface.
ConfigurationError[] Validates the configuration if validation="enabled" is set.
IDynamicFinder Interface
The IDynamicFinder interface returns the ID and properties of a finder programmatically, instead defining the
ID and properties in the vso.xml
file.
The IDynamicFinder Interface defines the following methods.
Method getIdAccessor(java.lang.String
type) getProperties(java.lang.String
type)
Returns Description java.lang.String
Provides an OGNL expression to obtain an object ID programmatically.
java.util.List<SDKFinderProperty> Provides a list of object properties programmatically.
VMware, Inc. 217
vCenter Orchestrator Developer's Guide
IPluginAdaptor Interface
You implement the
IPluginAdaptor
interface to manage plug-in factories, events and watchers. The
IPluginAdaptor interface defines an adapter between a plug-in and the Orchestrator server.
IPluginAdaptor instances are resonsible for session management. The IPluginAdaptor Interface defines the following methods.
Method addWatcher(PluginWatcher watcher) createPluginFactory(java.lang.String
sessionID, java.lang.String username, java.lang.String password,
IPluginNotificationHandler notificationHandler) installLicenses(PluginLicense[] licenses) registerEventPublisher(java.lang.String
type, java.lang.String id,
IPluginEventPublisher publisher) removeWatcher(java.lang.String watcherId) setPluginName(java.lang.String pluginName) setPluginPublisher(IPluginPublisher pluginPublisher) uninstallPluginFactory(IPluginFactory plugin) unregisterEventPublisher(java.lang.String
type, java.lang.String id,
IPluginEventPublisher publisher)
Returns Description
Void
IPluginFactory Creates an IPluginFactory instance. The
Orchestrator server uses the factory to obtain objects from the plugged-in technology by their ID, by their relation to other objects, and so on.
The session ID allows you to identify a running session. For example, a user could log into two different Orchestrator clients and run two sessions simultaneously.
Similarly, starting a workflow creates a session that is independent from the client in which the workflow started. A workflow continues to run even if you close the
Orchestrator client.
Void Installs the license information for standard plug-ins that VMware provides
Void
Adds a watcher to monitor for a specific event
Sets triggers and gauges on an element in the inventory
Void
Void
Void
Void
Void
Removes a watcher
Gets the plug-in name from the vso.xml file
Sets the publisher of the plug-in
Uninstalls a plug-in factory.
Removes triggers and gauges from an element in the inventory
IPluginEventPublisher Interface
The IPluginEventPublisher interface publishes gauges and triggers on an event notification bus for
Orchestrator policies to monitor.
You can create IPluginEventPublisher instances directly in the plug-in adaptor implementation or you can create them in separate event generator classes.
You can implement the IPluginEventPublisher interface to publish events in the plugged-in technology to the
Orchestrator policy engine. You create methods to set policy triggers and gauges on objects in the plugged-in technology and event listeners to listen for events on those objects.
218 VMware, Inc.
Chapter 7 Developing Plug-Ins
Policies can implement either gauges or triggers to monitor objects in the plugged-in technology. Policy gauges monitor the attributes of objects and push an event in the Orchestrator server if the values of the objects exceed certain limits. Policy triggers monitor objects and push an event in the Orchestrator server if a defined event occurs on the object. You register policy gauges and triggers with
IPluginEventPublisher
instances so that
Orchestrator policies can monitor them.
The IPluginEventPublisher Interface defines the following methods.
Type pushGauge(java.lang.String type, java.lang.String id, java.lang.String gaugeName, java.lang.String deviceName, java.lang.Double gaugeValue) pushTrigger(java.lang.String type, java.lang.String id, java.lang.String triggerName, java.util.Properties
additionalProperties)
Returns Description
Void
Void
Publish a gauge for policies to monitor. Takes the following parameters: n n n n n type : Type of the object to monitor.
id : Identifier of the object to monitor.
gaugeName : Name for this gauge.
deviceName : Name for the type of attribute that the gauge monitors.
gaugeValue : Value for which the gauge monitors the object.
Publish a trigger for policies to monitor. Takes the following parameters: n n type : Type of the object to monitor.
id : Identifier of the object to monitor.
n n triggerName : Name for this trigger.
additionalProperties : Any additional properties for the trigger to monitor.
IPluginFactory Interface
The IPluginAdaptor returns IPluginFactory instances. IPluginFactory instances run commands in the plugged-in application, and finds objects upon which to perform Orchestrator operations.
The IPluginFactory interface defines the following field: static final java.lang.String RELATION_CHILDREN
The IPluginFactory interface defines the following methods.
Method executePluginCommand(java.lang.String
cmd) find(java.lang.String type, java.lang.String id) findAll(java.lang.String type, java.lang.String query)
Returns Description
Void Use the plug-in to run a command. VMware recommends that you do not use this method.
java.lang.Object
Use the plug-in to find an object. Identify the object by its ID and type.
QueryResult java.util.List
Use the plug-in to find objects of a certain type and that match a query string. You define the syntax of the query in the
IPluginFactory implementation of the plug-in. If you do not define query syntax, findAll() returns all objects of the specified type.
Determines whether an object has children.
findRelation(java.lang.String
parentType, java.lang.String parentId, java.lang.String relationName) hasChildrenInRelation(java.lang.String
parentType, java.lang.String parentId, java.lang.String relationName)
HasChildrenResult Finds all children related to a given parent by a certain relation.
VMware, Inc. 219
vCenter Orchestrator Developer's Guide
Method invalidate(java.lang.String type, java.lang.String id) void invalidateAll()
Returns
Void
Void
Description
Invalidate objects by type and ID.
Invalidate all objects in the cache.
IPluginNotificationHandler Interface
The IPluginNotificationHandler defines methods to notify Orchestrator of different types of event that occur on the objects Orchestrator accesses through the plug-in.
The IPluginNotificationHandler Interface defines the following methods.
Method getSessionID() notifyElementDeleted(java.lang.String type, java.lang.String id) notifyElementInvalidate(java.lang.String
type, java.lang.String id) notifyElementUpdated(java.lang.String type, java.lang.String id) notifyMessage(ch.dunes.vso.sdk.api.ErrorLevel
severity, java.lang.String type, java.lang.String id, java.lang.String
message)
Returns Description java.lang.String
Returns the current session ID
Void
Void
Notifies the system that an object with the given type and ID has been deleted
Notifies the system that an object's relations have changed. You can use the notifyElementInvalidate() method to notify Orchestrator of all changes in relations between objects, not only for relation changes that invalidate an object. For example, adding a child object to a parent represents a change in the relation between the two objects.
Void
Void
Notifies the system that an object's attributes have been modified
Publishes an error message related to the current module
IPluginPublisher Interface
The
IPluginPublisher
interface publishes a watcher event on an event notification bus for long-running workflow Wait Event elements to monitor.
When a workflow trigger starts an event in the plugged-in technology, a plug-in watcher that watches that trigger and that is registered with an IPluginPublisher instance notifies any waiting workflows that the event has occurred.
The IPluginPublisher Interface defines the following method.
Type pushWatcherEvent(java.lang.String id, java.util.Properties properties)
Value Description
Void Publish a watcher event on event notification bus
WebConfigurationAdaptor Interface
The WebConfigurationAdaptor interface implements IConfigurationAdaptor and defines methods to locate and install a Web application in the configuration tab for a plug-in.
The WebConfigurationAdaptor interface defines the following methods.
220 VMware, Inc.
Chapter 7 Developing Plug-Ins
Method getWebAppContext() setWebConfiguration(boolean webConfiguration)
Returns Description
String Locates the WAR file of the Web application for the configuration tab.
Provide the name and path to the WAR file from the /webapps directory in the DAR file as a string.
Boolean Determine whether the contents of the configuration tab are defined by a Web application.
BaseAction Class
The BaseAction class is a helper class that you can use to create Orchestrator actions.
In the context of creating a plug-in configuration tab, the BaseAction class provides methods that you can implement to set up and run the configuration action that pushes configuration information to the Orchestrator server from the configuration interface.
The BaseAction class is contained in the ch.dunes.vso.configuration.web.commons
package.
The BaseAction class defines the following methods:
Method prepare() Void execute()
Returns Description
Void
Implement this method to instantiate the configuration adapter and load configuration information.
Implement this method to push the configuration information to the configuration server.
ConfigurationError Class
The ConfigurationError class defines the error objects that the
IConfigurationAdaptor.validateConfiguration() method returns the plug-in configuration contains errors.
public class ConfigurationError extends java.lang.Object
implements java.io.Serializable
The ConfigurationError class uses the ConfigurationError.Severity
enumeration and defines the following fields: n public ConfigurationError.Severity severity n public java.lang.String title n public java.lang.String description
Constructor
ConfigurationError(ConfigurationError.Severity severity, java.lang.String title, java.lang.String
description)
Localizator Class
The Localizator class is a helper class that locates and loads classes in the Orchestrator server.
In the context of creating a plug-in configuration tab, the Localizator class creates a classloader to load the classes of the configuration tab implementation to the configuration server and creates a hastable of properties to pass to the classes.
public class Localizator extends java.lang.Object
The Localizator class defines the following methods:
VMware, Inc. 221
vCenter Orchestrator Developer's Guide
Method fillTable(java.util.Hashtable table) getResourceString(java.lang.String key) getResourceString(java.lang.String key, java.lang.Object... args) hasKey(java.lang.String key)
Returns Description
Void Adds property values to a hashtable.
java.lang.String
Obtains a property from the hashtable.
java.lang.String
Obtains a property from the hashtable.
Boolean
Constructor
public Localizator(ClassLoader loader,String resourcePath)
PluginLicense Class
The PluginLicense class obtains and sets any licensing information that a plug-in requires.
public class PluginLicense extends java.lang.Object
implements java.io.Serializable
The PluginLicense class defines the following methods.
Method Returns Description getDescription() getLicenseString() setOwner(java.lang.String owner) java.lang.String
Obtains the license description.
java.lang.String
Obtains the license key.
getOwner() setDescription(java.lang.String description) java.lang.String
Obtains the license owner.
Void Sets the license description.
setLicenseString(java.lang.String licenseString) Void Sets the license key.
Void Obtains the license owner.
Constructor
PluginLicense()
PluginTrigger Class
The PluginTrigger class creates a trigger module that obtains information about objects and events to monitor in the plugged-in technology, on behalf of a Wait Event element in a workflow.
The PluginTrigger class defines methods to obtain or set the type and name of the object to monitor, the nature of the event, and a timeout period.
You create implementations of the PluginTrigger class exclusively for use by Wait Event elements in workflows. You define policy triggers for Orchestrator policies in classes that define events and implement the IPluginEventPublisher.pushTrigger() method.
public class PluginTrigger extends java.lang.Object
implements java.io.Serializable
The PluginTrigger class defines the following methods:
Method getModuleName() getProperties()
Returns Description java.lang.String
Obtains the name of the trigger module.
java.util.Properties
Obtains a list of properties for the trigger.
222 VMware, Inc.
Chapter 7 Developing Plug-Ins
Method getSdkId() getSdkType() getTimeout() setModuleName(java.lang.String
moduleName) setProperties(java.util.Properties
properties) setSdkId(java.lang.String sdkId) setSdkType(java.lang.String sdkType) setTimeout(long timeout)
Returns java.lang.String
java.lang.String
Long
Void
Void
Void
Void
Void
Description
Obtains the ID of the object to monitor in the plugged-in technology.
Obtains the type of the object to monitor in the plugged-in technology.
Obtains the trigger timeout period.
Sets the name of the trigger module.
Sets a list of properties for the trigger.
Sets the ID of the object to monitor in the plugged-in technology.
Sets the type of the object to monitor in the plugged-in technology.
Sets a timeout period in seconds. A negative value deactivates the timeout.
Constructors
n PluginTrigger() n PluginTrigger(java.lang.String moduleName, long timeout, java.lang.String sdkType, java.lang.String sdkId)
PluginWatcher Class
The
PluginWatcher
class watches a trigger module for a defined event in the plugged-in technology on behalf of a long-running workflow Wait Event element.
The PluginWatcher class defines a constructor that you can use to create plug-in watcher instances. The
PluginWatcher class defines methods to obtain or set the name of the workflow trigger to watch and a timeout period.
public class PluginWatcher extends java.lang.Object
implements java.io.Serializable
The
PluginWatcher
class defines the following methods:
Method Returns Description getId() getModuleName() getTimeoutDate() java.lang.String
Obtains the ID of the trigger java.lang.String
Obtains the trigger module name
Long Obtains the trigger timeout date getTrigger() Void setId(java.lang.String id) Void setTimeoutDate() Void
Obtains a trigger
Sets the ID of the trigger
Sets the trigger timeout date
Constructor
PluginWatcher(PluginTrigger trigger)
VMware, Inc. 223
vCenter Orchestrator Developer's Guide
224
QueryResult Class
The
QueryResult
class contains the results of a find
query made on the objects Orchestrator accesses through the plug-in.
public class QueryResult extends java.lang.Object
implements java.io.Serializable
The totalCount value can be greater than the number of elements the QueryResult returns, if the total number of results found exceeds the number of results the query returns. The number of results the query returns is defined in the query syntax in the vso.xml
file.
The
QueryResult
class defines the following methods:
Method Returns Description addElement(java.lang.Object element) Void addElements(java.util.List elements) Void getElements() getTotalCount() isPartialResult() removeElement(java.lang.Object
element)
Adds an element to the QueryResult
Adds a list of elements to the QueryResult java.util.List
Obtains elements from the plugged in application
Long
Boolean
Void
Obtains a count of all the elements available in the plugged in technology
Determines whether the result obtained is complete
Removes an element from the plugged in technology setElements(java.util.List elements) Void setTotalCount(long totalCount) Void
Sets elements in the plugged in technology
Sets the total number of elements available in the plugged in technology
Constructors
n QueryResult() n QueryResult(java.util.List ret) n QueryResult(java.util.List elements, long totalCount)
SDKFinderProperty Class
The SDKFinderProperty class defines methods to obtain and set properties in the objects found in the plugged in technology by the Orchestrator finder objects. The IDynanmicFinder.getProperties
method returns
SDKFinderProperty
objects.
public class SDKFinderProperty extends java.lang.Object
The SDKFinderProperty class defines the following methods:
Method getAttributeName() getBeanProperty() getDescription() getDisplayName() getPossibleResultType()
Returns Description java.lang.String
Obtains an object attribute name java.lang.String
Obtains properties from a Java bean java.lang.String
Obtains an object description java.lang.String
Obtains an object display name java.lang.String
Obtains the possible types of result the finder returns
VMware, Inc.
Chapter 7 Developing Plug-Ins
Method Returns Description getPropertyAccessor() getPropertyAccessorTree() isHidden() isShowInColumn() isShowInDescription() setAttributeName(java.lang.String
attributeName) java.lang.String
Obtains an object property accessor java.lang.Object
Obtains an object property accessor tree
Boolean
Boolean
Shows or hides the object
Shows or hides the object in the database column
Boolean
Void setBeanProperty(java.lang.String beanProperty) Void
Shows or hides the object description
Sets an object attribute name setDescription(java.lang.String description) setDisplayName(java.lang.String displayName) setHidden(boolean hidden) setPossibleResultType(java.lang.String
possibleResultType) setPropertyAccessor(java.lang.String
propertyAccessor)
Void
Void
Void
Void
Void
Sets properties in a Java bean
Sets an object description
Sets an object display name
Show or hide the object
Sets the possible types of result the finder returns
Sets an object property accessor
Void Sets an object property accessortree setPropertyAccessorTree(java.lang.Object
propertyAccessorTree) setShowInColumn(boolean showInTable) Void setShowInDescription(boolean showInDescription)
Void
Show or hide the object in the database column
Show or hide the object description
Constructor
SDKFinderProperty(java.lang.String attributeName, java.lang.String displayName, java.lang.String
beanProperty, java.lang.String propertyAccessor)
SDKHelper Class
You can add a tab to the Orchestrator configuration interface to allow users to configure a plug-in. The
SDKHelper class provides methods to obtain configuration information for a plug-in from the Orchestrator configuration interface.
The SDKHelper class is contained in the ch.dunes.vso.sdk.helper
package.
public class SDKHelper extends java.lang.Object
The
SDKHelper
class defines the following methods.
Method getConfigurationPathForPluginName(java.lang.String
moduleName) isPluginEnabled(java.lang.String pluginName) setPluginEnabled(java.lang.String pluginName, boolean flag)
Returns java.lang.String
Boolean
Void
Description
Obtains the path to the source files of the plug-in implementation.
Checks whether the plugin is enabled or disabled.
Enables the plug-in.
VMware, Inc. 225
vCenter Orchestrator Developer's Guide
Method loadPropertiesForPluginName(java.lang.String
moduleName) savePropertiesForPluginName(java.util.Properties
properties, java.lang.String moduleName) getPluginInstallCredentials()
Returns Description java.util.Properties
Loads a list of properties that users set in the configuration interface.
Void java.lang.String[]
Saves in the plug-in properties that the user sets in the configuration interface.
Obtains the credentials of the user who sets properties in the configuration interface.
Constructor
SDKHelper()
PluginExecutionException Class
The PluginExecutionException class returns an error message if the plug-in encounters an exception when it runs an operation.
public class PluginExecutionException extends java.lang.Exception
implements java.io.Serializable
The PluginExecutionException class inherits the following methods from class java.lang.Throwable
: fillInStackTrace , getCause , getLocalizedMessage , getMessage , getStackTrace , initCause , printStackTrace , printStackTrace , printStackTrace , setStackTrace , toStringfillInStackTrace , getCause , getLocalizedMessage , getMessage , getStackTrace , initCause , printStackTrace
Constructor
PluginExecutionException(java.lang.String message)
PluginLicenseException Class
The PluginLicenseException class returns an error message if the plug-in encounters an exception when it installs a license for a plug-in.
public class PluginLicenseException extends java.lang.Exception
implements java.io.Serializable
The PluginExecutionException class inherits the following methods from class java.lang.Throwable
: fillInStackTrace , getCause , getLocalizedMessage , getMessage , getStackTrace , initCause , printStackTrace , printStackTrace , printStackTrace , setStackTrace , toStringfillInStackTrace , getCause , getLocalizedMessage , getMessage , getStackTrace , initCause , printStackTrace
Constructor
PluginLicenseException(java.lang.String message)
226 VMware, Inc.
Chapter 7 Developing Plug-Ins
PluginOperationException Class
The
PluginOperationException
class handles errors encountered during a plug-in operation.
public class PluginOperationException extends java.lang.RuntimeException
implements java.io.Serializable
The PluginOperationException class inherits the following methods from class java.lang.Throwable
: fillInStackTrace , getCause , getLocalizedMessage , getMessage , getStackTrace , initCause , printStackTrace , printStackTrace
, printStackTrace
, setStackTrace
, toString
Constructor
PluginOperationException(java.lang.String message)
ConfigurationError.Severity Enumeration
The
ConfigurationError
class uses the
ConfigurationError.Severity
enumeration to set the level of severity of configuration errors.
public static enum ConfigurationError.Severity
extends java.lang.Enum<ConfigurationError.Severity> implements java.io.Serializable
The ConfigurationError.Severity
enumeration defines the following constant values for error levels: n public static final ConfigurationError.Severity Info n public static final ConfigurationError.Severity Warning n public static final ConfigurationError.Severity Error
The ConfigurationError.Severity
enumeration defines the following methods.
Method values() valueOf(java.lang.String
name) public int getValue()
Returns public static
ConfigurationError.Severity[] java.lang.String name int
Description
Returns an array containing the constants of this enumeration type, in the order that the plug-in declares them. You can use this method to iterate through the constants as follows: for (
ConfigurationError.Severity c :
ConfigurationError.Severity.
values())
System.out.println(c);
Returns the constant value of an enumeration with the specified name. The string must match an identifier that you use to declare an enumeration constant in this type. Extraneous whitespace characters are not permitted.
The name parameter is the name of the enumeration constant to return.
Returns the value of the error.
The ConfigurationError.Severity
enumeration inherits the following methods from class java.lang.Enum
: clone , compareTo , equals , finalize , getDeclaringClass , hashCode , name , ordinal , toString , valueOf
VMware, Inc. 227
vCenter Orchestrator Developer's Guide
ErrorLevel Enumeration
The ErrorLevel enumeration defines constant values for different levels of error that a plug-in encounters.
public enum HasChildrenResult extends java.lang.Enum<HasChildrenResult> implements java.io.Serializable
The
ErrorLevel
enumeration defines the following constant values for error levels: n public static final ErrorLevel Fatal n public static final ErrorLevel Error n public static final ErrorLevel Warning n public static final ErrorLevel Info n public static final ErrorLevel Debug
The ErrorLevel enumeration defines the following methods:
Method values() valueOf(java.lang.String
name) getSeverity()
Returns static
ErrorLevel[] java.lang.String
ErrorLevel
Description
Returns an array containing the constants of this enumeration type, in the order that plug-in declares them. You can use this method to iterate through the constants as follows: for (ErrorLevel c : ErrorLevel.values())
System.out.println(c);
Returns the constant value of an enumeration with the specified name. The string must match an identifier that you use to declare an enumeration constant in this type. Extraneous whitespace characters are not permitted.
The name parameter is the name of the enumeration constant to return.
Returns the ErrorLevel value of the error.
The ErrorLevel enumeration inherits the following methods from class java.lang.Enum
: clone , compareTo , equals , finalize , getDeclaringClass , hashCode , name , ordinal , toString , valueOf
HasChildrenResult Enumeration
The HasChildrenResult Enumeration declares whether a given parent has children. The
IPluginFactory.hasChildrenInRelation
method returns HasChildrenResult objects.
public enum HasChildrenResult extends java.lang.Enum<HasChildrenResult> implements java.io.Serializable
The HasChildrenResult enumeration defines the following constants: n public static final HasChildrenResult Yes n public static final HasChildrenResult No n public static final HasChildrenResult Unknown
The HasChildrenResult enumeration defines the following methods:
228 VMware, Inc.
Chapter 7 Developing Plug-Ins
Method getValue() valueOf(java.lang.String
name) values()
Returns int static
HasChildrenResult static
HasChildrenResult[]
1
-1
0
Description
Returns one of the following values:
Parent has children
Parent has no children
Unknown, or invalid parameter
Returns an enumeration constant of this type with the specified name. The String must match exactly an identifier used to declare an enumeration constant of this type. Do not use whitespace characters in the enumeration name.
Returns an array containing the constants of this enumeration type, in the order they are declared. This method can iterate over constants as follows: for (HasChildrenResult c :
HasChildrenResult.values())
System.out.println(c);
The HasChildrenResult enumeration inherits the following methods from class java.lang.Enum
: clone
, compareTo
, equals
, finalize
, getDeclaringClass
, hashCode
, name
, ordinal
, toString
, valueOf
ScriptingAttribute Annotation Type
The ScriptingAttribute annotation type annotates an attribute from an object in the plugged in technology for use as a property in scripting.
@Retention(value=RUNTIME)
@Target(value={METHOD,FIELD}) public @interface ScriptingAttribute
The ScriptingAttribute annotation type has the following value: public abstract java.lang.String value
ScriptingFunction Annotation Type
The
ScriptingFunction
annotation type annotates a method for use as a property in scripting.
@Retention(value=RUNTIME)
@Target(value={METHOD,CONSTRUCTOR}) public @interface ScriptingFunction
The ScriptingFunction annotation type has the following value: public abstract java.lang.String value
ScriptingParameter Annotation Type
The ScriptingParameter annotation type annotates a parameter for use as a property in scripting.
@Retention(value=RUNTIME)
@Target(value=PARAMETER) public @interface ScriptingParameter
The ScriptingParameter annotation type has the following value: public abstract java.lang.String value
VMware, Inc. 229
vCenter Orchestrator Developer's Guide
Elements of the vso.xml Plug-In Definition File
The vso.xml
file contains a set of standard elements. Some of the elements are mandatory while others are optional.
Each element has attributes that define values for the objects and operations you map to Orchestrator objects and operations. This information describes all of the elements of the vso.xml
file and the possible attribute values for each element.
module Element
A module describes a set of plug-in objects to make available to Orchestrator.
The module contains information about how data from the plugged-in technology maps to Java classes, versioning, how to deploy the module, and how the plug-in appears in the Orchestrator inventory.
The <module> element is optional. The <module> element has the following attributes:
Attributes name version build-number image display-name interfacemapping-allowed
Value Description
String
Number
Number
Defines the type of all the <finder> elements in the plug-in. Mandatory attribute.
The plug-in version number, for use when reloading packages in a new version of the plug-in. Mandatory attribute.
The plug-in build number, for use when reloading packages in a new version of the plug-in. Mandatory attribute.
Image file
String
The icon to display in the Orchestrator Inventory. Mandatory attribute.
The name that appears in the Orchestrator Inventory. Optional attribute.
true or false VMware strongly discourages interface mapping. Optional attribute.
Table 7-9. Element Hierarchy
Parent Element
None n n n n n n n n n
Child Elements
<description>
<installation>
<configuration>
<webview-components-library>
<finder-datasources>
<inventory>
<finders>
<scripting-objects>
<enumerations>
configuration Element
The <configuration> element allows you to add a tab in the Orchestrator configuration interface. You can use the tab to configure a plug-in.
The <configuration> element is optional. The <configuration> element has the following attributes:
230 VMware, Inc.
Chapter 7 Developing Plug-Ins
Attributes icon
Value
Image file adaptor-class Java class configuration-war WAR archive
Description
Icon that represents the plug-in in the Orchestrator configuration interface.
Mandatory attribute.
Implementation of the IConfigurationAdaptor Java interface that defines the actions to perform in the configuration interface. Mandatory attribute.
Web application archive (war file) that contains the components of the Web application that implements the adapter class. The pages of the Web application appear in the configuration interface. Optional attribute.
Validates the configuration against a function that you define in the adapter class. Optional attribute.
validation enabled or disabled
Table 7-10. Element Hierarchy
Parent Element
<module>
Child Element
None
description Element
The <description> elements provide descriptions of the elements of the plug-in that appear in the API Explorer documentation.
You add the text that appears in the API Explorer documentation between the
<description>
and
</description> tags.
The <description> element is optional. The <description> element has no attributes.
n n n n n n n n n
Table 7-11. Element Hierarchy
Parent Elements
<module>
<example>
<trigger>
<gauge>
<finder>
<constructor>
<method>
<object>
<enumeration>
Child Elements
None
deprecated Element
The <deprecated> element marks objects and methods that are deprecated in the API Explorer documentation.
You add the text that appears in the API Explorer documentation between the <deprecated> and
</deprecated> tags.
The <deprecated> element is optional. The <deprecated> element has no attributes.
n n
Table 7-12. Element Hierarchy
Parent Elements
<method>
<object>
Child Elements
None
VMware, Inc. 231
vCenter Orchestrator Developer's Guide
url Element
The
<url>
element provides a URL that points to external documentation about an object or enumeration.
You provide the URL between the <url> and </url> tags.
The <url> element is optional. The <url> element has no attributes.
n n
Table 7-13. Element Hierarchy
Parent Elements
<enumeration>
<object>
Child Elements
None
installation Element
The <installation> element allows you to install a package or run a script when the server starts.
The <installation> element is optional. The <installation> element has the following attributes:
Attributes Value mode always , never, or version
Description
Setting the mode value results in the following behavior when the Orchestrator server starts: n n
The action always runs
The action never runs n The action runs when the server detects a newer version of the plug-in
Mandatory attribute.
Table 7-14. Element Hierarchy
Parent Element
<module>
Child Element
<action>
action Element
The <action> element specifies the action that runs when the Orchestrator server starts.
The <action> element attributes provide the path to the Orchestrator package or script that defines the plugin's behavior when it starts.
The <action> element is optional. A plug-in can have an unlimited number of <action> elements. The
<action> element has the following attributes.
Attributes Value resource String type install-package or execute-script
Description
The path to the Java package or script from the root of the dar file. Mandatory attribute.
Either installs the specified Orchestrator package in the Orchestrator server, or runs the specified script. Mandatory attribute.
Table 7-15. Element Hierarchy
Parent Element
<installation>
Child Elements
None
232 VMware, Inc.
Chapter 7 Developing Plug-Ins
webview-components-library Element
The
<webview-components-library>
element points to a JAR file containing custom Web view tapestry components that extend Web view capabilities.
The <webview-components-library> element is optional. The <webview-components-library> element has the following attributes.
Attributes Value Description jar String A JAR file containing Web view components. Mandatory attribute.
specification-path String The path in the JAR file to the Tapestry component definition file, in the lib folder of the
*.dar
file. The path must begin with a forward slash (/). Mandatory attribute.
Table 7-16. Element Hierarchy
Parent Element
<module>
Child Elements
None
finder-datasources Element
The
<finder-datasources>
element is the container for the
<finder-datasource>
elements.
The <finder-datasources> element is optional. The <finder-datasources> element has no attributes.
Table 7-17. Element Hierarchy
Parent Element Child Elements
<module> <finder-datasource>
finder-datasource Element
The
<finder-datasource>
element points to the Java class file of the
IPluginAdaptor
implementation that you create for the plug-in.
You set how Orchestrator accesses the objects of the plugged-in technology in the <finder-datasource> element. The <finder-datasource> element identifies the Java class of the plug-in adapter that you create. The plug-in adapter class instantiates the plug-in factory that you create. The plug-in factory defines the methods that find objects in the plugged-in technology. You can set timeouts in the
<finder-datasource>
element for the finder method calls that the factory performs. Different timeouts apply to the different finder methods from the IPluginFactory interface.
The <finder-datasource> element is optional. A plug-in can have an unlimited number of <finderdatasources> elements. The <finder-datasource> element has the following attributes.
Attributes Value Description name String Identifies the data source in the <finder> element datasource attributes.
Equivalent to an XML id. Mandatory attribute.
adaptor-class Java class Points to the IPluginAdaptor implementation you define to create the plug-in adapter, for example, com.vmware.plugins.sample.Adaptor.
Mandatory attribute.
concurrent-call true (default) or false Allows multiple users to access the adapter at the same time. You must set concurrent-call to false if the plug-in does not support concurrent calls. Optional attribute.
VMware, Inc. 233
vCenter Orchestrator Developer's Guide
Attributes invoker-mode
Value direct (default) or timeout anonymous-loginmode timeout-fetchrelation never (default) or always
Number; default 30 seconds timeout-find-all Number; default 60 seconds timeout-find Number; default 60 seconds timeout-haschildren-inrelation
Number; default 2 seconds timeout-executeplugin-command
Number; default 30 seconds
Table 7-18. Element Hierarchy
Parent Element
<finder-datasources>
Description
Sets a timeout on the finder function. If set to direct, calls to finder functions never time out. If set to timeout, the Orchestrator server applies the timeout period that corresponds to the finder method. Optional attribute.
Passes or does not pass the user's username and password to the plug-in.
Optional attribute.
Applies to calls from findRelation(). Optional attribute.
Applies to calls from findAll(). Optional attribute.
Applies to calls from find(). Optional attribute.
Applies to calls from findChildrenInRelation(). Optional attribute.
Applies to calls from executePluginCommand(). Optional attribute.
Child Elements
None
inventory Element
The <inventory> element defines the root of the hierarchical list for the plug-in that appears in the Orchestrator client Inventory view and object selection dialog boxes.
The <inventory> element does not represent an object in the plugged-in application, but rather represents the plug-in itself as an object in the Orchestrator scripting API.
The <inventory> element is optional. The <inventory> element has the following attribute.
Attributes Value type
Description
An Orchestrator object type The type of the <finder> element that represents the root of the hierarchy of objects. Mandatory attribute.
Table 7-19. Element Hierarchy
Parent Element
<module>
Child Elements
None
finders Element
The <finders> element is the container for all the <finder> elements.
The <finders> element is optional. The <finders> element has no attributes.
Table 7-20. Element Hierarchy
Parent Element
<module>
Child Element
<finder>
234 VMware, Inc.
Chapter 7 Developing Plug-Ins
finder Element
The
<finder>
element represents in the Orchestrator client a type of object found through the plug-in.
The <finder> element identifies the Java class that defines the object the object finder represents. The
<finder> element defines how the object appears in the Orchestrator client interface. It also identifies the scripting object that the Orchestrator scripting API defines to represent this object.
Finders act as an interface between object formats used by different types of plugged-in technologies.
The
<finder>
element is optional. A plug-in can have an unlimited number of
<finder>
elements. The
<finder> element defines the following attributes:
Attributes Value type datasource
An Orchestrator object type
<finder-datasource name> attribute dynamic-finder Java method
Description
Type of object represented by the finder. Mandatory attribute.
hidden image java-class true or false (default)
Path to a graphic file
Name of a Java class script-object <scripting-object type> attribute
Identifies the Java class that defines the object by using the datasource refid . Mandatory attribute.
Defines a custom finder method you implement in an IDynamicFinder instance, to return the ID and properties of a finder programmatically, instead defining it in the vso.xml file. Optional attribute.
If true, hides the finder in the Orchestrator client. Optional attribute.
A 16x16 icon to represent the finder in hierarchical lists in the Orchestrator client. Optional attribute.
The Java class that defines the object the finder finds and maps to a scripting object. Optional attribute.
The <scripting-object> type, if any, to which to map this finder.
Optional attribute.
Table 7-21. Element Hierarchy
Parent Element
<finders> n n n n n n n n
Child Elements
<id>
<description>
<properties>
<default-sorting>
<inventory-children>
<relations>
<inventory-tabs>
<events>
properties Element
The <properties> element is the container for <finder><property> elements.
The <properties> element is optional. The <properties> element has no attributes.
Table 7-22. Element Hierarchy
Parent Element
<finder>
Child Element
<property>
VMware, Inc. 235
vCenter Orchestrator Developer's Guide
property Element
The
<property>
element maps the found object's properties to Java properties or method calls.
You can call on the methods of the SDKFinderProperty class when you implement the plug-in factory to obtain properties for the plug-in factory implementation to process.
You can show or hide object properties in the views in the Orchestrator client. You can also use enumerations to define object properties.
The <property> element is optional. A plug-in can have an unlimited number of <property> elements. The
<property>
element has the following attributes.
Attributes name display-name bean-property propertyaccessor show-in-column show-indescription hidden linkedenumeration
Value Description
Finder name
Finder name
Property name
The name the FinderResult uses to store the element. Mandatory attribute.
The displayed property name. Optional attribute.
You use the bean-property attribute to identify a property to obtain using get and set operations. If you identify a property named
MyProperty , the plug-in defines getMyProperty and setMyProperty operations.
You set one or the other of bean-property or property-accessor, but not both. Optional attribute.
The method that obtains a property value from an object
The property-accessor attribute allows you to define an OGNL expression to validate an object's properties.
You set one or the other of bean-property or property-accessor, but not both. Optional attribute.
true (default) or false If true, this property shows in the Orchestrator client results table.
Optional attribute.
true (default) or false If true, this property shows in the object description. Optional attribute.
true or false (default) If true, this property is hidden in all cases. Optional attribute.
Enumeration name Links a finder property to an enumeration. Optional attribute.
Table 7-23. Element Hierarchy
Parent Element
<properties>
Child Elements
Child Elements
relations Element
The
<relations>
element is the container for
<finder><relation>
elements.
The <relations> element is optional. The <relations> element has no attributes.
Table 7-24. Element Hierarchy
Parent Element Child Element
<finder> <relation>
236 VMware, Inc.
Chapter 7 Developing Plug-Ins
relation Element
The
<relation>
element defines how objects relate to other objects.
You define the relation name in the <relation> element.
The <relation> element is optional. A plug-in can have an unlimited number of <relation> elements. The
<relation>
element has the following attributes.
Attributes Value Description name Relation name A name for this relation. Mandatory attribute.
type Orchestrator object type The type of the object that relates to another object by this relation. Mandatory attribute.
cardinality to-one or to-many Defines the relation between the objects as one-to-one or one-to-many. Optional attribute.
Table 7-25. Element Hierarchy
Parent Element
<relations>
Child Elements
None
id Element
The
<id>
element defines a method to obtain the unique ID of the object that the finder identifies.
The <id> element is optional. The <id> element has the following attributes.
Attributes Value Description accessor Method name The accessor attribute allows you to define an OGNL expression to validate an object's properties. Mandatory attribute.
Table 7-26. Element Hierarchy
Parent Element
<finder>
Child Elements
None
inventory-children Element
The <inventory-children> element defines the hierarchy of the lists that show the objects in the Orchestrator client Inventory view and object selection boxes.
The <inventory-children> element is optional. The <inventory-children> element has no attributes.
Table 7-27. Element Hierarchy
Parent Element
<finder>
Child Element
<relation-link>
relation-link Element
The <relation-link> element defines the hierarchies between parent and child objects in the Inventory tab.
The <relation-link> element is optional. A plug-in can have an unlimited number of <relation-link> elements. The <relation-link> element has the following attribute.
VMware, Inc. 237
vCenter Orchestrator Developer's Guide
Type Value Description name Relation name A refid to a relation name. Mandatory attribute.
Table 7-28. Element Hierarchy
Parent Element
<inventory-children>
Child Elements
None
events Element
The <events> element is the container for the <trigger> and <gauge> elements.
The <events> element can contain an unlimited number of triggers or gauges.
The <events> element is optional. The <events> element has no attributes.
Table 7-29. Element Hierarchy
Parent Element Child Elements
<finder> n n
<trigger>
<gauge>
trigger Element
The <trigger> element declares the triggers you can use for this finder. You must implement the registerEventPublisher() and unregisterEventPublisher() methods of IPluginAdaptor to set triggers.
The <trigger> element is optional. The <trigger> element has the following attribute.
Type Value Description name Trigger name A name for this trigger. Mandatory attribute.
Table 7-30. Element Hierarchy
Parent Element
<events> n n
Child Elements
<description>
<trigger-properties>
trigger-properties Element
The <trigger-properties> element is the container for the <trigger-property> elements.
The <trigger-properties> element is optional. The <trigger-properties> element has no attributes.
Table 7-31. Element Hierarchy
Parent Element Child Element
<trigger> <trigger-property>
trigger-property Element
The <trigger-property> element defines the properties that identify a trigger object.
The <trigger-property> element is optional. A plug-in can have an unlimited number of <triggerproperty> elements. The <trigger-property> element has the following attributes.
238 VMware, Inc.
Chapter 7 Developing Plug-Ins
Type Value Description name Trigger name A name for the trigger. Optional attribute.
display-name Trigger name The name that displays in the Orchestrator client. Optional attribute.
type Trigger type The object type that defines the trigger. Mandatory attribute.
Table 7-32. Element Hierarchy
Parent Element
<trigger-properties>
Child Elements
None
gauge Element
The <gauge> element defines the gauges you can use for this finder. You must implement the registerEventPublisher() and unregisterEventPublisher() methods of IPluginAdaptor to set gauges.
The <gauge> element is optional. A plug-in can have an unlimited number of <gauge> elements. The <gauge> element has the following attributes.
Type Value Description name Gauge name A name for the gauge. Mandatory attribute.
min-value Number Minimum threshold. Optional attribute.
max-value Number unit Object type format String
Maximum threshold. Optional attribute.
Object type that defines the gauge. Mandatory attribute.
The format of the monitored value. Optional attribute.
Table 7-33. Element Hierarchy
Parent Element
<events>
Child Element
<description>
scripting-objects Element
The <scripting-objects> element is the container for the <object> elements.
The <scripting-objects> element is optional. The <scripting-objects> element has no attributes.
Table 7-34. Element Hierarchy
Parent Element
<module>
Child Element
<object>
object Element
The <object> element maps the plugged-in technology's constructors, attributes, and methods to JavaScript object types that the Orchestrator scripting API exposes.
See
“Naming Plug-In Objects,” on page 149 for object naming conventions.
The <object> element is optional. A plug-in can have an unlimited number of <object> elements. The
<object> element has the following attributes.
VMware, Inc. 239
vCenter Orchestrator Developer's Guide
Type Value Description script-name java-class create strict
JavaScript name Scripting name of the class. Must be globally unique. Mandatory attribute.
Java class The Java class wrapped by this JavaScript class. Mandatory attribute.
true (default) or false If true, you can create a new instance of this class. Optional attribute.
true or false (default) If true, you can only call methods you annotate or declare in the vso.xml file.
Optional attribute.
is-deprecated true or false (default) If true, the object maps a deprecated Java class. Optional attribute.
since-version String Version since the Java class is deprecated. Optional attribute.
Table 7-35. Element Hierarchy
Parent Element
<scripting-objects> n n n n n n n
Child Elements
<description>
<deprecated>
<url>
<constructors>
<attributes>
<methods>
<singleton>
constructors Element
The <constructors> element is the container for the <object><constructor> elements.
The <constructors> element is optional. The <constructors> element has no attributes.
Table 7-36. Element Hierarchy
Parent Element
<object>
Child Element
<constructor>
constructor Element
The <constructor> element defines a constructor method. The <constructor> method produces documentation in the API Explorer.
The <constructor> element is optional. A plug-in can have an unlimited number of <constructor> elements.
The
<constructor>
element has no attributes.
Table 7-37. Element Hierarchy
Parent Element
<constructors> n n
Child Elements
<description>
<parameters>
Constructor parameters Element
The <parameters> element is the container for the <constructor><parameter> elements.
The
<parameters>
element is optional. The
<parameters>
element has no attributes.
240 VMware, Inc.
Chapter 7 Developing Plug-Ins
Table 7-38. Element Hierarchy
Parent Element
<constructor>
Child Element
<parameter>
Constructor parameter Element
The
<parameter>
element defines the constructor's parameters.
The <parameter> element is optional. A plug-in can have an unlimited number of <parameter> elements. The
<parameter> element has the following attributes.
Type Value Description name type is-optional
String Parameter name to use in API documentation. Mandatory attribute.
Orchestrator parameter type Parameter type to use in API documentation. Mandatory attribute.
true or false If true, value can be null. Optional attribute.
since-version String Method version. Optional attribute.
Table 7-39. Element Hierarchy
Parent Element
<parameters>
Child Elements
None
attributes Element
The <attributes> element is the container for the <object><attribute> elements.
The
<attributes>
element is optional. The
<attributes>
element has no attributes.
Table 7-40. Element Hierarchy
Parent Element
<object>
Child Element
<attribute>
attribute Element
The <attribute> element maps the attributes of a Java class from the plugged-in technology to JavaScript attributes that the Orchestrator JavaScript engine exposes.
The
<attribute>
element is optional. A plug-in can have an unlimited number of
<attribute>
elements. The
<attribute> element has the following attributes.
Type java-name script-name return-type read-only is-optional show-in-api
Value Description
Java attribute Name of the Java attribute. Mandatory attribute.
JavaScript object Name of the corresponding JavaScript object. Mandatory attribute.
String true true or false true
or false
or false
The type of object this attribute returns. Appears in the API Explorer documentation.
Optional attribute.
If true, you cannot modify this attribute. Optional attribute.
If true, this field can be null. Optional attribute.
If false, this attribute does not appear in API documentation. Optional attribute.
VMware, Inc. 241
vCenter Orchestrator Developer's Guide
242
Type Value is-deprecated true or false since-version Number
Description
If true, the object maps a deprecated attribute. Optional attribute.
The version at which the attribute was deprecated. Optional attribute.
Table 7-41. Element Hierarchy
Parent Element
<attributes>
Child Elements
None
methods Element
The
<methods>
element is the container for the
<object><method>
elements.
The <methods> element is optional. The <methods> element has no attributes.
Table 7-42. Element Hierarchy
Parent Element Child Element
<object> <method>
method Element
The <method> element maps a Java method from the plugged-in technology to a JavaScript method that the
Orchestrator JavaScript engine exposes.
The <method> element is optional. A plug-in can have an unlimited number of <method> elements. The
<method> element has the following attributes.
Type Value Description java-name script-name return-type static
Java method Name of the Java method signature with argument types in parenthesis, for example, getVms(DataStore). Mandatory attribute.
JavaScript method Name of the corresponding JavaScript method. Mandatory attribute.
Java object type The type this method obtains. Optional attribute.
true or false If true, this method is static. Optional attribute.
show-in-api true or false is-deprecated true or false since-version Number
If false, this method does not appear in API documentation. Optional attribute.
If true, the object maps a deprecated method. Optional attribute.
The version at which the method was deprecated. Optional attribute.
Table 7-43. Element Hierarchy
Parent Element
<methods> n n n n
Child Elements
<deprecated>
<description>
<example>
<parameters>
example Element
The <example> element allows you to add code examples to Javascript methods that appear in the API Explorer documentation.
The <example> element is optional. The <example> element has no attributes.
VMware, Inc.
Chapter 7 Developing Plug-Ins
Table 7-44. Element Hierarchy
Parent Element
<method> n n
Child Elements
<code>
<description>
code Element
The
<code>
element provides example code that appears in the API Explorer documentation.
You provide the code example between the <code> and </code> tags. The <code> element is optional. The
<code> element has no attributes.
Table 7-45. Element Hierarchy
Parent Element
<example>
Child Elements
None
Method parameters Element
The <parameters> element is the container for the <method><parameter> elements.
The <parameters> element is optional. The <parameters> element has no attributes.
Table 7-46.
Parent Element
<method>
Child Element
<parameter>
Method parameter Element
The <parameter> element defines the method's input parameters.
The <parameter> element is optional. A plug-in can have an unlimited number of <parameter> elements. The
<parameter>
element has the following attributes.
Type Value Description name type is-optional
String Parameter name. Mandatory attribute.
Orchestrator parameter type Parameter type. Mandatory attribute.
true or false If true, value can be null. Optional attribute.
since-version String Method version. Optional attribute.
Table 7-47. Element Hierarchy
Parent Element
<parameters>
Child Element
None
VMware, Inc. 243
vCenter Orchestrator Developer's Guide
singleton Element
The
<singleton>
element creates a JavaScript scripting object as a singleton instance.
A singleton object behaves in the same way as a static Java class. Singleton objects define generic objects for the plug-in to use, rather than defining specific instances of objects that Orchestrator accesses in the pluggedin technology. For example, you can use a singleton object to establish the connection to the plugged-in technology.
The <singleton> element is optional. The <singleton> element has the following attributes.
Type Value Description script-name JavaScript object Name of the corresponding JavaScript object. Mandatory attribute.
datasource Java object The source Java object for this JavaScript object. Mandatory attribute.
Table 7-48. Element Hierarchy
Parent Element
<object>
Child Element
None
enumerations Element
The
<enumerations>
element is the container for the
<enumeration>
elements.
The <enumerations> element is optional. The <enumerations> element has no attributes.
Table 7-49. Element Hierarchy
Parent Element Child Element
<module> <enumeration>
enumeration Element
The
<enumeration>
element defines common values that apply to all objects of a certain type.
If all objects of a certain type require a certain attribute, and if the range of values for that attribute is limited, you can define the different values as enumeration entries. For example, if a type of object requires a color attribute, and if the only available colors are red, blue, and green, you can define three enumeration entries to define these three color values. You define entries as child elements of the enumeration element.
The <enumeration> element is optional. A plug-in can have an unlimited number of <enumeration> elements.
The
<enumeration>
element has the following attribute.
Type Value Description type Orchestrator object type Enumeration type. Mandatory attribute.
Table 7-50. Element Hierarchy
Parent Element
<enumerations> n n n
Child Elements
<url>
<description>
<entries>
244 VMware, Inc.
Chapter 7 Developing Plug-Ins
entries Element
The
<entries>
element is the container for the
<enumeration><entry>
elements.
The <entries> element is optional. The <entries> element has no attributes.
Table 7-51. Element Hierarchy
Parent Element Child Element
<enumeration> <entry>
entry Element
The
<entry>
element provides a value for an enumeration attribute.
The <entry> element is optional. A plug-in can have an unlimited number of <entry> elements. The <entry> element has the following attributes.
Type Value Description id Text name Text
The identifier that objects use to set the enumeration entry as an attribute. Mandatory attribute.
The entry name. Mandatory attribute.
Table 7-52. Element Hierarchy
Parent Element
<entries>
Child Elements
None
VMware, Inc. 245
vCenter Orchestrator Developer's Guide
246 VMware, Inc.
Developing a Web Services Client
8
VMware vCenter Orchestrator provides a Web services API so that you can develop applications to access workflows through Web services. The main purpose of the Orchestrator Web service is to start workflows and to retrieve their output parameters through a network or the Web.
The Web service API provides a set of Web service definition language (WSDL) object type definitions and a set of Web service operations, that obtain workflows, run workflows, refresh workflow states, and obtain their output parameter values. The Web service API also allows you to implement tree viewers, based on the relations between objects obtained from plug-ins. The API has few complex object types and relatively few operations.
N
OTE
To help understand how Orchestrator implements Web services, familiarize yourself with the Web services API for your development framework, for example Java or .Net.
This chapter includes the following topics: n
“Writing a Web Service Client Application,” on page 247
n n
“Web Service API Object Reference,” on page 262
“Web Service API Operation Reference,” on page 267
Writing a Web Service Client Application
Most applications that use the Orchestrator Web Service API have a common structure. To create Orchestrator
Web service client applications, you perform a standard sequence of tasks.
Process for Creating an Orchestrator Web Service Client Application
Developing a Web services client application follows a broad sequence of stages.
Figure 8-1 shows how to create a typical Orchestrator Web service client application.
VMware, Inc. 247
vCenter Orchestrator Developer's Guide
Figure 8-1. Process for Creating Orchestrator Web Service Applications
Create a VSOWebControl object to connect to the Web service
HTTP HTTPS
(Optional) check the connection to the server using echoWorkflow
(Optional) check for plug-ins using getAllPlugins
Use find to locate an object of a particular type, that matches a particular query criterion
If necessary, find objects to execute workflows upon
Use findForId to Iocate an object with a particular ID number
Use hasChildrenInRelation and findRelation to find children of a particular relation type
Use getAllWorkflows to list all workflows
Find a workflow
Use getWorkflowsWithName to find workflows with a particular name
Use getWorkflowsForId to find a workflow based on its unique ID
(Optional) check whether the current user has rights to read, execute, or edit the workflow using hasRights
Define the workflow's inParameters
Execute the workflow using executeWorkflow, which creates a
WorkflowToken
Check the status of the workflow with getWorkFlowToken
Status
Perform different actions while the WorkflowToken executes
Find other
WorkflowToken objects using getWorkFlowToken
ForId
Provide runtime input with answerWorkflow
Input
Cancel the workflow using cancelWorkflow
Send a custom event using sendCustomEvent
When the WorkflowToke n completes, check the results with getWorkflowTokenResult
Display, process, or otherwise act upon the results of the workflow
Follow the broad stages of development illustrated to create Orchestrator Web services client applications that satisfy most of your requirements.
248 VMware, Inc.
Chapter 8 Developing a Web Services Client
Web Service Endpoint
The Web service endpoint is the port upon which you connect a Web service client to the Orchestrator server.
You connect to the Orchestrator Web service's endpoint at the following URL, in which <Orchestrator_server> is the IP address or host name of the host on which the Orchestrator server is running.
http:// <Orchestrator_server>:8280/vmware-vmo-webcontrol/webservice
The Web service runs over HTTP or HTTPS on port 8280 or 8281 of the Orchestrator server. Access to the Web service API requires a valid username and password on the Orchestrator server. Because every access to the service is authenticated separately, a secure HTTPS connection is not strictly necessary. However, the Web service sends passwords over the network without encryption, so use a secure HTTPS connection if security is an issue for your applications.
N
OTE
Networks secured by HTTPS access the Web service endpoint on port 8281. In your network, the port number might be different from the defaults of 8280 or 8281.
Generating the Orchestrator Web Service Stubs
You generate the Web service objects from the Orchestrator WSDL description file to create the client and server stubs for the Web service application.
Orchestrator publishes the WSDL description file at the following location.
http:// <Orchestrator_server>:8280/vmware-vmo-webcontrol/webservice?WSDL
You generate the Web service client and server stubs by using a Java or .Net code generator. The Orchestrator
Web service supports all WSDL 1.1 parsers. Generating the Web service provides the following objects.
N
OTE
The exact objects that the Orchestrator Web service generates depend on your code generator. The objects in the following list are those that the Axis 1.4 code generator generates. Other code generators might generate the objects differently. If the generator that you use generates different objects, use
VSOWebControlService service as the point of access to the other Web service objects.
VSOWebControl
WebServiceStub
VSOWebControlProxy
VSOWebControlService
VSOWebControlServiceLoc ator
The Web service defines a WSDL port type named VSOWebControl , through which you access all the Orchestrator Web service operations.
The Web service defines client and server side stubs that the application uses to start the Web service.
The Web service provides access to the Orchestrator Web service operations through a proxy.
The VSOWebControlService service is a remote procedure call (RPC) Service implementation. The
VSOWebControlService
service is the point of access to the other Web service objects.
The VSOWebControlServiceLocator service extends VSOWebControlService to provide the following operations.
n getwebserviceAddress
obtains the endpoint URL for the Web service.
n getwebservice obtains the client-side stub for the Web service application and instantiates the VSOWebControl port type object with the appropriate endpoint URL.
VMware, Inc. 249
vCenter Orchestrator Developer's Guide
250
Accessing the Server from Web Service Clients
By default, Orchestrator permits access to workflows from Web service clients. However, the Orchestrator administrator can configure the server to deny connections from Web service clients.
If the Orchestrator administrator has disabled access to the server from Web service clients, the server only answers Web service client calls from the echo()
and echoWorkflow()
methods, for testing purposes.
The Orchestrator administrator enables and disables access to the server from Web service clients by setting a system property. See the VMware vCenter Orchestrator Administration Guide for information about setting system properties.
Create a Web Service Client
You can use the Orchestrator Web service API to create a Web service client to connect to the Orchestrator
Server. The Web service connection allows you to access workflows in the Orchestrator server and perform operations on them.
Prerequisites
You must have generated the Web service client stub from the Orchestrator WSDL definition by using a code generator.
Procedure
1
Connect to the Orchestrator Web Service on page 251
Web service applications establish connections to the Orchestrator server through simple object access protocol (SOAP) binding, using either the HTTP or HTTPS protocols.
2
Find Objects in the Orchestrator Server on page 252
To perform any useful task with a workflow, you must find the objects on which the workflow will run.
The Orchestrator Web service API provides functions for finding objects of all types in the VMware
Infrastructure inventory.
3
Find Objects by Using the find Operation on page 252
You can use the find operation to find objects of any type that match a particular search criterion, that you set in the query parameter.
4
Find Objects by Using the findForId Operation on page 253
You can use the findForId
operation to find an object if you know a specific object's unique ID.
5
Find Objects by Using the findRelation Operation on page 254
You can use the findRelation operation to locate the children of a particular object.
6
Find Workflows in the Orchestrator Server on page 256
When you have found the objects with which to interact, you must find the workflows that perform these interactions.
7
Find Workflows by Using the getAllWorkflows Operation on page 256
The getAllWorkflows
operation lists all workflows that a user can access as an array of
Workflow
objects.
8
Find Workflows by Using the getWorkflowsWithName Operation on page 256
If you know the name of a particular workflow, as it is defined in the Orchestrator client, the Web service application can obtain this workflow using its name or part of its name.
9
Find Workflows by Using the getWorkflowForID Operation on page 257
If you know a particular workflow ID, a Web service application can obtain this workflow by using the getWorkflowForID operation.
VMware, Inc.
Chapter 8 Developing a Web Services Client
10
Run Workflows from a Web Service Client on page 257
The main purpose of a Web services client is to run workflows across a network.
11
Interact with a Workflow While it Runs on page 259
After the workflow starts, the Web services client can perform various actions in response to events while the workflow is running.
12
Obtain Workflow Results on page 260
After the workflow completes its run, you can retrieve the results by calling the getWorkflowTokenResult( ) operation.
Connect to the Orchestrator Web Service
Web service applications establish connections to the Orchestrator server through simple object access protocol
(SOAP) binding, using either the HTTP or HTTPS protocols.
Prerequisites
You must have generated the Orchestrator Web service client and server stubs from the Orchestrator WSDL definition. You must create a Web service client application class that implements the VSOWebControl interface.
Procedure
1 In your Web service client application class, create a VSOWebControl instance that connects to the Web service endpoint.
You can either create an unsecured connection using HTTP, or a secure connection using HTTPS. The default HTTP port is 8280 and the default HTTPS port is 8281. The URL is also a default.
n The following example shows how to create an HTTP connection to the Web service.
n
String urlprefix = "http://10.0.0.1:8280" ;
URL url = new URL(urlprefix + "/vmware-vmo-webcontrol/webservice");
VSOWebControl vsoWebControl = new VSOWebControlServiceLocator().getwebservice(url);
The following example shows how to create an HTTPS connection to the Web service.
String urlprefix = "https://10.0.0.1:8281" ;
URL url = new URL(urlprefix + "/vmware-vmo-webcontrol/webservice"); vsoWebControl = new VSOWebControlServiceLocator().getwebservice(url);
2 Check the server connections by calling the echo
operation.
The following example shows how you can call the echo operation.
vsoWebControl.echo(string);
The preceding call to the echo operation returns the String object that you provided as an argument.
3 (Optional) Check what plug-ins are running the Orchestrator server by calling the getAllPlugins operation.
The following example shows how you can call the getAllPlugins operation.
ModuleInfo[] modules = vsoWebControl.getAllPlugins(username, password);
The preceding call to the getAllPlugins operation returns an array of ModuleInfo objects, each of which contains the name and version information about a plug-in running in the Orchestrator server.
You created a connection to the Orchestrator Web service, verified the connection, and established what technologies plug in to the Orchestrator server.
What to do next
Find objects in the Orchestrator server through the Web service connection.
VMware, Inc. 251
vCenter Orchestrator Developer's Guide
Find Objects in the Orchestrator Server
To perform any useful task with a workflow, you must find the objects on which the workflow will run. The
Orchestrator Web service API provides functions for finding objects of all types in the VMware Infrastructure inventory.
Workflows typically run on objects in the vCenter Server. Workflows can also run on objects from outside the vCenter Server by accessing them through plug-ins.
The operations that the Web service API defines for finding objects are as follows.
n find n findForId n findRelation n hasChildrenInRelation
All of the operations that find objects return FinderResult objects, either individually, as an array, or embedded in a
QueryResult
object.
Find Objects by Using the find Operation
You can use the find operation to find objects of any type that match a particular search criterion, that you set in the query parameter.
The vso.xml
file of the plug-in through which you access the object defines the syntax of the query parameter.
Prerequisites
You must have created a connection to the Orchestrator Web services endpoint in your Web service client application class.
Procedure
1 Create a QueryResult object by calling the find operation on an object.
The following code example shows how an application can call the find operation to find out how many virtual machines are accessible by a particular user through the vCenter Server plug-in.
QueryResult queryResult = vsoWebControl.find("VC:VirtualMachine", null,
<username>, <password>);
if (queryResult != null) {
System.out.println("Found " + queryResult.getTotalCount() +
" objs.");
FinderResult[] elts = queryResult.getElements();
finderResult = elts[0];
displayFinderResult(finderResult);
}
else {
System.out.println("Found nothing");
}
According to the query syntax defined by the vCenter Server plug-in, setting the query parameter to null returns the list of all of the objects of the type specified by the first parameter. The preceding code example performs the following tasks.
n Gets the list of any
VC:VirtualMachine
objects in the library.
n Calls the QueryResult object's getTotalCount operation to obtain the total number of
VC:VirtualMachine objects found and print the value.
252 VMware, Inc.
Chapter 8 Developing a Web Services Client n Calls the
QueryResult
object's getElements
operation to obtain the details of the objects found as an array of FinderResult objects.
n Passes the array of FinderResult objects to the internal method displayFinderResult , which extracts the information.
2 Extract the results from a
FinderResult
object.
To show, interpret, or process the results in the FinderResult objects that the find operation returns, you must convey these results to the Web service application.
The following example shows how to extract the results returned in a FinderResult object.
public static void displayFinderResult(FinderResult finderResult) {
if (finderResult != null) {
System.out.println("Finder result is of type '"
+ finderResult.getType()
+ "', id '" + finderResult.getId()
+ "' and uri '"
+ finderResult.getDunesUri() + "'");
System.out.println("And has properties :");
Property[] props = finderResult.getProperties();
if (props != null) {
for (int ii = 0; ii < props.length; ii++) {
System.out.println("\t" + props[ii].getName() + "="
+ props[ii].getValue());
}
}
}
The example defines an internal method, displayFinderResult , which takes a FinderResult object and obtains and shows its type, ID, the URI at which it is located, and its properties. You can use the URI to set arguments when starting or answering workflows. The getType , getId , getProperties and getDunesUri methods are defined by the FinderResult object.
You found objects in the Orchestrator server that the Web service client can access and run workflows upon.
What to do next
Implement Web service operations in the client application to find workflows in the Orchestrator server.
Find Objects by Using the findForId Operation
You can use the findForId operation to find an object if you know a specific object's unique ID.
To use findForId , you match a specific type of object to its identifier.
Prerequisites
You must have created a connection to the Orchestrator Web services endpoint in your Web service client application class.
VMware, Inc. 253
vCenter Orchestrator Developer's Guide
Procedure
1 Create a
FinderResult
object by calling the findForId
operation on an object.
finderResult = vsoWebControl.findForId("VC:VirtualMachine", "vcenter/vm-xx", username, password);
In the preceding example, vcenter/vm-xx is the ID of a virtual machine object that the findForID operation finds.
The findForID operation returns a FinderResult instance directly, rather than creating an array of
FinderResult
objects like find
. Finding objects by their unique ID always returns only one object.
2 Extract the results from a FinderResult object.
To show, interpret, or process the results in the FinderResult objects that the find operation returns, you must convey these results to the Web service application.
The following example shows how to extract the results returned in a FinderResult object.
public static void displayFinderResult(FinderResult finderResult) {
if (finderResult != null) {
System.out.println("Finder result is of type '"
+ finderResult.getType()
+ "', id '" + finderResult.getId()
+ "' and uri '"
+ finderResult.getDunesUri() + "'");
System.out.println("And has properties :");
Property[] props = finderResult.getProperties();
if (props != null) {
for (int ii = 0; ii < props.length; ii++) {
System.out.println("\t" + props[ii].getName() + "="
+ props[ii].getValue());
}
}
}
The example defines an internal method, displayFinderResult , which takes a FinderResult object and obtains and shows its type, ID, the URI at which it is located, and its properties. You can use the URI to set arguments when starting or answering workflows. The getType , getId , getProperties and getDunesUri methods are defined by the FinderResult object.
You found objects in the Orchestrator server that the Web service client can access and run workflows upon.
Find Objects by Using the findRelation Operation
You can use the findRelation operation to locate the children of a particular object.
The findRelation
operation returns an array of
FinderResult
objects that correspond to the children of a particular object.
Prerequisites
You must have created a connection to the Orchestrator Web services endpoint in your Web service client application class.
254 VMware, Inc.
Chapter 8 Developing a Web Services Client
Procedure
1 Create an array of
FinderResult
objects by calling the findRelation
operation on an object.
FinderResult[] results = vsoWebControl.findRelation("VC:ComputeResource",
"vcenter/domain-s114", "getResourcePool()", "username", "password");
The preceding example returns an array of FinderResult objects that match the following criteria.
n The parent element is of the type VC:ComputeResource .
n The parent element's ID is vchost/domain-s114
.
n The returned children are related to the parent by the getResourcePool relation, defined by the
Orchestrator vCenter Server 4 plug-in.
2 Extract the results from a FinderResult object.
To show, interpret, or process the results in the FinderResult objects that the find operation returns, you must convey these results to the Web service application.
The following example shows how to extract the results returned in a FinderResult object.
public static void displayFinderResult(FinderResult finderResult) {
if (finderResult != null) {
System.out.println("Finder result is of type '"
+ finderResult.getType()
+ "', id '" + finderResult.getId()
+ "' and uri '"
+ finderResult.getDunesUri() + "'");
System.out.println("And has properties :");
Property[] props = finderResult.getProperties();
if (props != null) {
for (int ii = 0; ii < props.length; ii++) {
System.out.println("\t" + props[ii].getName() + "="
+ props[ii].getValue());
}
}
}
The example defines an internal method, displayFinderResult , which takes a FinderResult object and obtains and shows its type, ID, the URI at which it is located, and its properties. You can use the URI to set arguments when starting or answering workflows. The getType , getId , getProperties and getDunesUri methods are defined by the FinderResult object.
You found objects in the Orchestrator server that the Web service client can access and and run workflows upon.
What to do next
Implement Web service operations in the client application to find workflows in the Orchestrator server.
VMware, Inc. 255
vCenter Orchestrator Developer's Guide
Find Workflows in the Orchestrator Server
When you have found the objects with which to interact, you must find the workflows that perform these interactions.
The Orchestrator Web service API includes the following operations to find all the workflows running in a given environment, to find a workflow with a particular name, or to find workflows with a particular ID.
n getAllWorkflows n getWorkflowsWithName n getWorkflowForID
Find Workflows by Using the getAllWorkflows Operation
The getAllWorkflows
operation lists all workflows that a user can access as an array of
Workflow
objects.
Because the getAllWorkflows operation returns Workflow objects that contain all the information about a workflow, it is useful for applications that require full information about workflows, such as the workflow's name, ID, description, parameters, and attributes.
Prerequisites
You must have implemented Web service operations in your client application to find objects in the
Orchestrator server.
Procedure u Create an array of Workflow objects by calling the getAllWorkflows operation.
Workflow[] workflows = vsoWebControl.getAllWorkflows(username, password);
The preceding code example calls getAllWorkflows to get an array of Workflow objects that the Web service client can run.
You found workflows in the Orchestrator server that the Web service client can run on objects.
What to do next
Implement operations in the Web services client to run the workflows it finds.
Find Workflows by Using the getWorkflowsWithName Operation
If you know the name of a particular workflow, as it is defined in the Orchestrator client, the Web service application can obtain this workflow using its name or part of its name.
The getWorkflowsWithName operation returns an array of workflows, so you can use it to match several workflows by using wildcards.
Prerequisites
You must have implemented Web service operations in your client application to find objects in the
Orchestrator server.
256 VMware, Inc.
Chapter 8 Developing a Web Services Client
Procedure u Create an array of
Workflow
objects by calling the getWorkflowsWithName
operation.
Workflow[] workflows =
vsoWebControl.getWorkflowsWithName("Simple user interaction",
username, password);
The preceding code example calls the getWorkflowsWithName operation to obtain all workflows for which the name, or part of the name, is Simple user interaction .
You found workflows in the Orchestrator server that the Web service client can run on objects.
What to do next
Implement operations in the Web services client to run the workflows it finds.
Find Workflows by Using the getWorkflowForID Operation
If you know a particular workflow ID, a Web service application can obtain this workflow by using the getWorkflowForID
operation.
The getWorkflowForID operation returns a single Workflow instance, because all workflow IDs are unique.
Prerequisites
You must have implemented Web service operations in your client application to find objects in the
Orchestrator server.
Procedure u Create a Workflow object by calling the getWorkflowForID operation.
String workflowId = "1880808080808080808080808080808087808080011713796199469943be4c882";
Workflow workflow = vsoWebControl.getWorkflowForID(workflowId, username, password);
You found a workflow in the Orchestrator server that the Web service client can run on objects.
What to do next
Implement operations in the Web services client to run the workflows it finds.
Run Workflows from a Web Service Client
The main purpose of a Web services client is to run workflows across a network.
Prerequisites
You must have implemented Web service operations in the client to find workflows in the Orchestrator server.
VMware, Inc. 257
vCenter Orchestrator Developer's Guide
Procedure
1 (Optional) Check the workflow user permissions by calling the hasRights
operation.
You can verify if a user has rights to read, run, or edit a particular workflow using the hasRights operation.
This operation is not mandatory, but checking user rights before you run a workflow can help prevent exceptions.
String workflowId = "1880808080808080808080808080808087808080011713796199469943be4c882";
Boolean rights = vsoWebControl.hasRights(workflowId, username, password, 'x');
The preceding code example calls the hasRights operation to discover whether the user has the right to run the workflow identified by workflowId
.
If the user has the right to run the workflow, hasRights returns true . Otherwise, hasRights returns false .
2 Set the workflow attributes in a WorkflowTokenAttribute object.
The Web services client passes WorkflowTokenAttributes arrays to a WorkflowToken object, which runs the workflow.
WorkflowTokenAttribute[] attributes = new WorkflowTokenAttribute[1];
WorkflowTokenAttribute attribute = new WorkflowTokenAttribute(); attribute.setName("vm"); attribute.setType(finderResult.getType()); attribute.setValue(finderResult.getDunesUri()); attributes[0] = attribute;
The preceding example creates a WorkflowTokenAttribute object, then populates it with the following information: n The name of the attribute, in this case, vm .
n n
The type of attribute, as discovered in a FinderResult object defined elsewhere in the code.
The attribute value, which in this case is a dunesUri string, signifying that the value specifies an object accessed through a plug-in.
3 Run the workflow by calling the executeWorkflow operation.
To run a workflow, you pass the workflow attributes to the executeWorkflow
operation in the form of a
WorkflowTokenAttribute array.
Running a workflow creates a WorkflowToken object, which represents the instance of the workflow that runs with the specific input parameters that it receives when it starts.
WorkflowToken token = vsoWebControl.executeWorkflow(workflowId, username, password, attributes);
In the preceding example, the attributes
property is the array of
WorkflowTokenAttribute
objects created in
Sometimes, workflows require input parameters during their run. In these cases, you can provide attributes through a user interaction while the workflow is running. You can pass attributes to the workflow during its run using the answerWorkflowInput operation.
You implemented operations in the Web service client that check user permissions, pass attributes to a workflow, and run the workflow.
What to do next
Implement operations in the Web services client to interact with workflows while they run.
258 VMware, Inc.
Chapter 8 Developing a Web Services Client
Interact with a Workflow While it Runs
After the workflow starts, the Web services client can perform various actions in response to events while the workflow is running.
Prerequisites
You must have implemented operations in the Web service client to run workflows in the Orchestrator server.
Procedure
1 Find running workflows by calling the getWorkflowTokenForId operation.
Calling getWorkflowTokenForId obtains a WorkflowToken object, which contains all of the information about that specific workflow token.
WorkflowToken onemoretoken = vsoWebControl.getWorkflowTokenForId(workflowTokenId, username, password);
AllActiveWorkflowTokens[n] = onemoretoken;
The preceding code example obtains a WorkflowToken object from its ID and sets it into an array of running
WorkflowToken objects.
2 Check the status of a workflow token by calling the getWorkFlowTokenStatus operation.
When a workflow runs, an application's main event loop usually concentrates on checking the status of the workflow at regular intervals. The getWorkflowTokenStatus
operation requires an array of the IDs of the workflow tokens for which it is obtaining the status.
String workflowId = workflows[0].getId();
WorkflowToken token = vsoWebControl.executeWorkflow(workflowId, username, password, null);
String[] tokenIds = { token.getId() };
String tokenStatus = ""; while ("completed".equals(tokenStatus) == false
&& "failed".equals(tokenStatus) == false
&& "canceled".equals(tokenStatus) == false
&& "waiting".equals(tokenStatus) == false) {
Thread.sleep(1 * 1000); // Wait 1s
String[] status = vsoWebControl.getWorkflowTokenStatus(tokenIds, username,
password);
tokenStatus = status[0];
System.out.println("Workflow is still running...(" + tokenStatus + ")");
}
The preceding example obtains the IDs of an array of workflow tokens. It checks the status of a
WorkflowToken by calling getWorkflowTokenStatus() .
The preceding example keeps the application updated on the status of the WorkflowToken objects by checking their state at one second intervals. For example, If the workflow is in the waiting
state, it is waiting for runtime input from the answerWorkflowInput operation.
VMware, Inc. 259
vCenter Orchestrator Developer's Guide
3 Provide inputs from user interactions by calling the answerWorkflowInput
operation.
If a workflow is waiting for user input in the waiting state, an application's event loop can specify that input at any time. You can create WorkflowTokenAttribute arrays as normal, and then supply them to a workflow during its run by using the answerWorkflowInput
operation. The following example continues the code from
if ("waiting".equals(tokenStatus) == true) {
System.out.println("Answering user interaction");
WorkflowTokenAttribute[] attributes = new WorkflowTokenAttribute[2];
WorkflowTokenAttribute attribute = null;
attribute = new WorkflowTokenAttribute();
attribute.setName("param1");
attribute.setType("string");
attribute.setValue("answer1");
attributes[0] = attribute;
attribute = new WorkflowTokenAttribute();
attribute.setName("param2");
attribute.setType("number");
attribute.setValue("123");
attributes[1] = attribute;
vsoWebControl.answerWorkflowInput(token.getId(), attributes, username,
password);
}
In the preceding example, if the workflow is in the waiting state, the application creates two
WorkFlowTokenAttribute objects. The objects call the various WorkFlowTokenAttribute operations to obtain the attribute values. The process then adds these WorkFlowTokenAttribute objects into a
WorkflowTokenAttribute array.
4 Cancel a workflow by calling the cancelWorkflow operation.
You can cancel a workflow at any time using the cancelWorkflow operation.
vsoWebControl.cancelWorkflow(workflowTokenId, username, password);
5 Check that the workflow canceled successfully.
Because the cancelWorkflow operation does not return anything, you must obtain the WorkflowToken status to make sure the workflow canceled successfully, as the following code example shows.
String[] status = vsoWebControl.getWorkflowTokenStatus(tokenIds, username, password); if ("canceled".equals(status) == true) {
System.out.println("Workflow canceled");
}
The Web service client interacts with workflows by finding their status, supplying input parameters from user interactions, and by canceling the workflows.
What to do next
Implement operations in the Web services client to extract the workflow results.
Obtain Workflow Results
After the workflow completes its run, you can retrieve the results by calling the getWorkflowTokenResult( ) operation.
Prerequisites
You must have implemented how workflows start in the Orchestrator server in the Web services client.
260 VMware, Inc.
Chapter 8 Developing a Web Services Client
Procedure
1 Obtain the results of a running workflow by calling the getWorkflowTokenResult( )
operation.
The getWorkflowTokenResult( ) operation stores the results as an array of attributes.
WorkflowTokenAttribute[] retAttributes =
vsoWebControl.getWorkflowTokenResult(token.getId(),
username, password);
The preceding example code obtains the result of a workflow token with a specific identifier.
2 (Optional) Print the workflow results.
WorkflowTokenAttribute resultCode = retAttributes[0];
WorkflowTokenAttribute resultMessage = retAttributes[1];
System.out.println("Workflow output code ... (" + resultCode.getValue() + ")");
System.out.println("Workflow output message... (" + resultMessage.getValue() + ")");
3 Emit the workflow token's result attributes for display or for use by other applications.
for (int ii = 0; ii < retAttributes.length; ii++) {
System.out.println("\tName:'" + retAttributes[ii].getName()
+ "' - Type:'" + retAttributes[ii].getType()
+ "' - Value:'" + retAttributes[ii].getValue()
}
The preceding example code prints out the name, type, and value of the workflow token's result attributes.
You defined a Web services client that finds objects in Orchestrator, runs workflows on them, interacts with the running workflows, and extracts the results of running those workflows.
Time Zones and Running Workflows Through Web Services
Running workflows through Web services can lead to erroneous timestamping, if the run request comes from an application running in a different time zone to the Orchestrator server.
If a workflow takes the time and date as an input parameter, and generates the time and date as output when it runs, and if this workflow runs through a Web services application, the time and date sent as an input parameter reflects the time and date of the system on which the Web services application is running. The time and date that the workflow sends as its output reflects the time and date of the system on which the Orchestrator server is running. If the Web services application is running in a different time zone than the Orchestrator server, the time returned by the workflow does not match the time that the Web services application provided as input when it called executeWorkflow or getWorkflowTokenResult .
To avoid this problem, you can create a function to compare dates in your Web services application. You must serialize the date and time, taking the time zone information into account. The following Java code example shows how to transform a String that Orchestrator returns into a
Date
object.
public Date dateFromString(String value){
java.text.DateFormat s_dateFormat = new java.text.SimpleDateFormat("yyyyMMddHHmmssZ");
Date date = null;
if (value != null && value.length() > 0) {
try {
date = s_dateFormat.parse(value);
} catch (ParseException e) {
System.err.println("Converting String to Date : ERROR");
date = null ;
}
}
return date;
}
VMware, Inc. 261
vCenter Orchestrator Developer's Guide
Web Service Application Examples
Orchestrator provides working examples of Web services client applications that provide Web access to
Orchestrator.
You can download the Orchestrator examples ZIP file from the VMware vCenter Orchestrator Documentation
download page. For information about where to find the documentation download page, see “Example
Web Service API Object Reference
The Orchestrator Web service API provides a collection of objects that serve as WSDL complex types and a collection of methods that server as WSDL operations.
FinderResult Object
A
FinderResult
represents an object from the Orchestrator inventory that Orchestrator locates in an external application by using a plug-in. For example, a FinderResult object can represent a virtual machine from vCenter Server.
FinderResult objects represent any object that a plug-in registers with Orchestrator in its vso.xml
file.
FinderResult
objects represent the items, from all installed plug-ins, that you find when you call one of the find* operations. The items returned can be any type of object that an Orchestrator plug-in defines. Most workflows require FinderResult instances as input parameters, as most workflows act upon Orchestrator objects.
You cannot set a FinderResult as a workflow attribute directly. You must set WorkflowTokenAttribute in workflows instead, which take the type and the dunesUri from FinderResult objects.
The find operation finds objects according to query criteria that the vso.xml
file defines. It does not return
FinderResult objects directly, but returns QueryResult objects instead. QueryResult objects contain arrays of
FinderResult objects.
The objects searched for can also be identified by ID or by relation using the findForId and findRelation operations, as the following example shows.
public FinderResult findForId(String type, String id, String username, String password); public FinderResult[] findRelation(String parentType, String parentId, String relation, String username, String password);
N
OTE
FinderResult
is not an Orchestrator scriptable object.
The following table shows the properties of the
FinderResult
object.
Type
String
String
Array of properties
String
Value Description type id
Type of object found.
ID of the discovered object.
properties A list of the discovered object's properties.
The format of the properties values is defined by each plug-in in its vso.xml file, under the FinderResult description.
dunesUri A string representation of the object.
If a FinderResult object is accessed through a plug-in, it is identified by a dunesUri string, rather than by another type of string or ID. The format of the dunesUri is as follows.
dunes://service.dunes.ch/CustomSDKObject?id=' <object_ID>'
&dunesName=' <plug-in_name>:<object_type>'
262 VMware, Inc.
Chapter 8 Developing a Web Services Client
ModuleInfo Object
ModuleInfo
stores the name, version, description, and display name attributes for each plug-in. A Web service application can use these attributes to modify its behavior based on the presence or absence of certain plugins or plug-in versions.
The getAllPlugins operation returns arrays of ModuleInfo objects to list all the plug-ins a user can access, as the following example shows.
public ModuleInfo[] getAllPlugins(username, password);
The following table shows the properties of the ModuleInfo object.
Type Value Description
String moduleName Name of the plug-in, used as a prefix in object names.
String moduleVersion Plug-in version.
String moduleDescription Description of the plug-in.
String moduleDisplayName Plug-in name shown in the Orchestrator inventory.
Property Object
A
Property
object represents a key-value pair that describes the properties of an item in the Orchestrator inventory.
You can obtain a Property object by calling the getProperties operation on a FinderResult object, as the following example shows.
Property[] props = finderResult.getProperties();
This example method call returns the contents of the FinderResult object's properties attribute.
The following table shows the properties of the
Property
object.
Type Value Description
String name Property name.
String value Property value.
The format of a property's values is defined by each plug-in in its vso.xml file, under the
FinderResult description.
QueryResult Object
The QueryResult object represents the results of a find query.
A
QueryResult
object contains an array of
FinderResult
objects and a counter. A
QueryResult
object is returned by the find operation, as the following example shows.
public QueryResult find(String type, String query, String username,
String password);
The following table shows the properties of the QueryResult object.
VMware, Inc. 263
vCenter Orchestrator Developer's Guide
Type Value Description
Long
FinderResult[] totalCount The total number of objects found.
The QueryResult object contains an array of FinderResult objects. The vso.xml file for the relevant plug-in sets the number of FinderResult objects the query returns. The standard plug-ins that Orchestrator provides all return an unlimited number of
FinderResult objects. The totalCount property reports the total number of
FinderResult objects found. If the value of totalCount is greater than the number set by the plug-in, the array of FinderResults returned does not include all the objects found in the queried inventory.
elements An array of FinderResult objects.
Workflow Object
A Workflow object represents an Orchestrator workflow that defines a certain sequence of tasks, decisions, and operations.
Users with the correct permissions can obtain specific Workflow objects by name or by ID, or they can obtain all the workflows they have the permission to see.
Orchestrator provides the following operations to obtain
Workflow
objects.
public Workflow[] getWorkflowsWithName(String name, String username, String password); public Workflow getWorkflowForId(String workflowId, String username, String password); public Workflow[] getAllWorkflows(String username, String password);
The following table shows the properties of the Workflow object.
Type Value Description
String id The workflow ID.
The id string is a globally unique ID string. Workflows that Orchestrator creates have identifiers that are very large strings, with a very low probability of namespace collision.
String name The name of the workflow, as it appears in the workflow's Name text box in
Orchestrator.
A detailed description of what the workflow does.
String description
WorkflowParameter[] inParameters The inParameters array is the set of WorkflowParameter objects that are the workflow's input parameters. The workflow can manipulate these input parameters or use them directly as the input parameters for tasks and other workflows.
You can set up arbitrary input parameters to provide any necessary input parameters. Omitting a required parameter at runtime causes the workflow to fail.
WorkflowParameter[] outParameters The outParameters array is the set of WorkflowParameter objects that result from running a workflow. This array allows the workflow to send errors, the names of any created objects, and other information as output.
You can set up arbitrary output parameters to generate any information that you need.
WorkflowParameter[] attributes The attributes array is a set of WorkflowParameter objects that represent constants and preset variables for a given workflow. Attributes differ from inParameters because they are intended to represent environmental constants or variables, rather than runtime information.
N
OTE
You cannot retrieve workflow attribute values by using the Web service. You can only retrieve output parameter values.
264 VMware, Inc.
Chapter 8 Developing a Web Services Client
WorkflowParameter Object
The
WorkflowParameter
object defines a parameter in a workflow, for example, an input, an output, or an attribute.
Workflow developers can set up arbitrary parameters to provide any input parameters or output parameters that the workflows need. The format of the parameters is defined entirely by the workflow.
The following table shows the properties of the WorkflowParameter object.
Type Value Description
String name The parameter name.
String type The parameter type.
WorkflowToken Object
A
WorkflowToken
object represents a specific instance of a workflow in the running
, waiting
, waiting-signal
, canceled , completed or failed state.
You obtain a WorkflowToken object by starting a workflow or by obtaining an existing workflow token by its
ID, as the following method signatures show.
public WorkflowToken executeWorkflow(String workflowId, String username, String password,
WorkflowTokenAttribute[] attributes); public WorkflowToken getWorkflowTokenForId(String workflowTokenId, String username, String password);
The following table shows the properties of the WorkflowToken object.
Type Value Description
String id
String title
The identifier of this particular instance of a completed workflow.
The title of this particular instance of a completed workflow.
By default, the WorkflowToken title is the same as the Workflow title, although some operations do allow you to set a different WorkflowToken title when you start the workflow.
String workflowId The identifier of the workflow of which this WorkflowToken object is a running instance.
String currentItemName The name of the step in the workflow that is running at the moment when getWorkflowTokenForId is called.
String currentItemState The state of the current step in the workflow, with the following possible values: n running : the step is running n waiting : the step is waiting for runtime parameters, which can be provided by answerWorkflowInput n n n n waiting-signal : the step is waiting for an external event from a plug-in canceled : the step was canceled by a user or API-integrated program completed : the step has finished failed : the step encountered an error
You must run getWorkflowTokenForId every time you update this value.
N
OTE
VMware recommends that you do not use currentItemState. The globalState property makes currentItemState redundant.
VMware, Inc. 265
vCenter Orchestrator Developer's Guide
Type Value
String globalState
String startDate
String endDate
String xmlContent
Description
The state of the workflow as a whole, with the following possible values: n running : the workflow is running n n waiting : the workflow is waiting for runtime parameters, which can be provided by answerWorkflowInput waiting-signal : the workflow is waiting for an external event n n canceled : the workflow was canceled by a user or by an application completed : the workflow has finished n failed : the workflow encountered an error
The globalState is the state of the workflow as a whole.
You must run getWorkflowTokenForId every time you update this value.
The date and time that this workflow token started
The startDate value is set at the moment the workflow starts. When you obtain a token, its startDate has already been initialized.
Date and time that this workflow token ended, if the workflow token has finished.
The endDate value is filled in at the moment the workflow reaches the end of its run.
The endDate is only set when the workflow finishes in one of the completed, failed or canceled states.
Defines input parameters, output parameters, attributes, and the content of error messages.
The values of the attributes and parameters are set in CDATA elements and error messages are set in <exception> tags, as the following example shows.
<token>
<atts>
<stack>
<att n='attstr' t='string' e='n'>
<![CDATA[attribute]]>Attribute value</att>
<att n='instr' t='string' e='n'>
<![CDATA[]]>Input parameter value</att>
<att n='outstr' t='string' e='n'>
<![CDATA[]]>Output parameter value</att>
</stack>
</atts>
<exception encoded='n'>Error message</exception>
</token>
WorkflowTokenAttribute Object
A WorkflowTokenAttribute object represents an input or output parameter of a running instance of a workflow.
A
WorkflowTokenAttribute
is a value that you pass to a predefined
WorkflowParameter
when a
WorkflowToken begins, or in some cases, at runtime. When you run a workflow, you supply the input parameters for that particular workflow as WorkflowTokenAttribute objects. The executeWorkflow operation takes an array of WorkflowTokenAttribute objects as an argument when you call it, as the following example shows.
public WorkflowToken executeWorkflow(String workflowId, String username,
String password, WorkflowTokenAttribute[] attributes);
Workflows also use WorkflowTokenAttribute as the output parameter of a run workflow.
WorkflowTokenAttribute contains the results of a completed WorkflowToken created by running executeWorkflow . You can collect the result of a WorkflowToken , in the form of a WorkflowTokenAttribute , by calling getWorkflowTokenResult , as the following example shows.
public WorkflowTokenAttribute[] getWorkflowTokenResult(String workflowTokenId,
String username, String password);
266 VMware, Inc.
Chapter 8 Developing a Web Services Client
You can also pass an array of
WorkflowTokenAttribute
objects to the answerWorkflowInput
operation to provide input that a workflow token needs while it runs.
public void answerWorkflowInput(String workflowTokenId,
WorkflowTokenAttribute[] answerInputs, String username, String password);
The following table shows the properties of the WorkflowTokenAttribute object.
Type Value Description
String name Name of the input or output parameter
String type Type of input or output parameter
String value The value property represents either the input or output parameter value for this particular workflow token, in the form of a string.
If the type is an array of objects, the value is a string of the following format:
"#{#<type1>#<value1>#;#<type2>#<value2>#...}#"
If the value property specifies an object obtained from a plug-in, then the input or output parameter value is a dunesUri string that points to the object in question. The following example shows the format of the dunesUri .
dunes://service.dunes.ch/CustomSDKObject?id=' <object_ID>'&dunesName='<plugin_name>:<object_type>'
Web Service API Operation Reference
The Orchestrator Web service API provides a collection of methods that server as WSDL operations.
N
OTE
Every Web service operation, except echo , echoWorkflow , and sendCustomEvent uses the Orchestrator user name and password to authenticate the session. The operations throw exceptions if you use the incorrect username or password.
answerWorkflowInput Operation
The answerWorkflowInput operation passes information from a user or an external application to a workflow while the workflow is running.
If a running workflow reaches a stage that requires an input from a user action or external application, the
WorkflowToken enters the waiting state until it receives the input from answerWorkflowInput . The answerWorkflowInput operation provides input in the form of an array of WorkflowTokenAttribute objects.
The answerWorkflowInput operation is declared as the following example shows.
public void answerWorkflowInput(String workflowTokenId, WorkflowTokenAttribute[] answerInputs,
String username, String password);
The Web service performs only a simple validation of the input attributes you provide for running a workflow.
The Web service verifies only that the attributes that you set in the WorkflowTokenAttribute objects are of the expected type. The Web service does not perform complex validation to verify that you set all of the
WorkflowTokenAttribute objects' properties correctly. The Web service does not access the parameter properties that the workflow developer set in the workflow Presentation. If one of the
WorkflowTokenAttribute
objects' properties is not set, or if an attribute value is not one that the workflow expects, the Web service sends the answerWorkflowInput request, with the invalid WorkflowTokenAttribute object. If a WorkflowTokenAttribute object is invalid, the workflow fails, entering the failed state without informing the Web service application. Your Web service application can check whether a workflow runs correctly or fails by calling the getWorkflowTokenStatus
operation during and after the workflow runs.
VMware, Inc. 267
vCenter Orchestrator Developer's Guide
Type
String
Array of WorkflowTokenAttribute objects
String
String
Value Description workflowTokenId The ID of a running workflow that is waiting for input from a user interaction or external application answerInputs username password
The result of the user interaction or external application, passed as input to the waiting workflow
Orchestrator user name
Orchestrator password
Return Value
No return value. Throws an exception if you pass it an invalid parameter.
cancelWorkflow Operation
The cancelWorkflow operation cancels a workflow.
The behavior of the cancelWorkflow operation depends on the workflow that it cancels. A canceled workflow stops running in the Orchestrator server and enters the canceled state, but the actions that it has already run or started running do not stop or reverse themselves. For example, if a workflow is performing a Power On
Virtual Machine operation when you cancel it, the virtual machine does not stop powering on, nor does it power itself off if it has already started.
The cancelWorkflow
operation is declared as follows.
public void cancelWorkflow(String workflowTokenId, String username, String password);
Type Value Description
String workflowTokenId The identifier of the running workflow to cancel
String username Orchestrator user name
String password Orchestrator password
Return Value
No return value. The cancelWorkflow operation returns an exception if you pass it an invalid parameter.
echo Operation
The echo operation tests the connection to the Web service by returning a String message.
The echo operation is declared as follows.
public String echo(String echo);
Type Value Description
String echo An arbitrary String. If the Web service connection is working correctly, it returns the String.
Return Value
Returns the same String as you provide as an input parameter.
268 VMware, Inc.
Chapter 8 Developing a Web Services Client
echoWorkflow Operation
The echoWorkflow
operation tests the connection to the Web service by checking serialization.
The echoWorkflow operation provides a useful debugging tool if you are connecting to an older Web service implementation. Calling this operation verifies the connection to the server by checking that the serialize and deserialize operations work correctly.
The echoWorkflow operation is declared as follows.
public Workflow echoWorkflow(Workflow workflow);
Type Value Description
Workflow workflow The echoWorkflow operation takes a Workflow object as a parameter. If the connection and serialization are working correctly, it returns the same workflow.
Return Value
Returns the same Workflow object as the object provided as an input parameter.
executeWorkflow Operation
The executeWorkflow operation runs a specified workflow.
The executeWorkflow takes an array of WorkflowTokenAttribute objects as input parameters, which provide the specific attributes with which this particular workflow instance runs.
The executeWorkflow operation is declared as follows.
public WorkflowToken executeWorkflow(String workflowId, String username, String password,
WorkflowTokenAttribute[] attributes);
Type
String
String
String
Array of WorkflowTokenAttribute instances
Value Description workflowId username password
The identifier of the workflow to run
Orchestrator user name
Orchestrator password workflowInputs Array of input parameters required to run the workflow
Return Value
Returns a WorkflowToken object. Returns an exception if you pass it an invalid parameter.
find Operation
The find operation finds elements that correspond to a particular query.
The find operation obtains objects of any type by searching for a particular name. The query results are provided in the form of a QueryResult object, which contains an array of FinderResult objects with a total counter. The query itself is passed to find as the second parameter, as the following operation declaration shows.
public QueryResult find(String type, String query, String username, String password);
VMware, Inc. 269
vCenter Orchestrator Developer's Guide
Query parsing is performed by the plug-in that contains the objects you are looking for. The query language used by the find
operation is defined by the plug-in. Consequently, the syntax of the query
parameter differs according to the implementation of the plug-in. Most of the officially supported Orchestrator plug-ins do not store any objects in the inventory, so they do not expose anything that can be searched for.
the syntax and behavior for the query parameter for the officially supported Orchestrator plug-ins.
This table describes the find operation query parameter syntax for each of the supported Orchestrator plugins.
Table 8-1. Query Syntax of the Orchestrator Plug-Ins
Orchestrator Plug-In
Database (for example Lifecycle
Manager)
Enumeration
Jakarta common set
JDBC
Library
SSH
VMware Infrastructure 3.5
Query Parameter Syntax
String
Not applicable
Not applicable
Not applicable
Not applicable
Not applicable
If you have configured Orchestrator to use SSH connections, you can make queries SSH commands.
String or null
Query Behavior
Searches for object names in SQL database tables. that Orchestrator sets the search String in an SQL WHERE keyword search. It searches the primary keys, then the object IDs in the database.
The enumeration plug-in stores nothing in the inventory. You can find enumerations on each data type that contains enumeration types.
The Jakarta plug-in stores nothing in the inventory.
The JDBC plug-in stores nothing in the inventory.
The library plug-in stores nothing in the inventory.
The mail plug-in stores nothing in the inventory.
The SSH plug-in stores nothing in the inventory.
vCenter Server 4.0
XML
String or null
Not applicable
Ignores the query string and returns all objects of the specified type.
Ignores the query string and returns all objects of the specified type.
The XML plug-in stores nothing in the inventory.
When you develop plug-ins, you can define a query language to use find to search for named objects through the custom plug-in. This definition is not mandatory. The syntax of the query parameter is entirely dependent on the query language that the plug-in implements. To avoid defining a query language, make find return all objects, as in the case of the VMware Infrastructure plug-ins.
The size of the array of objects that the QueryResult returns depends on the definition of the plug-in through which you make the query. For the queries you make through the standard Orchestrator plug-ins, the array contains an unlimited number of FinderResult objects. Developers of third-party plug-ins, however, can set a limit on the number of results the query returns. In these cases, if the value of totalCount exceeds the number of objects in the array of FinderResult objects, the array does not include all the objects found in the queried inventory. The totalCount property does report the total number of FinderResult objects found. The totalCount
property can be negative, which signifies that the plug-in cannot determine how many corresponding objects are in the plug-in.
270 VMware, Inc.
Chapter 8 Developing a Web Services Client
Type Value Description
String type
String query
Type of object looked for.
The query.
The query is a string enclosed in quotation marks. Any object of the type specified by the type parameter with a name that matches the query string is returned in the QueryResult.
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns the result of the query as a QueryResult object.
If find fails to match an object, QueryResult.getTotalCount
returns 0 and QueryResult.getElement
returns null.
If the server does not recognize the object type or plug-in searched for, find throws an exception. find also returns an exception if you pass it an invalid parameter.
findForId Operation
The findForId operation searches for a specific FinderResult object according to that FinderResult object's type and id properties.
You can use the findForId operation to acquire information about FinderResult objects you have already found by using the other find* operations. For example, you can use the findForId method to obtain the state of a
FinderResult object you found by using the find operation.
The findForId operation is declared as the following example shows.
public FinderResult findForId(String type, String id, String username,
String password);
Type Value Description
String type
String id
Type of object looked for.
ID of the object looked for.
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns a
FinderResult
object containing details of the object found. Returns null if you pass it an invalid parameter.
findRelation Operation
The findRelation operation finds all the children elements in an inventory that belong to a particular parent or type of parent.
Knowing how a child is related to its parent is useful if you develop tree viewers to view the objects in a library.
The findRelation operation is declared as follows.
public FinderResult[] findRelation(String parentType, String parentId,
String relation, String username, String password);
VMware, Inc. 271
vCenter Orchestrator Developer's Guide
Type Value Description
String parentType The type of parent object.
The parentType property can be the name of a plug-in, or it can specify a more narrowly defined parent. For example, you can specify the parentType as "VC:" to obtain the objects at the root of
VMware vCenter Server plug-in, or you can a specific folder, such as "VC:VmFolder".
String parentId
String relation
String username
String password
The ID of a particular parent object.
The parentId parameter allows you to find the children of a specific parent object, if you know its
ID.
The name of the relation.
Calling findRelation returns all children elements under a parent identified by its parentId. If you omit the parentId the parentType is not the root type of the inventory, the findRelation operation returns null.
See
“Relation Types,” on page 272 for more information.
Orchestrator user name.
Orchestrator password.
Relation Types
The relation
property types are defined by the plug-ins. The validity of relations depends on the parent type.
This table lists the relation types defined by each of the standard plug-ins provided by Orchestrator.
Table 8-2. Standard Orchestrator Relation Types
Plug-In Relation Names
Enumerations
Jakarta
Commons Net
JDBC
Library
Networking
No relations
No relations
No relations
No relations
No relations
SSH
Relation Types
No relations
No relations n n n n
No relations
No relations n n n n n n n
No relations
IpAddress
IPV4Address
MacAddressPool
NetworkDomain
Proxy
Subnet
Range
File
Folder
RootFolder
SshConnection
272 VMware, Inc.
Chapter 8 Developing a Web Services Client
Table 8-2. Standard Orchestrator Relation Types (Continued)
Plug-In Relation Names vCenter Server n getComputeResource_ClusterComputeResource() n getComputeResource_ComputeResource() n n getDatacenter() getDatastore() n n n n getDatastoreFolder() getFolder() getFolder() getFolder() n n n n n n n n getFolder() getFolder() getHost() getHostFolder() getNetwork() getNetworkFolder() getNetwork_DistributedVirtualPortgroup() getNetwork_Network() n n n n n n n n n n n n getOwner() getParentFolder() getPortgroup() getRecentTask() getResourcePool() getResourcePool_ResourcePool() getResourcePool_VirtualApp() getRootFolder() getSdkConnections() getVm() getVmFolder() getVmSnapshot()
XML No relations
Relation Types n n n n n n n n n n n n n n n n n n n n n n n n n n n n
ClusterComputeResource
ComputeResource
Datacenter
Datastore
DatastoreFolder
DatacenterFolder
DatastoreFolder
HostFolder
NetworkFolder
VmFolder
HostSystem
HostFolder
Network
NetworkFolder
DistributedVirtualPortgroup
Network
ComputeResource
VmFolder
DistributedVirtualPortgroup
Task
ResourcePool
ResourcePool
VirtualApp
DatacenterFolder
SdkConnection
VirtualMachine
VmFolder
VirtualMachineSnapshot
No relations
The relation property can also reference relation types specified in each plug-in's vso.xml
file. The following example is an excerpt from the networking plug-in vso.xml
file.
[...]
<relations>
<relation name="Subnet" type="Class:Subnet"/>
<relation name="Range" type="Class:Range"/>
<relation name="NetworkDomain" type="Class:NetworkDomain"/>
<relation name="MacAddressPool" type="Class:MacAddressPool"/>
</relations>
[...]
In addition to the relation types listed in Table 8-2 , Orchestrator also defines the
CHILDREN
relation, to represent all relation types.
Return Value
Returns a list of FinderResult objects.
Returns an exception if no children are found or if you pass it an invalid parameter.
VMware, Inc. 273
vCenter Orchestrator Developer's Guide
274
getAllPlugin Operation
The getAllPlugin
operation returns the description of all the plug-ins installed in Orchestrator.
I
MPORTANT
The getAllPlugin operation is deprecated since Orchestrator 4.0. Use getAllPlugins instead.
getAllPlugins Operation
The getAllPlugins operation returns the description of all the plug-ins installed in Orchestrator.
Many of the actions that you perform using Orchestrator depend on functions that you enable through plugins. Workflows might depend on the existence of certain custom plug-ins, or on standard plug-ins that the administrator has disabled. Consequently, you can check that the necessary plug-ins are present before you run a workflow. Without the necessary plug-ins, some object types used by workflows might be absent.
The getAllPlugins
operation lists all the available plug-ins as an array of
ModuleInfo
objects. The
ModuleInfo objects store the name, version, description, and name for each plug-in. A Web service application can use these attributes to modify its behavior based on the presence or absence of certain plugged-in modules or versions.
The getAllPlugins operation is declared as follows.
public ModuleInfo[] getAllPlugins(username, password);
N
OTE
The getAllPlugins operation replaces the deprecated operation getAllPlugin .
The following table describes the getAllPlugins operation properties.
Type Value Description
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns a list of plug-in descriptions as ModuleInfo objects.
getAllWorkflows Operation
The getAllWorkflows operation finds all available workflows.
The getAllWorkflows
operation lists all the workflows available in an Orchestrator server as an array of
Workflow objects. The getAllWorkflows operation is also useful for programs that must list information about workflows, such as the workflows' names, IDs, and so on. The Workflow objects present all the relevant information about the workflows.
The getAllWorkflows
operation is declared as follows.
public Workflow[] getAllWorkflows(String username, String password);
Type Value Description
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns an array of Workflow objects.
VMware, Inc.
Chapter 8 Developing a Web Services Client
getWorkflowForId Operation
The getWorkflowForId
operation retrieves a workflow identified by its unique ID.
If you know the ID of a specific workflow, you can use the getWorkflowForID operation to obtain the workflow object. Multiple workflows running through different plug-ins might have the same name. The safest way to obtain workflows is to use the getWorkflowsWithName operation to obtain their ID, rather than by obtaining them by name.
You can find out a workflow ID by checking the workflow's workflowID
property, as the following example shows.
String workflowId = workflows[0].getId();
The getWorkflowForId operation is declared as follows.
public Workflow getWorkflowForId(String workflowId, String username, String password);
Type Value Description
String workflowId ID of the workflow to retrieve.
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns the Workflow object that corresponds to the provided ID. Returns null if you pass it an invalid parameter.
getWorkflowsWithName Operation
The getWorkflowsWithName operation searches for workflows by their name.
The getWorkflowsWithName operation is declared as follows.
public Workflow[] getWorkflowsWithName(String workflowName, String username, String password);
If you know the name (or a part of the name) of a particular workflow, you can obtain this workflow by calling getWorkflowsWithName . The getWorkflowsWithName operation returns an array of workflows, so it can be used to find several workflows at one time.
I
MPORTANT
The getWorkflowsWithName operation is a convenient means of obtaining workflows, but you should not use it in production applications because workflow names can change. Use the getWorkflowForId operation rather than the getWorkflowsWithName
operation in production applications.
Type Value Description
String workflowName Name of the workflow to find.
The value of the workflowName property can be a full name or a wildcard (*), which returns all the workflows available to the user. You can also search for partial names. For example, if you enter *Clone or Clone* as the workflowName, this returns all workflows with names that contain the word Clone.
String username
String password
Orchestrator user name.
Orchestrator password.
VMware, Inc. 275
vCenter Orchestrator Developer's Guide
Return Value
Returns an array of Workflow objects that correspond to the provided name or name fragment. Workflows are returned in an array even if only one workflow is found. Returns null if you pass it an invalid parameter.
getWorkflowTokenForId Operation
The getWorkflowTokenForId operation finds the WorkflowToken object for a specific workflow token.
The getWorkflowTokenForId operation is declared as follows.
public WorkflowToken getWorkflowTokenForId(String workflowTokenId, String username,
String password);
Individual threads or functions can run multiple workflows. The getWorkflowTokenForId operation allows a central process or thread to track the progress of each workflow. Using getWorkflowTokenForId provides access to all the information about a specific
WorkflowToken
because, although checking the token status only requires the ID, it is often useful to obtain all the information about a given token.
Type Value Description
String workflowTokenId ID of this run of the workflow
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns a WorkflowToken object for a specific workflow token that corresponds to the provided workflow token
ID.
getWorkflowTokenResult Operation
The getWorkflowTokenResult operation obtains the result of running a given workflow.
You can view the results produced by a WorkflowToken object by calling getWorkflowTokenResult . The results of running a workflow are delivered as an array of WorkflowTokenAttribute objects that contain the output parameters that the workflow set during its run. The structure of the output WorkflowTokenAttribute objects is the same as the structure of the input parameters passed to the workflow when it starts. The parameters have a name, type, and value.
You can obtain the results before the workflow finishes. If the workflow has set its output parameters, you can obtain their values by calling getWorkflowTokenResult while the workflow runs. This method allows the workflow to communicate its results to external systems while it is still in the running state. You can also use getWorkflowTokenResult to obtain results from workflows in the failed , waiting , and canceled states, to show the results of the workflow up to the point it entered a nonrunning or incomplete state.
Objects of the Any type do not deserialize correctly. Consequently, you cannot call getWorkflowTokenResult on a workflow token if one of the token's attributes is of the Any type. If you specify the correct object type, for example, VC:VirtualMachine , then getWorkflowTokenResult returns the correct dunesURI value.
If the object that getWorkflowTokenResult
obtains is a plain Java object, you can perform deserialization on it by using the standard Java API, but to do so you must include the relevant Java class in your classpath. For example, if the object you obtain is of the type VirtualMachineRuntimeInfo , you must include
VirtualMachineRuntimeInfo.class
vc40.jar
or vmware-vmosdk-vc40.jar
in the classpath. You find the vmware-vmosdk-
file in install-directory\VMware\Orchestrator\app-server\server\vmo\tmp\dars\vmware-vmosdkvc40.dar\lib .
276 VMware, Inc.
Chapter 8 Developing a Web Services Client
The getWorkflowTokenResult
operation is declared as follows.
public WorkflowTokenAttribute[] getWorkflowTokenResult(String workflowTokenId,
String username, String password);
Type Value Description
String workflowTokenId ID of this specific run of the workflow
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns an array of WorkflowTokenAttribute objects that correspond to the provided workflow token ID or
IDs. Returns null if you pass it an invalid parameter.
getWorkflowTokenStatus Operation
The getWorkflowTokenStatus operation obtains the globalStatus of specific workflow tokens.
The getWorkFlowTokenStatus operation checks the status of a workflow or an array of workflows while they run. The getWorkFlowTokenStatus operation obtains the globalStatus value from running WorkflowToken objects, identified by their workflowTokenId . The globalStatus value can be one of the following.
n running : the workflow is running n waiting : the workflow is waiting for runtime parameters, which can be provided by answerWorkflowInput n waiting-signal : the workflow is waiting for an external event n canceled
: the workflow was canceled by a user or by an application n completed : the workflow has finished n failed : the workflow encountered an error
The getWorkflowTokenStatus
operation is declared as follows.
public String[] getWorkflowTokenStatus(String[] workflowTokenID, String username,
String password);
Type Value Description
Array of strings workflowTokenId List of workflow token IDs.
String username Orchestrator user name.
String password Orchestrator password.
Return Value
Returns a list of workflow token status values. The returned value is a string array of the globalStatus of each workflow token, ordered by their workflowTokenID values. Returns null if you pass it an invalid parameter.
Related Information
For related information, see “WorkflowToken Object,” on page 265.
VMware, Inc. 277
vCenter Orchestrator Developer's Guide
278
hasChildrenInRelation Operation
The hasChildrenInRelation
operation checks whether a given relation type has any children.
In some cases, objects are most easily located through their relationships with other objects. You can obtain all the objects that relate to another object by a given relation by calling the findRelation operation on that object.
The findRelation operation finds only the relatives of a known object. The hasChildrenInRelation operation checks for the presence of objects that present a given relation
property. hasChildrenInRelation
checks for the presence of objects that are children of other objects and are related to their parents by a given relation type. For example, a snapshot of a virtual machine is a child of the original virtual machine. Checking for all virtual machines that are children of other virtual machines enables you to identify all snapshots.
Knowing how a child is related to its parent is useful if you develop tree viewers to view the objects in the library. The hasChildrenInRelation operation is declared as follows.
public int hasChildrenInRelation(String parentType, String parentId, String relation, String username, String password);
Type Value Description
String parentType Type of parent object. You can narrow the search by specifying the parent type, which limits the result to children related by the given relation to parents of a given parent type.
This value can be null, in which case hasChildrenInRelation checks for child objects related by the specified relation type to all types of parent.
String parentId
String relation
ID of a particular parent object.
Specifying the parentId allows you to check for children related by a given relation to a particular parent. This check is useful if a particular parent has large numbers of children that are related to it by different relation types. The findRelation operation returns all of that parent's children, regardless of the relation type.hasChildrenInRelation checks for the presence of only the children related by the desired relation type.
This value can be null if you call hasChildrenInRelation on the root object of the hierarchy of objects.
The type of relation by which children are related to their parents.
Relation types are specified in the vso.xml file for each plug-in.
String username
String password
Orchestrator user name.
Orchestrator password.
Return Value
Returns one of the following values:
1
-1
0
Yes, children of the specified relation type are present
No, children of the specified relation type are not present
Unknown, or an input parameter is invalid
Related Information
For more information, see
“findRelation Operation,” on page 271.
hasRights Operation
The hasRights
operation checks whether a user has permissions to view, edit, and run workflows.
To check the rights that you have on a workflow, you must have permission to view that workflow. If you have only edit or run permission on a workflow, you cannot view what rights you have on this workflow, and hasRights returns False .
VMware, Inc.
Chapter 8 Developing a Web Services Client
A Web service application can check those rights by calling the hasRights
operation. In the following example, hasRights checks whether the user has the right to read the workflow.
hasRights( workflowId, username, password, 'r')
Type Value Description
String workflowId The ID of the workflow for which you are checking a user's rights.
String username Orchestrator user name.
String password
Int rights
Orchestrator password.
n n n n a : The administrator can change the rights of the object.
c : The user can edit the workflow.
I : The user can inspect the workflow schema and scripting.
r : The user can view the workflow (but not the schema or scripting).
n x : The user can run the workflow.
N
OTE
User rights are not cumulative. To perform all possible tasks on a workflow, a user must have all of the rights.
Return Value
Returns the following values: n True if the user has the specified rights on the workflow.
n False
if the user does not have the specified rights on the workflow.
The hasRights operation returns an "Unable to find workflow" exception if the workflow does not exist or if the user calling hasRights does not have permission to view the workflow.
sendCustomEvent Operation
The sendCustomEvent
operation synchronizes workflows with external events.
public void sendCustomEvent(String eventName, String serializedProperties);
The sendCustomEvent operation sends messages from Web service clients to workflows that are waiting for a particular event to occur before they run. The waiting workflows resume their run when they receive the message from sendCustomEvent .
A custom event that calls sendCustomEvent
to send a message when it occurs can be any script, workflow, or action that Orchestrator can run. For example, a workflow might use sendCustomEvent to trigger another workflow that reloads all Orchestrator plug-ins when the sending workflow performs a specific action while it is running.
The messages that sendCustomEvent sends are simple triggers, the format of which is not exposed to users. The message triggers the waiting workflow to run at the moment that the server receives it.
I
MPORTANT
Access to the sendCustomEvent operation is not protected by a username and password combination. VMware therefore recommends that you only use this function in secure, internal deployments.
For example, do not use this operation in deployments that operate openly across the Internet.
VMware, Inc. 279
vCenter Orchestrator Developer's Guide
Type Value Description
String eventName The eventName property is the name of the event that a workflow is waiting for before running. The eventName string you pass to sendCustomEvent must match the name of an Event object declared in the script, action or workflow that defines the custom event.
String serializedProperties The serializedProperties property defines the parameters to pass to the waiting workflow as a series of name-value pairs. The syntax of serializedProperties is as follows:
" name1=value1\nname2=value2\nname3=value3"
If the workflow requires no input parameters, the serializedProperties property can be null or omitted.
Return Value
No return value informs applications that the sendCustomEvent operation ran successfully.
The sendCustomEvent operation returns an exception if you pass it an invalid parameter.
Receiving Messages from sendCustomEvent
Workflows waiting for a message from sendCustomEvent before they run must declare the event they are waiting for by calling the
System.waitCustomEventUntil
operation from the Orchestrator API. The following example shows two calls to waitCustomEventUntil .
System.waitCustomEventUntil("internal", customEventKey, myDate);
System.waitCustomEventUntil("external", customEventKey, myDate);
The waitCustomEventUntil operation's parameters are as follows.
internal / external customEventKey myDate
The awaited event comes from another workflow ( internal ) or from a Web service application ( external ).
The name of the awaited event.
The date until which waitCustomEventUntil
waits for a message from sendCustomEvent .
simpleExecuteWorkflow Operation
The simpleExecuteWorkflow operation uses string attributes to start a workflow.
I
MPORTANT
This operation is deprecated since Orchestrator 4.0. Do not use simpleExecuteWorkflow .
Type Value Description
String workflowId ID of the Workflow to be run.
String username Orchestrator user name.
String password Orchestrator password.
String attributes The format for the attributes parameter is a list of attributes separated by commas. Because commas are used as separators, attribute name strings containing commas are not processed correctly.
Each attribute is represented by its name, type, and value, as shown in the following examples.
Name1,Type1,Value1,Name2,Type2,Value2
Return Value
Runs a workflow. Returns a WorkflowToken object.
280 VMware, Inc.
Developing Web Views
9
Orchestrator Web views are Web 2.0 frontends that allow users to access Orchestrator workflows and objects in the Orchestrator inventory by using a Web browser rather than by using the Orchestrator client.
Orchestrator provides a standard Web view that users can use to run workflows, called weboperator. The weboperator Web view provides end users with browser access to all of the workflows in the library, that they can run on all of the objects in the inventory.
Orchestrator provides a set of Web components that you can use to develop custom Web views to perform other orchestration operations through a browser.
n n
A Web view is a package of Web pages, style sheets, icons, and banners that represent a complete Web site. Web views can contain special Java Web Components (JWC) that add Orchestrator functions to the pages of the Web views. For example, you can add components that allow users to run workflows from a browser.
Weboperator Web View on page 282
Orchestrator provides a standard Web view called weboperator that allows users to run workflows from a browser.
n n n n
Web View Development Tasks to Perform in Orchestrator on page 283
You create the Web pages and Web view components that form an Orchestrator Web view by using Web development tools. You also use the Orchestrator client and configuration interface to perform many of the steps of Web view development.
File Structure of a Web View on page 293
When you develop a Web view, you must save the collection of Web pages and Web view components that comprise the Web view to a working folder. The Web view working folder must conform to basic file-naming and file-structuring rules.
Web View Home Page on page 293
All Web views must contain a file named default.html
, that you must save at the root of the Web view working folder. The default.html
file is the home page of the Web view.
Web View Components on page 294
Web view components add Orchestrator functions to Web pages. For example, you can add Web view components to Web pages that allow users to run workflows from a Web page in a browser.
VMware, Inc. 281
vCenter Orchestrator Developer's Guide n n
Accessing Server Objects from URLs on page 309
You can add URLs to Web view pages to access objects in the Orchestrator server, without having to implement a Web view component. For example, you can add URLs to Web view pages that run an action in the Orchestrator server or URLs that retrieve resource elements from the Orchestrator server.
Create a Simple Web View Using the Default Template on page 312
The easiest way to create a Web view is to use a template. Orchestrator provides a default Web view template to help you create Web views.
Web View Overview
A Web view is a package of Web pages, style sheets, icons, and banners that represent a complete Web site.
Web views can contain special Java Web Components (JWC) that add Orchestrator functions to the pages of the Web views. For example, you can add components that allow users to run workflows from a browser.
Orchestrator Web views update content dynamically without obliging users to reload complete pages.
Orchestrator provides a library of Tapestry Framework 4.0 components to help you build customized Web views to access Orchestrator functions from a Web browser. Tapestry components provide access to objects in the Orchestrator server, such as the workflows in the library and the virtual machines in the inventory. You can also insert Dojo 0.4.1 components into Web views.
Orchestrator provides a Web view template that you can use as the basis for developing Web views. The Web view template contains skeleton HTML pages and Web view components that you can extend and adapt. You can also export existing Web views to use as templates that you can adapt to create new Web views.
You typically create or modify the pages of a Web view externally by using Web design tools. Creating or modifying Web pages independently of Orchestrator allows you to separate the Web design process from the process of developing Orchestrator Web view components. You import the Web view pages and components into the Orchestrator server and complete the process of creating the Web view in the Orchestrator client.
Developing Orchestrator Web views can require knowledge of some or all of the following Web development technologies and standards. For documentation about the different technologies, consult the Web sites of the organizations that maintain the standards.
n n
Cascading stylesheets (CSS). See http://www.w3.org/Style/CSS/ .
Ajax platform. See http://www.ajax.org/ .
n n n n n
Dojo toolkit. See http://www.dojotoolkit.org/ .
Java programming language. See http://www.oracle.com/technetwork/java/index.html
.
Java Web Components (JWC) from the Tapestry Framework. See http://tapestry.apache.org/ .
JavaScript Object Notation (JSON). See http://www.json.org/ .
Object-Graph Navigation Language (OGNL). See http://www.opensymphony.com/ognl/ .
N
OTE
Third-party URLs are subject to changes beyond the ability of VMware to control. If you find a URL in
VMware documentation that is out of date, notify VMware at [email protected]
. You might be able to locate a third-party document by searching from the third-party home page.
Weboperator Web View
Orchestrator provides a standard Web view called weboperator that allows users to run workflows from a browser.
The weboperator Web view provides an example of the orchestration functions that Web views can provide to end users in browsers, without requiring that those users use the Orchestrator client.
282 VMware, Inc.
Chapter 9 Developing Web Views
Start the Weboperator Web View
You start the weboperator Web view from the Orchestrator client.
Procedure
1 Click the Web Views view in the Orchestrator client.
The weboperator Web view and any other Web views that you have imported into Orchestrator appear.
2 Right-click weboperator and select Publish.
3 Open a browser and go to http:// orchestrator_server:8280 .
In the URL, orchestrator_server is the DNS name or IP address of the Orchestrator server, and 8280 is the default port number where Orchestrator publishes Web views.
4 On the Orchestrator home page, click Web View List.
5 Click weboperator.
6 Log in using your Orchestrator user name and password.
7 Expand the hierarchical list of workflows to navigate through the workflows in the Orchestrator library.
8 Click a workflow in the hierarchical list to display information about the workflow in the right pane.
9 In the right pane, select whether to run the workflow now or at a later time.
Option Action
Run the workflow now
Run the workflow at a later time a Click Execute Workflow to run the workflow.
b Provide the required input parameters and click Submit to run the workflow.
a Click Schedule Workflow to run the workflow at a later time.
b Provide the time, date, and recurrence information to set when and how often to run the workflow and click Next.
c Provide the required input parameters and click Submit to schedule the workflow.
You can use the weboperator Web view to run workflows on objects in your inventory from a Web browser rather than from the Orchestrator client.
What to do next
If you only need a Web view to access the inventory and run workflows, the standard weboperator Web view should meet your requirements. If you require more complex functionality from a Web view, you can use the
Web components and default Web view template that Orchestrator provides to develop custom Web views.
Web View Development Tasks to Perform in Orchestrator
You create the Web pages and Web view components that form an Orchestrator Web view by using Web development tools. You also use the Orchestrator client and configuration interface to perform many of the steps of Web view development.
When you develop Web views, you use the Orchestrator client to perform tasks such as creating skeleton Web views, declaring objects in the Orchestrator server as Web view attributes, exporting and importing files to and from working directories, and creating and using templates to create other Web views. You set the
Orchestrator server to Web view development mode by using the Orchestrator configuration interface.
VMware, Inc. 283
vCenter Orchestrator Developer's Guide n n n n n n n n n n n n
Create a Web View Skeleton on page 284
You can create a Web view by creating a Web view skeleton. A Web view skeleton contains no HTML files or Web view components, and requires you to create these elements using Web development tools.
Export a Web View as a Template on page 285
You can use an existing Web view as a template. You can export a Web view as a template, and then edit the exported template to create a Web view.
Create a Web View from a Template on page 286
You can reduce the amount of development work by creating a Web view from a template.
Define a Web View Template as a Resource Element on page 287
Instead of exporting a Web view to your local system for use as a Web view template, you can define a
Web view template as a resource element in the Orchestrator server.
Create a Web View from a Resource Element Template on page 287
Instead of creating a Web view from the beginning, you can create a Web view from a resource element template that you or another developer has imported to the Orchestrator server.
Export Web View Files to a Working Folder on page 288
When you create a new Web view, either as a skeleton or from a template, you export the Web view files to a working folder on your local system for editing.
Configure the Server for Web View Development on page 289
During the Web view development process, you can configure the Orchestrator server to publish the
Web view from a working folder rather than from the Orchestrator server.
Import Web View Files from a Working Folder on page 290
After you edit the files of a Web view in the working folder, you must import them back to the Web view in the Orchestrator server.
Create a Web View Attribute on page 290
With Web view attributes, you can pass objects to Web view components. The functions that the Web view components define act on these objects to perform the orchestration actions that you run from the
Web view.
Add a Resource Element to a Web View on page 291
Resource elements are external objects that you can import into the Orchestrator server for Web views to use as Web view attributes. Web view attributes identify objects with which Web view components interact.
Disable Web View Development Mode on page 292
If you set the Orchestrator server to Web view development mode during the development process, you must set the Orchestrator server back to its normal mode before you can publish the Web view.
Publish a Web View on page 292
When you finish Web view development and import the modified files to the Web view in the
Orchestrator server, you can publish the Web view.
Create a Web View Skeleton
You can create a Web view by creating a Web view skeleton. A Web view skeleton contains no HTML files or
Web view components, and requires you to create these elements using Web development tools.
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click in the white space in the Web view list and select Add web view.
284 VMware, Inc.
Chapter 9 Developing Web Views
3 Type a name for the Web view in the Create Web View text box and click OK.
4 Right-click the Web view in the Web view list and select Edit.
The Web view editor opens.
5 On the General tab, set the URL folder value to include a suffix for the URL on which Orchestrator will publish the Web view.
For example, if you set the URL folder to MyWebView , Orchestrator publishes the Web view at http:// orchestrator_server:8280/vmo/MyWebView/ , where orchestrator_server is the IP address or
DNS name of the machine on which the Orchestrator server is running.
By default, the name of the URL folder matches the Web view name, but you can change this value.
N
OTE
If the Orchestrator server is running in Web view development mode, the URL folder value must match the name of the working folder in which you are developing the Web view.
6 Click the Version digits to increment the version number for the Web view.
The Version Comment dialog box opens.
7 Type a comment for this version of the Web view and click OK.
For example, type Initial creation if you created the Web view.
8 On the General tab, type a description of the Web view in the Description text box .
9 Click Save and close to close the Web view editor.
You created a Web view skeleton that does not yet contain any HTML pages or Web view components. If you export the Web view skeleton to a working folder, the only file it contains is the
VSO-WEBVIEW-
INF\.webview.xml
file, which sets the Web view name and ID.
What to do next
You must add HTML pages and Web view components to the Web view.
Export a Web View as a Template
You can use an existing Web view as a template. You can export a Web view as a template, and then edit the exported template to create a Web view.
When you export a Web view as a template, Orchestrator creates a ZIP file that contains all the files of the original Web view. You can then create a new Web view that uses these files.
Prerequisites
You must have an existing Web view to export as a template.
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click the Web view to export as a template and select Templates > Export as template.
3 (Optional) Change the name of the ZIP file as appropriate.
4 Select a location on your local system to save the ZIP file and click Save.
You exported the contents of an existing Web view to use as a template from which to create other Web views.
What to do next
Create a new Web view from the template.
VMware, Inc. 285
vCenter Orchestrator Developer's Guide
286
Create a Web View from a Template
You can reduce the amount of development work by creating a Web view from a template.
A Web view template is a ZIP file that contains all the files and components of an existing Web view that you can use as the basis from which to create a new Web view. Orchestrator provides a default Web view template that you can use as the starting point for Web view development.
Prerequisites
You must have exported an existing Web view to use as a template. Alternatively, you can use the default Web view template that Orchestrator provides.
Procedure
1 In the Orchestrator client, click the Web Views view.
2 Right-click in the white space in the Web view list and select New from > File template.
3 Navigate to a Web view template ZIP file and click Open.
Orchestrator provides a default Web view template at the following location on the Orchestrator server.
Option Action
If you installed the standalone version of Orchestrator
Go to C:\Program
Files\VMware\Orchestrator\apps\webviewTemplates\default_web view.zip
If the vCenter Server installed
Orchestrator
Go to C:\Program
Files\VMware\Infrastructure\Orchestrator\apps\webviewTempla tes\default_webview.zip
4 Type a name for the new Web view in the Create Web View dialog box and click OK.
By default, the new Web view name is web_view_template_name_FromTemplate .
5 Right-click the Web view in the Web view list and select Edit.
The Web view editor opens.
6 On the General tab, set the URL folder value to include a suffix for the URL on which Orchestrator will publish the Web view.
For example, if you set the URL folder to MyWebView , Orchestrator publishes the Web view at http:// orchestrator_server:8280/vmo/MyWebView/ , where orchestrator_server is the IP address or
DNS name of the machine on which the Orchestrator server is running.
By default, the name of the URL folder matches the Web view name, but you can change this value.
N
OTE
If the Orchestrator server is running in Web view development mode, the URL folder value must match the name of the working folder in which you are developing the Web view.
7 Click the Version digits to increment the version number for the Web view.
The Version Comment dialog box opens.
8 Type a comment for this version of the Web view and click OK.
For example, type Initial creation if you created the Web view.
9 On the General tab, type a description of the Web view in the Description text box .
10 Click Save and close to close the Web view editor.
You created a new Web view from a Web view template.
VMware, Inc.
Chapter 9 Developing Web Views
What to do next
Export the contents of the new Web view to a working folder to modify them, and edit the Web view settings and attributes in the Orchestrator client.
Define a Web View Template as a Resource Element
Instead of exporting a Web view to your local system for use as a Web view template, you can define a Web view template as a resource element in the Orchestrator server.
Defining a Web view template as a resource element makes it available to all Web view developers who connect to the Orchestrator server.
Prerequisites
You exported a Web view template ZIP file to define as a resource element.
Procedure
1 Click the Resources view in the Orchestrator client.
2 Right-click a resource folder in the hierarchical list and select New category to create a folder in which to store the resource element.
3 Right-click the resource folder in which to import the resource element and select Import resource(s).
4 Select the resource to import and click Open.
Orchestrator adds the resource element to the folder you selected.
You defined a Web view template ZIP file as a resource element that all Web view developers who connect to the Orchestrator server can use.
What to do next
Create a Web view from a resource element template.
Create a Web View from a Resource Element Template
Instead of creating a Web view from the beginning, you can create a Web view from a resource element template that you or another developer has imported to the Orchestrator server.
A Web view template ZIP file that a developer has defined as a resource element is available to all developers who connect to the Orchestrator server.
Prerequisites
Orchestrator must define a Web view template that you or another developer has imported to the server as a resource element.
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click in the white space in the Web view list and select New from > Resource template.
3 Press the Enter key in the Search text box to display a list of all the resource elements that the Orchestrator server defines.
4 Select the Web view template ZIP file from the list of resource elements and click Select.
5 Provide an appropriate name for the new Web view in the Create Web View dialog box and click OK.
6 Right-click the Web view in the Web view list and select Edit.
The Web view editor opens.
VMware, Inc. 287
vCenter Orchestrator Developer's Guide
7 On the General tab, set the URL folder value to include a suffix for the URL on which Orchestrator will publish the Web view.
For example, if you set the URL folder to MyWebView , Orchestrator publishes the Web view at http:// orchestrator_server:8280/vmo/MyWebView/ , where orchestrator_server is the IP address or
DNS name of the machine on which the Orchestrator server is running.
By default, the name of the URL folder matches the Web view name, but you can change this value.
N
OTE
If the Orchestrator server is running in Web view development mode, the URL folder value must match the name of the working folder in which you are developing the Web view.
8 Click the Version digits to increment the version number for the Web view.
The Version Comment dialog box opens.
9 Type a comment for this version of the Web view and click OK.
For example, type Initial creation if you created the Web view.
10 On the General tab, type a description of the Web view in the Description text box .
11 Click Save and close to close the Web view editor.
You created a new Web view from a Web view template that you or another developer has defined as a resource element.
What to do next
Export the contents of the new Web view to a working folder to modify them, and edit the Web view settings and attributes in the Orchestrator client.
Export Web View Files to a Working Folder
When you create a new Web view, either as a skeleton or from a template, you export the Web view files to a working folder on your local system for editing.
Prerequisites
You must have created a new Web view in the Orchestrator client, either as a skeleton or from a template.
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click the Web view in the Web view list and select Export to directory.
3 Select the working folder in your local system in which to develop the Web view and click Export.
The working folder in your local system now contains all the HTML, Web view component, image, and other files of the Web view.
What to do next
You can edit and adapt the Web view files by using Web development tools.
N
OTE
To preview the Web view from the working folder while you develop it, set the Orchestrator server to
Web view development mode.
288 VMware, Inc.
Chapter 9 Developing Web Views
Configure the Server for Web View Development
During the Web view development process, you can configure the Orchestrator server to publish the Web view from a working folder rather than from the Orchestrator server.
When the server runs in development mode, you can preview the Web view as you develop it, without having to import it to the Orchestrator server to view it. You set the Orchestrator server to Web view development mode in the Orchestrator configuration interface.
N
OTE
Because Orchestrator publishes Web views from the working folder, you cannot access Web views that you have not exported to the working folder when the server is in development mode.
Prerequisites
To enable Web view development mode, your working folder must be on the same machine as the Orchestrator server.
Procedure
1 Open the Orchestrator configuration interface in a browser.
Option Action
If you connect to the server using
HTTP
Go to http://orchestrator_server:8282
If you connect to the server securely using HTTPS
Go to https://orchestrator_server:8283
2 Log in to the configuration interface by using the configuration username and password.
The Orchestrator administrator set the configuration username and password when they installed
Orchestrator.
3 Click the Advanced Configuration tab in the General view.
4 Check the Enable Web view development mode check box.
5 Type the path to the root of your working folder in the text box.
Make sure you provide the path to the root of the working folder. Do not include the name of the folder that contains the Web view in the path.
For example, if you are working on a Web view in the folder C:\Documents and
Settings\ username\Desktop\MyWebView\ , type C:\Documents and Settings\ username\Desktop\ as the path.
6 Click Apply changes.
7 Click Restart Service in the the Startup Options view to restart the Orchestrator server in Web view development mode.
8 After the Orchestrator server has restarted, start and log into the Orchestrator client.
9 Click Web Views.
VMware, Inc. 289
vCenter Orchestrator Developer's Guide
10 Verify that your Web view's URL folder value matches the name of your working directory.
For example, if you created the working folder
C:\Documents and
Settings\ username\Desktop\MyWebView\ , set the URL folder to MyWebView .
a If the Web view is running, right-click the Web view and select Unpublish.
b Right-click the Web view and select Edit.
c On the General tab of the Web view editor, type the name of the working folder in the URL folder text box, and click Save and Close to close the Web view editor.
11 Right-click the Web view and select Publish.
You set the Orchestrator server to Web view development mode, in which you can preview a Web view from your working folder while you develop it.
Import Web View Files from a Working Folder
After you edit the files of a Web view in the working folder, you must import them back to the Web view in the Orchestrator server.
Prerequisites
Verify that you exported the files of a Web view to a working folder and edit them using Web development tools.
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click the Web view in the Web view list and select Edit.
3 Click the Elements tab in the Web view editor.
4 Click Import from directory.
5 Select the working folder in your local system from which to import the modified Web view files and click
Import.
6 Click Save and Close to exit the Web view editor.
You imported to the Web view in the Orchestrator server the Web view files that you modified on your local system.
What to do next
Create Web view attributes.
Create a Web View Attribute
With Web view attributes, you can pass objects to Web view components. The functions that the Web view components define act on these objects to perform the orchestration actions that you run from the Web view.
A Web view attribute can be an object of any type that the Orchestrator API supports. For example, a Web view attribute can be a VC:VirtualMachine object. A Web view component can define a function that requires this object as an attribute. For example, when a user clicks a button in a Web view, a Web view component associated to that button runs a workflow that starts a virtual machine. A Web view attribute provides the virtual machine object to the workflow that the Web view component starts.
Prerequisites
Create or import a Web view in the Orchestrator client.
290 VMware, Inc.
Chapter 9 Developing Web Views
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click the Web view and select Edit.
3 Click the Attributes tab in the Web view editor.
4 Right-click in the Attributes tab and select Add attribute.
5 Click the attribute name and type a name.
6 Click the attribute Type link and select the attribute type from the list.
7 Click the attribute Value link and type or select the value of the attribute.
You type or select the attribute value depending on the type of the attribute.
8 Click Save and Close to exit the Web view editor.
You defined attributes that direct the Web view to the objects in the Orchestrator server on which it performs tasks.
What to do next
Add a resource element to a Web view.
Add a Resource Element to a Web View
Resource elements are external objects that you can import into the Orchestrator server for Web views to use as Web view attributes. Web view attributes identify objects with which Web view components interact.
Prerequisites
You must have the following objects in your Orchestrator server: n n
An image, script, XML, or HTML file, or any other type of object that you imported into Orchestrator as a resource element.
A Web view that requires this resource element as an attribute.
Procedure
1 Click the Web views view in the Orchestrator client.
2 If the Web view is running, right-click the Web view to which to add the resource element and select
Unpublish.
3 Right-click the Web view and select Edit.
4 Click the Attributes tab.
5 Right-click in the Attributes tab and select Add attribute.
6 Click the attribute name and type a new name for the attribute.
7 Click Type to set the attribute type.
8 In the Select a type dialog box, type resource in the Filter box to search for an object type.
Option
Define a single resource element as an attribute
Define a category that contains multiple resource elements as an attribute
Action
Select ResourceElement from the list.
Select ResourceElementCategory from the list.
VMware, Inc. 291
vCenter Orchestrator Developer's Guide
9 Click Value and type the name of the resource element or category of resource elements in the Search text box.
10 Select the resource element or category of resource elements from the proposed list and click Select.
11 Click Save and Close to exit the editor.
You added a resource element or category of resource elements as an attribute in a Web view.
Disable Web View Development Mode
If you set the Orchestrator server to Web view development mode during the development process, you must set the Orchestrator server back to its normal mode before you can publish the Web view.
Prerequisites
You must have set the Orchestrator server to Web view development mode and finished modifying the Web view files in your working folder.
Procedure
1 Open the Orchestrator configuration interface in a browser.
Option Action
If you connect to the server using
HTTP
Go to http://orchestrator_server:8282
If you connect to the server securely using HTTPS
Go to https://orchestrator_server:8283
2 Log in to the configuration interface by using the configuration username and password.
The Orchestrator administrator set the configuration username and password when they installed
Orchestrator.
3 Click the Advanced Configuration tab in the General view and uncheck the Enable Web view
development mode check box.
4 Click Apply changes.
5 Click the Startup Options view.
6 Click Restart Service in the Startup Options view to restart the Orchestrator server in normal mode.
You disabled Web view development mode. Orchestrator now publishes Web views from the Orchestrator server, rather than from the working folder.
What to do next
Publish the Web view.
Publish a Web View
When you finish Web view development and import the modified files to the Web view in the Orchestrator server, you can publish the Web view.
Prerequisites
You must have a Web view that is ready for publishing. You must also have disabled Web view development mode.
292 VMware, Inc.
Chapter 9 Developing Web Views
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click the Web view to publish and select Publish.
Orchestrator publishes the Web view at http:// orchestrator_server:8280/vmo/web_view_url_folder/ . The
IP address or DNS name of the machine on which the Orchestrator server is running is orchestrator_server. The name of the Web view URL folder is web_view_url_folder.
File Structure of a Web View
When you develop a Web view, you must save the collection of Web pages and Web view components that comprise the Web view to a working folder. The Web view working folder must conform to basic file-naming and file-structuring rules.
You can name the working folder in which you develop the Web view pages and components any name that is appropriate. The working folder must contain the following file and folder at its root.
<WebView_Folder>\defaul t.html
The home page of the Web view. All Web views must include a default.html
file at the root of the working folder.
<WebView_Folder>\compon ents\
Contains the JWC files and the associated HTML templates of the Web view components. The components folder must be at the root of the working folder.
I
MPORTANT
If you create more than one Web view to run in the same Orchestrator server, you must save the
Web view components in subfolders inside the components
folder, to avoid conflicts between identically named componets. Alternatively, create all Web view components with a unique name.
The default.html
file and the components folder are the only mandatory elements that a Web view must contain.
You can add other files and folders in the Web view folder and organize the files and folders in any way. You can include HTML files that are not Web view component templates anywhere in the Web view folder.
Web View Home Page
All Web views must contain a file named default.html
, that you must save at the root of the Web view working folder. The default.html
file is the home page of the Web view.
The default.html
file is the point of entry to a Web view. The default Web view template that Orchestrator provides contains a skeleton default.html
file that you can adapt and extend. The following code extract shows the contents of the default.html
file from the default Web view template.
<vmo jwcid="@layout/MyBorder" section="literal: home" title="Home">
<!-- Content of the homepage -->
<h2 style="margin-left: 16px; margin-top: 0px; padding-top:18px;">
Welcome to the default Web view template
</h2>
<p style="margin-left: 16px;">
This Web view template is a base for your own Web view development.
</p>
</vmo>
Table 9-1 provides descriptions of the contents of the Web view template
default.html
file.
VMware, Inc. 293
vCenter Orchestrator Developer's Guide
Table 9-1. Contents of the Web View Template default.html File
Code
<vmo></vmo> tags jwcid="@layout/MyBorder" title="Home"
Description
You can insert Web view components in any type of HTML tag. The Web view template wraps all its content in <vmo> tags, to show that this code is specific to Orchestrator.
A reference to the MyBorder Web view component from the default Web view template. The MyBorder component defines the borders of the Web view pages.
The title that appears in the title bar of the Web view home page.
The rest of the code in the default.html
file is standard HTML. You can extend and adapt the content of the home page by adding HTML code and add functions to the page by adding Web view components.
Web View Components
Web view components add Orchestrator functions to Web pages. For example, you can add Web view components to Web pages that allow users to run workflows from a Web page in a browser.
You build Orchestrator Web views by adding JWC components to HTML Web pages. Orchestrator provides a library of JWC Web view components that add predefined orchestration functions to Web views. The JWC
Web view components that Orchestrator provides conform to the Tapestry Framework 4.0 standard.
In addition to the library of Web view components that Orchestrator provides, you can use every standard component from the Tapestry Framework 4.0 in Web views.
n
Tapestry Web View Components on page 294
With the Tapestry Web view components in the Orchestrator Web view component library, you can add orchestration functions to Web views. The Tapestry Web components in the Orchestrator library define actions that access objects in the Orchestrator server.
n n
Creating Tapestry Web View Components on page 295
With Orchestrator, you can create custom Tapestry Web view components to perform orchestration functions from Web pages. A Tapestry Web view component conforms to the Tapestry Framework standard version 4.0.
Orchestrator Tapestry Component Library on page 301
Orchestrator has a library of Tapestry components that you can reference in Web views. You can also use all the components that the Tapestry Framework 4.0 standard defines.
Tapestry Web View Components
With the Tapestry Web view components in the Orchestrator Web view component library, you can add orchestration functions to Web views. The Tapestry Web components in the Orchestrator library define actions that access objects in the Orchestrator server.
The Tapestry Web view components that Orchestrator provides add functions to Web views such as obtaining and displaying the properties of an object in the server, starting workflows, or obtaining information from the user.
You add Tapestry components to a Web view by adding a jwcid attribute to an HTML tag in a Web page.
When you reference a Web view component, you prefix the name of the component with the @ character.
Certain Web view components require you to set additional properties when you set the jwcid attribute.
294 VMware, Inc.
Chapter 9 Developing Web Views
Reference a Tapestry Component in an HTML Page
You add Tapestry components to a Web view by adding a jwcid attribute to an HTML tag in a Web page. The jwcid attribute references a Web view component.
You can add a jwcid attribute to any HTML tag. You can add references to components from the Orchestrator
Web view component library, to components from the Tapestry Standard, or to custom components that you create.
Prerequisites
You must have created a Web view in the Orchestrator client and exported its contents to a working directory.
Procedure
1 Open an HTML page of a Web view in an HTML editor.
2 Add an arbitrary tag to the HTML file, in the position at which the Web view component is to appear in the page.
For example, add the following arbitrary tag in the appropriate position in the HTML file:
<vmo>
3 Add a jwcid attribute to the arbitrary tag, that references a Web view component.
For example, the following jwcid attribute adds the vmo:DisplayProperty component from the
Orchestrator library to the Web view.
<vmo jwcid="@vmo:DisplayProperty">
The vmo:DisplayProperty
component obtains and displays the properties of an object in the server in the
Web view.
4 Add the additional properties that the component requires to the arbitrary HTML tag.
For example, the following Web view component displays the MyVirtualMachine virtual machine's Name property in a Web view.
<vmo jwcid="@vmo:DisplayProperty" name="Name" property="MyVirtualMachine"/>
You added a reference to a Web view component to a Web page in a Web view.
Creating Tapestry Web View Components
With Orchestrator, you can create custom Tapestry Web view components to perform orchestration functions from Web pages. A Tapestry Web view component conforms to the Tapestry Framework standard version 4.0.
A Tapestry Web view component must contain a component specification file and a component template.
I
MPORTANT
The Tapestry component template file and the component specification must have the same name.
For example, if you name a component template
MyComponent.html
, you must name the associated component specification MyComponent.jwc
. Web view components that you use in different Web views that run in the same server must have unique names.
You must save the component files in the components folder in the Web view file structure. If you create subfolders in the components folder, you must specify the full path to a component when you set the jwcid attribute in HTML pages. For example, if you include a
MyBorder
component in a
<WebView_Folder>\components\layout\ subfolder, you must set the jwcid attribute, as the following example shows:
<div jwcid="@layout/MyBorder">
VMware, Inc. 295
vCenter Orchestrator Developer's Guide
You can precede the
@
character with a unique identifier. With the unique identifier, you can reuse the class throughout the HTML page, by referencing the unique identifier.
In the following example, the component is Border and the unique identifier is myBorderComponent .
<div jwcid="myBorderComponent@MyBorder"> n n n n n
Tapestry Component Specification File on page 296
A Tapestry component specification file is a JWC file that refers to the Tapestry DTD definition and to the Java class that specifies the behavior of the component.
Tapestry Component Template File on page 296
A Tapestry component template file is an HTML file that defines the layout of a Web view component.
WebviewComponent Class on page 297
The ch.dunes.web.webview.WebviewComponent
class is the main class for Web view components. All Web view component specification JWC files must implement this class.
The ch.dunes.web.webview.WebviewPage
class provides methods that you call in OGNL expressions in
Web view component template HTML files.
WebObjectComponent Class on page 300
The ch.dunes.web.webview.components.WebObjectComponent
class provides methods to obtain information from objects in the Orchestrator server. The
WebObjectComponent
class extends
WebviewComponent .
Tapestry Component Specification File
A Tapestry component specification file is a JWC file that refers to the Tapestry DTD definition and to the Java class that specifies the behavior of the component.
The JWC file can also set the initial values of the Web view component properties.
Orchestrator Web views implement the following Java classes: n ch.dunes.web.webview.WebviewComponent
n ch.dunes.web.webview.WebviewPage
n ch.dunes.web.webview.components.WebObjectComponent.html
The name of the Tapestry component specification file must match the name of the component specification
that implements the WebviewComponent Java interface.
Example: Web View Template Access.jwc File
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE component-specification PUBLIC
"-//Apache Software Foundation//Tapestry Specification 4.0//EN"
"http://jakarta.apache.org/tapestry/dtd/Tapestry_4_0.dtd">
<component-specification class="ch.dunes.web.webview.WebviewComponent">
</component-specification>
Tapestry Component Template File
A Tapestry component template file is an HTML file that defines the layout of a Web view component.
The name of the Tapestry component template file must match the name of the component specification JWC
displays the user's username and adds a Logout link to a Web view page.
296 VMware, Inc.
Chapter 9 Developing Web Views
Example: Web View Template Access.html File
<strong>
<vmo jwcid="@Insert" value="ognl:page.user.displayName" />
</strong>
<vmo jwcid="@Insert" value="ognl:' (' + page.getUsername() + ')'" />
|
<a jwcid="@Any" href="ognl:page.webviewUrl + '?logout'">Logout</a>
WebviewComponent Class
The ch.dunes.web.webview.WebviewComponent
class is the main class for Web view components. All Web view component specification JWC files must implement this class.
Implementing the WebviewComponent class in an Orchestrator Web view component allows you to call methods in a Web view page to perform various functions in the Orchestrator server, such as retrieving attributes, making queries, getting and setting parameters and attributes, and implementing Dojo widgets in the Web view component.
The WebviewComponent class extends the org.apache.tapestry.BaseComponent
Tapestry class. The
BaseComponent class provides the implementation for all Tapestry components that implement an HTML definition file.
The WebviewComponent class defines the following methods.
Method Returns Description getWebviewPage() getWebview() getRequestCycle() getWebVisitor() getParameter(java.lang.String
parameterName) getParameters(java.lang.String
parameterName) objectToJson(java.lang.Object obj) objectToParam(java.lang.Object
obj) getAttribute(java.lang.String
attributeName, java.lang.Object
defaultValue) getAttribute(java.lang.String
attributeName) ch.dunes.web.webview.WebviewPage
Returns the WebviewPage object of the page that contains this component.
ch.dunes.model.webview.WebView
Returns the WebView object that represents the current Web view.
org.apache.tapestry.IRequestCycle
The IRequestCycle object is the
Tapestry object that controls every access to the server.
ch.dunes.web.webview.WebVisitor
The WebVisitor object contains information about the Web view user for the server to use.
java.lang.Object
java.lang.Object[] java.lang.String
java.lang.String
java.lang.Object
java.lang.Object
Returns a query parameter value, or null if no query parameter is provided in the request. If multiple values are provided, it returns the first value.
Retrieves an array of values for a query parameter.
Returns a JSON representation of the object as a parameter.
Returns a parameter string to identify an object.
Returns a Web view attribute, or the default value if the attribute is null or not set.
Returns a Web view attribute.
VMware, Inc. 297
vCenter Orchestrator Developer's Guide
Method translateParameters(java.util.List
parametersValues)
Returns java.lang.Object[] getClientId() setClientId(java.lang.String id) getDojoSource() java.lang.String
void org.apache.tapestry.IAsset
getDojoPath() getBrowser() org.apache.tapestry.IAsset
ch.dunes.web.Browser
Description
If the object value is a string that begins with "attribute:", translateParameters translates an array of objects into a
FinderResult object. If the string does not begin with
"attribute:" , it does nothing.
Obtains the ID of the client.
Sets the ID of the client.
Returns the source of any Dojo widgets in the Web view as a
Tapestry IAsset object.
Returns the path to any Dojo widgets in the Web view as a
Tapestry IAsset object.
Returns a Browser object that contains information about the browser in which the user accesses the Web view.
Adds a parameter to a server query.
addQueryParameter(java.lang.String
url, java.lang.String
parameterName, java.lang.Object
parameterValue) addQueryParameter(boolean condition, java.lang.String url, java.lang.String parameterName, java.lang.Object parameterValue) java.lang.String
java.lang.String
Adds a parameter to a server query if a given condition is met.
The WebviewComponent class inherits the following methods from class java.lang.Object
: clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait
Constructor public WebviewComponent()
WebviewPage Class
The ch.dunes.web.webview.WebviewPage
class provides methods that you call in OGNL expressions in Web view component template HTML files.
The WebviewPage class extends the Tapestry class org.apache.tapestry.html.BasePage
.
The WebviewPage class defines the following methods:
Description
Adds a parameter to a server query if a given condition is met.
Method addQueryParameter(boolean condition, java.lang.String url, java.lang.String parameterName, java.lang.Object parameterValue) addQueryParameter(java.lang.String
url, java.lang.String
parameterName, java.lang.Object
parameterValue) executeAction(java.lang.String
actionAttributeName)
Returns java.lang.String
java.lang.String
java.lang.Object
Adds a parameter to a server query.
Runs an action in the server and returns the result.
298 VMware, Inc.
Chapter 9 Developing Web Views
Method executeAction(java.lang.String
actionAttributeName, java.lang.Object actionParameters) getAbsoluteUrl(java.lang.String
relativeUrl) getAttribute(java.lang.String
attributeName) getAttribute(java.lang.String
attributeName, java.lang.Object
defaultValue) getAttributes() getBaseURL() getBrowser() getDojoPath() getDojoSource() getPageUrl() getPageUrlWithQuerryString() getParameter(java.lang.String
parameterName) getParameters(java.lang.String
parameterName) getRequest()
Returns java.lang.Object
java.lang.String
java.lang.Object
java.lang.Object
Description
Runs an action in the server and returns the result.
Returns the absolute URL from a relative
URL.
Returns the Web view attribute of the specified name. Use this method instead of getAttributes().get(String) because it returns an exception if it does not find the attribute.
Returns the Web view attribute of the specified name.
java.util.HashMap
java.lang.String
ch.dunes.web.Browser
Returns a hash map containing the Web view attributes.
Returns the URL of the Web view.
Returns a Browser object that contains information about the browser in which the user accesses the Web view.
org.apache.tapestry.IAsset
Returns the path to any Dojo widgets in the
Web view as a Tapestry IAsset object.
org.apache.tapestry.IAsset
Returns the source of any Dojo widgets in the Web view as a Tapestry IAsset object.
java.lang.String
java.lang.String
java.lang.Object
Returns the URL of the current page without the URL parameters.
Returns the URL of the current page with the URL parameters.
Returns a query parameter value, or null if no query parameter is provided in the request. If multiple values are provided, it returns the first value.
java.lang.Object[] Retrieves an array of values for a query parameter.
Abstract HttpServletRequest Returns HTTP servlet requests.
The WebviewPage class inherits the following methods from class java.lang.Object
: clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait
Fields n public static java.lang.String DEFAULT_FLASH_TYPE n public static java.lang.String LOGIN_MESSAGE_ATTRIBUTE n public static java.lang.String DEFAULT_LOGIN_MESSAGE
Constructor
WebviewPage()
VMware, Inc. 299
vCenter Orchestrator Developer's Guide
300
WebObjectComponent Class
The ch.dunes.web.webview.components.WebObjectComponent
class provides methods to obtain information from objects in the Orchestrator server. The WebObjectComponent class extends WebviewComponent .
You use the WebObjectComponent class in conjunction with vmo:ListPane components.
The vmo:ListPane component inserts a list of objects into a Web view. To display information about an object in the list in another Web view page or panel, the HTML file that displays that information must contain a Web view component that implements the WebObjectComponent class.
The
WebObjectComponent
class defines the following methods that obtain properties from objects in the
Orchestrator server.
Method get(java.lang.String name) get(java.lang.String name, java.lang.String
valueIfNotFound) toParam()
Returns Description java.lang.Object
Obtains the property of the given name.
java.lang.Object
Obtains the property of the given name.
java.lang.String
Obtains the output parameter of an Action or
Workflow object.
The WebObjectComponent class inherits the following methods from class java.lang.Object
: clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait
Constructor
WebObjectComponent()
Example: Using WebObjectComponent to Display Object Information
The following vmo:ListPane
component displays information about the objects it lists in an HTML page called panel.html
:
<p jwcid="@vmo:ListPane"
action="getVirtualMachineList"
actionParameters="attribute:vmFolder"
detailUrl="./panel.html"/>
The panel.html
file contains a reference to a Web view component called DisplayVmInfo :
<vmo jwcid="@DisplayVmInfo" urlParameter="itemId" />
The
DisplayVmInfo.jwc
component specification file implements the
WebObjectComponent
Java class:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE component-specification PUBLIC
"-//Apache Software Foundation//Tapestry Specification 4.0//EN"
"http://jakarta.apache.org/tapestry/dtd/Tapestry_4_0.dtd">
<component-specification class="ch.dunes.web.webview.components.WebObjectComponent">
</component-specification>
The DisplayVmInfo.html
component template file uses WebObjectComponent.get() methods in OGNL statements to display object properties in panel.html
:
<table width="200" border="1">
<tr>
<td>Virtual machine name</td>
<td><vmo jwcid="@Insert" value="ognl:get('name')"/></td>
VMware, Inc.
Chapter 9 Developing Web Views
</tr>
<tr>
<td>Object ID</td>
<td><vmo jwcid="@Insert" value="ognl:get('id')"/></td>
</tr>
</table>
Orchestrator Tapestry Component Library
Orchestrator has a library of Tapestry components that you can reference in Web views. You can also use all the components that the Tapestry Framework 4.0 standard defines.
All the Tapestry components in the Orchestrator library have the prefix vmo:
, to distinguish these components from the components that the standard Tapestry framework provides.
The components in the Orchestrator Web view component library require different properties to display different types of information in the Web view. In the property tables for each component, asterisks (*) denote mandatory properties.
vmo:DisplayProperty Component
The vmo:DisplayProperty component displays the names and values of the properties of objects in the
Orchestrator inventory.
Properties
The vmo:DisplayProperty component defines the following properties.
Name Type Description name * String Property name property * String Property value
Example: vmo:DisplayProperty Component
The following example shows how to use the vmo:DisplayProperty component to display the details of a virtual machine in a Web view.
<div jwcid="@vmo:DisplayProperty" name="Name" property="MyVirtualMachine"/>
<div jwcid="@vmo:DisplayProperty" name="Id" property="vm_89575"/>
<div jwcid="@vmo:DisplayProperty" name="State" property="poweredOff"/>
vmo:IfMemberOf Component
The vmo:IfMemberOf component includes a block of content if the current user is a member of a given LDAP group.
If you pass an array of LDAP groups to this component, the Web view displays the content if the current user is a member of at least one of the groups in the list.
Properties
The vmo:IfMemberOf component defines the following properties.
Name Type Description attribute * String An attribute of the LdapGroup type, or an array of LdapGroup objects.
VMware, Inc. 301
vCenter Orchestrator Developer's Guide
Example: vmo:IfMemberOf Component
The following example shows how to use the vmo:IfMemberOf
component to add information about a user's
LDAP group membership to a Web view.
<span jwcid="@vmo:IfMemberOf" attribute="ognl:'adminGroup'">
You are a member of the group defined by the adminGroup attribute.
</span>
<span jwcid="@Else">
You are not a member of the group defined by the adminGroup attribute.
</span>
vmo:IncludeJavascript Component
The vmo:IncludeJavascript component inserts a <script> tag that defines a URL to a JavaScript file, to add a
JavaScript function to a Web view.
You insert the vmo:IncludeJavascript component in the <head> tags of a Web view page.
Properties
The vmo:IncludeJavascript
component defines the following properties.
Name Type Description src String The path to a Javascript file, with or without the *.js extension
Example: vmo:IncludeJavascript Component
The *.js
file extension is optional. The following example code lines both return the same src value.
<script jwcid="@vmo:IncludeJavascript" src="dojo"/>
<script jwcid="@vmo:IncludeJavascript" src="dojo/dojo.js"/>
vmo:IncludeStylesheet Component
The vmo:IncludeStylesheet component inserts a <link> tag that links to an external CSS file in a Web view.
You insert the vmo:IncludeStylesheet component in the <head> tags of a Web view page.
Properties
The vmo:IncludeStylesheet component defines the following properties.
Name Type Description href or src String Name of a CSS file, with or without the *.css extension.
attribute String Name of a Web view attribute that contains a path to the CSS files.
The href or src properties are unnecessary if you provide an attribute property. If you store CSS files in a dedicated folder in the Web view file structure, you can include the folder name in the path you provide to the href or src property.
Example: vmo:IncludeStylesheet Component
The
*.css
file extension is optional. The following example code lines both return the same href
or src
value.
<link jwcid="@vmo:IncludeStylesheet" href="default.css"/>
<link jwcid="@vmo:IncludeStylesheet" href="default"/>
302 VMware, Inc.
Chapter 9 Developing Web Views
The following example code line references a Web view attribute that contains a path to a CSS file. You create
Web view attributes in the Orchestrator client.
<link jwcid="@vmo:IncludeStylesheet" attribute="cssDefault"/>
vmo:IncludeWorkflowHeader Component
You use the vmo:IncludeWorkflowHeader component in conjunction with the vmo:WebformContainer to display a Web form in a Web view.
You can insert a Web form in a Web view to request information from the user when they start a worfklow, or to prompt the user for information during the workflow's run.
Properties
The vmo:IncludeWorkflowHeader component defines the following property.
Name Type Description debug Boolean Set the Dojo debugging mode
You insert the vmo:IncludeWorkflowHeader component in the <head> tags of a Web view page. You insert the associated vmo:WebformContainer component in the <body> tags of the Web view page.
Example: vmo:IncludeWorkflowHeader
The following example shows how to use the vmo:IncludeWorkflowHeader component in a Web view.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<span jwcid="@vmo:IncludeWorkflowHeader"/>
</head>
<body jwcid="@Body">
<span jwcid="@WebformContainer"/>
</body> </html>
vmo:ListPane Component
The vmo:ListPane component displays a list of objects in a Web view, and displays an object's details when the user selects the object in the list.
Properties
The vmo:ListPane component defines the following properties.
Name attribute action actionParameters
Type
String
String
Array of objects
Description
A Web view attribute that references an array of objects that you define in the
Orchestrator client. The array of objects appears in the vmo:ListPane component in the Web view.
A Web view attribute that references an action. The action must return an array of objects.
Array of parameters that an action requires. If the parameter is a Web view attribute, use the syntax attribute:myAttribute.
VMware, Inc. 303
vCenter Orchestrator Developer's Guide
Name url detailUrl
Type
String
String detailParameterName String updateFrequency Integer showHeader jsonIdKey jsonStateKey jsonNameKey jsonTypeKey sizerWidth sizeShare
Boolean
String
String
String
String
Integer
Integer showState Boolean
Description
The URL of the content of the list. Returns a JavaScript Object Notation (JSON) string.
The URL of the HTML page in which to display the details of an object in the list.
The HTML page that detailUrl refers to must include a reference to a Web view component that implements the WebObjectComponent class.
Name of the parameter that stores the ID of the item. Default is itemId.
Time in milliseconds before the list of objects refreshes. Default is 0. If you do not set the property, the list never refreshes.
Displays the filtering table header. Default is false.
Name of the JSON ID key.
Name of the JSON state key. Default is state.
Name of the JSON name key. Default is name.
Name of the JSON type key. Default is type.
Width of the sizer method. Default is 9.
Width or height of a child of a SplitContainer. The value is relative to the sizeShare properties of other children. Default is 6, with the other columns set to 10.
Shows a state column if set to true. Default is false.
You must set at least one and only one of the attribute , url , or actions properties. If you do not set an attribute , url , or actions property, or if you set more than one of these properties together, the Web view returns an error.
Example: vmo:ListPane Component
The following example displays a list of virtual machines in a pane of a Web view.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
version="-//W3C//DTD XHTML 1.1//EN" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>
<span jwcid="@Insert" value="ognl:webview.name">Page Title</span>
| Home
</title>
</head>
<body>
<div jwcid="@Border">
<h1>Virtual Machine List</h1>
<div jwcid="vmList@vmo:ListPane"
action="getVirtualMachineList"
actionParameters="attribute:vmFolder"
detailUrl="system/partials/virtual_machine.html" >
Select a virtual machine on the left to display it.
304 VMware, Inc.
Chapter 9 Developing Web Views
</div>
</div>
</body>
</html>
vmo:Login Component
With the vmo:Login component, you can customize the login page of a Web view.
The login page of a Web view must adhere to the following rules.
n You must name the login page login.html
.
n You must save the login page at the root of the Web view file structure.
Properties
The vmo:Login component has no properties.
Example: vmo:Login Component
The following example code line adds a login link to a login.html
page.
<span jwcid="@vmo:Login">login here</span>
vmo:PageAccessControl Component
The vmo:PageAccessControl component allows or denies users access to the Web view page that contains this component. The vmo:PageAccessControl component checks the membership of the Web view user to an LDAP group.
If the user is a member of at least one group that the deny attribute defines, the Web view denies the user access to the page. If the user is not a member of a group in the deny attribute, the component checks the allow attribute.
If the user is a member of at least one group that the allow attribute defines, the user can access the page.
Otherwise, the Web view does not display the page.
You set the LDAP groups of users who can view the page as Web view attributes in the Orchestrator client.
Properties
The vmo:PageAccessControl component defines the following properties.
Name Type Description deny allow
String A Web view attribute of the type LdapGroup, or an array of LdapGroup objects.
String A Web view attribute of the type LdapGroup, or an array of LdapGroup objects.
redirectUrl String A URL to which to redirect the user if they are not authorized to view the page. If redirectUrl is not set, the Web view returns a 403 error.
message String If redirectUrl is set and message is set, the URL of the page to which the Web view redirects the user contains a msgquery parameter and the contents of the message property. For example error_page.html?msg=message_content .
Example: vmo:PageAccessControl Component
The following example code line allows access to a page to users who are members of the group that the adminGroup Web view attribute defines.
<span jwcid="@vmo:PageAccessControl" allow="adminGroup"/>
VMware, Inc. 305
vCenter Orchestrator Developer's Guide
The following example code line denies access to a page to users who are members of the group that the partnerGroup
Web view attribute defines.
<span jwcid="@vmo:PageAccessControl" deny="partnerGroup"/>
The following example code line redirects users who are members of the partnerGroup LDAP group to an error page. The error401.html
file is at the root of the Web view file structure.
<span jwcid="@vmo:PageAccessControl" deny="partnerGroup" redirectUrl="error401.html"/>
vmo:TaskAction Component
The vmo:TaskAction component displays the scheduled action from a Task object. A user selects the task from a list that a vmo:ListPane component generates.
Properties
The vmo:TaskAction component defines the following properties.
Name Type Description stringValue type attribute action
String The stringValue of the task the user selects. Every object in the Orchestrator server has a stringValue string representation.
String The type of the task that the user selects.
String A Web view attribute. The vmo:TaskAction displays the possible actions to perform on the object that corresponds to this Web view attribute.
String A Web view attribute of type Action. The vmo:TaskAction component displays the possible actions to perform on the object that this action returns.
actionParameters List object
A list of parameters for the action.
Object An object. The vmo:TaskAction component displays the possible actions to perform on this object.
urlParameter String The parameter name in the URL that represents the task the user selects.
You can only set the following parameters or combinations of parameters. Setting other combinations of parameters results in an error.
n stringValue and type n attribute n action and actionParameters n object n urlParameter
Example: vmo:TaskAction Component
The following example code line shows how to use the vmo:TaskAction component with the stringValue and type
parameters, if the Java interface that your Web view component or page references defines a getMyStringValue() method.
<div jwcid="@vmo:TaskAction" type="ognl:myType" stringValue="ognl:myStringValue"/>
The following code line shows how to use the vmo:TaskAction component with the object parameter, if the
Java interface that your Web view component or page references defines a getMyObject() method.
<div jwcid="@vmo:TaskAction" object="ognl:myObject"/>
306 VMware, Inc.
Chapter 9 Developing Web Views
vmo:WebformContainer Component
The vmo:WebformContainer component adds a Web form to a Web view, for users to complete when they run a worfklow or to allow users to provide information to a workflow during its run.
Properties
The vmo:WebformContainer component defines no properties.
You can use the vmo:WebformContainer component with the vmo:WorkflowLink component.
Example: vmo:WebformContainer Component
To add a vmo:WebformContainer component to a Web view, you must also include a vmo:IncludeWorkflowHeader component in the <head> tag of the Web view page, as the following example shows.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<span jwcid="@vmo:IncludeWorkflowHeader"/>
</head>
<body jwcid="@Body">
<span jwcid="@WebformContainer"/>
</body> </html>
vmo:WorkflowLink Component
The vmo:WorkflowLink component adds a link to a Web view to allow users to run a workflow. You can also use this component to display a link to schedule a workflow.
Properties
The vmo:WorkflowLink component defines the following properties.
Name workflow action actionParameters object workflowId returnUrl onReturn cancelUrl onCancel isSync
Type
String
String
List
Object
String
String
String
String
String
Boolean
Description
Web view attribute of type Workflow.
Web view attribute of type Action.
A list of parameters for the action.
A Workflow object.
ID of the Workflow object.
URL to which to redirect the user after starting the workflow.The default is the URL of the page that contains the component.
Run a JavaScript method when the workflow starts. For example, to display information about the running workflow in the Web view.
URL to which to redirect the user if they cancel a workflow. The default is the URL of the page that contains the component.
Run a JavaScript method if the user cancels the workflow.
If true, the workflow runs in synchronous mode. Default is false.
VMware, Inc. 307
vCenter Orchestrator Developer's Guide
Name Type returnUrlAttribute String webformPage String isDialog width height isScheduled isAutostart defaultValues
Boolean
Float
Float
Boolean
String
HashMap<String,
String>
Description
Workflow attribute containing a URL to which to redirect users after the workflow finishes its run. Default is returnUrl.
URL of a page that contains a vmo:WebformContainer component, to open a Web form when a user starts a workflow. Default is system/form.html
.
If true, the Web form opens in a dialog box. Default is false.
Width of the dialog box. Values less than 1 define a ratio in relation to the width of the window. Values greater than 1 define the size in pixels.
Default is 0.5.
Height of the dialog box. Values less than 1 define a ratio in relation to the height of the window. Values greater than 1 define the size in pixels.
Default is 0.9.
If true, when the workflow starts, the user is prompted for a time and date at which to run the workflow. Default is false.
If true, the workflow runs with preset default parameters without displaying them to the user. If set to never, the workflow never runs in autostart mode. If false, the workflow runs according to the Autostart property you set in the workflow presentation. Default is false.
A hashmap of default parameter values. If isAutostart is true, these parameters are not seen by the user when the workflow runs. If isAutostart is false, the workflow opens a parameters dialog box containing these default parameters. The key is the name of the parameter and the value is its string representation.
The properties of the vmo:WorkflowLink component must conform to the following rules: n Set only one of the workflow
, action
, object
, or workflowId
properties.
n n n
If you set the returnUrlAttribute property, you must set isSync to true.
Use the syntax #{'element1','element2'} to construct a list of properties in OGNL.
Use the syntax #{'foo':'foo value', 'bar':'bar value'} to construct a map in OGNL.
Example: vmo:WorkflowLink Component
The following code example adds a link to a Web view that starts an action when the user clicks it.
<span jwcid="@vmo:WorkflowLink"
action="myAction"
actionParameters="ognl:{'attribute:myParameter',
'attribute:myParameter2'}">
Click here
</span>
308 VMware, Inc.
Chapter 9 Developing Web Views
Accessing Server Objects from URLs
You can add URLs to Web view pages to access objects in the Orchestrator server, without having to implement a Web view component. For example, you can add URLs to Web view pages that run an action in the
Orchestrator server or URLs that retrieve resource elements from the Orchestrator server.
n n
Running Actions from URLs on page 309
Running actions from URLs rather than by implementing Web view components allows you to run operations directly in the Orchestrator server without requiring any input parameters from the Web view user. Running actions from URLs also allows you to define how to process the action results.
Accessing Resource Elements from URLs on page 311
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.
Running Actions from URLs
Running actions from URLs rather than by implementing Web view components allows you to run operations directly in the Orchestrator server without requiring any input parameters from the Web view user. Running actions from URLs also allows you to define how to process the action results.
When you run a workflow from a Web view component, the Web view prompts you for input parameters before it runs. Web view components also apply formatting to any data they receive from the server. If you retrieve objects from the server from a URL rather than from a Web view component, you can apply your own formatting or processing to the data that the URL retrieves.
For example, certain actions return JavaScript Object Notation (JSON) data. If you call such an action from a
URL in a Web view, you can write Ajax functions to process and format the action results. Similarly, if the action returns an object from the Orchestrator server, you can write JavaScript functions to act on this object in the Web view.
To run an action from a URL in a Web view, you must declare that action as a Web view attribute and reference the attribute in the URL.
Web views access actions that you have defined as Web view attributes at the following URL: http:// orchestrator_server:8280/vmo/web_view_url_folder/system/execute/action/action.html?
action= action_attribute_name
To avoid hard-coding the orchestrator_server address into the URL, you can provide relative paths to the action that start from the directory below the Web view URL folder, as the following path shows:
<a href="./system/execute/action/action.html?action= attribute_name"></a>
Setting Action Parameters in a URL
You pass input parameters to the action by setting the actionParameters property in the URL. Depending on the action, you might need to declare the input parameters for the action as Web view attributes. If the action parameters are Web view attributes, you must prefix the Web view attribute name of the parameter with attribute: , as the following example shows.
http:// orchestrator_server:8280/vmo/web_view_url_folder/system/execute/action/action.html?
action= action_attribute_name&actionParameters=attribute:parameter_attribute_name&actionParameters
= parameter_value
VMware, Inc. 309
vCenter Orchestrator Developer's Guide
Writing Action Results to a File
You can use a URL to run an action that returns its results as a MimeAttachment file. You provide the name and type of the file to which to write the results in the URL. You must define the action to run as a Web view attribute.
Web views access actions that you have defined as Web view attributes and obtain their results as
MimeAttachment files at the following URL: http:// orchestrator_server:8280/vmo/web_view_url_folder/system/execute/action/ action_attribute_name/filename.file_extension?actionParameters=parameter_value&mimetype=mime_type
The filename.file_extension
file you specify for the output file can be any type of file. If you set the optional mimeType property, the file type must be a valid MimeAttachment file, for example an EML or PDF file.
To avoid hard-coding the orchestrator_server address into the URL, you can provide relative paths to the action that start from the directory below the Web view URL folder, as the following path shows:
<a href="./system/execute/action/generateReport/annualReport.pdf?actionParameters="Annual
Report"&mimetype=application/pdf"></a>
The preceding example URL performs the following tasks: n Runs an action that you have declared as the Web view attribute generateReport
, which returns a
MimeAttachment object.
n n
Creates a PDF file called annualReport.pdf
Returns the PDF file
Run an Action from a URL
You can add URLs to Web view pages to run actions in the Orchestrator server. Running actions by using direct URLs rather than by using Web view components allows you to specify the parameters with which to run the action in the URL, and allows you to provide your own formatting to the action results.
Prerequisites
You have created a Web view in the Orchestrator client and have Web view page in which to insert a URL to run an action.
Procedure
1 In the Web views view of the Orchestrator client, right-click the Web view to which to add the URL and select Edit.
You must unpublish a running Web view to edit it.
2 Right-click in the Attributes tab of the Web view editor and select Add attribute.
3 Create a Web view attribute, of type Action with the value set to the action of your choice.
For example, name the Web view attribute MyAction .
4 Create Web view attributes for each of the input parameters that the action requires.
For example, name a Web view attribute ActionParameterAttribute .
5 Click Save and close to exit the Web view editor.
310 VMware, Inc.
Chapter 9 Developing Web Views
6 Open the HTML page in which to insert the URL in an HTML editor.
7 Add a link to http:// orchestrator_server:
8280/vmo/ web_view_url_folder/system/vmo/pages/action.html
at the appropriate place in the HTML file.
Add a relative link to the action URL, that starts below the Web view URL folder value, rather than hardcoding the address of the Orchestrator server in the URL, as the following example shows:
<a href="./system/vmo/pages/action.html?action=myAction
&actionParameters=attribute:ActionParameterAttribute
&actionParameters= action_parameter_value">
Click here to run an action</a>
The URL uses the Web view attributes you set in the Orchestrator client to start the action myAction and to set the
ActionParameterAttribute parameter. The second parameter,
ActionParameterValue
, is not a
Web view attribute so you add the parameter value directly in the URL.
You added a link to run an action from a URL. When users click the link in the published Web view, the action runs with the parameters you reference in the URL. JavaScript functions that you define can process the results of running the action.
Accessing Resource Elements from URLs
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.
You can add URLs to Web view pages to retrieve resource elements from the Orchestrator server. You can then add JavaScript functions to the Web view to process the resource elements. To access a resource element from a URL in a Web view, you must declare that resource element as a Web view attribute and reference the attribute in the URL.
Web views access resource elements at the following URL: http:// orchestrator_server:
8280/vmo/ web_view_url_folder/system/resources/attributes/resource_attribute_name.att
To avoid hard-coding the orchestrator_server address into the URL, you can provide relative paths to the action that start from the directory below the Web view URL folder, as the following path shows:
<a href="./system/resources/attributes/ resource_attribute_name.att"></a>
Obtain a Resource Element from a URL
Resource elements are files that are imported into the Orchestrator server for use by Orchestrator applications.
By accessing a resource element from a URL in a Web view, you make that resource element available to processing that you define in the Web view.
Objects that workflows and Web views can use as resource elements include image files, scripts, XML templates, HTML files, and so on. Any workflows or Web views that run in the Orchestrator server can use any resource elements that you import into Orchestrator.
Prerequisites
You must have performed the following tasks: n Imported a file into the Orchestrator server to use as a resource element n n
Created a Web view in the Orchestrator client
Created a Web view page in which to insert a URL to run an action
VMware, Inc. 311
vCenter Orchestrator Developer's Guide
Procedure
1 In the Web views view of the Orchestrator client, right-click the Web view to which to add the URL and select Edit.
You must unpublish a running Web view to edit it.
2 Right-click in the Attributes tab of the Web view editor and select Add attribute.
3 Create a Web view attribute, of type
ResourceElement
with the value set to the resource element of your choice.
For example, name the Web view attribute MyImage if the resource element is an image file.
4 Click Save and close to exit the Web view editor.
5 Open the HTML page in which to insert the URL in an HTML editor.
6 Add a link to http:// orchestrator_server:
8280/vmo/ web_view_url_folder/system/resources/attributes/resource_attribute_name.att
appropriate place in the HTML file.
at the
Add a relative link to the resource element URL, that starts below the Web view URL folder value, rather than hard-coding the address of the Orchestrator server in the URL, as the following example shows:
<a href="./system/resources/attributes/MyImage.att">
Click here to obtain an image</a>
The URL uses the Web view attribute you set in the Orchestrator client to obtain the resource element in the
Web view.
Create a Simple Web View Using the Default Template
The easiest way to create a Web view is to use a template. Orchestrator provides a default Web view template to help you create Web views.
You can use the default template to create a simple Web view called Virtual Machine Manager. You can find a ready-made version of the Virtual Machine Manager sample Web view in the bundle of Orchestrator
examples. For details about where to download the Orchestrator examples bundle, see “Example
N
OTE
If you install the Virtual Machine Manager Web view from the Orchestrator samples bundle, you must edit the vmFolder
attribute to point to a virtual machine folder in your vCenter Server before you publish the
Web view.
Procedure
1
Import the Default Web View Template on page 313
To create a Web view by using the default Web view template, you must import the template to the
Orchestrator client.
2
Export the Virtual Machine Manager Web View to a Working Folder on page 314
You edit the HTML files and Web view components of the Virtual Machine Manager Web view on your local system, using Web development tools.
3
Provide Unique Component Names on page 315
To avoid conflicts if you run multiple Web views in the same Orchestrator server, you must make sure that all Web view components have unique names.
4
Configure the Server for Web View Development on page 316
During the Web view development process, you can configure the Orchestrator server to publish the
Web view from a working folder rather than from the Orchestrator server.
312 VMware, Inc.
Chapter 9 Developing Web Views
5
Edit the Virtual Machine Manager Web View Home Page on page 317
You create the home page of the Virtual Machine Manager Web view in the default.html
file. The default.html
file must be at the root of the working directory.
6
Add a vmo:ListPane Component to the Web View Home Page on page 318
You can add a vmo:ListPane component to the Virtual Machine Manager Web view home page to display a list of vCenter server objects.
7
Define the Web View Attributes for the vmo:ListPane Component on page 319
The vmo:ListPane component refers to Web view attributes that provide an action to obtain an array of virtual machines from the server and the virtual machine folder from which to obtain them.
8
Create a Web View Component to Display Virtual Machine Information on page 320
The vmo:ListPane component lists virtual machines in the left side of the Web view. You can create a
Web view component to show information about each virtual machine in a Web view panel on the right side.
9
Create a Web View Tab by Using the Menu Component on page 322
The default Web view template provides a
Menu
component that you can use to create navigation tabs in a Web view.
10
Add Links to Run Workflows from a Web View by Using the vmo:WorkflowLink Component on page 323
You add links to run workflows from a Web view by using the vmo:WorkflowLink component. You define the workflows to run by setting Web view attributes.
11
Customize the Web View Interface on page 325
You can customize the appearance of the Web view by adjusting the custom.css
style sheet and changing the images in the
\images
folder.
12
Publish the Virtual Machine Manager Web View on page 326
After you finish developing the Virtual Machine Manager, you must disable Web view development mode, import the Web view from your working directory to the Orchestrator server, and publish the
Web view.
Import the Default Web View Template
To create a Web view by using the default Web view template, you must import the template to the Orchestrator client.
When you create Web views, it is easier to customize an existing template than to start from the beginning.
Procedure
1 Click the Web Views view in the Orchestrator client.
2 Right-click in the white space under the Web views list and select New from > File template to import a
Web view template to the Orchestrator server.
3 Click Browse and browse to the appropriate folder.
Option
If you installed the standalone version of Orchestrator
If the vCenter Server installed
Orchestrator
Action
Go to C:\Program
Files\VMware\Orchestrator\apps\webviewTemplates\default_web view.zip
Go to C:\Program
Files\VMware\Infrastructure\Orchestrator\apps\webviewTempla tes\default_webview.zip
VMware, Inc. 313
vCenter Orchestrator Developer's Guide
4 Select the default_webview.zip
file and click Open.
5 Name the Web view Virtual Machine Manager .
The Virtual Machine Manager Web view now appears in the list in the Web Views view in the client.
6 Right-click Virtual Machine Manager and select Publish to preview the empty template.
7 In a browser, go to http:// <orchestrator_server>:8280/vmo/ to see the list of Web views running on the
Orchestrator server.
8 Click Virtual Machine Manager and log in using your Orchestrator username and password.
You see a basic Web view, with no operations or functions.
You created an empty Web view from a template, and inspected it in a browser.
What to do next
Export the empty Web view to a working folder.
Export the Virtual Machine Manager Web View to a Working Folder
You edit the HTML files and Web view components of the Virtual Machine Manager Web view on your local system, using Web development tools.
Prerequisites
Verify that you imported the default Web view template to Orchestrator and used it to create a new Web view.
Procedure
1 Create a folder on your local system in which to develop the Virtual Machine Manager Web view.
For example,
MyWebView
.
2 (Optional) If Virtual Machine Manager is running, in the Web Views view of the Orchestrator client, rightclick Virtual Machine Manager and select Unpublish.
3 Right-click Virtual Machine Manager and select Export to directory.
4 Navigate to your working folder and click Export.
You exported the empty Web view to a working directory.
What to do next
Provide the Web view components with unique names.
Contents of the Default Web View Template
After you export the Web view to your working folder, you can examine the contents of the default Web view template.
The default_webview Web view template contains the following files:
Home page of the default Web view template.
JWC component that provides a login function.
default.html
components\layout\Acces s.jwc
components\layout\Acces s.html
components\layout\Menu.
jwc
HTML template that defines how the login component appears in the browser.
JWC component that specifies menu tabs for the default Web view.
314 VMware, Inc.
Chapter 9 Developing Web Views components\layout\Menu.
html components\layout\MyBor der.jwc
components\layout\MyBor der.html
css\border.css
css\custom.css
HTML template that you edit to add menu tabs to the default Web view.
JWC component that defines the borders of the default Web view, sets its name, loads the logos and stylesheets, and so on.
HTML template that defines how the borders appear in the browser.
css\login.css
images\
CSS style sheet that renders the border component.
Customizes other stylesheets, such as border.css
or login.css
. Every page of the default Web view imports the custom.css
file. The custom.css
file overrides the other style sheets in the template.
N
OTE
The custom.css
style sheet is the only style sheet you can edit. If you edit the other style sheets directly rather than editing custom.css
, your edits are overwritten every time you upgrade to a new version of Orchestrator.
CSS style sheet that renders the login component.
Contains image files for the banners, logos, and icons that appear in the default
Web view.
Provide Unique Component Names
To avoid conflicts if you run multiple Web views in the same Orchestrator server, you must make sure that all
Web view components have unique names.
You can ensure that Web view components have unique names either by moving the components into a unique subfolder in the \components folder, or by changing the names of the Web view components. Because the Virtual
Machine Manager example uses only one component from the template, the easiest solution is to rename the component.
Prerequisites
Export the contents of the Web view template to a working folder.
Procedure
1 Navigate to the \components\layout folder in the working folder.
For example, \MyWebView\components\layout .
2 Rename the MyBorder.html
file to VMMBorder.html
.
3 Rename the
MyBorder.jwc
file to
VMMBorder.jwc
.
What to do next
Configure the server for Web view development.
VMware, Inc. 315
vCenter Orchestrator Developer's Guide
Configure the Server for Web View Development
During the Web view development process, you can configure the Orchestrator server to publish the Web view from a working folder rather than from the Orchestrator server.
When the server runs in development mode, you can preview the Web view as you develop it, without having to import it to the Orchestrator server to view it. You set the Orchestrator server to Web view development mode in the Orchestrator configuration interface.
N
OTE
Because Orchestrator publishes Web views from the working folder, you cannot access Web views that you have not exported to the working folder when the server is in development mode.
Prerequisites
To enable Web view development mode, your working folder must be on the same machine as the Orchestrator server.
Procedure
1 Open the Orchestrator configuration interface in a browser.
Option Action
If you connect to the server using
HTTP
Go to http://orchestrator_server:8282
If you connect to the server securely using HTTPS
Go to https://orchestrator_server:8283
2 Log in to the configuration interface by using the configuration username and password.
The Orchestrator administrator set the configuration username and password when they installed
Orchestrator.
3 Click the Advanced Configuration tab in the General view.
4 Check the Enable Web view development mode check box.
5 Type the path to the root of your working folder in the text box.
Make sure you provide the path to the root of the working folder. Do not include the name of the folder that contains the Web view in the path.
For example, if you are working on a Web view in the folder C:\Documents and
Settings\ username\Desktop\MyWebView\ , type C:\Documents and Settings\ username\Desktop\ as the path.
6 Click Apply changes.
7 Click Restart Service in the the Startup Options view to restart the Orchestrator server in Web view development mode.
8 After the Orchestrator server has restarted, start and log into the Orchestrator client.
9 Click Web Views.
316 VMware, Inc.
Chapter 9 Developing Web Views
10 Verify that your Web view's URL folder value matches the name of your working directory.
For example, if you created the working folder
C:\Documents and
Settings\ username\Desktop\MyWebView\ , set the URL folder to MyWebView .
a If the Web view is running, right-click the Web view and select Unpublish.
b Right-click the Web view and select Edit.
c On the General tab of the Web view editor, type the name of the working folder in the URL folder text box, and click Save and Close to close the Web view editor.
11 Right-click the Web view and select Publish.
You set the Orchestrator server to Web view development mode, in which you can preview a Web view from your working folder while you develop it.
Edit the Virtual Machine Manager Web View Home Page
You create the home page of the Virtual Machine Manager Web view in the default.html
file. The default.html
file must be at the root of the working directory.
Prerequisites n n n
Import the default Web view template to Orchestrator to create the Virtual Machine Manager Web view
Export the contents of the Virtual Machine Manager Web view to a working directory
Configure Orchestrator in Web view development mode
Procedure
1 Go to the root of your working directory.
2 Open the default.html
file in an HTML editor.
The default.html
page uses the Border component to render itself. It contains little code, as the following code sample shows.
<vmo jwcid="@layout/MyBorder" section="literal: home" title="Home">
<!-- Content of the homepage -->
<h2 style="margin-left: 16px; margin-top: 0px; padding-top:18px;">
Welcome to Default Webview Template
</h2>
<p style="margin-left: 16px;">
This webview is a base for your own webview development.
</p>
</vmo>
The vmo tag initializes a Tapestry component by setting the jwcid attribute to point to the MyBorder component, which you renamed to VMMBorder .
3 Change the jwcid
attribute to refer to
VMMBorder
instead of
MyBorder
.
<vmo jwcid="@layout/VMMBorder" section="literal: home" title="Virtual Machine Manager">
4 Change the title
attribute to Virtual Machine Manager .
<vmo jwcid="@layout/VMMBorder" section="literal: home" title="Virtual Machine Manager">
VMware, Inc. 317
vCenter Orchestrator Developer's Guide
5 Delete the default
<h2>
heading from the default.html
file.
This heading is unnecessary for the simple Web view that this example demonstrates. Delete the following code line.
<h2 style="margin-left: 16px; margin-top: 0px; padding-top:18px;">
Welcome to Default Webview Template
</h2>
6 Change the paragraph text from This webview is a base for your own webview development to the following text:
<p style="margin-left: 16px; margin-top: 0px; padding-top:18px;">
Click one of the virtual machines in your inventory to display its information.</p>
7 Go to http:// orchestrator_server:8280/vmo/ in a browser to check the appearance of the Web view.
8 Make any necessary adjustments to the HTML code to improve the appearance of the Web view.
For example, change the spacing of the text by adjusting the margins of the
<p>
tag and add a hard return line under the text.
<p style="margin-left: 16px; margin-top: 5px; margin-bottom: 5px;">
Click one of the virtual machines in your inventory to display its information.
</p>
<hr />
What to do next
Add a function to the default.html
page by referring to a Web view component.
Add a vmo:ListPane Component to the Web View Home Page
You can add a vmo:ListPane
component to the Virtual Machine Manager Web view home page to display a list of vCenter server objects.
Prerequisites n n n n
Import the default Web view template into the Orchestrator server.
Export the contents of the default Web view template to a working directory.
Configure the Orchestrator server for Web view development.
Open the default.html
file in an HTML editor.
318 VMware, Inc.
Chapter 9 Developing Web Views
Procedure u Add a vmo:ListPane Component
to the default.html
file to add a list of virtual machines in the page.
You add a vmo:ListPane Component by adding the following <p> tag after the instruction to click a virtual machine.
<vmo jwcid="@layout/VMMBorder" section="literal: home" title="Virtual Machine Manager">
<p style="margin-left: 16px; margin-top: 5px; margin-bottom: 5px;">
Click one of the virtual machines in your inventory to display its information.
</p>
<hr />
<p jwcid="@vmo:ListPane"
action="getVirtualMachineList"
actionParameters="attribute:vmFolder"
detailUrl="./panel.html"/>
</vmo>
The <p> tag instantiates the vmo:ListPane component with the following properties: jwcid= "@vmo:ListPane" action=
"getVirtualMachineList
" actionParameters=
"attribute:vmFolder" detailUrl=
"./panel.html"
Refers to the vmo:ListPane component, to add a list of virtual machines from the server inventory to the Web view.
Links to a Web view attribute that runs an action in the Orchestrator server to retrieve a list of virtual machines.
Passes parameters to the actionParameters getVirtualMachineList action. The
property passes the vmFolder Webview attribute to the action, to retrieve a list of the virtual machines from a virtual machine folder.
The path to an HTML page in which to display information about each virtual machine in the list.
You added a component to the Virtual Machine Manager Web view that obtains a list of virtual machines from a given folder in the vCenter Server.
N
OTE
You create the Web view attributes that the vmo:ListPane component requires in the Orchestrator client.
What to do next
Define the Web view attributes that the vmo:ListPane component requires.
Define the Web View Attributes for the vmo:ListPane Component
The vmo:ListPane component refers to Web view attributes that provide an action to obtain an array of virtual machines from the server and the virtual machine folder from which to obtain them.
Prerequisites
You added the vmo:ListPane component to the default.html
Web view file.
Procedure
1 In the Web Views view in the Orchestrator client, right-click the Virtual Machine Manager Web view and select Edit.
2 Click the Attributes tab in the Web view editor.
3 Right-click in the Attributes tab and select Add attribute.
VMware, Inc. 319
vCenter Orchestrator Developer's Guide
4 Click the attribute name and type getVirtualMachineList .
5 Click the attribute Type link and select Action from the list.
6 Click the attribute Value link and search for and select the getAllVirtualMachinesByFolder action.
The getAllVirtualMachinesByFolder action returns an array of VC:VirtualMachine objects.
7 Right-click in the Attributes tab and select Add attribute to create the following Web view attribute: n Name: vmFolder n Type:
VC:VmFolder n Value: A virtual machine folder that you select from the vCenter server inventory
N
OTE
If you install the Virtual Machine Manager Web view from the Orchestrator samples bundle, you must edit the vmFolder attribute to point to a virtual machine folder in your vCenter Server before you publish the Web view.
8 Click Save and Close to exit the Web view editor.
9 Open the Virtual Machine Manager Web view in a browser at http:// <orchestrator_server>:
8280/vmo/
The Virtual Machine Manager Web view displays a list of virtual machines.
The Virtual Machine Manager Web view uses the getVirtualMachineList Web view attribute to obtain the list of virtual machines from the virtual machine folder that the vmFolder attribute defines. However, clicking on a virtual machine in the list returns an error, as you did not define how to obtain and display the virtual machine information.
What to do next
Create a Web view component to obtain and display information about a virtual machine when you click it in the list.
Create a Web View Component to Display Virtual Machine Information
The vmo:ListPane component lists virtual machines in the left side of the Web view. You can create a Web view component to show information about each virtual machine in a Web view panel on the right side.
The Web view panel that displays the virtual machine information requires a Web view component that obtains information from the objects that the vmo:ListPane component lists and displays the information on the right.
The Web view component that obtains object properties implements the WebObjectComponent class.
Prerequisites
You added a vmo:ListPane component to the default.html
file, and defined the Web view attributes that the component requires.
Procedure
1 Create a file called panel.html
, and save it at the root of your working folder.
2 Add a title to the panel.html
file.
<h3>Virtual Machine Information</h3>
3 Create a Web view component specification file called DisplayVmInfo.jwc
in the \components folder.
320 VMware, Inc.
Chapter 9 Developing Web Views
4 Add references to the Tapestry DTD and the
WebObjectComponent
Java class to the
DisplayVmInfo.jwc
component specification file.
You refer to the DTD in the DOCTYPE metatag and use <component-specification> tags to refer to the
WebObjectComponent Java class.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE component-specification PUBLIC
"-//Apache Software Foundation//Tapestry Specification 4.0//EN"
"http://jakarta.apache.org/tapestry/dtd/Tapestry_4_0.dtd">
<component-specification class="ch.dunes.web.webview.components.WebObjectComponent">
</component-specification>
5 Create a Web view component template called
DisplayVmInfo.html
in the
\components
folder.
The DisplayVmInfo.html
file defines how to present the information that the component obtains.
6 Add a table to the DisplayVmInfo.html
file to contain information about the virtual machines that are in the list.
<table width="200" border="1">
<tr>
<td>Virtual machine name</td>
<td></td>
</tr>
<tr>
<td>Virtual machine attributes</td>
<td></td>
</tr>
<tr>
<td>Object ID</td>
<td></td>
</tr>
</table>
7 Add references to the standard Tapestry Insert component and OGNL statements to obtain properties from the array of VC:VirtualMachine objects that the vmo:ListPane component obtains.
<table width="200" border="1">
<tr>
<td>Virtual machine name</td>
<td><vmo jwcid="@Insert" value="ognl:get('name')"/></td>
</tr>
<tr>
<td>Object ID</td>
<td><vmo jwcid="@Insert" value="ognl:get('id')"/></td>
</tr>
</table>
The value attributes of the Insert component use the WebObjectComponent.get() methods in OGNL statements to obtain the following properties from the VC:VirtualMachine objects: n n
The name property to display the virtual machine name
The id property to display the Orchestrator ID of the virtual machine
VMware, Inc. 321
vCenter Orchestrator Developer's Guide
8 Add a reference to the
DisplayVmInfo
component to the panel.html file.
<h3>Virtual Machine Information</h3>
<vmo jwcid="@DisplayVmInfo" urlParameter="itemId" />
9 Open the Virtual Machine Manager Web view in a browser at http:// orchestrator_server:8280/vmo/ and click one of the virtual machines in the list on the left.
Information about the virtual machine you clicked appears on the right.
You created a Web view page that obtains a list of virtual machines from the vCenter server and displays information about each virtual machine in the list.
What to do next
Create a tab in the Virtual Machine Manager Web view to run workflows on objects in the vCenter server inventory.
Create a Web View Tab by Using the Menu Component
The default Web view template provides a Menu component that you can use to create navigation tabs in a Web view.
The VMMBorder component that the default Web view template uses to render its layout includes a reference to the Menu component. Any changes you make to the Menu component appear in the Web view.
Prerequisites n n n
Import the default Web view template to Orchestrator to create the Virtual Machine Manager Web view
Export the contents of the Virtual Machine Manager Web view to a working directory
Configure Orchestrator in Web view development mode
Procedure
1 Create an HTML file called runWorkflows.html
and save it at the root of your working folder.
The runWorkflows.html
file defines the body of the new tab.
2 Add a reference to the MyBorder component, a title, and some text to the runWorkflows.html
file.
<vmo jwcid="@layout/VMMBorder" section="literal: home" title="Run Workflows">
<p style="margin-left: 16px; margin-top: 5px; margin-bottom: 5px;">Click a workflow to run it.</p>
</vmo>
3 Rename the
\component\Menu.html
Web view template file to
\component\VMMMenu.html
.
If you run more than one Web view in the same Orchestrator server, all components must have a unique name.
4 Open the \component\VMMBorder.html
Web view template file in an HTML editor.
5 Change the reference to the Menu component to VMMMenu .
jwcid="@layout/VMMMenu
322 VMware, Inc.
Chapter 9 Developing Web Views
6 Open the
\component\VMMMenu.html
Web view template file in an HTML editor.
The Menu.html
file contains an unordered list with one <li> entry that links to the home page of the Web view.
<ul id="sectionMenu" class="menu">
<li jwcid="@Any" class="ognl:page.isCurrentPage(webview.urlFolder + '/default')?
'selected':''">
<a href="./">Home</a></li>
</ul>
7 Copy and paste the <li> entry to create a second menu tab.
You create menu tabs in the Web view by adding
<li>
entries to the unordered list.
8 Modify the new <li> entry to point to runWorkflows.html
.
a Change the ognl:page.isCurrentPage
OGNL statement to add the runWorkflows suffix to the URL.
b Change the <a href> link to point to ./runWorkflows.html
.
c Change the <a href> text to Workflows .
<li jwcid="@Any" class="ognl:page.isCurrentPage(webview.urlFolder + '/runWorkflows')?
'selected':''">
<a href="./runWorkflows.html">Workflows</a></li>
9 Open the Virtual Machine Manager Web view in a browser at http:// <orchestrator_server>:
8280/vmo/ .
The Workflows tab appears in the Web view. If you click the tab, you see the contents of the runWorkflows.html
file.
You added a tab to the Web view.
What to do next
Use the vmo:WorkflowLink
component to run workflows from the Workflows tab.
Add Links to Run Workflows from a Web View by Using the vmo:WorkflowLink
Component
You add links to run workflows from a Web view by using the vmo:WorkflowLink component. You define the workflows to run by setting Web view attributes.
Prerequisites n n
Create a Web view tab in the Virtual Machine Manager Web view by modifying the
Menu.html
component template.
Create the runWorkflows.html
file to define the contents of the tab.
VMware, Inc. 323
vCenter Orchestrator Developer's Guide
Procedure
1 Open the runWorkflows.html
file in an HTML editor.
2 Add a reference to the vmo:WorkflowLink component to the runWorkflows.html
file.
<vmo jwcid="@layout/VMMBorder" section="literal: home" title="Run Workflows">
<p style="margin-left: 16px; margin-top: 5px; margin-bottom: 5px;">
Click a workflow to run it.</p>
<ul>
<li>
<a jwcid="@vmo:WorkflowLink" workflow="createVM" isDialog="true">
Create simple virtual machine</a>
</li>
</ul>
</vmo>
Setting the isDialog property to true displays a dialog box in which users provide input parameters to run the workflow.
The workflow
property refers to a Web view attribute called createVM
that you create in the Orchestrator client.
3 In the Web Views view in the Orchestrator client, right-click the Virtual Machine Manager Web view and select Edit.
4 Right-click in the Attributes tab in the Web view editor and select Add attribute.
5 Click the attribute name and type createVM .
6 Click the attribute Type link and select Workflow from the list.
7 Click the attribute Value link and search for and select the Create simple virtual machine workflow.
8 Click Save and Close to exit the Web view editor.
9 Open the Virtual Machine Manager Web view in a browser at http:// <orchestrator_server>:
8280/vmo/ .
324 VMware, Inc.
Chapter 9 Developing Web Views
10 Click the Create simple virtual machine link in the Workflows tab.
A Web form opens in the browser to allow users to enter parameters to create a virtual machine.
11 (Optional) Add more links to start workflows by adding more vmo:WorkflowLink
references to runWorkflows.html
.
For example, add the following vmo:WorkflowLink references:
<li><a jwcid="@vmo:WorkflowLink" workflow="cloneVM" isDialog="true">
Clone a virtual machine
</a></li>
<li><a jwcid="@vmo:WorkflowLink" workflow="snapVM" isDialog="true">
Take a snapshot of all virtual machines in a resource pool
</a></li>
<li><a jwcid="@vmo:WorkflowLink" workflow="removeSnaps" isDialog="true">
Remove virtual machine snapshots of a given size
</a></li>
<li><a jwcid="@vmo:WorkflowLink" workflow="thickToThin" isDialog="true">
Convert a virtual disk from thick to thin provisioning
</a></li>
<li><a jwcid="@vmo:WorkflowLink" workflow="deleteVM" isDialog="true">
Delete a virtual machine
</a></li>
Make sure that you create the Web view attribute for each vmo:WorkflowLink
reference.
You added links to the Virtual Machine Manager Web view that run workflows on virtual machines in the vCenter server inventory.
What to do next
Customize the appearance of the Web view.
Customize the Web View Interface
You can customize the appearance of the Web view by adjusting the custom.css
style sheet and changing the images in the
\images
folder.
Prerequisites
You created the Virtual Machine Manager Web view.
Procedure
1 (Optional) Change the Web view logo by overwriting the \images\header_logo.jpg
file, for example, with a JPEG of your company logo.
2 Open the \css\custom.css
style sheet file in a text editor.
3 Adjust the width
and height
values of siteTitle
to fit the proportions of your company logo file.
VMware, Inc. 325
vCenter Orchestrator Developer's Guide
4 Refresh the page in the browser.
5 (Optional) Customize any part of the Web view by modifying the custom.css
file.
You can edit the custom.css
to override the VMMBorder.html
component template file and the border.css
style sheet to modify the overall layout of the Web view.
N
OTE
The custom.css
style sheet is the only layout file that you should modify. If you modify other style sheets or component template files, your changes are lost if you upgrade Orchestrator.
You customized the appearance of the Web view by adjusting the custom.css
style sheet and by changing the logo.
What to do next
Disable Web view development mode, import the Web view files to the server, and publish the Web view.
Publish the Virtual Machine Manager Web View
After you finish developing the Virtual Machine Manager, you must disable Web view development mode, import the Web view from your working directory to the Orchestrator server, and publish the Web view.
Prerequisites
You finished developing the Virtual Machine Manager Web view.
Procedure
1 Open the Orchestrator configuration interface in a browser.
Option Action
If you connect to the server using
HTTP
Go to http://orchestrator_server:8282
If you connect to the server securely using HTTPS
Go to https://orchestrator_server:8283
2 Log in to the configuration interface by using the configuration username and password.
The Orchestrator administrator set the configuration username and password when they installed
Orchestrator.
3 Click the Advanced Configuration tab in the General view and uncheck the Enable Web view
development mode check box.
4 Click Apply changes.
5 Click Restart Service in the Startup Options view to restart the Orchestrator server in normal mode.
6 After the Orchestrator server restarts, right-click Virtual Machine Manager in the Web Views view of the Orchestrator client, and select Edit.
7 Click Import from directory in the Elements tab in the Web view editor.
8 Select your working folder and click Import to import the updated files from your working directory to the server.
9 Click Save and Close to exit the Web view editor.
10 Right-click the Virtual Machine Manager Web view and select Publish.
326 VMware, Inc.
Chapter 9 Developing Web Views
You imported the Virtual Machine Manager Web view from your working directory to the server and published it.
N
OTE
If you install the Virtual Machine Manager Web view from the Orchestrator samples bundle, you must edit the vmFolder attribute to point to a virtual machine folder in your vCenter Server before you publish the
Web view.
What to do next
You can open the Virtual Machine Manager Web view in a browser and use it to examine virtual machines and run workflows.
VMware, Inc. 327
vCenter Orchestrator Developer's Guide
328 VMware, Inc.
Refactoring Orchestrator Applications
After Upgrading vCenter Server
10
If you upgrade the virtual infrastructure from VMware Infrastructure 3.5 to vCenter Server 4.0, you must refactor any Orchestrator applications that you wrote for use with the older version. Orchestrator 4.0 provides workflows to help you refactor the applications to the new version. Alternatively, you can run VMware
Infrastructure 3.5 on Orchestrator 4.0 by installing the VMware Infrastructure 3.5 plug-in.
This chapter includes the following topics: n
“When to Refactor Applications,” on page 329
n n n
“Install the VMware Infrastructure 3.5 Plug-In,” on page 330
“Refactoring Packages with the Basic Refactoring Workflow,” on page 330
“Refactoring Packages with the Advanced Refactoring Workflows,” on page 333
When to Refactor Applications
If you upgrade the virtual infrastructure from VMware Infrastructure 3.5 to vCenter Server 4.0, you must take action to continue to run your existing applications.
You develop Orchestrator applications as plug-ins. Plug-ins consist of one or more packages that can contain workflows, actions, Java classes, XML files, Web views, configuration elements, or policy templates. The package names and certain object types used by the vCenter Server 4.0 API are different from those used by previous versions of VMware Infrastructure. The name and type changes are listed in
If you upgrade the virtual infrastructure from VMware Infrastructure 3.5 to vCenter Server 4.0, one course of action is to install the VMware Infrastructure 3.5 plug-in on an Orchestrator server 4.0 platform and then import your applications. The VMware Infrastructure 3.5 plug-in communicates with the vCenter Server 4.0 plug-in and allows you to run your applications without change.
Alternatively, to benefit from all the features of vCenter Server 4.0, you can refactor Orchestrator applications that you wrote with the old version. Orchestrator 4.0 provides workflows to help you refactor the applications to the new version.
Table 10-1. Object Name Changes from Previous Versions of VMware Infrastructure to vCenter Server 4.0
Object
Package name
FinderResult type
Scripting type
Host
Value in Previous Versions of
VMware Infrastructure vim3
VIM3
Vim
VMware3:VimHost
Value in vCenter Server 4.0
vcenter
VC
Vc <ScriptName>
VC:SdkConnection
VMware, Inc. 329
vCenter Orchestrator Developer's Guide
Because of these name and type changes, you must update all the VMware Infrastructure function calls made by the applications so that they can find the functions in the vCenter Server 4.0 API packages, through the vCenter Server 4.0 plug-in.
I
MPORTANT
To avoid accidentally overwriting packages during the refactoring process, you must back up your packages and applications before you run the refactoring workflows. If the refactoring fails, restore your server to its previous state.
In addition, when you refactor an application, all the refactored workflows have new workflow IDs. If you have applications, for example, Web service clients, that access workflows by using their IDs, you must update those workflow IDs accordingly.
Install the VMware Infrastructure 3.5 Plug-In
To continue running applications you developed for VMware Infrastructure 3.5 with Orchestrator 4.0, one solution is to install the optional VMware Infrastructure 3.5 plug-in. The VMware Infrastructure 3.5 plug-in is delivered with Orchestrator 4.0, but is not installed by default.
If you install the VMware Infrastructure 3.5 plug-in, you can run applications you developed for VMware
Infrastructure 3.5. However, you will not benefit from the features of vCenter Server 4.0 with these applications.
To benefit from the features of vCenter Server 4.0, refactor your VMware Infrastructure 3.5 applications.
Procedure
1 Open the Orchestrator configuration interface in a browser, at the following URL and log in.
http:// <orchestrator_server>:8282
2 In the General tab, click Install Application.
3 Browse to one of the following locations on the machine that hosts the Orchestrator server.
n c:\Program Files\VMware\Orchestrator\extras\plugins if you installed the standalone version of
Orchestrator.
n c:\Program Files\VMware\Infrastructure\Orchestrator\extras\plugins if the vCenter Server installed Orchestrator.
4 Select vmo_vi35_4_0_1_ <build_number>.vmoapp
and click Open.
5 Click Install.
6 Click Startup Options.
7 Click Restart Service to restart the Orchestrator server.
You installed the VMware Infrastrcuture 3.5 plug-in.
What to do next
You can run applications you wrote for VMware Infrastructure 3.5 using Orchestrator 4.0.
Refactoring Packages with the Basic Refactoring Workflow
Orchestrator provides a basic workflow to help you refactor packages so that they access vCenter Server 4.0.
The refactoring workflow makes a copy of an existing VMware Infrastructure 3.5 Orchestrator package and modifies all the elements in the copy to use vCenter Server 4.0. When you run the workflow, the original
VMware Infrastructure 3.5 application remains untouched, but the new duplicate is updated to run using vCenter Server 4.0.
330 VMware, Inc.
Chapter 10 Refactoring Orchestrator Applications After Upgrading vCenter Server
Set Up the Refactoring Tutorial Example Application (Optional)
You can use the Refactor Tutorial example to experiment with the refactoring workflows. You can import the example package into Orchestrator and set up the example.
The Refactor Tutorial example consists of a package containing two basic workflows and a Web view.
n n
The Suspend virtual machine workflow requests the suspension of a virtual machine running in a VMware
Infrastructure 3.5 inventory and waits for the VMware Infrastructure to complete the suspension request.
The Resume virtual machine workflow requests the resumption of the VMware Infrastructure 3.5 virtual machine and waits for the VMware Infrastructure to complete the resumption request.
n The Refactor Tutorial Web view allows you to run the Suspend virtual machine and Resume virtual machine workflows from a Web interface in a browser.
Initially, the Refactor Tutorial Web view accesses and interacts with virtual machines running in theVMware
Infrastructure 3.5 inventory. After you run the refactoring workflow, this Web view application accesses and interacts with the virtual machines in the vCenter Server 4.0 inventory instead.
Prerequisites n n n
You must have the VMware Infrastructure 3.5 and the vCenter Server 4.0 plug-ins installed on the
Orchestrator server.
Orchestrator must be connected to a VMware Infrastructure 3.5 server and to a vCenter Server 4.0 server, with virtual machines running in both.
You must have downloaded the ZIP file of examples from the Orchestrator documentation index page.
See
“Example Applications,” on page 9.
Procedure
1 Unzip the ZIP file of examples to an appropriate location.
2 Open <installation_directory>/Refactoring .
The Refactoring folder contains com.vmware.refactor.tutorial.package
.
3 Import com.vmware.refactor.tutorial.package
.
a Click the Packages view in the left pane of the Orchestrator client.
b Right-click anywhere on the whitespace under the list of packages and select Import Package.
c Locate com.vmware.library.refactor.tutorial.package
and click Open.
Information about the package certificates appears.
d Click Import.
The package contents appear, with a checklist of elements to import.
e Click Import checked elements.
4 Select Documentation > Refactor tutorial to check that the Refactoring Tutorial workflows are present in the Workflows view in the left pane.
5 Start the Refactor Tutorial Web view.
a Click the Web Views view in the left pane.
b Right-click the Refactor Tutorial Web view and select Publish to start it.
6 In a Web browser, go to http:// Orchestrator_server:8280 , in which Orchestrator_server is the name or IP address of the machine on which the Orchestrator server is running.
VMware, Inc. 331
vCenter Orchestrator Developer's Guide
7 Select Web View List > Refactor Tutorial.
8 Log in using the same user name and password that you use to access the Orchestrator client.
You installed the Refactor Tutorial example. The Refactor Tutorial Web view allows you to suspend and resume virtual machines running in the VMware Infrastructure 3.5 server. You can experiment with refactoring an application from VMware Infrastucture 3.5 to vCenter Server 4.0.
What to do next
You can refactor this example application.
Run the Basic Refactoring Workflow
The basic refactoring workflow successfully refactors most VMware Infrastructure 3.5 applications so that they use the vCenter Server 4.0 API.
Prerequisites
You must have a VMware Infrastructure 3.5 Orchestrator application to refactor.
Procedure
1 Click the Workflows view in the left pane of the Orchestrator client interface.
2 Select Library > Refactoring in the workflows hierarchical list to view the refactoring workflows.
3 Right-click the Migrate package to vCenter Server 4 workflow and select Execute workflow.
4 Under Package, click the Source package value and select the package to refactor from VMware
Infrastructure 3.5 to vCenter Server 4.0.
5 Enter a destination package in the Destination package text box.
You use the destination package to create the refactored application.
6 Under Rules, point the refactoring workflow to the different sets of objects that the application contains, and provide destinations in which to make copies of these objects.
If you do not provide destinations, the refactoring tool does not perform the refactoring. If the application does not feature a certain type of object, leave that text box set to Not set.
N
OTE
When you set the source location of action rules, you cannot select the location from a list. You must type the source location manually.
7 Under Save XML, click the Not set button to select a resource folder in which to store the result of the refactoring workflow.
8 Click Submit.
The Migrate package to vCenter Server 4 workflow runs.
The Migrate package to vCenter Server 4 workflow copied and refactored the application so that the new version implements the vCenter Server 4.0 plug-in instead of the VMware Infrastructure 3.5 plug-in. The
VMware Infrastructure 3.5 version of the application remains in place, unmodified.
What to do next
Verify that the refactoring workflow refactored the application correctly.
332 VMware, Inc.
Chapter 10 Refactoring Orchestrator Applications After Upgrading vCenter Server
Verify the Refactoring
When you have run the refactoring workflow, verify that the workflow refactored the application correctly.
Procedure
1 Click the Packages view in the Orchestrator client interface to check that the new package is present.
In the Refactoring Tutorial example, a package called com.vmware.refactor.tutorial_vcenter40
is listed.
2 Click the Workflows view to check that the refactored workflows are present.
In the Refactoring Tutorial example, select Documentation > Refactor tutorial copy to view the Submit
VM and Resume VM workflows that are in the workflows hierarchical list.
3 Check that the new workflows implement the vCenter Server 4.0 plug-in.
a Click on one of the new workflows.
b In the right pane, click the Schema tab.
c In the schema diagram, double-click one of the elements to show the element in the element hierarchical list on the left.
The vCenter Server 4.0 plug-in appears in the list.
For example, in the Refactor Tutorial example, select Refactor Tutorial Copy > Suspend VM and doubleclick the Suspend virtual machine and wait workflow element. The Suspend virtual machine and wait workflow element is located in the Library > vCenter Server > Virtual machine management > Power
Management node of the workflows hierarchical list. In the original version of the example, this element is in the VIM3 node rather than the vCenter Server node.
4 Click the Web views view.
5 Right-click the old Refactor Tutorial Web view and select Unpublish.
6 Right-click the new, refactored Refactor Tutorial Web view and select Publish.
7 In a browser, go to http:// <orchestrator_server>:8280/vmo/refactortutorial/default.html
to access the Refactor Tutorial Web view.
8 Log in to the Refactor Tutorial Web view with your Orchestrator user name and password.
9 Click Suspend VM.
10 Search for a virtual machine to suspend.
If the virtual machines that you can suspend are in the vCenter Server 4.0 environment, the refactoring was successful.
You verified that you successfully refactored an application. Your application now implements the vCenter
Server 4.0 plug-in.
Refactoring Packages with the Advanced Refactoring Workflows
If the basic refactoring workflow does not successfully refactor the VMware Infrastructure 3.5 application, you can try to refactor the application by using the advanced refactoring workflows.
The advanced refactoring workflows use the same workflows that the basic refactoring workflow calls upon.
If the basic workflow does not work, or to define the output parameters of the refactoring workflows yourself, you can use the advanced refactoring workflows directly.
VMware, Inc. 333
vCenter Orchestrator Developer's Guide
The advanced refactoring workflows make a copy of an existing VMware Infrastructure 3.5 Orchestrator application and modify all the elements in the copy to use vCenter Server 4.0. When you run the workflows, the original VMware Infrastructure 3.5 application remains untouched, but the new duplicate is updated to run using vCenter Server 4.0.
Advanced Refactoring Workflows
The advanced refactoring workflows use XML description files to define which applications to refactor, where to create the duplicate application, which elements in the application to refactor, where to find the refactoring rules, and so on. The advanced refactoring workflows include a workflow that creates these XML description files for you.
Table 10-2 shows the advanced refactoring workflows that Orchestrator provides.
Table 10-2. Advanced Refactoring Workflows
Workflow Name
Library > Refactoring > Advanced > Create refactoring description XML file
Library > Refactoring > Advanced > Copy VMware
Infrastructure 3 application and migrate to vCenter Server
4
Library > Refactoring > Advanced > Copy VMware
Infrastructure 3 application and migrate to vCenter Server
4, with a String input
Library > Refactoring > Advanced > Run refactoring
Library > Refactoring > Advanced > Refactor using resources
Description
Requests user input to define the following information: n The name and location of the application to refactor n n
The rules for copying the package objects
The types of elements to refactor in the duplicate application n Names and locations for the resource files that the refactoring workflows use
This information is recorded in XML description files that the other refactoring workflows use when they run.
Performs the following actions: n Creates a duplicate of the application with the name and in the location specified in the XML description files.
n n
Updates the elements in the duplicate application so that they implement the vCenter Server 4.0 plug-in.
Optionally provides a log of all the elements that the workflow has updated. This log is an XML mapping file that you can use when refactoring other applications.
Performs the following actions: n n
Creates a duplicate of the application with the name and in the location specified in an XML description you provide to the workflow as a String.
Updates the elements in the duplicate application so that they implement the vCenter Server 4.0 plug-in.
n
Optionally provides a log of all the elements that the workflow has updated. This log is an XML mapping file that you can use when refactoring other applications.
Performs refactoring without input parameters. This workflow is run by the Copy VMware Infrastructure 3 application and migrate to vCenter Server 4 workflow. If necessary, you can modify this workflow to define refactoring rules specific to the application. This is an advanced use case.
Performs refactoring according to rules defined in a resource element (an XML file) instead of in an XML string. This workflow is run by the Copy VMware Infrastructure 3 application and migrate to vCenter Server 4 workflow. If necessary, you can modify this workflow to define refactoring rules specific to the application. This is an advanced use case.
334 VMware, Inc.
Chapter 10 Refactoring Orchestrator Applications After Upgrading vCenter Server
Run the Advanced Refactoring Workflows
If the basic Migrate package to vCenter Server 4 workflow does not successfully refactor your application, you can run the advanced refactoring workflows.
Prerequisites
You must have a VMware Infrastructure 3.5 Orchestrator application to refactor.
Procedure
1 Run the Create refactoring description XML file workflow to create a copy.xml
XML description file.
2 Run the Create refactoring description XML file workflow again to create an update-references.xml
XML description file.
3 Run the Copy VMware Infrastructure 3 application and migrate to vCenter Server 4 workflow to refactor the application and migrate to the vCenter Server 4.0 plug-in.
To run the refactoring workflow, you must pass to it the copy.xml
file and the update-references.xml
file.
You refactored your application by running the advanced refactoring workflows directly.
VMware, Inc. 335
vCenter Orchestrator Developer's Guide
336 VMware, Inc.
Appendix: Workflow Name Changes
Many workflow names have changed in this release. Workflow name changes can affect Web service applications, if a Web service client uses the getWorkflowsWithName operation.
You must update Web services applications that use getWorkflowsWithName
to reflect the new workflow names.
The following sections list all the workflows for which the names changed between Orchestrator 4.0 and
Orchestrator 4.0.1.
This appendix includes the following topics: n
“JDBC Workflow Name Changes,” on page 337
n n n n
“Locking Workflow Names Unchanged,” on page 338
“Mail Workflow Name Changes,” on page 338
“Orchestrator Workflows,” on page 338
“Refactoring Workflow Name Changes,” on page 338
n n n
“SSH Workflow Name Changes,” on page 339
“vCenter Server Workflow Name Changes,” on page 339
“XML Workflow Name Changes,” on page 342
JDBC Workflow Name Changes
The workflow library includes a set of workflows to demonstrate JDBC tasks.
Table A-1 lists the JDBC workflow names that changed.
Table A-1. JDBC Workflow Name Changes
Old Workflow Name
Tests JDBC > JDBC url generator
Tests JDBC > Test All database
Tests JDBC > Test connection
Tests JDBC > Test create table
Tests JDBC > Test delete all from table
Tests JDBC > Test delete entry from table
Tests JDBC > Test drop table
Tests JDBC > Test insert into table
Tests JDBC > Test select from table
New Workflow Name
JDBC URL generator
JDBC Examples > Full JDBC cycle example
JDBC Examples > JDBC connection example
JDBC Examples > JDBC create table example
JDBC Examples > JDBC delete all from table example
JDBC Examples > JDBC delete entry from table example
JDBC Examples > JDBC drop table example
JDBC Examples > JDBC insert into table example
JDBC Examples > JDBC select from table example
VMware, Inc. 337
vCenter Orchestrator Developer's Guide
Locking Workflow Names Unchanged
The Orchestrator workflow library includes a set of workflows for locking.
Mail Workflow Name Changes
The Orchestrator workflow library includes a set of workflows for managing email.
Table A-2 lists the Mail workflow names that changed.
Table A-2. Mail Workflow Name Changes
Old Workflow Name
Email - Retrieve Messages
Email Send (Interaction)
Email Send (Notification to Mailing list)
Email Send (Notification)
Example Interaction with mail
New Workflow Name
Retrieve messages
Send interaction
Send notification to mailing list
Send notification
Example interaction with email
Orchestrator Workflows
The Orchestrator workflow library includes a set of workflows specific to Orchestrator operations.
Table A-3 lists the Orchestrator workflow names that changed.
Table A-3. Orchestrator Workflow Name Changes
Old Workflow Name
Tasks > Create Recurrent Task
Tasks > Create Task
Workflows > Start Workflows in Parallel
Workflows > Start Workflows in Serial
New Workflow Name
Tasks > Create recurrent task
Tasks > Create task
Workflows > Start workflows in parallel
Workflows > Start workflows in a series
Refactoring Workflow Name Changes
The Orchestrator workflow library includes a set of workflows for refactoring your applications.
Table A-4 lists the refactoring workflow names that changed.
Table A-4. Refactoring Workflow Name Changes
Old Workflow Name
Migrate Package To vCenter 4
Advanced > Refactor - Copy VMware3 based application and migrate to use vCenter 4.0 plugin
Advanced > Refactor - Copy VMware3 based application and migrate to use vCenter 4.0 plugin With String Input
Advanced > Refactor - Create RefactorDescription XML
Advanced > Refactor - Execute Refactor Using Resources
Advanced > Refactor - Execute Refactor
New Workflow Name
Migrate package to vCenter Server 4
Advanced > Copy VMware Infrastructure 3 application and migrate to vCenter Server 4
Advanced > Copy VMware Infrastructure 3 application and migrate to vCenter Server 4, with a String input
Advanced > Create refactoring description XML file
Advanced > Refactor using resources
Advanced > Run refactoring
338 VMware, Inc.
Appendix: Workflow Name Changes
SSH Workflow Name Changes
The Orchestrator workflow library includes a set of SSH workflows.
Table A-5 lists the SSH workflow names that changed.
Table A-5. SSH Workflow Name Changes
Old Workflow Name
Change Key Pair passphrase
Generate Key Pair
SSH Execute command
SCP Get
SCP Put
New Workflow Name
Change key pair passphrase
Generate key pair
Run SSH command
SCP get command
SCP put command
vCenter Server Workflow Name Changes
The Orchestrator workflow library includes a set of workflows for accessing the objects in the vCenter Server.
Table A-6 lists the vCenter server workflow names that changed.
Table A-6. vCenter Workflow Name Changes
Old Workflow Name New Workflow Name
Cluster and Compute resource > Destroy cluster
Custom attributes > Add custom attribute
Datacenter > Destroy datacenter
Datacenter > Rescan Datacenter HBAs
Folder management > Datacenter folder > Create
Datacenter folder
Folder management > Datacenter folder > Destroy
Datacenter folder
Folder management > Datacenter folder > Rename
Datacenter folder
Folder management > Host folder > Create Host folder
Folder management > Host folder > Destroy Host folder
Folder management > Host folder > Rename Host folder
Folder management > VM folder > Create VM folder
Folder management > VM folder > Destroy VM folder
Folder management > VM folder > Rename VM folder
Cluster and Compute resource > Delete cluster
Custom attributes Add custom attribute to multiple virtual machines
Datacenter > Delete datacenter
Datacenter > Rescan datacenter HBAs
Folder management > Datacenter folder > Create datacenter folder
Folder management > Datacenter folder > Delete datacenter folder
Folder management > Datacenter folder > Rename datacenter folder
Folder management > Host folder > Create host folder
Folder management > Host folder > Delete host folder
Folder management > Host folder > Rename host folder
Folder management > VM folder > Create virtual machine folder
Folder management > VM folder > Delete virtual machine folder
Folder management > VM folder > Rename virtual machine folder
Host management > Basic > Move Host into Cluster
Host management > Power > Shutdown host
Host management > Basic > Move host into cluster
Host management > Power > Shut down host
Host management > Registration > Reconnect host (simple) Host management > Registration > Reconnect host
Host management > Registration > Reconnect host (with all info)
Host management > Registration > Reconnect host with all information
VMware, Inc. 339
vCenter Orchestrator Developer's Guide
Table A-6. vCenter Workflow Name Changes (Continued)
Old Workflow Name New Workflow Name
Resource Pool > Create resource pool (with default values) Resource Pool > Create resource pool
Resource Pool > Create resource pool Resource Pool > Create resource pool with specified values
Resource Pool > Destroy resource pool Resource Pool > Delete resource pool
Resource Pool > Reconfig resource pool Resource Pool > Reconfigure resource pool
Virtual Machine management > Basic > Create VM (Full) Virtual Machine managementBasic > Create custom virtual machine
Virtual Machine management > Basic > Create VM
(Simple)
Virtual Machine management > Basic > Destroy VM
Virtual Machine managementBasic > Create simple virtual machine
Virtual Machine managementBasic > Delete virtual machine
Virtual Machine management > Basic > Mark as Template Virtual Machine managementBasic > Mark as template
Virtual Machine management > Basic > Mark as Virtual
Machine
Virtual Machine managementBasic > Mark as virtual machine
Virtual Machine management > Basic > Move VM to folder Virtual Machine managementBasic > Move virtual machine to folder
Virtual Machine management > Basic > Move VM to
Resource pool
Virtual Machine managementBasic > Move virtual machine to resource pool
Virtual Machine management > Basic > Move VMs to
Folder
Virtual Machine management > Basic > Move VMs to
Resource pool
Virtual Machine management > Basic > Register Virtual machine
Virtual Machine management > Basic > Reload VM
Virtual Machine management > Basic > Rename VM
Virtual Machine managementBasic > Move virtual machines to folder
Virtual Machine managementBasic > Move virtual machines to resource pool
Virtual Machine managementBasic > Register virtual machine
Virtual Machine managementBasic > Reload virtual machine
Virtual Machine managementBasic > Rename virtual machine
Virtual Machine management > Basic > Set VM
Performance
Virtual Machine management Basic Unregister VM
Virtual Machine management > Basic > Upgrade VM
Virtual Machine managementBasic > Set virtual machine performance
Virtual Machine managementBasic > Unregister virtual machine
Virtual Machine managementBasic > Upgrade virtual machine
Virtual Machine managementBasic > Wait for task and answer virtual machine question
Virtual Machine management > Clone > Clone virtual machine, no customization
Virtual Machine management > Basic > Wait for task and answer VM question if asked
Virtual Machine management > Clone > Clone VM (No customization at all)
Virtual Machine management > Clone > Clone VM from
Properties
Virtual Machine management > Clone > Linux
Customization > Clone VM (Linux customization, 1 Nic)
Virtual Machine management > Clone > Linux
Customization > Clone VM (Linux customization, Multiple
Nic)
Virtual Machine management > Clone > Tools > Get 1 Nic
Setting Map
Virtual Machine management > Clone > Clone virtual machine from properties
Virtual Machine management > Clone > Linux
Customization > Clone, Linux with single NIC
Virtual Machine management > Clone > Linux
Customization > Clone, Linux with multiple NICs
Virtual Machine management > Clone > Tools > Get NIC setting map
340 VMware, Inc.
Appendix: Workflow Name Changes
Table A-6. vCenter Workflow Name Changes (Continued)
Old Workflow Name
Virtual Machine management > Clone > Tools > Get Linux
Customization
Virtual Machine management > Clone > Tools > Get
Multiple VirtualEthernetCard devices change
(add/remove)
Virtual Machine management > Clone > Tools > Get
Windows Customization (Sysprep)
Virtual Machine management > Clone > Tools > Tools > Get
Windows Customization (Sysprep, Credential)
Virtual Machine management > Clone > Tools > Get
Windows Customization (Unattended.txt)
Virtual Machine management > Clone > Windows
Customization > Clone VM (Windows customization
(Sysprep.inf), 1 Nic, Credential)
Virtual Machine management > Clone > Windows
Customization > Clone VM (Windows customization, 1
Nic)
Virtual Machine management > Clone > Windows
Customization > Clone VM (Windows customization, 1
Nic, Credential)
Virtual Machine management > Clone > Windows
Customization > Clone VM (Windows customization, 1
Nic, Credential, Thin provisionned)
Virtual Machine management > Clone > Windows
Customization > Clone VM (Windows customization,
Multiple Nic, Credential)
Virtual Machine management > Clone > Windows
Customization > Only Customize > Customize VM
(Windows customization, 1 Nic, Credential)
Virtual Machine management > Device Management >
Add Disk
Virtual Machine management > Device Management >
Mount floppy
Virtual Machine management > Device Management >
Add Disk
Virtual Machine management > Move and Migrate >
Migrate VM
Virtual Machine management > Move and Migrate >
Relocate VM
Virtual Machine management > Others > Extract VM informations
Virtual Machine management > Power Management >
Power off VM and wait
Virtual Machine management > Power Management >
Reset VM and wait
Virtual Machine management > Power Management >
Resume VM and wait
Virtual Machine management > Power Management >
Shutdown & Destroy VM
New Workflow Name
Virtual Machine management > Clone > Tools > Get Linux customization
Virtual Machine management > Clone > Tools > Get multiple VirtualEthernetCard device changes
Virtual Machine management > Clone > Tools > Get
Windows customizations for Sysprep
Virtual Machine management > Clone > Tools > Get
Windows customization, Sysprep with credentials
Virtual Machine management > Clone > Tools > Get
Windows customization, Sysprep with Unattended.txt
Virtual Machine management > Clone > Windows
Customization > Clone, Windows Sysprep with single NIC and credential
Virtual Machine management > Clone > Windows
Customization > Clone, Windows with single NIC
Virtual Machine management > Clone > Windows
Customization > Clone, Windows with single NIC and credential
Virtual Machine management > Clone > Windows
Customization > Clone thin provisioned, Windows with single NIC and credential
Virtual Machine management > Clone > Windows
Customization > Clone, Windows with multiple NICs and credential
Virtual Machine management > Clone > Windows
Customization > Only Customize > Customize, Windows with single NIC and credential
Virtual Machine management > Device Management >
Add disk
Virtual Machine management > Device Management >
Mount floppy disk drive
Virtual Machine management > Device Management >
Add disk
Virtual Machine management > Move and Migrate >
Migrate virtual machine
Virtual Machine management > Move and Migrate >
Relocate virtual machine disks
Virtual Machine management > Others > Extract virtual machine information
Virtual Machine management > Power Management Power off virtual machine and wait
Virtual Machine management > Power Management >
Reset virtual machine and wait
Virtual Machine management > Power Management >
Resume virtual machine and wait
Virtual Machine management > Power Management > Shut down and delete virtual machine
VMware, Inc. 341
vCenter Orchestrator Developer's Guide
Table A-6. vCenter Workflow Name Changes (Continued)
Old Workflow Name
Virtual Machine management > Power Management >
Shutdown guest OS and wait
Virtual Machine management > Power Management >
Standby OS
Virtual Machine management > Power Management > Start
VM and wait
Virtual Machine management > Power Management >
Suspend VM and wait
Virtual Machine management > Snapshot > Create a
Snapshot
Virtual Machine management > Snapshot > Create snapshots of all VMs in Resource Pool
Virtual Machine management > Snapshot > Remove all
Snapshots
New Workflow Name
Virtual Machine management > Power Management > Shut down guest OS and wait
Virtual Machine management > Power Management > Set guest OS to standby
Virtual Machine management > Power Management > Start virtual machine and wait
Virtual Machine management > Power Management >
Suspend virtual machine and wait
Virtual Machine management > Snapshot > Create a snapshot
Virtual Machine management > Snapshot > Create snapshots of all virtual machines in a resource pool
Virtual Machine management > Snapshot > Remove all snapshots
XML Workflow Name Changes
The Orchestrator workflow library includes a set of XML workflows.
Table A-7 lists the XML workflow names that changed.
Table A-7. XML Workflow Name Changes
Old Workflow Name New Workflow Name
Samples XML (Address Book) > Address Book Append
Stylesheet information
Samples XML (Address Book) > Append address book stylesheet information
Samples XML (Address Book) > Address Book Create CSS Samples XML (Address Book) > Create address book CSS
Samples XML (Address Book) > Address Book Create DTD Samples XML (Address Book) > Create address book DTD
Samples XML (Address Book) > Address Book Create XML Samples XML (Address Book) > Create address book XML
Samples XML (Address Book) > Address Book Full Test Samples XML (Address Book) > Full address book test
Samples XML (Simple) > Create simple document
Samples XML (Simple) > Modify Document
Samples XML (Simple) > Create a simple XML document
Samples XML (Simple) > Modify XML document
342 VMware, Inc.
Index
A
actions
finding elements that implement 113
advanced refactoring workflow 333, 335
attributes
B
basic refactoring workflow 330, 332
basic refactoring workflow, set up example 331
binding
bindings
C
configuration elements, creating 65
VMware, Inc.
D
default Web view template, contents 314
E
exception bindings, creating 38 exception handing 38
F
file system, System.getTempDirectory 121 file system access 121
FinderResult 252–254, 262, 297
findForId operation 252, 253 findRelation 252, 254, 271
G
getAllPlugin 274 getAllPlugins 274
getWorkflowForID 256, 257 getWorkflowsWithName 256, 275
getWorkflowsWithName operation 337
getWorkflowTokenResult 260, 276
getWorkflowTokenStatus 259, 277
343
vCenter Orchestrator Developer's Guide
H
HasChildrenResult Enumeration 228
I
IConfigurationAdaptor interface 217
input parameters
input parameters dialog box, creating 90, 108
input parameters, obtaining from user 39
IPluginAdaptor interface 144, 186, 218
IPluginEventPublisher interface 174, 218
IPluginFactory interface 145, 187, 219
IPluginNotificationHandler 220
IPluginPublisher interface 179, 180, 220
J
javascript, file system access 121
JavaScript API
adding functions 185 adding objects 185
JDBC workflows, name changes 337
L
linking
Locking workflows, name changes 338
long-running workflows
M
Mail workflows, name changes 338
Mozilla Rhino JavaScript engine 115
Mozilla Rhino Javascript engine, limitations 116
344
N
O
Orchestrator client, accessing 17
Orchestrator workflows, name changes 338
P
packages
create 137 digital rights management 137
parameter properties
parameters
plug-in API
HasChildrenResult Enumeration 228
IPluginEventPublisher interface 218
IPluginNotificationHandler 220
IPluginPublisher interface 220
ScriptingAttribute annotation 229
ScriptingFunction annotation 229
ScriptingParameter annotation 229
plug-ins
add configuration tab 192, 193, 196, 198, 200
VMware, Inc.
configuration adapter 191–193, 196
ConfigurationError class 221, 227
ConfigurationError.Severity enumeration 227
create event generator 170, 171
create scripting singleton 185
create workflow triggers 176, 177
creating workflow triggers 175, 178
factory 145, 153, 158–161, 163, 165
find objects by identifier 160
hasChildrenInRelation() method 163, 165
IConfigurationAdaptor interface 191–193, 196
implementing notification handlers 168
interact with plugged-in technology 212
IPluginEventPublisher interface 170, 172, 174
IPluginNotificationHandler interface 167–169
IPluginPublisher interface 179, 180, 182
VMware, Inc.
mapping classes 206 mapping methods 206
obtain configuration from user 196
policies 147 policy gauges 147 policy triggers 147
registering event listeners 168
SDKHelper class 191–193, 196, 225
solar system finder mappings 205
solar system JavaScript mappings 208
SolarSystemEventListener class 166
using the solar system plug-in 212 view scripting objects 212
WebConfigurationAdaptor interface 220
workflow triggers 147, 175, 176
plug-ins, add configuration tab 191
plug-ins, build solar system DAR 210
plug-ins, CelestialBody.java 155
plug-ins, ISolarSystemListener.java 156
plug-ins, scripting objects 146
plug-ins, SolarSystemEventHandler.java 156
Index
345
vCenter Orchestrator Developer's Guide
plug-ins, SolarSystemRepository.java 156
plugs-in, PluginTrigger class 175
presentation
display groups 39 input steps 39
properties
Q
R
Refactoing workflows, name changes 338
refactoring
resource elements
S
schema
346
links 31, 32 logical flow 31, 32 standard path 31, 32
schema elements
scriptable task elements, binding 81, 82
scripting
Mozilla Rhino Javascript engine 116
ScriptingAttribute annotation 229
ScriptingFunction annotation 229
ScriptingParameter annotation 229
solar system application, components 154
solar system plug-in
VMware, Inc.
SSH workflows, name changes 339
Start workflows in a series workflow 59
Start workflows in parallel workflow 59
U
user interactions
user interactions, exceptions 49
user interactions, input parameters dialog
user interactions, responding 52
user interactions, security.group attribute 45
user interactions, timeout.date attribute 46, 48
V
vCenter server workflows, name changes 339
VMware Infrastructure 3.5, install plug-in 330
vso.xml
attribute element 241 attributes element 241
constructor parameter element 241
entries element 245 entry element 245
enumeration element 244 enumerations element 244
finder-datasource element 233 finder-datasources element 233
VMware, Inc.
inventory-children element 237
method parameter element 243 method parameters element 243
relation element 237 relation-link element 237
trigger element 238 trigger-properties element 238 trigger-property element 238
webview-components-library element 233
vso.xml file
elements 230 module element 230
W
Web service
endpoint 249 generating stubs 249
Web service API
Web services
writing client application 247
Index
347
vCenter Orchestrator Developer's Guide
Web view
starting 282, 283 weboperator 282, 283
Web views
accessing resource elements from URLs 311
create from resource element template 287
custom.css 325 customize interface 325
default template 286, 312, 313
defining resource element template 287
development mode 284, 288, 289, 292, 316
disable development mode 292, 326
file structure 293 home page 293, 317
library of Tapestry components 301
Orchestrator development tasks 283
referencing Tapestry components 295
running actions from URLs 309, 310
Tapestry component specification file 296
Tapestry component template file 296
Vmo:DisplayProperty component 301
348
vmo:IncludeJavaScript component 302 vmo:IncludeStylesheet component 302
vmo:IncludeWorkflowHeader component 303,
vmo:ListPane component 300, 303, 318, 319
vmo:LoginComponent 305 vmo:PageAccessControl component 305
vmo:WebformContainer component 303, 307
vmo:WorkflowLink 307 vmo:WorkflowLink component 307, 323
Web views, component names 315
Web views. vmo:TaskAction component 306
workflow
workflow attributes, naming 22
workflow editor
workflow name changes
VMware, Inc.
Index
workflow parameters, naming 22
workflow presentation, creating 40
workflow schema
create 24, 73, 95 edit 24 elements 24
schema element properties tabs 29
Workflow schema, schema element
workflow token
workflows
editing 18 editing standard workflows 18
running on a selection of objects 58
starting 53 synchronous 53, 55
workflows, reserved OGNL keywords 22
X
XML workflows, name changes 342
VMware, Inc. 349
vCenter Orchestrator Developer's Guide
350 VMware, Inc.
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project