VMware vRealize Orchestrator - 7.0 User’s Manual

Developing a Web Services Client for

VMware vRealize Orchestrator

vRealize Orchestrator 7.0

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-001863-00

Developing a Web Services Client for VMware vRealize Orchestrator

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

docfeedback@vmware.com

VMware, Inc.

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

2 VMware, Inc.

Developing a Web Services Client for VMware vRealize Orchestrator 7

Developing a Web Services Client 9

Using the vRealize Orchestrator REST API 11

Authenticating Against Orchestrator and Third-Party Systems 12

Using vCenter Single Sign-On Authentication with the Orchestrator REST API 12

Using LDAP Authentication with the Orchestrator REST API 14

Accessing the Reference Documentation for the Orchestrator REST API 14

Using the Java REST SDK 14

Operations with Workflows 16

Find a Workflow and Retrieve Its Definition 16

Run a Workflow 18

Run a Workflow After Validating Its Input Parameters Against the Workflow Presentation 20

Interacting with a Workflow While It Runs 23

Retrieve a Workflow's Interactions 29

Access a Workflow's Schema 29

Working with Tasks 29

Create a Task 30

Modify a Task 31

Check the State of a Task 31

Finding Objects in the Orchestrator Inventory 32

Find Objects by Type and ID 32

Find Objects by Relations 33

Apply Filters 34

Importing and Exporting Orchestrator Objects 34

Import a Workflow 34

Export a Workflow 35

Import an Action 35

Export an Action 35

Import a Package 36

Export a Package 36

Import a Resource 37

Export a Resource 37

Import a Configuration Element 38

Export a Configuration Element 38

Deleting Orchestrator Objects 38

Delete a Workflow 38

Delete an Action 39

Delete a Package 39

Delete a Resource 39

Delete a Configuration Element 40

VMware, Inc.

Developing a Web Services Client for VMware vRealize Orchestrator

Setting Permissions on Orchestrator Objects 40

REST API Permissions 40

Retrieve the Permissions of a Workflow 41

Delete the Permissions of a Workflow 41

Set the Permissions for a Workflow 41

Retrieve the Permissions of an Action 42

Delete the Permissions of an Action 42

Set the Permissions for an Action 42

Retrieve the Permissions of a Package 43

Delete the Permissions of a Package 43

Set the Permissions for a Package 43

Retrieve the Permissions of a Resource 44

Delete the Permissions of a Resource 44

Set the Permissions for a Resource 44

Retrieve the Permissions of a Configuration Element 45

Delete the Permissions of a Configuration Element 45

Set the Permissions for a Configuration Element 46

Performing Operations with Plug-Ins 46

Retrieve Information About Plug-Ins 46

Import a Plug-In 46

Export a Plug-In 47

Enable or Disable a Plug-In 47

Performing Server Configuration Operations 48

Retrieve Information About the Orchestrator Server Configuration 48

Import Orchestrator Server Configuration 48

Export Orchestrator Server Configuration 48

Performing Tagging Operations 49

Tag an Object 49

Untag an Object 49

List Object Tags 50

List Tagged Objects by Type 50

List Tag Owners 50

List Tags by Users 51

List Tags by Users Filtered by Tag Name 51

Remove Tags by Users 51

Writing a Client Application for the Orchestrator SOAP Service 53

Process for Creating an Orchestrator Web Service Client Application 53

Web Service Endpoint 55

Generating the Orchestrator Web Service Stubs 55

Accessing the Server from Web Service Clients 56

Create a Web Service Client 56

Connect to the Orchestrator Web Service 57

Find Objects in the Orchestrator Server 58

Find Objects by Using the find Operation 58

Find Objects by Using the findForId Operation 59

Find Objects by Using the findRelation Operation 60

Find Workflows in the Orchestrator Server 61

Find Workflows by Using the getAllWorkflows Operation 62

4 VMware, Inc.

Retrieve the ID of a Workflow 62

Find Workflows by Using the getWorkflowsWithName Operation 62

Find Workflows by Using the getWorkflowForID Operation 63

Run Workflows from a Web Service Client 63

Interact with a Workflow While it Runs 64

Obtain Workflow Results 66

Time Zones and Running Workflows Through Web Services 67

Web Service Application Examples 67

Contents

Web Service API Object Reference 69

FinderResult Object 69

ModuleInfo Object 70

Property Object 71

QueryResult Object 71

Workflow Object 72

WorkflowParameter Object 73

WorkflowToken Object 73

WorkflowTokenAttribute Object 76

Web Service API Operation Reference 79

answerWorkflowInput Operation 80

cancelWorkflow Operation 80

echo Operation 81

echoWorkflow Operation 81

executeWorkflow Operation 81

find Operation 82

findForId Operation 83

findRelation Operation 84

getAllPlugins Operation 86

getAllWorkflows Operation 86

getWorkflowForId Operation 87

getWorkflowInputForId Operation 87

