VMware vRealize Automation - 6.2 Programming Guide

Programming Guide

vRealize Automation 6.2

Programming Guide

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

https://docs.vmware.com/

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

VMware, Inc. 2

vRealize Automation Programming Guide

The Programming Guide provides information about the vRealize Automation REST APIs, including how to use the REST API services and resources, create HTTP bearer tokens for authentication and authorization, and construct REST API service calls.

Intended Audience

This information is intended for administrators and programmers who want to configure and manage vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on common use cases. For related information about all available REST API services, see in REST API Reference at https://www.vmware.com/support/pubs/vcac-pubs.html.

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

https://www.vmware.com/support/pubs/vcac-pubs.html.

VMware, Inc.

5

Updated Information

This Programming Guide is updated with each release of the product or when necessary.

This table provides the update history of the Programming Guide.

Revision Description

EN-001636-04 Updated the input URL in Syntax for Displaying All Available Resource Types.

EN-001636-03

EN-001636-02

n

Removed the section titled Logging in Programmatically.

n

Minor reorganization of Using the API Explorer.

n

Updated the format of the Use Cases section topics.

n

Updated the order of topics in the Authentication, Filtering, and Related Tools sections.

EN-001636-01 Updated the documentation to include the following changes:

n

Added new topic section Working with Key Pairs.

n

Added new topic section Working with Network Profiles.

n

Added new topic Syntax for Creating a vCloud Reservation.

n

Added new topic Syntax for Creating an Amazon Reservation.

n

Added new topic Get Resources Schema for an Amazon EC2 Reservation Syntax.

n

Added new topic Get Resources Schema for a vCloud Reservation Syntax.

n

Added new topic Syntax for Displaying a Schema Definition for an Amazon Reservation.

n

Added new topic Syntax for Displaying a Schema Definition for a vCloud Reservation.

n

Added new topic Creating an API Explorer Command Using Supplied curl Examples.

n

Added Amazon EC2 and vCloud information to Syntax for Getting a Compute Resource for a Reservation.

n

Updated Syntax for Constructing a JSON File For a Machine Request and Syntax for Requesting a Machine.

n

Updated Syntax for Constructing a JSON File for a vCloud Air Machine Request and Syntax for Requesting a

vCloud Air Machine.

n

Updated Syntax for Constructing a JSON File for an Amazon Machine Request and Syntax for Requesting an

Amazon Machine.

n

Revised topic flow and content formatting throughout the guide.

EN-001636-00 Initial 6.2 release.

VMware, Inc. 6

Overview of the

vRealize Automation REST API 1

The vRealize Automation REST API provides consumer, administrator, and provider-level access to the service catalog with the same services that support the vRealize Automation console user interface. You can perform vRealize Automation functions programmatically by using REST API service calls.

The vRealize Automation REST API offers the following services and functions.

Table 1‑1. vRealize Automation REST API Services

Service Description

Advanced Designer Service Manage Advanced Service Designer elements such as forms, endpoints

vRealize Orchestrator workflows, and work items through the Advanced Designer Service.

Approval Service Retrieve, create, update, and delete approval policies, policy types, policy

instances, and policy requests.

Branding Service Change the background and text colors, company logo, company name,

product name, tenant name, and other resources in the console.

Catalog Service Retrieve global and entitled catalog items, and entitlements for a catalog

item and its service that the current user can review. A consumer can retrieve, edit, and submit a request form for a catalog item. A provider can retrieve, register, update, and delete catalog items. Provision and manage systems.

Component Registry Access and manage all services and serves as the central view for all

service lookups.

Event Log Service Provide a central location and a consistent way of recording events and

querying for events.

File Service Unused.

Identity Service Manage tenants, business groups, SSO and custom groups, users, and

identity stores.

Licensing Service Retrieve permissions and post serial keys.

Management Service Retrieve work item forms, callbacks, and tasks. Manage endpoint details

including tenant, password, user name, and endpoint URL. Retrieve performance metrics. Retrieve and cancel reclamation requests.

Notification Service Configure and send notifications for several types of events such as the

successful completion of a catalog request or a required approval.

Plug-in Service Retrieve, create, update, and delete a resource. Retrieve an extension.

Retrieve license notifications.

VMware, Inc. 7

Programming Guide

Table 1‑1. vRealize Automation REST API Services (Continued)

Service Description

Portal Service Retrieve, create, update, and delete a portal resource.

Reservation Service Retrieve, create, update, and delete a reservation or reservation policy.

vCO Service Manage vRealize Orchestrator actions, tasks, packages, and workflows.

Browse system and plug-in inventories.

WorkItem Service Retrieve, create, update, complete, cancel, and delete a work item. Also

retrieve form data, metadata, detail forms, and submission forms from service providers.

When a service request contains a resource URL, the first part of the URL identifies the service and the last part identifies the resource. For example, the following resource URL identifies the catalog service and the providers resource:

https://$host/component-registry/api/services

For more information about all the vRealize Automation REST API service calls, see Using the vRealize

Automation REST API Reference and the REST API Reference in the vRealize Automation

Documentation Center at https://www.vmware.com/support/pubs/vcac-pubs.html.

VMware, Inc. 8

REST API Authentication 2

In the REST API, vRealize Automation requires HTTP bearer tokens in request headers for authentication of consumer requests. A consumer request applies to tasks that you can perform in the vRealize Automation console, such as requesting a machine.

To acquire an HTTP bearer token, you authenticate with an identity service that manages the communication with the SSO server. The identity service returns an HTTP bearer token that you include in all request headers until the token expires, or you delete it. An HTTP bearer token expires in 24 hours by default, but you can configure the token with a different duration.

Using HTTP Bearer Tokens

You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You create a request header with the curl command or with some other utility.

For information about requesting a bearer token, see the Identity option on the REST API Reference landing page.

You use POST, HEAD, and DELETE methods to manage HTTP bearer tokens.

Method URL Description

POST /tokens Authenticate the user with the identity service /tokens and

generate a new token.

HEAD /tokens/tokenID Validate the token tokenID.

DELETE /tokens/tokenID Delete the token tokenID.

The root URL for HTTP bearer calls is https://$vra_server/identity/api/tokens.

Conﬁgure the Duration of an HTTP Bearer Token

You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties file on the vRealize Automation appliance.

VMware, Inc.

9

Programming Guide

The effective duration or lifetime of an HTTP bearer token depends on the duration of its corresponding SAML token, which the SSO server creates at request time. An HTTP bearer token expires when it reaches the end of its configured duration, or at the end of the configured duration of the SAML token, whichever comes first. For example, if the configured duration is three days for the HTTP bearer token and two days for the SAML token, the HTTP bearer token expires in two days. A configuration setting on the SSO server determines the duration of SAML tokens.

Prerequisites

n

Log in to the vRealize Automation appliance with SSH as root. The password is the one you specified when you deployed the appliance.

n

The /etc/vcac/security.properties file on the appliance must be editable.

Procedure

1 Open the /etc/vcac/security.properties file for editing.

2 Add the following lines to the file, where N is an integer specifying the duration of the token in hours.

identity.basic.token.lifetime.hours=N

#The number is in hours.

3 Save and close the file.

4 Log out of the vRealize Automation appliance.

The new value applies the next time someone requests an HTTP bearer token.

Request an HTTP Bearer Token

You use an HTTP bearer token to authenticate a vRealize Automation REST API consumer request .

A consumer request must specify the correct component registry service and resource. For example, the URL to obtain an HTTP bearer token must specify the identity service and token resource.

The HTTP bearer token expires in 24 hours by default. See Configure the Duration of an HTTP Bearer

Token for information on how to set the duration.

For related information, see Syntax for Requesting an HTTP Bearer Token.

