Developing a Web Services Client for VMware vRealize Orchestrator vRealize Orchestrator 7.1 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
Developing 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 Copyright © 2008–2016 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.
Contents Developing a Web Services Client for VMware vRealize Orchestrator 5 1 Updated Information 7 2 Developing a Web Services Client 9 3 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
Developing a Web Services Client for VMware vRealize Orchestrator Delete a Package 39 Delete a Resource 39 Delete a Configuration Element 40 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 Permissi
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 a Web services API so that you can develop applications to access and use workflows through the Web. Orchestrator provides a representational state transfer (REST) API that you can use to perform various operations over workflows.
Developing a Web Services Client for VMware vRealize Orchestrator 6 VMware, Inc.
Updated Information 1 Developing a Web Services Client for VMware vRealize Orchestrator is updated with each release of the product or when necessary. This table provides the update history of the Developing a Web Services Client for VMware vRealize Orchestrator. Revision Description EN-001863-01 Deleted the Writing a Client Application for the Orchestrator SOAP Service, Web Service API Object Reference, and Web Service API Operation Reference sections, because of SOAP API deprecation.
Developing a Web Services Client for VMware vRealize Orchestrator 8 VMware, Inc.
Developing a Web Services Client 2 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 a Web services API that is based on a representational state transfer (REST) API.
Developing a Web Services Client for VMware vRealize Orchestrator 10 VMware, Inc.
Using the vRealize Orchestrator REST API 3 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.
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.
Chapter 3 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. n Authorization. You must pass your principal holder-of-key token in this header. n VCOAuthorization.
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 element of the response contains the solution user name of Orchestrator. The following is an example of a solution user name of Orchestrator.
Chapter 3 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.
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.
Chapter 3 Using the vRealize Orchestrator REST API PAGE 18
Developing a Web Services Client for VMware vRealize Orchestrator You receive the definition of the Send Hello workflow in the response body: PAGE 19Chapter 3 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.
Developing a Web Services Client for VMware vRealize Orchestrator href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/ico n/" /> Send Hello 2 Make a POST request at the URL that holds the execution objects for the work
Chapter 3 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.
Developing a Web Services Client for VMware vRealize Orchestrator href="https://localhost: 8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/exec utions/" />
Chapter 3 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:
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.
Chapter 3 Using the vRealize Orchestrator REST API Hello, John Smith! 2012-01-31T14:28:40.223+03:00 2012-01-31T14:28:40.410+03:00 vcoadmin Send Hello ...... Answer to a Waiting User Interaction You can answer to a waiting user interaction of a workflow run by using the Orchestrator REST API.
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/CF8080808080808080808080808
Chapter 3 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.
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/
Chapter 3 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 Wo
Developing a Web Services Client for VMware vRealize Orchestrator 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.
Chapter 3 Using the vRealize Orchestrator REST API 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 Make a GET request at the URL of the task that you want to modify: GET https://{orchestrator_host}:{port}/vco/api/tasks/{task ID}/ 2 Check the properties of the task in the response body of the request.
Developing a Web Services Client for VMware vRealize Orchestrator Finding Objects in the Orchestrator Inventory You can find any object in the Orchestrator inventory by using the Catalog or the Inventory services. You can access only a certain subset of objects by applying filter parameters at the end of the URLs where you make HTTP requets. You can use the Catalog service to find objects in the Orchestrator inventory that are of a certain type, or retrieve a specific object by its type and ID.
Chapter 3 Using the vRealize Orchestrator REST API 2 Make a GET request at the URL where all system objects in Orchestrator are located: GET https://localhost:8281/vco/api/catalog/System/ 3 Make a GET request at the URL where all workflows reside: GET https://localhost:8281/vco/api/catalog/Workflow/ 4 Make a GET request at the URL of the Send Hello workflow: GET https://localhost: 8281/vco/api/catalog/Workflow/CF808080808080808080808080808080DA808080013086668236014a0614d16 e1/ Find Objects by Relatio
Developing a Web Services Client for VMware vRealize Orchestrator Apply Filters The services of the Orchestrator REST API support additional URL parameters that allow you to narrow the objects that HTTP requests to the API return. Different query parameters are supported for every URL to a resource that you can access through the REST API. To learn which query parameters are applicable to a URL, see the vRealize Orchestrator REST API reference documentation.
Chapter 3 Using the vRealize Orchestrator REST API Export a Workflow You can export a workflow by using the Orchestrator REST API and download the workflow as a file. Procedure 1 2 In a REST client application, add a request header with the following values.
Developing a Web Services Client for VMware vRealize Orchestrator Import a Package You can import a package by using the Orchestrator REST API. Depending on the library of your REST client application, you can use custom code that defines the properties of the package. By default, if you import an Orchestrator package with a duplicate name, the existing package is not overwritten. You can specify whether to overwrite existing packages by using a parameter in the request.
Chapter 3 Using the vRealize Orchestrator REST API Procedure 1 2 In a REST client application, add a request header with the following values.
Developing a Web Services Client for VMware vRealize Orchestrator 2 Make a GET request at the URL of the resource that you want to export: GET http://{orchestrator_host}:{port}/vco/api/resources/{resourceID}/ If the GET request is successful, you receive the status code 200. The content of the resource is available in the response body. Import a Configuration Element You can import a configuration element by using the Orchestrator REST API.
Chapter 3 Using the vRealize Orchestrator REST API 2 Make a DELETE request at the URL of the workflow: DELETE http://{orchestrator_host}:{port}/vco/api/workflows/{workflowID}/ If the DELETE request is successful, you receive the status code 200, and the response body is empty. Delete an Action You can delete an action by using the Orchestrator REST API.
Developing a Web Services Client for VMware vRealize Orchestrator 2 Make a DELETE request at the URL of the resource: DELETE http://{orchestrator_host}:{port}/vco/api/resources/{resourceID}/ If the DELETE request is successful, you receive the status code 200, and the response body is empty. Delete a Configuration Element You can delete a configuration element by using the Orchestrator REST API.
Chapter 3 Using the vRealize Orchestrator REST API Example: Syntax for Setting Permissions You can use the following example syntax in the request body of a POST request at the URL of an Orchestrator element's permissions. PAGE 42Developing a Web Services Client for VMware vRealize Orchestrator Procedure 1 Make a GET request and retrieve the ID of the workflow from the list of returned workflows: GET http://{orchestrator_host}:{port}/vco/api/workflows/ 2 In a REST client application, add request headers to define the properties of the workflow for which you want to set permissions. 3 In the request body, specify the permissions that you want to set.
Chapter 3 Using the vRealize Orchestrator REST API Procedure 1 Make a GET request and retrieve the ID of the action from the list of returned actions: GET http://{orchestrator_host}:{port}/vco/api/actions/ 2 In a REST client application, add request headers to define the properties of the action for which you want to set permissions. 3 In the request body, specify the permissions that you want to set.
Developing a Web Services Client for VMware vRealize Orchestrator Procedure 1 Make a GET request and retrieve the name of the package from the list of returned packages: GET http://{orchestrator_host}:{port}/vco/api/packages/ 2 In a REST client application, add request headers to define the properties of the package for which you want to set permissions. 3 In the request body, specify the permissions that you want to set.
Chapter 3 Using the vRealize Orchestrator REST API Procedure 1 Make a GET request and retrieve the ID of the resource from the list of returned resources: GET http://{orchestrator_host}:{port}/vco/api/resources/ 2 In a REST client application, add request headers to define the properties of the resource for which you want to set permissions. 3 In the request body, specify the permissions that you want to set.
Developing a Web Services Client for VMware vRealize Orchestrator Set the Permissions for a Configuration Element You can set the permissions for a configuration element by using the Orchestrator REST API. Prerequisites Review the types of permissions that you can set and the syntax that you can use in the request body. See “REST API Permissions,” on page 40.
Chapter 3 Using the vRealize Orchestrator REST API Procedure 1 In a REST client application, add request headers to define the properties of the plug-in that you want to import. 2 Make a POST request at the URL of the plug-in objects: POST http://{orchestrator_host}:{port}/vco/api/plugins/ If the POST request is successful, you receive the status code 200. Export a Plug-In You can export a plug-in by using the Orchestrator REST API.
Developing a Web Services Client for VMware vRealize Orchestrator Performing Server Configuration Operations The Orchestrator REST API provides Web services that you can use to perform various operations related to the Orchestrator server configuration. Retrieve Information About the Orchestrator Server Configuration You can retrieve information about the Orchestrator server configuration by using the Orchestrator REST API.
Chapter 3 Using the vRealize Orchestrator REST API 3 Make a POST request at the URL of the server configuration: POST http://{orchestrator_host}:{port}/vco/api/server-configuration/ If the POST request is successful, you receive the status code 200. Performing Tagging Operations The Orchestrator REST API provides Web services that you can use to perform various operations to make objects more searchable by using tags in Orchestrator. You can make objects more searchable by attaching tags to them.
Developing a Web Services Client for VMware vRealize Orchestrator Procedure u Make a DELETE request to remove private or global tags.
Chapter 3 Using the vRealize Orchestrator REST API List Tags by Users You can use the Orchestrator REST API to retrieve a list of tags created by a specific user. You can also retrieve global tags. Global tags are listed under the system user name __GLOBAL__. Procedure u Make a GET request at the URL of the user.
Developing a Web Services Client for VMware vRealize Orchestrator If the DELETE request is successful, you receive the status code 204. 52 VMware, Inc.
Index A I action delete permissions 42 deleting 39 download 35 export 35 get permissions 42 import 35 retrieve permissions 42 upload 35 API documentation 14 audience 5 authentication LDAP 14 Orchestrator solution user name 13 solution user name 13 vCenter Single Sign-On 12 import 34 inventory, search 32 C configuration element delete permissions 45 deleting 40 download 38 export 38 get permissions 45, 46 import 38 retrieve permissions 45, 46 upload 38 D deleting objects 38 E export 34 F filters 34 f
Developing a Web Services Client for VMware vRealize Orchestrator retrieve permissions 44 upload 37 REST API, permissions 40 S schedule workflow 29 SDK, Java REST 14 server configuration export 48 import 48 operations 48 retrive information 48 interact while running 23 retrieve permissions 41 retrieving interactionsl 29 run 18, 20, 28 runs 23 upload 34 user interaction 25, 26 validate 20 validate and run 20 T taggaing, operations 49 tagging list tags 50 list filtered tags by users 51 list tag owners 50