getWorkflowInputForWorkflowTokenId Operation 88

getWorkflowsWithName Operation 88

getWorkflowTokenBusinessState Operation 89

getWorkflowTokenForId Operation 89

getWorkflowTokenResult Operation 90

getWorkflowTokenStatus Operation 90

hasChildrenInRelation Operation 91

hasRights Operation 92

sendCustomEvent Operation 93

simpleExecuteWorkflow Operation 94

Index 97

VMware, Inc. 5

Developing a Web Services Client for VMware vRealize Orchestrator

6 VMware, Inc.

Developing a Web Services Client for VMware vRealize Orchestrator

Developing a Web Services Client for VMware vRealize Orchestrator provides information about developing a Web services client for VMware® vRealize Orchestrator.

Orchestrator provides Web services APIs so that you can develop applications to access and use workflows through the Web. Orchestrator provides a representational state transfer (REST) API as well as a simple object access protocol (SOAP) service that you can use to perform various operations over workflows.

Intended Audience

This information is intended for Web application developers who want to access the Orchestrator processes across a network, through technologies such as SOAP and RESTful Web services.

VMware, Inc.

Developing a Web Services Client for VMware vRealize Orchestrator

8 VMware, Inc.

Developing a Web Services Client 1

VMware vRealize Orchestrator provides Web services APIs so that you can develop applications to access workflows through the Web. The main purpose of the Orchestrator Web services APIs is to allow you to integrate Orchestrator workflows in custom Web-based applications.

Orchestrator provides Web services APIs that are based on two types of technologies:

A representational state transfer (REST) API. The Orchestrator REST API exposes the objects in the

Orchestrator inventory and the inventories of the installed plug-ins as resources that you can access at predefined URLs. HTTP requests at these URLs result in triggering operations over workflows. The Orchestrator REST API exposes inventory objects as resources through a set of RESTful Web services that you can use to retrieve the definitions of workflows, run workflows, check the status of the running workflows, cancel workflow runs, process waiting user interactions, retrieve the presentation of workflows, and so on.

A simple object access protocol (SOAP) service. The Orchestrator SOAP 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. You can also use the SOAP service 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.

VMware, Inc.

Developing a Web Services Client for VMware vRealize Orchestrator

10 VMware, Inc.

Using the vRealize Orchestrator

REST API 2

The Orchestrator REST API provides functionality that allows you to communicate with the Orchestrator server directly through HTTP and perform various workflow-related operations over workflows.

The Orchestrator REST API exposes the objects from the inventories of the Orchestrator server and the installed plug-ins as resources at predefined URLs. You make HTTP calls at these URLs to trigger operations in Orchestrator. In this way, you can perform various tasks over workflows:

Run a workflow, schedule a workflow, retrieve the runs of a workflow, answer to a user interaction,

and cancel a workflow run.

Retrieve details about a workflow such as its input and output parameters and its presentation.

Retrieve details about a workflow run, such as its state, generated logs, start date, and end date.

Browse the inventories of Orchestrator and the installed plug-ins.

Import and export workflows, actions, and packages.

By using the Orchestrator REST API you can easily integrate Orchestrator workflows in custom applications that you can build in any programing language.

The Orchestrator REST API also provides eTag support as well as a mechanism for caching of response data.

This chapter includes the following topics:

“Authenticating Against Orchestrator and Third-Party Systems,” on page 12

“Accessing the Reference Documentation for the Orchestrator REST API,” on page 14

“Using the Java REST SDK,” on page 14

“Operations with Workflows,” on page 16

“Working with Tasks,” on page 29

“Finding Objects in the Orchestrator Inventory,” on page 32

“Importing and Exporting Orchestrator Objects,” on page 34

“Deleting Orchestrator Objects,” on page 38

“Setting Permissions on Orchestrator Objects,” on page 40

“Performing Operations with Plug-Ins,” on page 46

“Performing Server Configuration Operations,” on page 48

“Performing Tagging Operations,” on page 49

VMware, Inc.

Developing a Web Services Client for VMware vRealize Orchestrator

Authenticating Against Orchestrator and Third-Party Systems

You must authenticate against Orchestrator in the HTTP requests that you make through the Orchestrator REST API. If you use the Orchestrator REST API to access resources on a third-party system, such as vCenter Server, you must authenticate against that system as well.

For example, to access all workflows in the Orchestrator inventory, you must authenticate against Orchestrator. However, to run a workflow against vCenter Server, you must authenticate against Orchestrator and vCenter Server.

Depending on whether you configure Orchestrator with LDAP or with vCenter Single Sign-On, the authentication scheme for the Orchestrator REST API is different. If Orchestrator uses LDAP, you must authenticate by using valid credentials. If Orchestrator uses vCenter Single Sign-On, depending on your configuration, you can authenticate by using basic authentication or by using a holder-of-key token issued by the vCenter Single Sign-On server.

NOTE LDAP authentication is deprecated.