Prerequisites

n

Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a role, log in as a tenant administrator.

n

Verify that the host name and fully qualified domain name of the vRealize Automation instance are available.

VMware, Inc. 10

Programming Guide

Procedure

u

Enter a curl command in the following format, replacing the variables with the correct values.

The variable $vRA used in this example represents the host name.domain name of the vRealize Automation server, for example, mycompany.mktg.mydomain.com.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'

--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}'

https://$vRA/identities/api/tokens

For example, enter the following command line:

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data

'{"username":"TenantAdminUser @example.com","password":"password","tenant":"MYCOMPANY"}'

https://vra.mycompany.com/identities/api/tokens

The command returns a response header with a status code and, if your request is successful, an HTTP bearer token.

For example, the following sample output displays based on the command input:

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Cache-Control: no-cache, no-store

Pragma: no-cache

Expires: Thur, 16 Jul 2015 23:59:59 GMT

Content-Type: application/json;charset=UTF-8

Content-Length: 324

Date: Wed, 15 Jul 2015 13:04:50 GMT

{

"expires":"2015-16-01T13:09:45.619Z",

"id":"MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLmNvb

TplMDViNGU0NGM2ZWU0MWQ1OWEwMTNmZGExNTQwZjNlNGM3YTBlM2I5MDhlYWZjYjY1ZjhiODI2OTg4ODU3M2UwOTUwOWRk

MjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==",

"tenant":"MYCOMPANY"

}

What to do next

Include the HTTP bearer token in your REST API service calls. You can store the token in a variable such as $AUTH and then use the variable in your requests.

Syntax for Requesting an HTTP Bearer Token

An HTTP bearer token is required by the REST client to use the vRealize Automation REST API. You can obtain a bearer token by authenticating to the identity service.

Input

Use the supported input parameters to control the command output.

VMware, Inc. 11

Programming Guide

A consumer request must specify the correct component registry service and resource. For example, the URL to obtain an HTTP bearer token must contain the identity service and token resource values.

Input Description

host host name.domain name of the vRealize Automation server, for example,

mycompany.mktg.mydomain.com.

usrname Specifies the tenant administrator user name.

passwd Specifies the tenant administrator password.

tenantURLtoken Specifies the tenant URL token determined by the system administrator when creating the

tenant, for example, support.

Output

The following information is displayed as a result of your HTTP bearer token request.

Output Description

expires Contains the ISO 8601 timestamp indicating when the token expires.

id Contains the HTTP bearer token to use in Authorization header in subsequent requests.

tenant Displays the tenant ID associated with the token.

Response Status Codes

One of the following codes are displayed as a result of your HTTP bearer token request.

Status Code Description

200 OK Your request succeeded and the resource was updated. The

response body contains the full representation of the resource.

400 BAD REQUEST The data you provided in the POST failed validation. Inspect the

response body for details.

401 UNAUTHORIZED The request could not authenticate the user or authentication

credentials required.

Example: curl Command

You can enter the following command line format to request an HTTP bearer token.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data

'{"username":"usrname",

"password":"passwd","tenant":"tenantURLtoken"}' https://$host/identity/api/tokens

When your request succeeds, the system returns the 200 OK status code, the expiration date and time of the token, and the HTTP bearer token. After receiving the bearer token, you can include it in your request headers.

VMware, Inc. 12

Programming Guide

Validate an HTTP Bearer Token

You can validate an existing HTTP bearer token.

Prerequisites

n

Request an HTTP Bearer Token.

Procedure

u

Create the request to validate the HTTP bearer token, as in the following example.

HEAD

/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O

DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==

Accept: application/json

The system returns one of the following status codes.

Status Code Description

204 NO CONTENT The request succeeded.

401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must be

authenticated.

403 FORBIDDEN Your authentication credentials do not provide sufficient access to the resource.

404 NOT FOUND Could not locate the resource based on the specified URI.

405 METHOD NOT ALLOWED The HEAD method is not supported for the resource.

500 SERVER ERROR Could not create or update the resource because of an internal server error.

Delete an HTTP Bearer Token

You can delete an HTTP bearer token.

Prerequisites

n

Request an HTTP Bearer Token.

Procedure

u

Create the request to delete the HTTP bearer token, as in the following example.

DELETE

/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O

DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==

Accept: application/json

The system returns one of the following status codes.

VMware, Inc. 13

Programming Guide

Status Code Description

204 NO CONTENT The request succeeded. The resource has been deleted.

401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must be

authenticated.

403 FORBIDDEN Your authentication credentials do not provide sufficient access to the resource.

404 NOT FOUND Could not locate the resource based on the specified URI.

405 METHOD NOT ALLOWED The DELETE method is not supported for the resource.

500 SERVER ERROR Could not create or update the resource because of an internal server error.

VMware, Inc. 14

REST API Use Cases 3

Available use cases provide the prerequisite, command line options and format, and sample results to help you perform a variety of vRealize Automation functions, such as requesting a machine or creating a reservation.

You can find information about all of the available vRealize Automation REST API calls in the REST API Reference zip file located in the vRealize Automation Documentation Center. The use cases provide samples of calls that you might commonly use and descriptions of example inputs and outputs relative to those calls.

This chapter includes the following topics:

n

Create a Tenant

n

Requesting a Machine By Type

n

Approve a Machine Request

n

List Provisioned Resources

n

Reprovision a Machine Resource

n

Working with Reservations

n

Working with Reservation Policies

n

Working with Key Pairs

n

Working with Network Profiles

Create a Tenant

You can use the REST API identity service to create a vRealize Automation tenant and perform related functions. Perform the tasks required to create a tenant with the REST API in sequence. For information about creating and working with tenants and roles by using thevRealize Automation application user interface, see the Tenant Administration and IaaS Configuration documentation.

Prerequisites

n

Log in to vRealize Automation as a system administrator and a tenant administrator.

n

Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity server.

VMware, Inc.

15

Programming Guide

n

Verify that the identity server details required for the JSON template are available.

n

Verify that the host name and fully qualified domain name of the vRealize Automation instance are available.

n

If you are not using the API Explorer, verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2 REST API Authentication.

Procedure

1 Use the identity service to display all the available tenants.

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants

2 Submit a request for a new tenant and either call a JSON file that contains tenant request parameters

or specify those parameters using inline text. The first example uses a JSON file as input. The second example uses inline text as input.

The first example calls the following sample newTenant.json file.

{

"@type" : "Tenant",

"id" : "development",

"urlName" : "development",

"name" : "DevelopmentTenant",

"description" : "Tenant for all developers",

"contactEmail" : "admin@mycompany.com",

"defaultTenant" : false

}

Examples Command

Example 1

Call the above newTenant.json file,

which contains parameters for the

tenant request.

Example 2

Specify the parameters for the tenant

request by using inline text.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token" https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json

curl --insecure -H "Accept: application/json" -H "ContentType: application/json"

-H "Authorization: Bearer $token"

--data '{"@type":"Tenant","id":"development","urlName":"development"," name": "DevelopmentTenant","description":"Tenant for all developers","contactEmail": "admin@mycompany.com","defaultTenant":false}'

VMware, Inc. 16

Programming Guide

3 List all available identity stores for a named tenant, such as the default tenant vsphere.local by using

variables, instead of the full token and host name.domain name.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'

-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories

4 Link an LDAP, Active Directory, or Native Active Directory identity store to the tenant by using the

identity service.

Call the following sample ldap.json.txt input file from the command line to specify necessary parameters.

{

"alias": "example.com",

"domain": "example.mycompany.com",

"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

"name": "openLDAPDemo",

"password": "password",

"type": "LDAP",

"url": "ldap://10.000.00.000:389",

"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"

}