If you make HTTP requests at the top-level URL of the Orchestrator REST API, you do not need to authenticate against Orchestrator. The top level URL of the Orchestrator REST API is https://orchestrator_host:port/vco/api/.

NOTE The default port number is 8281.

A GET request at the top level URL of the REST API returns URLs to all resources that are accessible through the API. To make HTTP requests at these URLs, you must authenticate against Orchestrator.

Using vCenter Single Sign-On Authentication with the Orchestrator REST API

If Orchestrator is configured with the vCenter Single Sign-On Server and basic authentication is disabled, you need a principal holder-of-key token to access system objects in Orchestrator through the Orchestrator REST API. To access vCenter Server or third-party systems that use the vCenter Single Sign-On Server through the Orchestrator server, you need a delegate holder-of-key token for Orchestrator and your principal token.

If Orchestrator is configured with the vCenter Single Sign-On Server and basic authentication is enabled, you must authenticate by using valid credentials and Orchestrator manages the holder-of-key token.

Accessing System Objects in Orchestrator

You can access system objects in Orchestrator at the URLs of the Inventory and the Catalog services of the REST API.

https://orchestrator_host:port/vco/api/inventory/System/

https://orchestrator_host:port/vco/api/catalog/System/

When you access system objects in Orchestrator, you pass your principal holder-of-key token in the

Authorization header of HTTP requests that you make to the Inventory or the Catalog service.

For example, to retrieve all system objects of type Workflow, you make a GET request at https://orchestrator_host:port/vco/api/catalog/System/Workflow/. To authenticate against Orchestrator, you need to pass your principal holder-of-key token in the Authorization header of the request.

12 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

Accessing Objects in Third-Party Systems

To perform operations in third-party systems that are registered with the vCenter Single Sign-On Server through the Orchestrator REST API, you must authenticate against Orchestrator and the third-party system. You include two headers in the HTTP calls that you make through the Orchestrator REST API.

Authorization. You must pass your principal holder-of-key token in this header.

VCOAuthorization. You must pass a delegate holder-of-key token for Orchestrator in this header. You

must acquire the delegate token for Orchestrator from the vCenter Single Sign-On Server. Orchestrator uses the delegate token to authenticate against the third-party system on your behalf.

For example, to run a workflow that uses a virtual machine through the Orchestrator REST API, you access resources both in Orchestrator and in vCenter Server. To authenticate against Orchestrator and vCenter Server, you must pass your principal holder-of-key token in the Authorization header of the request that you make, and the delegate token in the VCOAuthorization header. In this way, you authenticate against Orchestrator with your principal token and Orchestrator authenticates on your behalf against vCenter Server with the delegate token.

The vCenter Single Sign-On Server treats Orchestrator as a solution, and every solution is registered with a unique user name with the vCenter Single Sign-On Server. You request a delegate token for Orchestrator by passing the solution user name of Orchestrator and a principal holder-of-key token to the vCenter Single Sign-On Server. The token that the vCenter Single Sign-On Server issues is a delegate holder-of-key token for Orchestrator to authenticate on your behalf against third-party systems.

Example: Obtain a Session in vCenter Single Sign-On Mode

The following example code obtains a session in vCenter Single Sign-On mode.

URI uri = URI.create("https://orchestrator-server:8281/vco/api"); VcoSessionFactory sessionFactory = new DefaultVcoSessionFactory(uri);

//provide the address of the vCenter Single Sign-On server URI ssoUri = URI.create("https://sso-server:7444/ims/STSService?wsdl");

//set the tokens to be valid for an hour long lifeTimeSeconds = 60 * 60;

//create a factory for vCenter Single Sign-On tokens SsoAuthenticator sso = new SsoAuthenticator(ssoUri, sessionFactory, lifeTimeSeconds);

//provide vCenter Single Sign-On credentials SsoAuthentication authentication = sso.createSsoAuthentication("username", "password");

VcoSession session = sessionFactory.newSession(authentication); //use session here

Get the Solution User Name of Orchestrator

The vCenter Single Sign-On Server treats Orchestrator as a solution, and every solution is registered with a unique user name with the vCenter Single Sign-On Server. To be able to request a delegate holder-of-key token for Orchestrator from the vCenter Single Sign-On Server, you need the solution user name of Orchestrator.

Prerequisites

Verify that you have a valid principal holder-of-key token that the vCenter Single Sign-On Server issued.

VMware, Inc. 13

Developing a Web Services Client for VMware vRealize Orchestrator

Procedure

1 Make a GET request at the URL of the solution user name of Orchestrator:

GET https://{orchestrator_host}:{port}/vco/api/users/

2 Provide your principal holder-of-key token in the Authorization header of the request.

The <user solution-user="OrchestratorSolutionUserName"/> element of the response contains the solution user name of Orchestrator. The following is an example of a solution user name of Orchestrator.

What to do next

Use the solution user name of Orchestrator and your principal holder-of-key token to request a delegate holder-of-key token from the vCenter Single Sign-On Server.

Using LDAP Authentication with the Orchestrator REST API

You must apply the Basic HTTP Authentication scheme if Orchestrator is configured with LDAP, or if you use the Orchestrator server to access a third-party system that is configured with LDAP.

The Basic HTTP Authentication scheme allows you to authenticate against Orchestrator or a third-party system by including an Authorization header in the API calls that you make. You must provide base64encoded credentials in the Authorization header. Orchestrator uses the same credentials to authenticate on your behalf against third-party systems that are configured with LDAP.

For details about the Basic HTTP Authentication, see RFC 2617.

Example: Obtain a Session in LDAP Mode

The following example code obtains a session in LDAP mode.

URI uri = URI.create("https://orchestrator-server:8283/vco/api"); VcoSessionFactory sessionFactory = new DefaultVcoSessionFactory(uri);

//provide LDAP credentials Authentication auth = new UsernamePasswordAuthentication("username", "password");

VcoSession session = sessionFactory.newSession(auth); //use session here

Accessing the Reference Documentation for the Orchestrator REST API

The reference documentation for the Orchestrator REST API contains information about the RESTful Web services of the API, the data model that is applicable for the API, the response codes that are valid for the API, code examples, and so on.

The reference documentation of the Orchestrator REST API is installed together with Orchestrator. The reference documentation is available at https://orchestrator_host:port/vco/api/docs/.

Using the Java REST SDK

You can use a Java SDK library to call operations on the Orchestrator REST API in Java applications and work directly with objects.

Every RESTful Web service of the Orchestrator REST SDK has a wrapping Java class with methods that correspond to the operations that can be run by using the service.

14 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

The Java REST SDK is installed together with Orchestrator. The Java REST SDK artifacts are available at the following locations.

NOTE You can only access the artifacts if you have deployed the Orchestrator Appliance.

https://orchestrator_host:port/vco-repo/com/vmware/o11n/o11n-rest-client/

https://orchestrator_host:port/vco-repo/com/vmware/o11n/o11n-rest-client-examples/

https://orchestrator_host:port/vco-repo/com/vmware/o11n/o11n-rest-client-services/

https://orchestrator_host:port/vco-repo/com/vmware/o11n/o11n-rest-client-stubs/

Example: Run a Workflow and Wait for Its Completion

The following example code runs a workflow and waits for it to complete.

//start a new session to Orchestrator by using specified credentials VcoSession session = DefaultVcoSessionFactory.newLdapSession(new URI("https://orchestratorserver:8281/vco/api/"), "username", "password");

//create the services WorkflowService workflowService = new WorkflowService(session); ExecutionService executionService = new ExecutionService(session);

//find a workflow by ID Workflow workflow = workflowService.getWorkflow("1231235");

//create an ExecutionContext from the user's input ExecutionContext context = new ExecutionContextBuilder().addParam("name", "Jerry").addParam("age", 18).build();

//run the workflow WorkflowExecution execution = executionService.execute(workflow, context);

//wait for the workflow to reach the user interaction state, checking every 500 milliseconds execution = executionService.awaitState(execution, 500, 10, WorkflowExecutionState.CANCELED, WorkflowExecutionState.FAILED, WorkflowExecutionState.COMPLETED);

String nameParamValue = new ParameterExtractor().fromTheOutputOf(execution).extractString("name"); System.out.println("workflow was executed with 'name' input set to" + nameParamValue);

VMware, Inc. 15

Developing a Web Services Client for VMware vRealize Orchestrator

Operations with Workflows

The Orchestrator REST API provides Web services that you can use to perform various operations with workflows.

Find a Workflow and Retrieve Its Definition

To be able to perform any kind of operation with a workflow, you must find that workflow in the Orchestrator inventory and retrieve its definition. The definition lists the workflow input and output parameters, and contains links to the available workflow runs, the workflow presentation, and other objects.

Prerequisites

Verify that you have imported the sample workflows package in Orchestrator. The package is included in the Orchestrator sample applications ZIP file that you can download from the Orchestrator documentation page.

Procedure

1 Find the inventory item of the workflow.

If you have the full name of the workflow or a key word from the name, make a GET request at the

URL of the Workflow service by applying a filter:

GET https://{orchestrator_host}:{port}/vco/api/workflows? conditions=name={workflowFullName}

GET https://{orchestrator_host}:{port}/vco/api/workflows?conditions=name~{keyWord}

Search for the workflow through the Catalog or the Inventory service by making a GET request at

the URL that is an entry point for the workflow inventory items:

GET https://{orchestrator_host}:{port}/vco/api/catalog/System/Workflow/

GET https://{orchestrator_host}:{port}/vco/api/inventory/System/Workflows/

2 Retrieve the inventory item of the workflow by making a GET request at its URL:

GET https://{orchestrator_host}:{port}/vco/api/catalog/System/Workflow/{workflowID}/