Use the following command to call the example JSON text file and link an identity store to a tenant. The command also tests that vRealize Automation can connect to the identity store successfully. If the command finishes successfully, vRealize Automation succeeded in connecting to the identity store.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/identity/api/tenants/development/directories/example.mycompany.com

--data @C:\Temp\ldap.json.txt

5 Query the configured LDAP directory, Active Directory, or Native Active Directory for a specific user.

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants/$tenantId/principals/$userId

6 Assign a user to a role with the REST API identity service.

Use the following command string to submit a request to assign the user tony in the domain example.mycompany.com to the tenant administrator role. It provides empty braces for the required

JSON payload.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"

"https://$host/identity/api/authorization/tenants/development/principals/

susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"

VMware, Inc. 17

Programming Guide

7 Display all of the roles assigned to a user with the identity service.

Use the following command to list all the roles that are assigned to tony@example.mycompany.com.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"

https://$host/identity/api/authorization/tenants/development/principals/

tony@example.mycompany.com/roles

What to do next

Syntax for Displaying Your Current Tenants

You can use the REST API identity service to list of all the vRealize Automation tenants in your system.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/tenants

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output

The command output contains property names and values based on the command input parameters.

VMware, Inc. 18

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of

the tenant objects returned in a pageable list. Each tenant object can contain the following information:

n

Id:

Specifies the unique tenant identifier.

n

urlName:

Specifies the name of the tenant as it appears in URLs.

n

Name:

Specifies the name of the tenant for display purposes.

n

description:

Specifies the long description of the tenant.

n

contactEmail:

Specifies the primary contact email address.

n

Password:

Unused

n

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

n

Size: Specifies the maximum number of rows per page.

n

totalElement: Specifies the number of rows returned.

n

totalPages: Specifies the total number of pages of data available.

n

Number: Specifies the current page number.

n

Offset: Specifies the number of rows skipped.

VMware, Inc. 19

Programming Guide

Example: curl Command

The following example command displays all available tenants.

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants

Format the XML output to improve its readability. For information about formatting output, see Chapter 4

Filtering and Formatting REST API Information.

Example: JSON Output

The following JSON output is returned based on the command input.

{

"links" : [ ],

"content" : [ {

"@type" : "Tenant",

"id" : "vsphere.local",

"urlName" : "vsphere.local",

"name" : "vsphere.local",

"description" : null,

"contactEmail" : null,

"password" : null,

"defaultTenant" : true

}, {

"@type" : "Tenant",

"id" : "MYCOMPANY",

"urlName" : "MYCOMPANY",

"name" : "QETenant",

"description" : "Test tenant",

"contactEmail" : null,

"password" : "defaultPwd#1",

"defaultTenant" : false

} ],

"metadata" : {

"size" : 19,

"totalElements" : 2,

"totalPages" : 1,

"number" : 1,

"offset" : 0

}

Syntax for Requesting a New Tenant

You can use the REST API identity service to submit a request for a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON file from the command line.

VMware, Inc. 20

Programming Guide

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/tenants/$tenantId --data @

$inputFileName.json

$token Specifies a valid HTTP bearer token with necessary credentials.

$host Specifies the host name and fully qualified domain name or IP address

of the vRealize Automation identity server.

$tenantId Specifies the ID of the tenant.

$tenantURL Specifies the URL of the tenant.

$enantName Specifies the name of the tenant.

$description Specifies a description of the tenant.

$emailAddress Specifies the contact email address for the tenant.

JSON Input File Template

To simplify command line input, create a JSON file and call that file from the command line. To create a JSON file, copy the following template to a new text file. To maintain formatting, use an XML editor. Replace the italicized variables in the template with your specific values.

{

"@type" : "Tenant",

"id" : "$tenantId",

"urlName" : "$tenantURL",

"name" : "$tenantName",

"description" : "$description",

"contactEmail" : "$emailAddress",

"defaultTenant" : false

}

Output

The command output contains property names and values based on the command input parameters.

VMware, Inc. 21

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of

the tenant objects returned in a pageable list. Each tenant object can contain the following information:

n

Id:

Specifies the unique tenant identifier.

n

urlName:

Specifies the name of the tenant as it appears in URLs.

n

Name:

Specifies the name of the tenant for display purposes.

n

description:

Specifies the long description of the tenant.

n

contactEmail:

Specifies the primary contact email address.

n

Password:

Unused

n

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

n

Size: Specifies the maximum number of rows per page.

n

totalElement: Specifies the number of rows returned.

n

totalPages: Specifies the total number of pages of data available.

n

Number: Specifies the current page number.

n

Offset: Specifies the number of rows skipped.

Example: curl Command

Submit a request for a new tenant and either call a JSON file that contains tenant request parameters or specify those parameters using inline text. The first example uses a JSON file as input. The second example uses inline text as input.

VMware, Inc. 22

Programming Guide

The first example calls the following sample newTenant.json file.

{

"@type" : "Tenant",

"id" : "development",

"urlName" : "development",

"name" : "DevelopmentTenant",

"description" : "Tenant for all developers",

"contactEmail" : "admin@mycompany.com",

"defaultTenant" : false

}

Example 1: Use the following example to call the above newTenant.json file, which contains parameters for the tenant request.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json

Example 2: Use the following example to specify parameters for the tenant request by using inline text.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json"

-H "Authorization: Bearer $token"

--data '{"@type":"Tenant","id":"development","urlName":"development","name":

"DevelopmentTenant","description":"Tenant for all developers","contactEmail":

"admin@mycompany.com","defaultTenant":false}'

Syntax for Listing All Tenant Identity Stores

You can use the REST API identity service to list all available identity stores for a named vRealize Automation tenant, such as the default tenant vsphere.local.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/tenants/$tenantId/directories

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

Output

The command output contains property names and values based on the command input parameters.

VMware, Inc. 23

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of

the tenant objects returned in a pageable list. Each tenant object can contain the following information:

n

Id:

Specifies the unique tenant identifier.

n

urlName:

Specifies the name of the tenant as it appears in URLs.

n

Name:

Specifies the name of the tenant for display purposes.

n

description:

Specifies the long description of the tenant.

n

contactEmail:

Specifies the primary contact email address.

n

Password:

Unused

n

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

n

Size: Specifies the maximum number of rows per page.

n

totalElement: Specifies the number of rows returned.

n

totalPages: Specifies the total number of pages of data available.

n

Number: Specifies the current page number.

n

Offset: Specifies the number of rows skipped.

VMware, Inc. 24

Programming Guide

Example: curl Command

The following example command lists the identity stores by using variables, instead of the full token and host name.domain name.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'

-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories

Example: JSON Output

The following JSON output is returned based on the command input.

HTTP/1.1 200 OK

Server: Apache-Beach/1.1

Cache-Control: no-cache, no-store

Pragma: no-cache

Expires: Wed, 31 Dec 1969 23:59:59 GMT

Content-Type: application/json;charset=UTF-8

Content-Length: 830

Date: Sat, 01 Feb 2014 13:07:54 GMT