3 Retrieve the definition of the workflow by making a GET request at the URL of the definition:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

Example: Search for the Send Hello Workflow

You can find the Send Hello workflow and retrieve its definition:

1 To find the Send Hello workflow, make a GET request at the URL of the Workflow service by applying a

filter:

GET https://localhost:8281/vco/api/workflows?conditions=name~Hello

You receive a list of the workflows that contain Hello in their names:

16 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

2 Make a GET request at the URL of the inventory item of the Send Hello workflow:

GET https://localhost: 8281/vco/api/catalog/System/Workflow/CF808080808080808080808080808080DA808080013086668236014a 0614d16e1/

You receive the inventory item of the Send Hello workflow in the response body:

3 To retrieve the workflow's definition make a GET request at its URL:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/

VMware, Inc. 17

Developing a Web Services Client for VMware vRealize Orchestrator

You receive the definition of the Send Hello workflow in the response body:

<xml version="1.0" encoding="UTF-8" standalone="yes"> <workflow xmlns="http://www.vmware.com/vco" customized-icon="false" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/"> <relations> <link rel="up" href="https://localhost: 8281/vco/api/inventory/System/Workflows/Samples/HelloWorld/" /> <link rel="add" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/pres entation/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/task s/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/ico n/" /> </relations> <input-parameters> <parameter name="name" type="string" /> </input-parameters> <output-parameters> <parameter name="message" type="string" /> </output-parameters> <name>Send Hello</name> <description></description> </workflow>

Run a Workflow

You run a workflow through the Orchestrator REST API by creating a new execution object for a particular workflow.

Prerequisites

18 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

Procedure

1 Retrieve the definition of the workflow that you want to run by making a GET request at the URL of the

definition:

GET http://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

You receive the definition of the workflow in the response body of the request. In the workflow definition, you can view the input parameters of the workflow, the workflow description, and other information.

2 Make a POST request at the URL that holds the execution objects of the workflow:

POST https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/executions/

3 Provide values for the input parameters of the workflow in an execution-context element in the

request body.

If you provide an empty execution-context in the request body, the workflow runs with default values for its input parameters, if any.

If the POST request is successful, you receive the status code 202 with an empty response body and a link to the newly created execution object in the Location header.

Example: Run the Send Hello Workflow

You can retrieve the definition of the Send Hello workflow and run it.

1 Make a GET request at the URL that holds the definition of the Send Hello workflow:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/

You receive the workflow definition in the response body of the request:

VMware, Inc. 19

Developing a Web Services Client for VMware vRealize Orchestrator

href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/ico n/" /> </relations> <input-parameters> <parameter name="name" type="string" /> </input-parameters> <output-parameters> <parameter name="message" type="string" /> </output-parameters> <name>Send Hello</name> <description></description> </workflow>

2 Make a POST request at the URL that holds the execution objects for the workflow:

POST https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/

Pass values for the input parameters in an execution-context element in the request body:

<execution-context xmlns="http://www.vmware.com/vco"> <parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </parameters> </execution-context>

Run a Workflow After Validating Its Input Parameters Against the Workflow Presentation

The presentation of a workflow can define constraints for the values that you can pass to the input parameters of the workflow, such as a predefined list of values or a certain range of values. To ensure that the workflow runs successfully, you must validate the values that you pass to the input parameters of the workflow against the definition of the workflow presentation.

When you integrate workflows in custom applications, you might need to create a wizard where you enter values for the input parameters of the workflow when you run it. By using the Workflow Presentation service, you can instantiate the presentation of a workflow and pass values for its input parameters in parts that correspond to the different screens of the wizard. You can validate the values that you pass to the input parameters against the constraints that are defined in the workflow presentation.

Prerequisites

Procedure

1 Retrieve the definition of the workflow that you want to run by making a GET request at the URL that

contains the workflow definition:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

20 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

2 Retrieve the definition of the workflow presentation by making a GET request at its URL:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/presentation/

3 In the response body of the request, examine the definition of the workflow presentation for any

constraints of the values that you can pass to the input parameters.

For example, an input parameter can have a predefined list of values to choose from.

4 Instantiate the workflow presentation by making a POST request at the URL of the presentation

instances:

POST https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/presentation/instances/

5 Provide an execution-context element in the request body to instantiate the presentation.

You can pass an empty execution-context or pass an execution-context with values only for some of the input parameters.

6 To pass values to the input parameters in parts, make as many POST or PUT requests as needed at the

URL that holds the presentation instance:

PUT https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/presentation/instances/{executionID}/

7 Review the response body of the POST or PUT request that you made.

If the values that you passed to the input parameters are valid, you find a valid="true" attribute in the

execution tag. If the presentation is valid, you can take the values that are listed in the out-parameters

element of the response, and pass them as values to the input parameters when you run the workflow.

8 If the values for the input parameters are valid, run the workflow by making a POST request at the URL

that holds the workflow executions:

POST https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/executions/

9 Provide the valid values to the input parameters of the workflow in an execution-context element.

Example: Run the Send Hello Workflow by Validating Its Input Parameters

You can run the Send Hello workflow by validating its input parameters against the definitions of its presentation.

1 Make a GET request at the URL that holds the definition of the Send Hello workflow:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/

You receive the workflow definition in the response body of the request:

VMware, Inc. 21

Developing a Web Services Client for VMware vRealize Orchestrator

href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/pres entation/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/task s/" /> <link rel="down" href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/ico n/" /> </relations> <input-parameters> <parameter name="name" type="string" /> </input-parameters> <output-parameters> <parameter name="message" type="string" /> </output-parameters> <name>Send Hello</name> <description></description> </workflow>

2 Make a GET request at the URL that holds the definition of the workflow presentation:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/pres entation/

3 Make a POST request at the URL that holds the execution instances of the workflow presentation:

POST https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/pres entation/instances/

Provide an empty execution-context so that just to instantiate the presentation without providing any values for the input parameters:

<execution-context xmlns="http://www.vmware.com/vco"/>

The response body contains error messages attached to every field, indicating that the values for the input parameters are invalid.

.......

<fields> <field type="string" hidden="false" id="name"> <display-name>name</display-name> <description>name</description> <messages> <message severity="ERROR" code="VCO-CNS0002"> <Summary> The minimum number of characters allowed for this field is 3.0 </Summary> </message> </messages>

22 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

.......

4 Make a POST request at the URL that holds the particular presentation instance:

POST https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/pres entation/instances/888080808080808080808080808080803F8080800132145338690643f66a027ec/

In the request body, provide values for the input parameters:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <execution-context xmlns="http://www.vmware.com/vco"> <parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </parameters> </execution-context>

In the response body of the request, you can check whether the values of the input parameters are valid:

5 If the presentation is valid, run the workflow by making a POST request at the URL that holds the

workflow executions:

POST https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/

In the request body, pass values to the input parameters of the workflow. Use the same values that are returned as output parameters of the workflow presentation, or directly use the request body of the last

POST request that you made to the workflow presentation.

Interacting with a Workflow While It Runs

The Orchestrator REST API allows you to perform various operations with a workflow during its run. You can get the status of a running workflow, answer to a waiting user interaction, and cancel a workflow run.

Get Workflow Run Objects and Check the Workflow Status

You can get information about the runs of a workflow, such as the start and end dates, the state of the run, and the values for the input parameters. You can also get logs that are generated for a workflow run.

Prerequisites

Procedure

1 Retrieve the definition of the workflow whose status you want to check by making a GET request at the

URL of the workflow:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

You receive the definition of the workflow in the response body of the request. The workflow definition contains a link to the execution instances of the workflow.

VMware, Inc. 23

Developing a Web Services Client for VMware vRealize Orchestrator

2 Retrieve the available execution instances of the workflow by making a GET request at their URL:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/executions/

The response body of the request lists the available execution instances of the workflow where you can view the start and end dates of every workflow run as well their status and initiator.

3 (Optional) To get more details about a particular run of the workflow, make a GET request at the URL of

that run:

GET https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/

In the response body of the request, you receive the XML representation of the particular workflow run. You can check the values of the input parameters that are passed for this run, the user who initiated the run, the start and end dates, as well as the state of the run.

4 (Optional) To retrieve the logs that are generated for the workflow run, make a GET request at the URL

that holds the logs:

GET https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/logs/

5 (Optional) To retrieve additional information about the state of the run, make a GET request at the URL

that holds the state of the workflow:

GET https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/state/

Example: Get the Runs of the Send Hello Workflow and Check the State of a Particular Run

If you have run the Send Hello workflow, you can get the available execution objects and check details about them.

1 Get the definition of the Send Hello workflow by making a GET request at the URL that holds the

definition:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/

2 Get the available runs of the workflow by making a GET request at the URL that holds the execution

objects for the workflow:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/

3 From the response body of the request, select a workflow run and make a GET request to retrieve it:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/888080808080808080808080808080803A8080800132145338690643f66a027ec/

The response body contains the XML representation of the workflow run with the specified ID, where you can check details about that run:

.......

<input-parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </input-parameters> <output-parameters> <parameter name="message" type="string">

24 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

<string>Hello, John Smith!</string> </parameter> </output-parameters> <start-date>2012-01-31T14:28:40.223+03:00</start-date> <end-date>2012-01-31T14:28:40.410+03:00</end-date> <started-by>vcoadmin</started-by> <name>Send Hello</name>

......

Answer to a Waiting User Interaction

You can answer to a waiting user interaction of a workflow run by using the Orchestrator REST API.

Prerequisites

Procedure

1 Retrieve the list of all user interaction objects by making a GET request at the URL that holds the

available user interaction objects, or by filtering only the waiting user interactions:

URL Description

https://orchestrator_host:port/vco/a pi/catalog/System/UserInteraction