{"links":[],

"content":[

{"@type":"IdentityStore",

"domain":"vcac.mycompany.com",

"name":"openLDAPPromocom",

"description":null,

"alias":"promocom.com",

"type":"LDAP",

"userNameDn":"cn=promocomadmin,ou=promocom,dc=vcac,dc=mycompany,dc=com",

"password":null,

"url":"ldap://10.000.00.000:389",

"groupBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com",

"userBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com"

},

{"@type":"IdentityStore",

"domain":"example.mycompany.com",

"name":"openLDAPDemo",

"description":null,

"alias":"example.com",

"type":"LDAP",

"userNameDn":"cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com",

"password":null,

"url":"ldap://10.000.00.000:389",

"groupBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com",

"userBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com"

}],

"metadata":{

"size":20,

"totalElements":2,

"totalPages":1,

VMware, Inc. 25

Programming Guide

"number":1,

"offset":0

}

Syntax for Linking an Identity Store to the Tenant

You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory identity store to the vRealize Automation tenant.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/tenants/$tenantId/directories/$domainName --data @

$inputFileName.json

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

userId Specifies the ID of the user in the form name@domain.

$domainAlias Specifies the domain alias.

$domainName Specifies the domain of the identity store.

$grpBaseSearchDn Specifies the group search base Distinguished Name.

$identityStoreName Specifies a description of the new tenant.

$password Specifies the password.

$identityStoreType Specifies the identity store type for the tenant. The following values are

supported:

n

LDAP

n

AD

n

NATIVE_AD

$identityServerUrl Specifies the URL of the identity server.

$usrBaseSearchDn Specifies the user search base Distinguished Name.

$usrNameDn Specifies the Distinguished Name for the login user.

JSON Input File Template

Use this template to create a JSON input file. Replace the variables in the template with actual values in the file.

{

"alias": "$domainAlias",

"domain": "$domainName",

"groupBaseSearchDn": "$grpBaseSearchDn",

VMware, Inc. 26

Programming Guide

"name": "$identityStoreName",

"password": "$password",

"type": "$identityStoreType",

"url": "$identityServerUrl",

"userBaseSearchDn": "$usrBaseSearchDn",

"userNameDn": "$usrNameDn"

}

Output

The command output contains property names and values based on the command input parameters.

VMware, Inc. 27

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of

the tenant objects returned in a pageable list. Each tenant object can contain the following information:

n

Id:

Specifies the unique tenant identifier.

n

urlName:

Specifies the name of the tenant as it appears in URLs.

n

Name:

Specifies the name of the tenant for display purposes.

n

description:

Specifies the long description of the tenant.

n

contactEmail:

Specifies the primary contact email address.

n

Password:

Unused

n

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

n

Size: Specifies the maximum number of rows per page.

n

totalElement: Specifies the number of rows returned.

n

totalPages: Specifies the total number of pages of data available.

n

Number: Specifies the current page number.

n

Offset: Specifies the number of rows skipped.

VMware, Inc. 28

Programming Guide

Example JSON Input File

Call the following sample ldap.json.txt input file from the command line to specify necessary parameters.

{

"alias": "example.com",

"domain": "example.mycompany.com",

"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

"name": "openLDAPDemo",

"password": "password",

"type": "LDAP",

"url": "ldap://10.000.00.000:389",

"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"

}

Example: curl Command

The following example command calls the example JSON text file and links an identity store to a tenant. The command also tests that vRealize Automation can connect to the identity store successfully. If the command finishes successfully,vRealize Automation succeeded in connecting to the identity store.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/identity/api/tenants/development/directories/example.mycompany.com

--data @C:\Temp\ldap.json.txt

Example: JSON Output

This output indicates that an identity store is successfully linked to the specified tenant.

Request Headers

{

Content-Type = application/json

Accept = application/json

Content-Length = 413

Accept-Charset = big5, big5-hkscs, euc-jp, euc-kr, gb18030, gb2312, gbk,

ibm-thai, ibm00858, ibm01140, ibm01141, ibm01142, ibm01143, ibm01144, ibm01145,

ibm01146, ibm01147, ibm01148, ibm01149, ibm037, ibm1026, ibm1047, ibm273, ibm277,

ibm278, ibm280, ibm284, ibm285, ibm290, ibm297, ibm420, ibm424, ibm437, ibm500,

ibm775, ibm850, ibm852, ibm855, ibm857, ibm860, ibm861, ibm862, ibm863, ibm864,

ibm865, ibm866, ibm868, ibm869, ibm870, ibm871, ibm918, iso-2022-cn, iso-2022-jp,

iso-2022-jp-2, iso-2022-kr, iso-8859-1, iso-8859-13, iso-8859-15, iso-8859-2,

iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9,

jis_x0201, jis_x0212-1990, koi8-r, koi8-u, shift_jis, tis-620, us-ascii, utf-16,

utf-16be, utf-16le, utf-32, utf-32be, utf-32le, utf-8, windows-1250, windows-1251,

windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257,

windows-1258, windows-31j, x-big5-hkscs-2001, x-big5-solaris, x-compound_text,

x-euc-jp-linux, x-euc-tw, x-eucjp-open, x-ibm1006, x-ibm1025, x-ibm1046, x-ibm1097,

x-ibm1098, x-ibm1112, x-ibm1122, x-ibm1123, x-ibm1124, x-ibm1364, x-ibm1381,

VMware, Inc. 29

Programming Guide

x-ibm1383, x-ibm300, x-ibm33722, x-ibm737, x-ibm833, x-ibm834, x-ibm856, x-ibm874,

x-ibm875, x-ibm921, x-ibm922, x-ibm930, x-ibm933, x-ibm935, x-ibm937, x-ibm939,

x-ibm942, x-ibm942c, x-ibm943, x-ibm943c, x-ibm948, x-ibm949, x-ibm949c, x-ibm950,

x-ibm964, x-ibm970, x-iscii91, x-iso-2022-cn-cns, x-iso-2022-cn-gb, x-iso-8859-11,

x-jis0208, x-jisautodetect, x-johab, x-macarabic, x-maccentraleurope, x-maccroatian,

x-maccyrillic, x-macdingbat, x-macgreek, x-machebrew, x-maciceland, x-macroman,

x-macromania, x-macsymbol, x-macthai, x-macturkish, x-macukraine, x-ms932_0213,

x-ms950-hkscs, x-ms950-hkscs-xp, x-mswin-936, x-pck, x-sjis_0213, x-utf-16le-bom,

x-utf-32be-bom, x-utf-32le-bom, x-windows-50220, x-windows-50221, x-windows-874,

x-windows-949, x-windows-950, x-windows-iso2022jp

}

Response Headers

{

Date = Wed, 29 Oct 2014 22:41:57 GMT

Content-Type = application/json;charset=UTF-8

Content-Length = 0

Vary = Accept-Encoding,User-Agent

Keep-Alive = timeout=15, max=100

Connection = Keep-Alive

}

Successful

Unlinked Identity Store Error

The following output indicates that an identity store is not linked to the specified tenant. To resolve the problem, correct the identity store and connection details in the JSON input file and rerun the command.

Command failed [Rest Error]: {Status code: 400}, {Error code: 90027} , {Error

Source: null}, {Error Msg: Cannot connect to the directory service.}, {System

Msg: 90027-Connection to directory service can’t be established}

Syntax for Searching LDAP or Active Directory for a User

You can use the vRealize Automation REST API identity service to search the configured LDAP directory, Active Directory, or Native Active Directory for a user.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/tenants/$tenantId/principals/$userId

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

$userId Specifies the ID of the user in the form name@domain.

VMware, Inc. 30

Programming Guide

Output

The command output contains property names and values based on the command input parameters.

Property Description

Links Specifies an array of link objects, each of which contains the following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

@type Specifies the user name.

firstName Specifies the first name of the user.

lastName Specifies the last name of the user.

description Specifies the description of the user.

emailAddress Specifies the email address of the user.

locked Specifies the Boolean flag indicating if the user is locked out.

disabled Specifies the Boolean flag indicating if the user is disabled.

principalId Specifies the principal ID of the user in username@domain format.

tenantName Specifies the name of tenant to which user belongs.

name Specifies the first and last name concatenated.

Example: curl Command

The following example command queries the configured LDAP directory for a specific user.

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants/$tenantId/principals/$userId

Example: JSON Output

The following JSON output is returned based on the command input.

{

"links" : [ ],

"content" : [ {

"@type" : "User",

"firstName" : "Tony",

"lastName" : "Anteater",

"emailAddress" : "tony@example.mycompany.com",

"locked" : false,

VMware, Inc. 31

Programming Guide

"disabled" : false,

"principalId" : {

"domain" : "example.mycompany.com",

"name" : "susan"

},

"tenantName" : "MYCOMPANY1",

"name" : "Tony Anteater"

} ]

}

Syntax for Assigning a User to a Role

You can use the REST API identity service to assign a user to a role.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/authorization/tenants/$tenantId/principals/$principalId/rol

es/roleId

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

$principalId Specifies the ID of the user in name@domain format.

$roleId Specifies the ID of the user role.

Example: curl Command

The following example command string submits a request to assign the user tony in the domain example.mycompany.com to the tenant administrator role. It provides empty braces for the required

JSON payload. See Syntax for Searching LDAP or Active Directory for a User for more information about getting the user name and domain values.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"

"https://$host/identity/api/authorization/tenants/development/principals/

susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"

Example: JSON Output

If the command is successful, the HTTP response body is empty except for a 204 No Content status statement.

Syntax for Displaying all Roles Assigned to a User

You can use the REST API identity service to display all of the roles assigned to a user.

VMware, Inc. 32

Programming Guide

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/authorization/tenants/$tenantId/principals/$principalId/ro

les

$token Specifies a valid HTTP bearer token with necessary credentials.

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$tenantId Specifies the ID of the tenant.

principalId Specifies the ID of the user in the form name@domain.

Output

The command output contains property names and values based on the command input parameters.

Property Description

id Specifies the role ID.

name Specifies the role name.

description Specifies the role description.

status Specifies the status of this role.

assignedPermissions Specifies the set of permissions that are implied by this role assignment.

Example: curl Command

The following example command lists all the roles that are assigned to tony@example.mycompany.com.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"

https://$host/identity/api/authorization/tenants/development/principals/

tony@example.mycompany.com/roles

Example: JSON Output

The following JSON output is returned based on the command input.

{

"links" : [ ],

"content" : [ {

"@type" : "SystemRole",

"id" : "ABX_TENANT_ADMIN",

"name" : "Tenant Administrator",

"description" : "ABX Tenant Administrator",

"assignedPermissions" : [ {

"id" : "CATALOG_CONSUME_TENANT_MGMT",

VMware, Inc. 33

Programming Guide

"name" : "Catalog Consume Tenant Management",

"description" : "Consume services, resources and manage requests on

behalf of any user within a Tenant",

"prereqAdminPermissions" : null

}, {

"id" : "MY_TENANT_MANAGEMENT",

"name" : "My Tenant Management",

"description" : "Manage my tenant.",

"prereqAdminPermissions" : null

}, {

"id" : "CATALOG_AUTHOR_TENANT",

"name" : "Catalog Tenant-level Author",

"description" : "Create, update and publish services, catalog items and actions shared across a

Tenant.",

"prereqAdminPermissions" : null

}, {

"id" : "GUI_MY_TENANT_MANAGEMENT",

"name" : "My Tenant Administration User Interface",

"description" : "Access my tenant administration GUI.",

"prereqAdminPermissions" : null

}, {

"id" : "CATALOG_ENTITLE_TENANT",

"name" : "Catalog Tenant-level Entitlement Management",

"description" : "Entitle services, catalog items and actions to all users within a tenant.",

"prereqAdminPermissions" : null

}, {

"id" : "FILE_EDIT_TENANT",

"name" : "Manage Tenant Files",

"description" : "Upload and delete files belonging to this tenant.",

"prereqAdminPermissions" : null

}, {

"id" : "TENANT_USER_DATA_MANAGEMENT",

"name" : "Manage user data (requests, items, tasks etc) within a tenant.",

"description" : "Manage user created objects belonging to the tenant.",

"prereqAdminPermissions" : null

}, {

"id" : "TENANT_ADMIN_ROLE_ASSIGNMENT",

"name" : "Tenant Administrator Role Assignment",

"description" : "Assign the tenant administrator role to other users.",

"prereqAdminPermissions" : null

}, {

"id" : "GUI_MY_TENANT_TUG_MANAGEMENT",

"name" : "My Tenant Identity Stores, Groups and Users Administration User Interfaces",

"description" : "Access my tenant identity stores, groups and users administration GUIs.",

"prereqAdminPermissions" : null

} ]

} ],

"metadata" : {

"size" : 20,

"totalElements" : 1,

"totalPages" : 1,

"number" : 1,

"offset" : 0

VMware, Inc. 34

Programming Guide

Requesting a Machine By Type

You can use the REST API catalog service to request a machine by type.

Your vRealize Automation API calls vary slightly based on your intended machine type.

For information about requesting a machine by using the vRealize Automation application user interface, see the IaaS Configuration documentation.

Request a Machine

You can use a sequence of Rest API catalog service commands to request a machine. This procedure provides sample command line syntax to request a machine. Supporting information regarding available input and output parameters, command-line entry samples, and sample JSON output samples is available in the following reference topics.

This procedure provides sample command line syntax for approving a machine request. Supporting information regarding available input and output parameters, command-line entry samples, and sample JSON output samples is available.

Prerequisites

n

Log in to vRealize Automation as a consumer and current business group user.

n

Verify that the host name and fully qualified domain name of the vRealize Automation instance are available.

n

If you are not using the API Explorer, verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2 REST API Authentication.

Procedure

1 List all shared catalog items in the catalog.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/entitledCatalogItems

2 Locate the details of a specific catalog item by name.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/entitledCatalogItems

3 Locate the blueprint values to complete a machine request by listing the entitled catalog items, and

then locating the catalog item that corresponds to the machine blueprint.

4 Create a JSON file that contains the blueprint values to construct a machine request.

a Open a text editor and create a file, for example, request.json.

b Save the file with any valid file name and file extension, for example, request.json.

VMware, Inc. 35

Programming Guide

c Include the file in the command line when you submit the work item approval.

5 Submit the machine request with the catalog service.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/requests --verbose --data @C:/Temp/requestMachine.json

6 View the requests with the catalog service.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/requests

7 Find the corresponding resource with the catalog service using a request ID.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/resources/?$filter=request/id+eq+%279e3

e2e33-2361-4c0a-8dcf-ff0a347bb08e%27

8 View the details of a machine request by using the catalog service.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/requests/3a5d9697-e3c8-476f-9754-29e773af

Syntax for Listing Shared and Private Catalog Items

You can use the REST API catalog service to retrieve a list of all shared viewable catalog items. Shared catalog items do not belong to a specific business group. Also, this service retrieves a list of all shared and private catalog items that can be viewed, including their business groups.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/catalog-service/api/consumer/catalogItems

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output

The command output contains property names and values based on the command input parameters.

Property Description

version

id Specifies the UUID Identifier of the object. Specifies the property type is string.

VMware, Inc. 36

Programming Guide

Property Description

outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.

name Specifies the user friendly name of the catalog item. Specifies the property type is string.

description Specifies a short description of the catalog item. Specifies the property type is string.

status Specifies the life cycle stage of the catalog item.

statusName Specifies the life cycle status name, such as Active.

catalogItemTypeRef Specifies the type of the catalog item.

serviceRef Specifies the catalog service that contains the catalog item.

iconId Specifies the associated icon representing this item.

organization Specifies the subtenant and/or tenant to which this item belongs

providerBinding Specifies the provider side identifier of this item.

forms Specifies the forms that are associated with catalog items of this type.

callbacks Specifies the call-backs to the provider that are supported by this catalog item.

isNoteworthy Specifies if the catalog item should be highlighted to users for a period of time.

dateCreated Specifies the date that this item was created in the catalog.

lastUpdatedDate Specifies the date that this item was last updated in the catalog.

entitledOrganizations Specifies the organizations in which the catalog item can be consumed by the current user.

catalogItem Specifies the catalog item value.

Example: YouCommand

The following example command retrieves information about all the available shared catalog items.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/entitledCatalogItems

Example: JSON Output

The following JSON output is returned based on the command input.

{

"links" : [ ],

"content" : [ {

"@type" : "entitledCatalogItem",

"id" : "65fbca06-a28e-46f3-bced-c6e5fb3a66f9",

"version" : 1,

"name" : "RHEL 6-vsphere",

"description" : "",

"status" : "PUBLISHED",

"organization" : {

"tenantRef" : "MYCOMPANY",

"tenantLabel" : "ABTenant",

"subtenantRef" : "cccd7a7e-5283-416b-beb0-45eb4e924dcb",

VMware, Inc. 37

Programming Guide

"subtenantLabel" : "MyTestAgentBusinessGroup"

},

"providerBinding" : {

"bindingId" : "e16edcf9-6a10-4bc7-98e2-a33361aeb857",

"providerRef" : {

"id" : "c6fb1980-75b4-4adc-ac71-020d75f61978",

"label" : "iaas-service"

}

},

"forms" : null,

"callbacks" : null,

"isNoteworthy" : true,

"dateCreated" : "2014-02-14T21:53:39.072Z",

"lastUpdatedDate" : "2014-02-14T21:54:07.756Z",

"iconId" : "cafe_default_icon_genericCatalogItem",

"catalogItemTypeRef" : {

"id" : "Infrastructure.Virtual",

"label" : "Virtual Machine"

},

"serviceRef" : {

"id" : "e90847d7-03e1-45a9-8377-be77be03af6f",

"label" : "Tyler's Service"

},

"outputResourceTypeRef" : {

"id" : "Infrastructure.Virtual",

"label" : "Virtual Machine"

}

} ],

"metadata" : {

"size" : 20,

"totalElements" : 1,

"totalPages" : 1,

"number" : 1,

"offset" : 0

}

Syntax for Finding a Catalog Item by Name

You can use the REST API catalog service to locate a catalog item in the service catalog.

Input

Use the input parameters to control the command output.

Parameter Description

URL https://$host/catalog-service/api/consumer/entitledCatalogItems?$filter=name+eq+%27my

+custom+blueprint%27

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$catalogItemId Specifies the ID of a catalog item.

VMware, Inc. 38

Programming Guide

Output

The command output contains property names and values based on the command input parameters.

VMware, Inc. 39

Programming Guide

Property Description

Links Specifies an array of link objects, each of which contains the following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects returned in

a pageable list. Each tenant object can contain the following information:

n

@type:

entitledCatalogItem

n

Id:

Specifies the unique tenant identifier.

n

version:

Displays the object version number.

n

Name:

Specifies the name of the tenant for display purposes.

n

description:

Specifies the long description of the tenant.

n

status:

Specifies the life cycle stage of this catalog item.

n

organization:

Business group or tenant to which this item belongs.

n

tenantRef:

ID of the tenant.

n

tenantLabel:

Name of the tenant.

n

subtenantRef:

ID of the business group.

n

subtenantLabel:

Name of the business group.

n

providerBinding:

Provider side identifier of this item.

n

bindingId:

binding ID.

VMware, Inc. 40

Programming Guide

Property Description

n

providerRef:

Provider.

n

forms:

A specification for the various forms associated with catalog items of this type.

n

callbacks:

A specification for the various call-backs to the provider supported by this catalog item.

n

isNoteworthy:

Flag indicating that this catalog item should be highlighted to users for a period of time.

n

dateCreated:

Date this item was created in catalog.

n

lastUpdatedDate:

Date this item was last updated in catalog.

n

iconId:

Associated icon representing this item.

n

catalogItemTypeRef:

Type of the catalog item.

n

serviceRef:

Catalog service that contains this catalog item.

n

outputResourceTypeRef:

Type of the resource resulting from requesting this catalog item.

Metadata Specifies the paging-related data:

n

Size:

Specifies the maximum number of rows per page.

n

totalElements:

Specifies the number of rows returned.

n

totalPages:

Specifies the total number of pages of data available.

n

Number:

Specifies the current page number.

n

Offset:

Specifies the number of rows skipped.

Example: curl Command

The following example command retrieves all allowed shared catalog items.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/entitledCatalogItems

VMware, Inc. 41

Programming Guide

Example: JSON Output

The following JSON output is returned based on the command input.

{

"links" : [ ],

"content" : [ {

"@type" : "entitledCatalogItem",

"id" : "65fbca06-a28e-46f3-bced-c6e5fb3a66f9",

"version" : 1,

"name" : "RHEL 6-vsphere",

"description" : "",

"status" : "PUBLISHED",

"organization" : {

"tenantRef" : "MYCOMPANY",

"tenantLabel" : "ABTenant",

"subtenantRef" : "cccd7a7e-5283-416b-beb0-45eb4e924dcb",

"subtenantLabel" : "MyTestAgentBusinessGroup"

},

"providerBinding" : {

"bindingId" : "e16edcf9-6a10-4bc7-98e2-a33361aeb857",

"providerRef" : {

"id" : "c6fb1980-75b4-4adc-ac71-020d75f61978",

"label" : "iaas-service"

}

},

"forms" : null,

"callbacks" : null,

"isNoteworthy" : true,

"dateCreated" : "2014-02-14T21:53:39.072Z",

"lastUpdatedDate" : "2014-02-14T21:54:07.756Z",

"iconId" : "cafe_default_icon_genericCatalogItem",

"catalogItemTypeRef" : {

"id" : "Infrastructure.Virtual",

"label" : "Virtual Machine"

},

"serviceRef" : {

"id" : "e90847d7-03e1-45a9-8377-be77be03af6f",

"label" : "Tyler's Service"

},

"outputResourceTypeRef" : {

"id" : "Infrastructure.Virtual",

"label" : "Virtual Machine"

}

} ],

"metadata" : {

"size" : 20,

"totalElements" : 1,

"totalPages" : 1,

"number" : 1,

"offset" : 0

}

VMware, Inc. 42

Programming Guide

Syntax for Locating the Blueprint Values Required to Construct a Machine Request

You can find the blueprint values you need to complete a machine request by listing your entitled catalog items, and then locating the catalog item that corresponds to the machine blueprint.

Shared and Private Catalog Items

n

In the list of catalog items requested, locate the catalog item that corresponds to the machine blueprint. Refer the sample catalog item output in the example.

n

The following attributes and their values are available in the catalog item output. The actual values are required for the machine request.

Table 3‑1. Attribute Values

Attribute Sample Value Description

id 65fbca06-a28e-46f3-bced-

c6e5fb3a66f9

tenant Ref MYCOMPANY Tenant name

subtenantRef cccd7a7e-5283-416b-

beb0-45eb4e924dcb

bindingId e16edcf9-6a10-4bc7-98e2-

a33361aeb857

Catalog item ID

Business group ID

Machine blueprint ID

Excerpt from Sample Catalog Item Output

...

"@type" : "CatalogItem",

"id" : "65fbca06-a28e-46f3-bced-c6e5fb3a66f9",

"version" : 1,

"name" : "RHEL 6-vsphere",

"description" : "",

"status" : "PUBLISHED",

"organization" : {

"tenantRef" : "MYCOMPANY",

"tenantLabel" : "QETenant",

"subtenantRef" : "cccd7a7e-5283-416b-beb0-45eb4e924dcb",

"subtenantLabel" : "MyTestAgentBusinessGroup"

},

"providerBinding" : {

"bindingId" : "e16edcf9-6a10-4bc7-98e2-a33361aeb857",

"providerRef" : {

"id" : "c6fb1980-75b4-4adc-ac71-020d75f61978",

"label" : "iaas-service"

}

},

...

VMware, Inc. 43

Programming Guide

Syntax for Constructing a JSON File For a Machine Request

You can use the REST API catalog service to construct a JSON file for use in a command line machine request.

Prerequisites

n

Obtain the information that you need to add to your JSON file. See Syntax for Locating the Blueprint

Values Required to Construct a Machine Request.

n

Use an XML editor to create your JSON file.

Example: JSON Input File

Use the following JSON input file sample when constructing a file.

{

"@type": "CatalogItemRequest",

"catalogItemRef": {

"id": "65fbca06-a28e-46f3-bced-c6e5fb3a66f9"

},

"organization": {

"tenantRef": "MYCOMPANY",

"subtenantRef": "cccd7a7e-5283-416b-beb0-45eb4e924dcb"

},

"requestedFor": "fritz@example.mycompany.com",

"state": "SUBMITTED",

"requestNumber": 0,

"requestData": {

"entries": [{

"key": "provider-blueprintId",

"value": {

"type": "string",

"value": "e16edcf9-6a10-4bc7-98e2-a33361aeb857"

}

},

{

"key": "provider-provisioningGroupId",

"value": {

"type": "string",

"value": "cccd7a7e-5283-416b-beb0-45eb4e924dcb"

}

},

{

"key": "requestedFor",

"value": {

"type": "string",

"value": "fritz@example.mycompany.com"

}

},

{

"key": "provider-VirtualMachine.CPU.Count",

"value": {

"type": "integer",

VMware, Inc. 44

Programming Guide

"value": 1

}

},

{

"key": "provider-VirtualMachine.Memory.Size",

"value": {

"type": "integer",

"value": 1024

}

},

{

"key": "provider-VirtualMachine.LeaseDays",

"value": {

"type": "integer",

"value": 30

}

},

{

"key": "provider-__Notes",

"value": {

"type": "string",

"value": "MYCOMPANY machine"

}

},

{

"key": "provider-VirtualMachine.Disk0.Size",

"value": {

"type": "string",

"value": "1"

}

},

{

"key": "provider-VirtualMachine.Disk0.Letter",

"value": {

"type": "string",

"value": "C"

}

},

{

"key": "provider-VirtualMachine.Disk0.Label",

"value": {

"type": "string",

"value": "main"

}

}]

}

Syntax for Requesting a Machine

You can use the REST API catalog service to submit a machine request.

VMware, Inc. 45

Programming Guide

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/catalog-service/api/consumer/requests/requestId

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

JSON file or string input Add required JSON input to the command line. See Syntax for Constructing a

JSON File For a Machine Request.

Output

The command output contains property names and values based on the command input parameters.

Property Description

version Displays the object version number.

state Specifies the item state, such as submitted.

approvalStatus Specifies a status indicating whether this request has been approved, rejected, or is still

pending some form of approval.

waitingStatus Specifies a status indicating whether this request is waiting on any external users or services

before it is able to progress.

requestNumber Specifies a more user-friendly identifier for this request.

executionStatus Specifies the current execution status of the request.

stateName Specifies the localized state name.

phase Specifies the current phase of the request, which is more coarse grained and easier for users to

understand.

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

description Contains a brief description of this request.

reasons Specifies the business reasons entered by the requestor or owner of this request.

requestedFor Specifies the ID of the user for whom this request is logged.

requestedBy Specifies the ID of the user who actually submitted the request

organization Subtenant and/or tenant owner of this request.

requestorEntitlementId Specified the value of the requestorEntitlement setting.

preApprovalId Specifies the ID of the preApproval setting.

postApprovalId Specifies the ID of the approval generated for the post-provisioning workflow step.

dateCreated Specifies the date when this request was sent to the catalog.

lastUpdated Specifies the date when this request was last updated.

dateSubmitted Specifies the date when this request was first submitted.

VMware, Inc. 46

Programming Guide

Property Description

dateApproved Specifies the date when this request was approved.

dateCompleted Specifies the date when this request was completed.

quote Contains a quote made by the provider defining the estimated cost(s) associated with the

request and/or any resources provisioned as a result of the request.

requestCompletion Contains additional request completion information.

requestData Contains a map of the provider-specific field-value pairs collected for this request.

retriesRemaning Specifies the number of attempts remaining to move this request from its current state to the

next state in the request workflow.

Some state transitions require calls to external services. These calls may fail due to transient errors such as momentary network errors. In these cases, the catalog will retry the call a number of times before failing.

This property defines the number of retries remaining for the current state transition. When it reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset to the default number of retries for every new operation that is triggered.

requestedItemName Specifies the item name.

requestedItemDescription Specifies the item description.

Example: curl Command

The following example command submits a machine request.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/requests --verbose --data @C:/Temp/requestMachine.json

Example: Output with Request and Response Headers

The following sample displays the request and response headers and the command output. Use the indicated JSON text file or inline text as input.

{

Accept = application/json

Content-Type = application/json

Content-Length = 2806

}

Response Headers

{

Date = Wed, 03 Dec 2014 20:58:34 GMT

ETag = "0"

Location = https://vcac152-013-208.mycompany.com/catalog-service/api/consumer/

requests/3a5d9697-e3c8-476f-9754-29e773af4aa8

Content-Type = application/json;charset=UTF-8

Content-Length = 0

Vary = Accept-Encoding,User-Agent

VMware, Inc. 47

Programming Guide

Keep-Alive = timeout=15, max=100

Connection = Keep-Alive

}

null

Syntax for Viewing All of Your Requests

You can use the vRealize Automation REST API catalog service to view all of your requests.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/catalog-service/api/consumer/requests

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output

The command output contains property names and values based on the command input parameters.

VMware, Inc. 48

Programming Guide

Property Description

Links Specifies an array of link objects, each of which contains the following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects returned in a

pageable list. Each tenant object can contain the following information:

n

version:

Displays the object version number.

n

state:

Specifies the transaction state.

n

approvalStatus:

Indicates whether this request has been approved, rejected, or is still pending some form of approval.

n

waitingStatus:

Indicates whether this request is waiting on any external users or services before it is able to progress.

n

requestNumber:

Specifies the number for this request.

n

executionStatus:

Indicates the current execution status of the request.

n

stateName:

Specifies the localized state name.

n

phase:

Indicates current phase of the request, which is more coarse grained and easier for users to understand.

n

id:

Specifies the UUID Identifier of this object.

n

iconId:

Specifies the associated icon representing this item.

n

description:

Contains a brief description of the tenant.

n

reasons:

Contains the business reasons entered by the requestor or owner of this request.

n

requestedFor:

Specifies the ID of the user for whom this request is logged.

n

requestedBy:

ID of the user who actually submitted the request.

VMware, Inc. 49

Programming Guide

Property Description

n

organization:

Specifies the business group or tenant to which this item belongs.

n

tenantRef:

ID of the tenant.

n

tenantLabel:

Name of the tenant.

n

subtenantRef:

ID of the business group.

n

subtenantLabel:

Name of the business group.

n

requestorEntitlementId:

Contains the requestorEntitlement value.

n

preApprovalId:

Specifies the ID of the preApproval entity.

n

postApprovalId:

Specifies the ID of the approval generated for the post-provisioning workflow step.

n

dateCreated:

Specifies the date this item was created in catalog.

n

lastUpdatedDate:

Specifies the date this item was last updated in catalog.

n

dateSubmitted:

Specifies the date this request was first submitted.

n

dateApproved:

Specifies the date this request was approved.

n

dateCompleted:

Specifies the date this request was completed.

n

quote:

Contains a quote made by the provider defining the estimated cost(s) associated with the request and/or any resources provisioned as a result.

n

requestCompletion:

Requests completion information.

n

requestData:

Requests a map of the provider-specific field-value pairs collected for this request.

n

retriesRemaning:

Specifies the number of attempts remaining to move this request from its current state to the next state in the request workflow.

Some state transitions require calls to external services. These calls may fail due to transient errors such as momentary network errors. In these cases, the catalog will retry the call a number of times before failing.

VMware, Inc. 50

Programming Guide

Property Description

This property defines the number of retries remaining for the current state transition. When it reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset to the default number of retries for every new operation that is triggered.

n

requestedItemName

n

requestedItemDescription

Metadata Specifies the paging-related data:

n

Size:

Specifies the maximum number of rows per page.

n

totalElements:

Specifies the number of rows returned.

n

totalPages:

Specifies the total number of pages of data available.

n

Number:

Specifies the current page number.

n

Offset:

Specifies the number of rows skipped.

Example: curl Command

The following example command displays all requests.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/requests

Example: JSON Output

The following JSON output is returned based on the command input.

{

"links" : [ ],

"content" : [ {

"@type" : "CatalogItemRequest",

"id" : "ec813a12-68c3-40a2-9a33-7efa38e8e2c9",

"iconId" : "Travel_100.png",

"version" : 5,

"requestNumber" : 1,

"state" : "SUCCESSFUL",

"description" : "Attending conference",

"reasons" : "Cuz I wanna go to Austrailia",

"requestedFor" : "tony@example.vmware.com",

"requestedBy" : "tony@example.vmware.com",

"organization" : {

"tenantRef" : "MYCOMPANY",

"tenantLabel" : "QETenant",

"subtenantRef" : "27b85c29-2624-459d-91d6-09ad071c6eb1",

"subtenantLabel" : "Finance"

},

"requestorEntitlementId" : "7840175e-08e8-4152-a3f9-c53a4dd10f38",

VMware, Inc. 51

Programming Guide

"preApprovalId" : null,

"postApprovalId" : null,

"dateCreated" : "2014-02-14T19:45:28.361Z",

"lastUpdated" : "2014-02-14T19:48:27.690Z",

"dateSubmitted" : "2014-02-14T19:45:28.361Z",

"dateApproved" : null,

"dateCompleted" : "2014-02-14T19:48:27.683Z",

"quote" : {

"leasePeriod" : {

"type" : "timeSpan",

"unit" : "DAYS",

"amount" : 5

},

"leaseRate" : {

"type" : "moneyTimeRate",

"cost" : {

"type" : "money",

"currencyCode" : null,

"amount" : 213.0

},

"basis" : {

"type" : "timeSpan",

"unit" : "DAYS",

"amount" : 1

}

},

"totalLeaseCost" : {

"type" : "money",

"currencyCode" : null,

"amount" : 1065.0

}

},

"requestCompletion" : {

"requestCompletionState" : "SUCCESSFUL",

"completionDetails" : "The request was successfully completed"

},

"requestData" : {

"entries" : [ {

"key" : "provider-roomType",

"value" : {

"type" : "entityRef",

"componentId" : null,

"classId" : "roomType",

"id" : "2",

"label" : "Deluxe"

}

}, {

"key" : "provider-workspaceType",

"value" : {

"type" : "entityRef",

"componentId" : null,

"classId" : "workspaceType",

"id" : "1",

"label" : "Private Office"

}

VMware, Inc. 52

Programming Guide

}, {

"key" : "provider-arrivalDate",

"value" : {

"type" : "dateTime",

"value" : "2014-02-21T19:44:00.000Z"

}

}, {

"key" : "provider-address",

"value" : {

"type" : "string",

"value" : "25 McLaren Street\nNorth Sydney, NSW 2060\nAUS"

}

}, {

"key" : "provider-hotel",

"value" : {

"type" : "entityRef",

"componentId" : null,

"classId" : "hotel",

"id" : "8",

"label" : "Racecar Hotel"

}

}, {

"key" : "provider-location",

"value" : {

"type" : "entityRef",

"componentId" : null,

"classId" : "location",

"id" : "3",

"label" : "AUS-Sydney-Napier"

}

}, {

"key" : "provider-duration",

"value" : {

"type" : "integer",

"value" : 5

}

} ]

},

...

Syntax for Finding a Resource by its Request ID

You can use the REST API catalog service with a request ID to find its corresponding resource.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/catalog-service/api/consumer/resources?$filter=request/id+eq+

%27requestId%27

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

VMware, Inc. 53

Programming Guide

Parameter Description

$token Specifies a valid HTTP bearer token with necessary credentials.

requestId Specifies the ID of the request used for the resource, for example,

9e3e2e33-2361-4c0a-8dcf-ff0a347bb08e.

Add one of the following strings to the URL in the command line. Replace requestId with the actual request ID.

n

?$filter=request/id eq 'requestId'

n

?$filter=request/id%20eq%20%27requestId%27

n

?$filter=request/id+eq+%27requestId%27

Output

Use the supported input parameters to control the command output.

Property Description

Links Specifies an array of link objects, each of which contains the following parts:

n

rel

Specifies the name of the link.

n

Self refers to the object that was returned or requested.

n

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

n

Specifies the application or service that determines the other names.

n

href

Specifies the URL that produces the result.

work itemNumber Displays a reference number for the work item.

id Specifies the unique identifier of this resource.

version Displays the object version number.

assignees Displays the list of work item assignees.

subTenantId Optionally associates the work item with a specific business group granting users with

management responsibilities over that business group permission to see the approval.

tenantId Specifies the tenant ID for the work item.

callbackEntityId Specifies the callback entity ID for the work item.

work itemType Specifies the work item type for the work item.

completedDate Specifies the date when the work item was completed.

assignedDate Specifies the date when the work item was assigned.

createdDate Specifies the created date of this instance.

assignedOrCompletedDate Specifies the date to be displayed on UI.

formUrl Specifies the URL from which the layout for this work item can be retrieved.

serviceId Specifies the service ID that generated this work item instance.

work itemRequest Specifies the corresponding work item request object.

VMware, Inc. 54

Programming Guide

Property Description

status Specifies the status of the work item.

completedBy Specifies the principal ID of user who completed the work item.

availableActions Contains a list of relevant work item actions.

Metadata Specifies the paging-related data:

n

Size: Specifies the maximum number of rows per page.

n

totalElement: Specifies the number of rows returned.

n

totalPages: Specifies the total number of pages of data available.

n

Number: Specifies the current page number.

n

Offset: Specifies the number of rows skipped.

Example: curl Command

The following example command locates a resource by using its resource ID.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”

https://$host/catalog-service/api/consumer/resources/?$filter=request/id+eq+%279e3

e2e33-2361-4c0a-8dcf-ff0a347bb08e%27

Syntax for Viewing the Details of a Machine Request

You can use the vRealize Automation REST API catalog service to view the details of a machine request.

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/catalog-service/api/consumer/requests/$requestId

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$requestId Specifies the request ID. See Syntax for Viewing All of Your Requests to view all of your

requests and search for a request ID.

The required request ID is located at the end of the Location URL in the response header.

The request ID is located in the Location field of the response header if you submitted the request with the –headers flag.

Output

The command output contains property names and values based on the command input parameters.

Property Description

version Displays the object version number.

state Specifies the item state, such as submitted.

VMware, Inc. 55