https://orchestrator_host:port/vco/a pi/catalog/System/UserInteraction? status=0

Holds the available user interaction objects in Orchestrator

Filters only the waiting user interaction objects.

You receive a list of the available user interaction objects. User interactions that are waiting have an attribute with name state and value waiting.

2 Make a GET request at the URL that holds the inventory item of the waiting user interaction to which

you want to answer:

GET https://{orchestrator_host}: {port}/vco/api/catalog/System/UserInteraction/{userInteractionID}/

The inventory item contains a link to the user interaction instance.The user interaction instance is associated with a particular workflow run.

3 Make a POST request at the URL of the user interaction instance for the particular workflow execution:

POST https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/interaction/

4 Provide values for the input parameters of the user interaction in an execution-context element in the

request body.

The REST API returns a 204 status when you answer to a user interaction successfully.

Example: Answer to the User Interaction of the Interactive Hello World Workflow

You can run the Interactive Hello World sample workflow and answer to its user interaction.

1 Search for the waiting user interaction of the workflow by making GET request at the endpoint for the

user interaction objects of the Catalog service:

GET https://localhost:8281/vco/api/catalog/System/UserInteraction?status=0

VMware, Inc. 25

Developing a Web Services Client for VMware vRealize Orchestrator

2 Locate the user interaction inventory object for the Interactive Hello World workflow and make a GET

request at its URL:

GET https://localhost: 8281/vco/api/catalog/System/UserInteraction/888080808080808080808080808080805A808080013214533 8690643f66a027ec/

3 Make a POST request at the URL of the user interation objects for the currently running workflow

execution:

POST https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080E6808080013086668236014a0614d16e1/exec utions/88808080808080808080808080808080578080800132145338690643f66a027ec/interaction/

Provide a value for the input parameter in the request body:

<execution-context xmlns="http://www.vmware.com/vco"> <parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </parameters> </execution-context>

Answer to a User Interaction After Validating Input Parameters

The presentation of a user interaction might define constraints for the values that you can pass to the input parameters of the workflow. When you answer to a user interaction, you can validate the values that you pass to the input parameters against the constraints that are defined in the presentation of the user interaction.

Prerequisites

Procedure

1 Retrieve the list of all user interaction objects by making a GET request at the URL that holds the

available user interaction objects, or by filtering only the waiting user interactions:

URL Description

https://orchestrator_host:port/vco/a pi/catalog/System/UserInteraction

https://orchestrator_host:port/vco/a pi/catalog/System/UserInteraction? status=0

You receive a list of the available user interaction objects. User interactions that are waiting have an attribute with name state and value waiting.

Holds the available user interaction objects in Orchestrator.

Filters only the waiting user interaction objects.

2 Make a GET request at the URL that holds the inventory item of the waiting user interaction that you

want to answer:

GET https://{orchestrator_host}: {port}/vco/api/catalog/System/UserInteraction/{userInteractionID}/

The response body contains a link to the user interaction instance. The user interaction instance is associated with a particular workflow run.

26 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

3 Make a GET request at the URL of the user interaction instance:

GET https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/interaction/

In the response body, you find a down link to the presentation of the user interaction.

4 Make a GET request at the URL of the presentation of the user interaction:

GET https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/interaction/presentation/

You receive the definition of the user interaction presentation in the response body.

5 In the presentation definition, check for constraints of the values that you can pass to the input

parameters.

6 Run the user interation presentation by making a POST request at the URL where the instances of the

presentation reside:

POST https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/interaction/presentation/insta nces/

7 In the request body, provide values for the input parameters in an execution-context element.

In the response body, you receive the instance of the user interaction presentation. If the values that you passed to the input parameters are valid, you find a valid="true" attribute in the execution element. In the output-parameters element, you find the valid values for the input parameters that you can use to answer to the user interaction.

8 Answer to the user interaction by making a POST request at the URL where the user interaction instance

resides:

POST https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/interaction/

9 In the request body, pass an execution-context context with the values for the input parameters.

You can use the same request body as the one for the POST request that you made at the URL for the user interaction presentation.

If the last request is successful, you receive a status code 204 and an empty response body.

Example: Answer to the User Interaction of the Interactive Hello World Workflow by Validating Input Parameters

You can answer to the user interaction of the Interactive Hello World workflow by validating the values of the input parameters against the constraints that are defined in the presentation of the user interaction.

1 Search for the waiting user interactions of the workflow by making a GET request at the endpoint for the

user interaction objects of the Catalog service:

GET https://localhost:8281/vco/api/catalog/System/UserInteraction?status=0

2 Locate the user interaction inventory object for the Interactive Hello World workflow and make a GET

request at its URL:

GET https://localhost: 8281/vco/api/catalog/System/UserInteraction/888080808080808080808080808080805A808080013214533 8690643f66a027ec/

VMware, Inc. 27

Developing a Web Services Client for VMware vRealize Orchestrator

3 Make a GET request at the URL of the user interaction instance:

GET https://localhost: 8281/vco/api/catalog/System/UserInteraction/888080808080808080808080808080805A808080013214533 8690643f66a027ec/interaction/

4 Make a GET request at the URL of the user interaction presentation:

GET https://localhost: 8281/vco/api/catalog/System/UserInteraction/888080808080808080808080808080805A808080013214533 8690643f66a027ec/interaction/presentation/

The presentation defines the input parameter as mandatory, and contains a constraint for the length of the string that you can pass.

5 Make a POST request at the URL that holds the instances of the user interaction presentation:

POST https://localhost: 8281/vco/api/catalog/System/UserInteraction/888080808080808080808080808080805A808080013214533 8690643f66a027ec/interaction/presentation/instances/

Provide a value for the input parameter in the request body:

<execution-context xmlns="http://www.vmware.com/vco"> <parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </parameters> </execution-context>

The execution element of the response body contains a valid="true" attribute, indicating that the input parameter value is valid against the constraints in the user interaction presentation. The valid value is listed in the output-parameters element:

............

<output-parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </output-parameters>

............

6 Make a POST request at the URL of the user interaction instance by passing the same request body as in

the POST request in step 5.

POST https://localhost: 8281/vco/api/catalog/System/UserInteraction/888080808080808080808080808080805A808080013214533 8690643f66a027ec/interaction/

Cancel a Workflow Run

You can cancel the run of a workflow by using the Orchestrator REST API.

Procedure

1 Retrieve the definition of the workflow by making a GET request at the URL of the workflow's

definition:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

The workflow definition contains a link to the available execution objects of the workflow.

28 VMware, Inc.

Chapter 2 Using the vRealize Orchestrator REST API

2 Get the available workflow runs by making a GET request to the URL that holds the available execution

objects for the workflow:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/executions/

3 From the list of the available workflow executions, select the one that you want to cancel and make a

DELETE request at its URL:

DELETE https://{orchestrator_host}: {port}/vco/api/workflows/{workflowID}/executions/{executionID}/

Retrieve a Workflow's Interactions

You can retrieve the list of all user interactions for a workflow by using the Orchestrator REST API.

Procedure

1 Retrieve the definition of the workflow by making a GET request at the URL of the workflow's

definition:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

2 Get the list of workflow interactions by making a GET request to the URL of the workflow's interactions:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/interactions/

If the GET request is successful, you receive the status code 200 and a list of all user interactions available for the workflow.

Access a Workflow's Schema

You can access the schema image of a workflow by using the Orchestrator REST API.

Procedure

1 Retrieve the definition of the workflow by making a GET request at the URL of the workflow's

definition:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

2 Get the workflow's schema image by making a GET request to the URL of the workflow's schema:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/schema/

If the GET request is successful, you receive the status code 200 and the binary data of the image, representing the workflow schema. The response content type is set to a correct media type, for example

Content-Type:image/png.

Working with Tasks

Using the Task service of the Orchestrator REST API, you can perform any operation that is related to managing tasks in Orchestrator. You can create a task for scheduling a workflow, modify the properties of an already existing task, delete a task, and so on.

The maximum number of scheduled tasks supported by Orchestrator is 50.

VMware, Inc. 29

Developing a Web Services Client for VMware vRealize Orchestrator

Create a Task

You can create a task for scheduling a workflow by using the Orchestrator REST API.

Prerequisites

Procedure

1 Retrieve the definition of the workflow for which you want to create a task by making a GET request at

the URL of the workflow:

GET https://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/

In the workflow definition you can view the name and the ID of the workflow, as well as its input parameters.

2 To create a new task for the workflow, make a POST request at the URL of the Task service:

POST https://{orchestrator_host}:{port}/vco/api/tasks/

3 In the request body, provide the parameters for the new task in a task element.

If the request is successful, the API responds with status code 202 and an empty response body.

Example: Create a Task for the Send Hello Workflow

You can create a task that schedules the Send Hello workflow to run on the fifteenth minute of every hour starting from a specific date.

1 Make a GET request at the URL of the Send Hello workflow to retrieve its definition:

GET https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/

2 Make a POST request at the URL of the Task service by providing the parameters of the new task in the

request body:

POST https://localhost:8281/vco/api/tasks/

<task xmlns="http://www.vmware.com/vco"> <name>Send Hello Task</name> <recurrence-cycle>every-hours</recurrence-cycle> <recurrence-start-date>2012-01-31T11:00:00+00:00</recurrence-start-date> <recurrence-end-date>2012-02-05T11:00:00+00:00</recurrence-end-date> <recurrence-pattern>15:15</recurrence-pattern> <input-parameters> <parameter name="name" type="string"> <string>John Smith</string> </parameter> </input-parameters> <workflow href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/"> <name>Send Hello</name> </workflow> <start-mode>normal</start-mode> </task>

30 VMware, Inc.

+ 70 hidden pages