VMware vRealize Automation - 7.3 Programming Guide

Programming Guide
vRealize Automation 7.3
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
Copyright © 2008–2017 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc. 2

Contents

vRealize Automation Programming Guide 7
Updated Information 8
Overview of the vRealize Automation REST API 9
1
REST API Services 9
Using the vRealize Automation REST API 11
About the API Use Cases 12
REST API Authentication 13
2
About HTTP Bearer Tokens 13
Configure the Duration of an HTTP Bearer Token 14
Request an HTTP Bearer Token 14
Syntax for Requesting an HTTP Bearer Token 16
Validate an HTTP Bearer Token 17
Delete an HTTP Bearer Token 18
Creating a Tenant 20
3
Prerequisites for Creating a Tenant 20
Create a Tenant With Parameters Inline 20
Create a Tenant With a JSON File 23
Identity Service Examples for Creating a Tenant 25
Syntax for Displaying Your Current Tenants 26
Syntax for Requesting a New Tenant 28
Syntax for Listing All Tenant Identity Stores 31
Syntax for Linking an Identity Store to the Tenant 33
Syntax for Searching LDAP or Active Directory for a User 37
Syntax for Assigning a User to a Role 38
Syntax for Displaying all Roles Assigned to a User 39
VMware, Inc.
Requesting a Machine 42
4
Request a Machine 42
Catalog Service Examples for Requesting a Machine 44
Syntax for Listing Shared and Private Catalog Items 44
Syntax for Getting Information for a Catalog Item 48
Syntax for Getting a Template Request for a Catalog Item 52
Syntax for Requesting a Machine 55
Syntax for Viewing Details of a Machine Request 59
3
Programming Guide
Approving a Machine Request 63
5
Approve a Machine Request 63
Work Item Service Examples for Approving a Machine Request 64
Syntax for Listing Work Items 65
Syntax for Getting Work Item Details 71
Syntax for Constructing a JSON File to Approve a Machine Request 76
Syntax for Approving a Submitted Machine Request 79
Syntax for Updating Price Information 81
Listing Provisioned Resources 85
6
Prerequisites for Listing Provisioned Resources 85
Display Your Provisioned Resources Example 85
Display Provisioned Resources by Resource Type Example 89
Display All Available Resource Types Example 92
Display Provisioned Resources by Business Groups You Manage Example 94
View Machine Details Example 103
Managing Provisioned Deployments 107
7
Manage Provisioned Deployments 107
Power Off 108
Change Lease 109
Catalog Service Examples for Managing Provisioned Deployments 111
Syntax for Getting Deployment Details 111
Syntax for Navigating to the Children of a Deployed Resource 115
Working with Reservations 122
8
Prerequisites for Working With Reservations 123
Create a Reservation 123
Display a List of Supported Reservation Types 124
Displaying a Schema Definition for a Reservation 127
Get the Business Group ID for a Reservation 153
Get a Compute Resource for the Reservation 155
Getting a Resources Schema by Reservation Type 158
Creating a Reservation By Type 162
Verify a Reservation and Get Reservation Details 173
Display a List of Reservations 181
Update a Reservation 186
Delete a Reservation 191
Service Examples for Working with Reservations 191
Syntax for Displaying a List of Reservations 193
Syntax for Displaying a Schema Definition for a vSphere Reservation 199
VMware, Inc. 4
Programming Guide
Syntax for Displaying a Schema Definition for an Amazon Reservation 206
Syntax for Displaying a Schema Definition for a vCloud Air Reservation 221
Syntax for Getting the Business Group ID for a Reservation 233
Syntax for Getting a Compute Resource for a Reservation 236
Syntax for Getting Resources Schema for a vSphere Reservation 240
Syntax for Getting Resources Schema for an Amazon Reservation 242
Syntax for Getting Resources Schema for a vCloud Air Reservation 245
Syntax for Creating a vSphere Reservation 249
Syntax for Creating an Amazon Reservation 254
Syntax for Creating a vCloud Air Reservation 257
Syntax for Verifying a Reservation and Getting Reservation Details 262
Syntax for Displaying a List of Supported Reservation Types 270
Syntax for Updating a Reservation 275
Syntax for Deleting a Reservation 280
Working with Reservation Policies 282
9
Prerequisites for Working with Reservation Policies 282
List Reservation Policies Example 282
Create a Reservation Policy Example 284
Display a Reservation Policy by ID Example 286
Update a Reservation Policy Example 287
Deleting a Reservation Policy Example 288
Working with Key Pairs 290
10
Prerequisites for Working with Key Pairs 290
Get a Key Pair List Example 290
Create a Key Pair Example 293
Query a Key Pair Example 296
Update a Key Pair Example 298
Delete a Key Pair Example 299
Working with Network Profiles 301
11
Prerequisites for Working With Network Profiles 303
Get a Network Profile List Example 303
Create an External Network Profile Without IPAM Example 312
Create an External Network Profile Using External IPAM Example 314
Query a Network Profile Example 317
Update a Network Profile Example 321
Delete a Network Profile Example 322
Getting a List of Available IP Ranges 324
12
Get a List of Available IP Ranges for an IPAM Provider 324
VMware, Inc. 5
Programming Guide
Importing and Exporting Content 342
13
Understanding Blueprint Schema 343
Prerequisites for Importing and Exporting Content 345
List Supported Content Types Example 345
List Available Content Example 349
Filter Content by Content Type Example 354
Create a Package for Export Example 355
List Packages in the Content Service Example 356
Export a Package Example 360
Validate a Content Bundle Before Importing example 360
Import a Package Example 363
Export XaaS Content Example 364
Import XaaS Content Example 365
Related Tools and Documentation 367
14
Viewing API Reference Information 367
Using vRealize CloudClient 368
Using Third Party Tools 368
Filtering and Formatting REST API Information 370
15
VMware, Inc. 6

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 the vRealize Automation API Reference at https://code.vmware.com/apis/vrealize-automation.
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.
7

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
002448-01
002448-00 Initial release.
n
Removed Day 2 action terminology from Chapter 7 Managing Provisioned Deployments.
n
Clarified procedure in Viewing API Reference Information.
VMware, Inc. 8
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.
This chapter includes the following topics:
n

REST API Services

n
Using the vRealize Automation REST API
n
About the API Use Cases
REST API Services
The vRealize Automation REST API offers the following services and functions.
Table 11. vRealize Automation REST API Services
Service Description
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 Service Access and manage all services and serves as the central view for all
service lookups.
Composition Service Allows vRealize Automation services to register application components,
which the composition service manages so that they can be used in composite blueprints.
Content Management Service Access and manage the content controller and package controller for
export and import processes. This includes export and import for blueprints and software.
Endpoint Configuration Service Create, read, update and delete endpoint types, endpoint categories, and
endpoints.
VMware, Inc. 9
Programming Guide
Table 11. vRealize Automation REST API Services (Continued)
Service Description
Event Broker Service Provide a central location and a consistent way of recording events and
querying for events.
Forms Service Used internally by the vRealize Automation system to create, read,
update and delete (perform CRUD operations on) request forms for XaaS components.
IaaS Proxy Provider Service Run a proxy service that acts as a bridge between the service catalog
and the IaaS provider to call other services, such as the catalog service, composition service, reservation service, and event broker service.
Identity Service Manage tenants, business groups, SSO and custom groups, users, and
identity stores.
IP Address Management Service Allocate and deallocate IP addresses from IP address management
(IPAM) providers.
Licensing Service Retrieve permissions and post serial keys.
Management Service (Reclamation 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.
Network Service Access and manage application network and security settings for
creating and configuring NAT and routed networks; creating load balancers; and adding and configuring security groups, security tags and security policies for application components.
Notification Service Configure and send notifications for several types of events such as the
successful completion of a catalog request or a required approval.
Orchestration Gateway Service Provides a gateway to VMware Realize Orchestrator (vRO) for services
running on vRealize Automation. By using the gateway, consumers of the API can access a vRO instance, and initiate workflows or script actions without having to deal directly with the vRO APIs.
Extensibility (Plug-in) Service Retrieve, create, update, and delete a resource. Retrieve an extension.
Retrieve license notifications.
Placement Service Provides vRealize Automation with recommendations for the placement
of deployments. With cluster health information from an external service such as vRealize Operations Manager, the service can recommend reservations to use for the provisioning of blueprint components.
Portal Service Retrieve, create, update, and delete a portal resource.
Properties Service Manage custom properties, property groups, and property definitions.
Properties specify items that can be added to blueprints to trigger vRealize Orchestrator actions.
Reservation Service Retrieve, create, update, and delete a reservation or reservation policy.
Software Services Triggers the execution life cycle of software components using the
software agent, registers software agents, and manages the creation, modification and deletion of software component, software component types, software resource requests, and nodes (machines).
vRA Orchestrator Service Manage vRealize Orchestrator actions, tasks, packages, and workflows.
Browse system and plug-in inventories.
VMware, Inc. 10
Programming Guide
Table 11. vRealize Automation REST API Services (Continued)
Service Description
Work Item Service Retrieve, create, update, complete, cancel, and delete a work item. Also
retrieve form data, metadata, detail forms, and submission forms from service providers.
XaaS Service Manages XaaS elements such as forms, endpoints, XaaS blueprints,
tenants, vRealize Orchestrator imports, workflows, and work items.
The advanced designer service selection on the vRealize Automation API Reference landing page selects the documentation for the XaaS service.

Using the vRealize Automation REST API

To make vRealize Automation REST API service calls, you can use a browser application or an HTTP client program to send requests and review responses.
REST Client Programs
Any client application that can send HTTPS requests is an appropriate tool for developing REST applications with the vRealize Automation API. The following open-source programs are commonly used:
n
cURL. http://curl.haxx.se
n
Postman application. http://www.getpostman.com
About the API Reference
The vRealize Automation API Reference lists all REST API service calls. It is provided as a Swagger document and is available in either of the following ways.
n
If vRealize Automation is installed, documentation is available with the product.
n
A list of general services
https://$vRA/component-registry/services/docs
n
A list of installation and configuration services
https://$vRA:5480/config/
$vRA denotes an instance of vRealize Automation.
n
If vRealize Automation is not installed, documentation is available from the APIs section for the vRealize Automation API at VMware{code} or, https://code.vmware.com/apis/vrealize-automation.
For information about using the vRealize Automation API Reference, see Viewing API Reference
Information.
VMware, Inc. 11
Programming Guide

About the API Use Cases

While the vRealize Automation API Reference contains a menu that lists all REST API service calls, it does not document use cases. The Programming Guide provides frequently used use cases including sample requests and responses.
The following REST API 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. Each includes service examples that provide syntax for the calls referenced in the use case.
n
Chapter 3 Creating a Tenant
n
Chapter 4 Requesting a Machine
n
Chapter 5 Approving a Machine Request
n
Chapter 6 Listing Provisioned Resources
n
Chapter 7 Managing Provisioned Deployments
n
Chapter 8 Working with Reservations
n
Chapter 9 Working with Reservation Policies
n
Chapter 10 Working with Key Pairs
n
Chapter 11 Working with Network Profiles
n
Chapter 12 Getting a List of Available IP Ranges
n
Chapter 13 Importing and Exporting Content
curl is used for example requests. Request headers required by the API are included in example requests that are not fragments of a larger example. The variable $vRA represents the appliance name.domain name of the vRealize Automation server in all URLs.
Most example responses show only those elements and attributes that are relevant to the operation being discussed. Ellipses (...) indicate omitted content within response bodies.
Postman collections are not used in the API examples, but are available from the Code Samples section for the vRealize Automation API at VMware{code} or, https://code.vmware.com/apis/vrealize-automation.
VMware, Inc. 12

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.
This chapter includes the following topics:
n

About HTTP Bearer Tokens

n
Configure the Duration of an HTTP Bearer Token
n
Request an HTTP Bearer Token
n
Validate an HTTP Bearer Token
n
Delete an HTTP Bearer Token
About 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.
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.
Use the following root URL for HTTP bearer token calls:
https://$vRA/identity/api/tokens
The variable $vRA represents the appliance name.domain name of the vRealize Automation server such as, vra-appliance-name.company.com.
VMware, Inc.
13
Programming Guide
Configure 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.
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 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 details regarding input, output, and response codes, see Syntax for Requesting an HTTP Bearer
Token.
VMware, Inc. 14
Programming Guide
Prerequisites
n
Secure a channel between the web browser and the vRealize Automation server. Open a browser and enter the URL such as:
https://vra-appliance-name.company.com
The system warns that your connection is not private. Click through to confirm the security exception and establish an SSL handshake.
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 appliance name and fully qualified domain name of the vRealize Automation instance are available.
Procedure
1 Enter the command to request the HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"vra-user@company.com","password":"vra-user-password","tenant":"company.com"}'
https://$vRA/identity/api/tokens
In this example, $vRA is an instance of vRealize Automation. The --insecure flag is included so that the request will return a response even if the traffic is not secured with a trusted certificate.
2 Examine the response.
A successful request returns an HTTP bearer token that you include in subsequent API requests.
3 For convenience, store the token in a variable.
export token="EXAMPLE-TOKEN-TEXT"
Example: Token Request and Response
The following sample displays output based on the example request.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"vra-user@company.com","password":"vra-user-password","tenant":"company.com"}'
https://$vRA/identity/api/tokens
{"expires":"2017-04-14T04:46:43.000Z","id":"MTQ5Mj ... M2RmMA==","tenant":"company.com"}
The id is the bearer token to store for future use.
export token="MTQ5Mj ... M2RmMA=="
VMware, Inc. 15
Programming Guide
If the credentials supplied in the Authorization header are invalid, the response includes status code 401 as in the following output.
<!DOCTYPE html><html><head><title>Error report</title></head><body><h1>HTTP Status 401 -
Authentication required</h1></body></html>

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 obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/tokens
$vRA appliance name.domain name of the vRealize Automation server.
usrname Tenant administrator user name.
passwd Tenant administrator password.
tenantURLtoken Tenant URL token determined by the system administrator when creating the tenant such
as, support.
Output
The following information is displayed as a result of your HTTP bearer token request.
Parameter 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.
VMware, Inc. 16
Programming Guide
Example: curl Command to Request HTTP Bearer Token
The following example command requests an HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}' https://$vRA/identity/api/tokens
When your request succeeds, the system returns the expiration date and time of the token, and the HTTP bearer token.

Validate an HTTP Bearer Token

You can validate an existing HTTP bearer token.
Prerequisites
n
Request an HTTP Bearer Token.
Procedure
1 Enter the command to validate the HTTP bearer token.
curl --insecure -I -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-
Control: no-cache" "https://$vRA/identity/api/tokens/$token"
2 Examine the response.
A successful request returns status code 204.
Example: Validate Token Request and Response
The following sample displays output based on the example request.
curl --insecure -I -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-Control:
no-cache" "https://$vRA/identity/api/tokens/$token"
HTTP/1.1 204
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Date: Thu, 13 Apr 2017 21:56:02 GMT
X-Frame-Options: SAMEORIGIN
The server returns one of the following status codes.
VMware, Inc. 17
Programming Guide
Table 21. Status Codes for Validate a Bearer Token
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
1 Enter the command to delete the HTTP bearer token, as in the following example.
curl --insecure -X DELETE -H "Accept: application/json" -H "Authorization: Bearer $token" -H
"Cache-Control: no-cache" "https://$vRA/identity/api/tokens/$token"
2 Examine the response.
A successful request returns status code 204.
Example: Delete Token Request and Response
The following sample displays output based on the example request.
curl --insecure -X DELETE -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-
Control: no-cache" "https://$vRA/identity/api/tokens/$token"
204 NO CONTENT
The server returns one of the following status codes.
Table 22. Status Codes for Delete a Bearer Token
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.
VMware, Inc. 18
Programming Guide
Table 22. Status Codes for Delete a Bearer Token (Continued)
Status Code Description
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. 19

Creating a Tenant 3

You use the identity service to create a tenant.
The identity service is comprised of two components: authentication and authorization. The authentication component manages tenants, groups, users, and identity stores. Creating a tenant is an authentication example.
Two use cases show how to create a tenant, either with parameters inline or with input values in a JSON file. After creating a tenant, you can use other service examples to perform additional authentication and authorization functions.
For general information about creating and working with tenants, see Configuring vRealize Automation in the vRealize Automation information center.
This chapter includes the following topics:
n

Prerequisites for Creating a Tenant

n

Create a Tenant With Parameters Inline

n
Create a Tenant With a JSON File
n
Identity Service Examples for Creating a Tenant
Prerequisites for Creating a Tenant
Satisfy the following conditions before performing any tasks for this use case.
n
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Create a Tenant With Parameters Inline
To create a tenant with parameters inline, you first display all available tenants then request a new tenant with input parameters specified inline.
VMware, Inc.
20
Programming Guide
Prerequisites
In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for the new tenant.
Procedure
1 Use the identity service to display all the available tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
For details regarding input and output of this sample, see Syntax for Displaying Your Current Tenants.
2 Examine the response to verify that the tenant you plan to create is not listed.
See the output of the request to display all tenants Example: Create a Tenant With Parameters Inline.
3 Submit a request for a new tenant with parameters inline.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant","description":"New
Custom Tenant","contactEmail":"admin@vmware.com","defaultTenant":false}'
For details regarding input and output of this sample, see Syntax for Requesting a New Tenant
4 Use the identity service to display all the available tenants again.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
5 Examine the response to verify that the tenant you requested is listed.
See the output of the request to verify the new tenant is created Example: Create a Tenant With
Parameters Inline.
Example: Create a Tenant With Parameters Inline
The following sample output for Step 1 lists three tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
"content"[
{"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true},
VMware, Inc. 21
Programming Guide
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...}
],
"metadata":{"size":20,"totalElements":3,"totalPages":1,"number":1,"offset":0}
}
The following sample output for Step 3 shows that the tenant named rainpole has been created.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant","description":"New
Custom Tenant","contactEmail":"admin@vmware.com","defaultTenant":false}'
{
"id":"rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"admin@vmware.com",
"defaultTenant":false
}
The following sample output for Step 4 lists four tenants including rainpole.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
"content":[
{"@type":"Tenant",
"id":"vsphere.local",
...},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...},
{"@type":"Tenant",
"id":"rainpole",
...}
],
"metadata":{"size":20,"totalElements":4,"totalPages":1,"number":1,"offset":0}
}
VMware, Inc. 22
Programming Guide

Create a Tenant With a JSON File

To create a tenant with a JSON file, you first display all available tenants then request a new tenant with input parameters. The input parameters are specified in a separate JSON file that you call from the request.
Prerequisites
In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for the new tenant required for the JSON file input.
Procedure
1 Use the identity service to display all the available tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
For details regarding input and output of this sample, see Syntax for Displaying Your Current Tenants.
2 Examine the response to verify that the tenant you plan to create is not listed.
See the output of the request to display all tenants Example: Create a Tenant With a JSON File.
3 Create a JSON file for the new tenant request to call.
The newTenant.json file contains information about the new tenant.
{
"@type":"Tenant",
"id":"rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"admin@vmware.com",
"defaultTenant":false
}
4 Submit a request for a new tenant that calls the JSON file.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type:application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
@C:/Temp/newTenant.json
For details regarding input and output of this sample, see Syntax for Requesting a New Tenant
5 Use the identity service to display all the available tenants again.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
VMware, Inc. 23
Programming Guide
6 Examine the response to verify that the tenant you requested is listed.
See the output of the request to verify the new tenant is created Example: Create a Tenant With a
JSON File.
Example: Create a Tenant With a JSON File
The following sample output for Step 1 lists three tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
"content"[
{"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...}
],
"metadata":{"size":20,"totalElements":3,"totalPages":1,"number":1,"offset":0}
}
The following sample output for Step 4, shows that the tenant named rainpole has been created.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type:application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
@C:/Temp/newTenant.json
{
"id": "rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"admin@vmware.com",
"password":"",
"defaultTenant":false
}
The following sample output for Step 5 lists four tenants including rainpole.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
VMware, Inc. 24
Programming Guide
"content":[
{"@type":"Tenant",
"id":"vsphere.local",
...},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...},
{"@type":"Tenant",
"id":"rainpole",
...}
],
"metadata":{"size":20,"totalElements":4,"totalPages":1,"number":1,"offset":0}
}

Identity Service Examples for Creating a Tenant

Syntax for each service example lists input parameters, output parameters, and curl commands.
n
Syntax for Displaying Your Current Tenants
GET /api/tenants lists all the vRealize Automation tenants in your system.
n
Syntax for Requesting a New Tenant
PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON file from the command line.
n
Syntax for Listing All Tenant Identity Stores
GET /api/tenants/{tenantId}/directories lists all available identity stores for a named vRealize Automation tenant, such as the default tenant vsphere.local.
n
Syntax for Linking an Identity Store to the Tenant
PUT /api/tenants/{tenantId}/directories/{id} links an LDAP, Active Directory, or Native Active Directory identity store to the vRealize Automation tenant.
n
Syntax for Searching LDAP or Active Directory for a User
GET /api/tenants/{tenantId}/principals/{userId} searches the configured LDAP directory, Active Directory, or Native Active Directory for a user.
n
Syntax for Assigning a User to a Role
PUT /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/{scope Id}/roles/{scopeRoleId} assigns a user to a role.
n
Syntax for Displaying all Roles Assigned to a User
GET /api/authorization/tenants/{tenantId}/principals/{principalId}/roles displays all of the roles assigned to a user.
VMware, Inc. 25
Programming Guide

Syntax for Displaying Your Current Tenants

GET /api/tenants lists all the vRealize Automation tenants in your system.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/tenants
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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. 26
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. This parameter does not appear when you query a single profile.
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. This parameter is not output when you query for a single profile.
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.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.
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 to Display Current Tenants
The following example command displays all available tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
The response in JSON lists the current tenants. Format the output to improve its readability. For information about formatting output, see Chapter 15 Filtering and Formatting REST API Information.
{
"links":[],
"content"[
{
"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
VMware, Inc. 27
Programming Guide
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true
},
{
"@type":"Tenant",
"id":"qe",
"urlName":"qe",
"name":"QETenant",
"description":"Precreated test tenant",
"contactEmail":null,
"password":"",
"defaultTenant":false
}
{
"@type":"Tenant",
"id":"management",
"urlName":"management",
"name":"Management-ITTenant",
"description":"Precreated test tenant",
"contactEmail":null,
"password":"",
"defaultTenant":false
}
],
"metadata":{
"size":20,
"totalElements":3,
"totalPages":1,
"number":1,
"offset":0
}
}

Syntax for Requesting a New Tenant

PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON file from the command line.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/tenants/$tenantId --data @$inputFileName.json
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
VMware, Inc. 28
Programming Guide
Parameter Description
$tenantId Specifies the ID of the tenant.
$tenantURL Specifies the URL of the tenant.
$tenantName Specifies the name of the tenant.
$description Specifies a description of the tenant.
$emailAddress Specifies the contact email address for the tenant.
$password Optional password for the new tenant. If blank, no password is required.
JSON Input File Template
To simplify command line input, you can call a JSON file with input parameters from the command line. You create the JSON file using a text editor, replacing italicized variables in the following template with your specific values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"password": "$password",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 29
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. This parameter does not appear when you query a single profile.
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. This parameter is not output when you query for a single profile.
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.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.
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 to Request a New Tenant With JSON File
The following sample newTenant.json file contains parameters for the tenant request.
{
"@type" : "Tenant",
"id" : "rainpole",
"urlName" : "rainpole",
"name" : "rainpoleTenant",
"description" : "New Custom Tenant",
"contactEmail" : null,
"password": "",
"defaultTenant" : true
}
VMware, Inc. 30
Programming Guide
The following example command requests a new tenant by calling the newTenant.json file.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants/rainpole --data @C:\Temp\newTenant.json
Example: curl Command to Request a New Tenant With Parameters Inline
The following example command requests a new tenant with input parameters specified inline.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization:
Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant",
"description":"New Custom Tenant","contactEmail":null,"defaultTenant":false}'

Syntax for Listing All Tenant Identity Stores

GET /api/tenants/{tenantId}/directories lists 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://$vRA/identity/api/tenants/$tenantId/directories
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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. 31
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. This parameter does not appear when you query a single profile.
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. This parameter is not output when you query for a single profile.
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.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.
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 to List All Identity Stores for the Tenant
The following example command lists the identity stores.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' -H "Authorization:
Bearer $token” https://$vRA/identity/api/tenants/MYCOMPANY/directories
The following JSON output is returned based on the command input.
{
"links":[],
"content":[
{
"@type":"IdentityStore",
"domain":"vcac.mycompany.com",
"name":"openLDAPPromocom",
VMware, Inc. 32
Programming Guide
"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,
"number":1,
"offset":0
}
}

Syntax for Linking an Identity Store to the Tenant

PUT /api/tenants/{tenantId}/directories/{id} links 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://$vRA/identity/api/tenants/$tenantId/directories/$domainName --data @
$inputFileName.json
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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.
VMware, Inc. 33
Programming Guide
Parameter Description
$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",
"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. 34
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. This parameter does not appear when you query a single profile.
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. This parameter is not output when you query for a single profile.
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.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.
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 to Link an Identity Store to a Tenant
The following sample ldap.json.txt file contains parameters for the tenant request.
{
"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"
}
VMware, Inc. 35
Programming Guide
The following example command links an identity store to a tenant by calling the example JSON text file.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token
https://$vRA/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
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.
This response in JSON 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,
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
VMware, Inc. 36
Programming Guide
Unlinked Identity Store Error
If an identity store is not linked to the specified tenant, the response includes status code 400 such as in the following output.
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}
To resolve the problem, correct the identity store and connection details in the JSON input file and rerun the command.

Syntax for Searching LDAP or Active Directory for a User

GET /api/tenants/{tenantId}/principals/{userId} searches 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://$vRA/identity/api/tenants/$tenantId/principals/$userId
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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.
Output
The command output contains property names and values based on the command input parameters.
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. This parameter does not appear when you query a single profile.
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.
VMware, Inc. 37
Programming Guide
Parameter Description
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 to Search LDAP or Active Directory for a User
The following example command queries the configured LDAP directory for a specific user.
curl --insecure -H "Accept:text/xml" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants/$tenantId/principals/$userId
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,
"disabled" : false,
"principalId" :
{
"domain" : "example.mycompany.com",
"name" : "susan"
},
"tenantName" : "MYCOMPANY1",
"name" : "Tony Anteater"
}
]
}

Syntax for Assigning a User to a Role

PUT /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/{scopeId }/roles/{scopeRoleId} assigns a user to a role.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 38
Programming Guide
Parameter Description
URL https://$vRA/identity/api/authorization/tenants/$tenantId/principals/$principalId/roles/roleId
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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 to Assign a User to a Role
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. For more information about getting the user name and domain values, see Syntax for
Searching LDAP or Active Directory for a User .
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token"
"https://$vRA/identity/api/authorization/tenants/development/principals/susan@example.mycompany.com/rol
es/CSP_TENANT_ADMIN/" --data "{}"
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

GET /api/authorization/tenants/{tenantId}/principals/{principalId}/roles displays all of the roles assigned to a user.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/authorization/tenants/$tenantId/principals/$principalId/roles
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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 the form name@domain.
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 39
Programming Guide
Parameter 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 to Display all Roles Assigned to a User
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://$vRA/identity/api/authorization/tenants/development/principals/tony@example.mycompany.com/roles
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",
"name" : "Catalog Consume Tenant Management",
"description" : "Consume services, resources and manage requests ... 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 ... 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",
VMware, Inc. 40
Programming Guide
"description" : "Entitle services, catalog items and actions ... 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 ... users administration GUIs.",
"prereqAdminPermissions" : null
}
],
"metadata" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
VMware, Inc. 41

Requesting a Machine 4

You use the catalog service to perform tasks related to requesting a machine.
The catalog service is comprised APIs for the consumer, service providers, and service administrators. It is designed to be used by consumers and providers of the service catalog. For example, a consumer would request a catalog item such as a machine. The service provider would fulfill the request.
The catalog service includes Hypermedia as the Engine of Application State (HATEOAS) links. The links function as templates that you can use to complete common tasks supported by the API.
For example, if you submit a template request for a given context, such as: catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1­d5f997c8ad66/requests/template. You use the returned template, either as-is or modified, to create a request that you POST or PUT to the target API, such as: catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1­d5f997c8ad66/requests.
This chapter includes the following topics:
n

Request a Machine

n
Catalog Service Examples for Requesting a Machine
Request a Machine
To request a machine, you first list all shared catalog items to find the machine, then make the request for that item using a template.
Prerequisites
n
Log in to vRealize Automation as a consumer and current business group user.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
VMware, Inc.
42
Programming Guide
Procedure
1 List all shared catalog items in the catalog.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews
For details regarding input and output for this request, see Syntax for Listing Shared and Private
Catalog Items.
2 Examine the response to find the catalogItemId
3 Get a template request for a catalog item.
Use the catalogItemId to submit the template request for this catalog item. In this example, the catalogItemId is dc808d12-3786-4f7c-b5a1-d5f997c8ad66.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template
For details regarding input and output for this request, see Syntax for Getting a Template Request for
a Catalog Item.
A template request for the catalog item is created. The fields and default values are populated based on the configuration of the underlying blueprint. By default, requestMachine.json is the name of the template request.
4 Review and edit the template request.
Review the contents of the template request and edit the values if you want to change them from the default prior to submitting the request for a machine. For example, you can specify a value for the description field or change the values for the machine resources if the blueprint allows for a range.
5 Submit the request for a machine.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$vRA/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests --verbose --data
@C:/Temp/requestMachine.json
{
$contentsOfTemplateFromPrecedingSections
}
For details regarding input and output for this request see Syntax for Requesting a Machine.
VMware, Inc. 43
Programming Guide
6 (Optional) View the details of your request.
You can perform a GET on the URI in the Location header to retrieve the updated request details. In this example, the URI-in-Location-header is 7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b
For details regarding input and output for this request, see Syntax for Viewing Details of a Machine
Request.

Catalog Service Examples for Requesting a Machine

Syntax for each service example lists input parameters, output parameters, and curl commands.
n

Syntax for Listing Shared and Private Catalog Items

GET /api/consumer/entitledCatalogItemViews retrieves a list of all shared viewable catalog items for the current user. Shared catalog items do not belong to a specific business group. This service also retrieves a list of all shared and private catalog items that can be viewed, including their business groups.
n
Syntax for Getting Information for a Catalog Item
GET /api/consumer/entitledCatalogItemViews/{id} gets information about a specific catalog item.
n
Syntax for Getting a Template Request for a Catalog Item
GET /api/consumer/entitledCatalogItems/{id}/requests/template retrieves a template request for a specific catalog item. VMware supplies a number of templates to help you create different types of machine requests.
n
Syntax for Requesting a Machine
POST /api/consumer/entitledCatalogItems/{id}/requests submits a request for a specific catalog item with input provided in a JSON file.
n
Syntax for Viewing Details of a Machine Request
GET /api/consumer/requests/{requestId} provides the details of a machine request, where requestId is the URI in the Location header.
Syntax for Listing Shared and Private Catalog Items
GET /api/consumer/entitledCatalogItemViews retrieves a list of all shared viewable catalog items for the current user. Shared catalog items do not belong to a specific business group. This service also 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.
VMware, Inc. 44
Programming Guide
Parameter Description
URL https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
page number The page number. Default is 1.
limit The number of entries per page. The default is 20.
$orderby Multiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example : Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example: "Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example: "VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
$top Sets the number of returned entries from the top of the response
$skip Sets the number of entries to skip.
VMware, Inc. 45
Programming Guide
Parameter Description
$filter Boolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example : Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example: "Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example: "VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
serviceId (Optional) Query parameter to filter the returned catalog items by one specific service.
onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a request on
behalf of another user.
Output
The command output contains property names and values based on the command input parameters.
Property Description
outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.
catalogItemId Specifies the catalog item identifier.
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.
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.
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.
VMware, Inc. 46
Programming Guide
Example: curl Command to List All Shared Catalog Items
The following example command retrieves information about all shared catalog items of type
ConsumerEntitledCatalogItemView.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews
If backward compatibility is required, use the following example command instead.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/entitledCatalogItems
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
}
],
"entitledOrganizations": [
{
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
}
],
"catalogItemId": "dc808d12-3786-4f7c-b5a1-d5f997c8ad66",
"name": "Linux",
"description": "Linux blueprint for API demo",
"isNoteworthy": false,
"dateCreated": "2015-07-29T03:54:28.141Z",
"lastUpdatedDate": "2015-07-29T12:46:56.405Z",
"iconId": "cafe_default_icon_genericCatalogItem",
"catalogItemTypeRef": {
"id": "com.vmware.csp.component.cafe.composition.blueprint",
"label": "Composite Blueprint"
VMware, Inc. 47
Programming Guide
},
"serviceRef": {
"id": "057d4095-95f1-47da-b14b-641ac9010c97",
"label": "Infrastructure Services"
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Example: curl Command to Locate the Details of a Specific Catalog Item
To search for specific catalog item, add the $catalogItemId. The following example command retrieves information about a catalog item with the name $catalogItemName.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews?
$filter=name+eq+%27$catalogItemName%27

Syntax for Getting Information for a Catalog Item

GET /api/consumer/entitledCatalogItemViews/{id} gets information about a specific catalog item.
REST API Catalog Service
The REST API supports OData filtering. For more information about supported OData filters, refer to the vRealize Automation API Reference, particularly the REST API Tips page located at https://$vRA/component-registry/services/docs/odata.html.
For specific information about catalog service filters, see the "Important Notes About catalog-service and OData Queries" topic located at https://$vRA/catalog-service/api/docs/index.html.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 48
Programming Guide
Parameter Description
URL https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews/{id}
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
page number The page number. Default is 1.
limit The number of entries per page. The default is 20.
$orderby Multiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example : Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example: "Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example: "VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
$top Sets the number of returned entries from the top of the response
$skip Sets the number of entries to skip.
VMware, Inc. 49
Programming Guide
Parameter Description
$filter Boolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example : Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example: "Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example: "VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
serviceId (Optional) Query parameter to filter the returned catalog items by one specific service.
onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a request on
behalf of another user.
Output
The command output contains property names and values based on the command input parameters.
Property Description
outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.
catalogItemId Specifies the catalog item identifier.
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.
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.
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 The list of organizations in which the current user can consume the catalog item.
VMware, Inc. 50
Programming Guide
Example: curl Command to Get Information for a Catalog Item
The following example command retrieves information catalog item with the name $filter=name+eq+ %27$catalogItemName%27.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews?
$filter=name+eq+%27$catalogItemName%27
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
}
],
"entitledOrganizations": [
{
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
}
],
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"name": "Linux",
"description": "Linux blueprint for API demo",
"isNoteworthy": false,
"dateCreated": "2015-07-29T03:54:28.141Z",
"lastUpdatedDate": "2015-07-29T12:46:56.405Z",
"iconId": "cafe_default_icon_genericCatalogItem",
"catalogItemTypeRef": {
"id": "com.vmware.csp.component.cafe.composition.blueprint",
"label": "Composite Blueprint"
},
"serviceRef": {
"id": "057d4095-95f1-47da-b14b-641ac9010c97",
"label": "Infrastructure Services"
},
VMware, Inc. 51
Programming Guide
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Getting a Template Request for a Catalog Item

GET /api/consumer/entitledCatalogItems/{id}/requests/template retrieves a template request for a specific catalog item. VMware supplies a number of templates to help you create different types of machine requests.
Overview
In the entitledCatalogItemViews response, a link field contains a value similar to the following.
{
"@type":"link",
"href":"https://$vRA/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests/template",
"rel":"GET: Request Template"
}
This URL is a HATEOAS link for a template request for this catalog item. The rel field provides a description of the link (request template) and indicates the HTTP method to use with the URI in the href field (GET). By using these HATEOAS links, you can make follow-on API calls without having to consult the API documentation for the URI syntax or construct the links programmatically.
Review and Edit the Template Request
The returned template request is specific to the applicable catalog item. The fields and default values are populated based on the configuration of the underlying blueprint.
You can review the contents of the template and optionally edit the values if you want to change them from the default prior to submitting the request. For example, you can specify a value for the description field or change the values for the machine resources if the blueprint allows for a range.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 52
Programming Guide
Parameter Description
id The UUID of the catalog item.
Output
The command output contains property names and values based on the command input parameters.
Property Description
entitledOrganizations The list of organizations in which the current user can consume the catalog item.
catalogItemId Specifies the catalog item identifier.
Example: curl Command to Get a Template Request for a Catalog Item
The following example command retrieves a template request for the catalog item with ID
dc808d12-3786-4f7c-b5a1-d5f997c8ad66.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template
The following JSON output is returned based on the command input.
Note Price is referred to as cost in API commands and output.
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogItemProvisioningRequest",
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"requestedFor": "csummers@example.com",
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"description": null,
"reasons": null,
"data": {
"Existing_Network_1": {
"componentTypeId": "com.vmware.csp.component.cafe.composition",
"componentId": null,
"classId": "Blueprint.Component.Declaration",
"typeFilter": "LinuxDemo*Existing_Network_1",
"data": {
"_cluster": 1,
"_hasChildren": false,
"description": null,
"name": "Existing Network",
"networkname": "Existing Network",
"subnetmask": "255.255.255.0"
}
},
"vSphere-Linux": {
"componentTypeId": "com.vmware.csp.component.cafe.composition",
"componentId": null,
"classId": "Blueprint.Component.Declaration",
VMware, Inc. 53
Programming Guide
"typeFilter": "LinuxDemo*vSphere-Linux",
"data": {
"Cafe.Shim.VirtualMachine.MaxCost": 0,
"Cafe.Shim.VirtualMachine.MinCost": 0,
"_cluster": 1,
"_hasChildren": false,
"action": "FullClone",
"allow_storage_policies": false,
"archive_days": 0,
"blueprint_type": "1",
"cpu": 1,
"custom_properties": [],
"daily_cost": 0,
"datacenter_location": null,
"description": null,
"disks": [
{
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Compute.Machine.MachineDisk",
"typeFilter": null,
"data": {
"capacity": 6,
"id": 0,
"initial_location": "",
"is_clone": false,
"label": "",
"storage_reservation_policy": "",
"userCreated": true,
"volumeId": 0
}
}
],
"display_location": false,
"guest_customization_specification": null,
"lease_days": 0,
"machine_actions": [
"DESTROY",
"POWER_ON",
"CONNECT_RDP_SSH",
"REPROVISION",
"POWER_CYCLE",
"EXPIRE",
"SUSPEND",
"CONNECT_REMOTE_CONSOLE",
"CONNECT_USING_VDI"
],
"machine_prefix": {
"componentId": null,
"classId": "Infrastructure.Compute.MachinePrefix",
"id": "Use group default"
},
"max_network_adapters": 0,
"max_per_user": 0,
"max_volumes": 60,
VMware, Inc. 54
Programming Guide
"memory": 4096,
"nics": [
{
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Compute.Machine.Nic",
"typeFilter": null,
"data": {
"address": "",
"assignment_type": "DHCP",
"custom_properties": null,
"id": 0,
"load_balancing": "",
"network_profile": "Existing Network"
}
}
],
"number_of_instances": 1,
"os_arch": "x86_64",
"os_distribution": null,
"os_type": "Linux",
"os_version": null,
"platform_name": "vsphere",
"platform_type": "virtual",
"property_groups": [
null
],
"provisioning_workflow": {
"componentId": null,
"classId": "Infrastructure.Compute.ProvisioningWorkflow",
"id": "CloneWorkflow"
},
"reservation_policy": {
"componentId": null,
"classId": "Infrastructure.Reservation.Policy.ComputeResource",
"id": "None"
},
"security_groups": [],
"security_tags": [],
"source_machine": null,
"source_machine_external_snapshot": null,
"source_machine_name": "cbpcentos_63_x86",
"source_machine_vmsnapshot": null,
"storage": 6
}
}
}
}

Syntax for Requesting a Machine

POST /api/consumer/entitledCatalogItems/{id}/requests submits a request for a specific catalog item with input provided in a JSON file.
VMware, Inc. 55
Programming Guide
Prepare your Request
From the entitledCatalogItemViews response, locate the link field that contains a value similar to the following:
{
"@type":"link",
"href":"https://$vRA/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests",
"rel":"POST: Submit Request"
}
Use the information in this response to edit the template construct the URI to request the desired catalog item using a POST command.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/catalog-
service/api/consumer/entitledCatalogItems/$catalogId/requests
$vRA Specifies the appliance name and fully qualified domain name, or IP address of
the vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
catalogItemId The identifier of a catalog item. Typically, this is provided by users via the REST
URI when making an entitledCatalogItem provisioning request.
requestedFor The user for whom this request is being made. Must be the fully qualified user
ID. Typically this is provided by the REST URI when making an entitledCatalogItem provisioning request.
businessGroupId The business group identifier associated with the request. Typically this is
provided via the REST URI when making the request.
description The catalog item description.
reasons
data Context-specific properties. Obtain the consumerEntitledCatalogItem template
request to identify the properties available for a given context.
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.
VMware, Inc. 56
Programming Guide
Property Description
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.
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 price(es) 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.
requestedItemDescriptionSpecifies the item description.
components Returns the list of components associated with the request. The provider supplies this list of components
after request initialization.
VMware, Inc. 57
Programming Guide
Example: curl Command to Request a Machine
To construct your request, refer to the entitledCatalogItemViews response received when you ran the request described in Syntax for Getting a Template Request for a Catalog Item, locate a link field that contains a value similar to the following:
{
"@type":"link",
"href":"https://$vRA/catalog-service/api/consumer/entitledCatalogItems/f89fcbbf-7716-4a61-
addd-a822dd4206f6/requests",
"rel":"POST: Submit Request"
}
The following example command submits a machine request using appropriately edited template content from the entitledCatalogItemViews response.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$vRA/catalog-service/api/consumer/entitledCatalogItems/f89fcbbf-7716-4a61-addd-
a822dd4206f6/requests
{
$contentsOfTemplateFromPrecedingSections
}
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://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b
{
$requestObjectDetails
}
Content-Type = application/json;charset=UTF-8
Content-Length = 0
Vary = Accept-Encoding,User-Agent
Keep-Alive = timeout=15, max=100
Connection = Keep-Alive
}
null
VMware, Inc. 58
Programming Guide

Syntax for Viewing Details of a Machine Request

GET /api/consumer/requests/{requestId} provides the details of a machine request, where
requestId is the URI in the Location header.
Request Status
Typically, the request status information is the most important part of request details. The phase field corresponds to the status displayed in the Requests tab in the interface. You can rerun this command multiple times to monitor the state of a machine request.
Table 41. Request Phase Status
Phase Description End State?
UNSUBMITTED Request was saved but not submitted. No
PENDING_PRE_APPROVAL Request is subject to approval - pre-provisioning approval required. No
IN_PROGRESS Request is in progress, machine is being provisioned. No
PENDING_POST_APPROVAL Request is subject to approval, post-provisioning approval
required.
SUCCESSFUL Request completed successfully. The machine is available under
provisioned resources on the Items tab.
FAILED Request failed. Yes
REJECTED Request approval was rejected and will not complete. Yes
No
Yes
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/catalog-service/api/consumer/requests/$requestId
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$requestId Specifies the request ID. See Display Your Provisioned Resources Example 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.
VMware, Inc. 59
Programming Guide
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.
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 price(es) 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.
VMware, Inc. 60
Programming Guide
Property Description
requestedItemDescriptionSpecifies the item description.
components Returns the list of components associated with the request. The provider supplies this list of components
after request initialization.
Example: curl Command to View the Details of the Machine Request
The following example command displays details of a request.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token
https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b
The following sample output contains information about the catalog item request 7aaf9baf­aa4e-47c4-997b-edd7c7983a5b.
{
"@type": "CatalogItemRequest",
"id": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"iconId": "cafe_default_icon_genericCatalogItem",
"version": 6,
"requestNumber": 8,
"state": "SUCCESSFUL",
"description": "API test",
"reasons": null,
"requestedFor": "csummers@example.com",
"requestedBy": "csummers@example.com",
"organization": {
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
},
"requestorEntitlementId": "1b409157-152c-43c4-b4cc-1cdef7f6adf8",
"preApprovalId": null,
"postApprovalId": null,
"dateCreated": "2015-07-29T13:50:33.689Z",
"lastUpdated": "2015-07-29T13:55:35.951Z",
"dateSubmitted": "2015-07-29T13:50:33.689Z",
"dateApproved": null,
"dateCompleted": "2015-07-29T13:55:35.949Z",
"quote": {},
"requestCompletion": {
"requestCompletionState": "SUCCESSFUL",
"completionDetails": null
},
"requestData": {
$detailsOfSubmittedRequest
},
"retriesRemaining": 3,
"requestedItemName": "Linux",
"requestedItemDescription": "Linux blueprint for API demo",
VMware, Inc. 61
Programming Guide
"stateName": "Successful",
"approvalStatus": "POST_APPROVED",
"executionStatus": "STOPPED",
"waitingStatus": "NOT_WAITING",
"phase": "SUCCESSFUL",
"catalogItemRef": {
"id": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"label": "Linux"
}
}
Note In the request details, the phase field corresponds to the status that is displayed in the Requests
tab in the user interface.
VMware, Inc. 62

Approving a Machine Request 5

You use a series of work item service commands to approve a machine request.
Basic components of the work item service are the work item and the assignment. The work item service provides a standard way to present work items to users. For example, a user can view all work items and select the item to perform such as approving a machine request.
This chapter includes the following topics:
n

Approve a Machine Request

n
Work Item Service Examples for Approving a Machine Request
Approve a Machine Request
To approve a machine request, you first get a work item ID, then specify the ID in the approval.
Prerequisites
n
Log in to vRealize Automation as an approver with at least one of the following qualifications:
n
You are designated as an approver in an approval policy.
n
You belong to a group which has been designated as an approval group in an approval policy.
n
You are designated as a delegate for someone who is an approver.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
1 List all available work item IDs.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems
For details regarding input and output for this request, see Syntax for Listing Work Items.
2 Examine the response to find the workItemId
VMware, Inc.
63
Programming Guide
3 Get details for a specific work item ID.
Use the workItemId to get the details for this work item. In this example, the workItemId is 5e3e9519-78ea-4409-a52c-e4aa3bc56511.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511
For details regarding input and output for this request, see Syntax for Getting Work Item Details.
4 Construct a JSON file that contains the work item ID information that you need to approve a machine
request.
a Copy the appropriate JSON input file template to a new file in an XML editor that maintains
formatting.
b Substitute the input variables in the template with the values you obtained for your specific work
item ID, for example 5e3e9519-78ea-4409-a52c-e4aa3bc56511.
Save the file with a new name, for example, approve.json.
c
For details regarding input and output for this request, see Syntax for Constructing a JSON File to
Approve a Machine Request.
5 Approve the submitted machine request by specifying the work item ID and including the JSON file as
part of the command line.
curl --insecure -H "Content-Type:application/json"
-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json
For details regarding input and output for this request, see Syntax for Approving a Submitted Machine
Request.
If the command is successful, the HTTP status is 201 Created. If the command is not successful, the HTTP status is 204 No Content.

Work Item Service Examples for Approving a Machine Request

Syntax for each service example lists input parameters, output parameters, and curl commands.
n
Syntax for Listing Work Items
GET /api/workitems lists the unique IDs of all available work items.
n
Syntax for Getting Work Item Details
GET /api/workitems/{id} retrieves the details of a pending work item. You need these details to submit a completion request.
VMware, Inc. 64
Programming Guide
n
Syntax for Constructing a JSON File to Approve a Machine Request
You can specify a JSON file in your vRealize Automation REST API command line input. For example, when you enter a command to approve a machine request, you can include the name of a JSON file that contains all the parameters required to approve the request and complete the work item.
n
Syntax for Approving a Submitted Machine Request
PUT /api/workitems/{id} approves a submitted work item request to complete the request. To construct the approval command, you add work item and work item form details to a JSON file, and call that JSON file from the command line. Use a template to correctly format the JSON file content.
n
Syntax for Updating Price Information
POST /api/blueprints/{id}/costs/upfront of the composition service, updates and displays price information for a deployment. The price of a deployment is based on which blueprint you request plus details of the specific request. For example, if the blueprint allows for a range of CPU, memory, or storage values, the price depends on the value requested.

Syntax for Listing Work Items

GET /api/workitems lists the unique IDs of all available work items.
Inputs
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/workitem-service/api/workitems
$vRA Specifies the appliance name and fully qualified domain name, or IP address of
the vRealize Automation 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
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. This property does not exist when you query for a single profile.
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.
VMware, Inc. 65
Programming Guide
Property Description
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.
assignedOrCompletedD ate
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.
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:
Specifies the date to be displayed on UI.
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 retrieves all the available work item IDs.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$vRA/workitem-service/api/workitems
Example: JSON Output
The following JSON output is returned based on the command input.
Note Price is referred to as cost in API commands and output.
{
"links" : [ ],
"content" : [ {
"@type" : "WorkItem",
VMware, Inc. 66
Programming Guide
"id" : "1755ef1a-d6f0-4901-9ecd-d03352ae4a05",
"version" : 1,
"workItemNumber" : 1,
"assignees" : [ {
"principalId" : "tony@example.mycompany.com",
"principalType" : "USER"
} ],
"tenantId" : "MYCOMPANY",
"callbackEntityId" : "1",
"workItemType" : {
"id" : "com.mycompany.cafe.samples.travel.workItem",
"name" : "Workspace Assignment",
"pluralizedName" : "Workspace Assignments",
"description" : "Location Specific Workspace Assignment",
"serviceTypeId" : "com.mycompany.cafe.samples.travel.api",
"actions" : [ {
"id" : "com.mycompany.cafe.samples.travel.workItem.complete",
"name" : "Reserve Workspace",
"stateName" : "Completed",
"icon" : {
"id" : "baa623db-0ca0-4db7-af41-9a301bc9e152",
"name" : "Complete Action Icon",
"contentType" : "image/png",
"image" : null
}
}, {
"id" : "com.mycompany.cafe.samples.travel.workItem.cancel",
"name" : "Workspace Unavailable",
"stateName" : "Cancelled",
"icon" : {
"id" : "b03f994a-e1ec-4aae-8fae-e747ed680a5e",
"name" : "Cancel Action Icon",
"contentType" : "image/png",
"image" : null
}
} ],
"completeByEmail" : true,
"commentsField" : null,
"listView" : {
"columns" : [ {
"id" : "duration",
"label" : "Duration",
"description" : "The length of stay, measured in days.",
"dataType" : {
"type" : "primitive",
"typeId" : "INTEGER"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
VMware, Inc. 67
Programming Guide
}, {
"id" : "location",
"label" : "Destination",
"description" : "The destination to which travel is being requested.",
"dataType" : {
"type" : "ref",
"componentTypeId" : null,
"componentId" : null,
"classId" : "location",
"typeFilter" : null,
"label" : null
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
}, {
"id" : "arrivalDate",
"label" : "Arrival Date",
"description" : "The date of arrival at the destination",
"dataType" : {
"type" : "primitive",
"typeId" : "DATE_TIME"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
} ],
"defaultSequence" : [ "location", "arrivalDate", "duration" ]
},
"version" : 3,
"forms" : {
"workItemDetails" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemNotification" : {
"type" : "external",
"formId" : "travel.itinerary.details"
}
}
},
VMware, Inc. 68
Programming Guide
.
.
.
"completedDate" : null,
"assignedDate" : "2014-02-20T23:55:31.600Z",
"createdDate" : "2014-02-20T23:55:31.600Z",
"assignedOrCompletedDate" : "2014-02-20T23:55:31.600Z",
"serviceId" : "2af18227-6a00-49e9-a76b-96de3ee767d2",
"workItemRequest" : {
"itemId" : "531660fd-b540-4946-9917-38c023b61c02",
"itemName" : "test travel 1",
"itemDescription" : "test travel 1",
"itemRequestor" : "tony@example.mycompany.com",
"itemCost" : 0.0,
"itemData" : {
"entries" : [ {
"key" : "requestLeaseTotal",
"value" : {
"type" : "money",
"currencyCode" : null,
"amount" : 1065.0
}
}, {
"key" : "approvalId",
"value" : {
"type" : "string",
"value" : "7a8b6054-1922-4f82-9266-245dffaa957c"
}
}, {
"key" : "requestClassId",
"value" : {
"type" : "string",
"value" : "request"
}
}, {
"key" : "requestedFor",
"value" : {
"type" : "string",
"value" : "tony@example.mycompany.com"
}
}, {
"key" : "requestReasons"
}, {
"key" : "requestedItemName",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestInstanceId",
"value" : {
"type" : "string",
VMware, Inc. 69
Programming Guide
"value" : "1cfe7177-74e3-4d68-a559-ea17587022ca"
}
}, {
"key" : "requestRef",
"value" : {
"type" : "string",
"value" : "15"
}
}, {
"key" : "requestedItemDescription",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestLeaseRate",
"value" : {
"type" : "moneyTimeRate",
"cost" : {
"type" : "money",
"currencyCode" : null,
"amount" : 213.0
},
"basis" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 1
}
}
}, {
"key" : "requestingServiceId",
"value" : {
"type" : "string",
"value" : "f91d044a-04f9-4b96-8542-375e3e4e1dc1"
}
}, {
"key" : "policy",
"value" : {
"type" : "string",
"value" : "test travel approval policy"
}
}, {
"key" : "phase",
"value" : {
"type" : "string",
"value" : "Pre Approval"
}
}, {
"key" : "requestDescription",
"value" : {
"type" : "string",
"value" : "t"
}
}, {
"key" : "requestLease",
VMware, Inc. 70
Programming Guide
"value" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 5
}
}, {
"key" : "requestedBy",
"value" : {
"type" : "string",
"value" : "tony@example.mycompany.com"
}
} ]
}
},
"status" : "Active",
"availableActions" : [ ]
} ],
"metadata" : {
"size" : 20,
"totalElements" : 7,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}

Syntax for Getting Work Item Details

GET /api/workitems/{id} retrieves the details of a pending work item. You need these details to submit a completion request.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/workitem-service/api/workitems/workitem_ID
$vRA Specifies the appliance name and fully qualified domain name, or IP address of
the vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
workitem_ID Specifies the unique identifier of a work item. See Syntax for Listing Work Items.
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 71
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. This property does not exist when you query for a single profile.
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.
assignedOrCompletedD
Specifies the date to be displayed on UI.
ate
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.
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.
VMware, Inc. 72
Programming Guide
Example: curl Command
The following example command retrieves the necessary details for the specified work item.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511
Example: JSON Output
The following JSON output is returned based on the command input.
Note Price is referred to as cost in API commands and output.
To view the contents of a JSON output file, for example workItemDetails.json, use the ! command with more in UNIX or type in Windows.
n
(UNIX) vcac-shell>! more workItemDetails.json
n
(Windows) vcac-shell> ! CMD /C type workItemDetails.json
vcac-shell> ! more workItemDetails.json
{
"id" : "5e3e9519-78ea-4409-a52c-e4aa3bc56511",
"version" : 0,
"workItemNumber" : 8,
"assignees" : [ {
"principalId" : "tony@example.mycompany.com",
"principalType" : "USER"
} ],
"subTenantId" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"tenantId" : "MYCOMPANY",
"callbackEntityId" : "069dc3ce-a260-4d6a-b191-683141c994c0",
"workItemType" : {
"id" : "com.mycompany.csp.core.approval.workitem.request",
"name" : "Approval",
"pluralizedName" : "Approvals",
"description" : "",
"serviceTypeId" : "com.mycompany.csp.core.cafe.approvals",
"actions" : [ {
"id" : "com.mycompany.csp.core.approval.action.approve",
"name" : "Approve",
"stateName" : "Approved",
"icon" : {
"id" : "c192b6a7-5b35-4a3b-8593-107ffcf8c3a8",
"name" : "approved.png",
"contentType" : "image/png",
"image" : null
}
}, {
"id" : "com.mycompany.csp.core.approval.action.reject",
"name" : "Reject",
VMware, Inc. 73
Programming Guide
"stateName" : "Rejected",
"icon" : {
"id" : "61c6da67-1164-421d-b575-10a245c89e10",
"name" : "rejected.png",
"contentType" : "image/png",
"image" : null
}
} ],
"completeByEmail" : true,
"commentsField" : "businessJustification",
"listView" : {
"columns" : [ {
"id" : "requestedItemName",
"label" : "Requested Item",
"description" : "",
"dataType" : {
"type" : "primitive",
"typeId" : "STRING"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
},
.
.
.
{
"id" : "requestLease",
"label" : "Lease",
"description" : "",
"dataType" : {
"type" : "primitive",
"typeId" : "TIME_SPAN"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
} ],
"defaultSequence" : [ "requestRef", "requestedItemName", "requestedFor", "requestLease",
"requestLeaseRate", "requestLeaseTotal" ]
},
"version" : 1,
"forms" : {
VMware, Inc. 74
Programming Guide
"workItemDetails" : {
"type" : "external",
"formId" : "approval.details"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "approval.submission"
},
"workItemNotification" : {
"type" : "external",
"formId" : "approval.notification"
}
}
},
"completedDate" : null,
"assignedDate" : "2014-02-25T01:26:07.153Z",
"createdDate" : "2014-02-25T01:26:07.153Z",
"assignedOrCompletedDate" : "2014-02-25T01:26:07.153Z",
"serviceId" : "2af18227-6a00-49e9-a76b-96de3ee767d2",
"workItemRequest" : {
"itemId" : "069dc3ce-a260-4d6a-b191-683141c994c0",
"itemName" : "test-blueprint",
"itemDescription" : "",
"itemRequestor" : "fritz@example.mycompany.com",
"itemCost" : 0.0,
"itemData" : {
"entries" : [ {
"key" : "requestLeaseTotal"
}, {
"key" : "approvalId",
"value" : {
"type" : "string",
"value" : "469c11ae-ed27-4790-baf1-c6839f35d474"
}
}, {
"key" : "requestClassId",
"value" : {
"type" : "string",
"value" : "request"
}
}, {
"key" : "requestedFor",
"value" : {
"type" : "string",
"value" : "fritz@example.mycompany.com"
}
}, {
"key" : "requestReasons",
"value" : {
"type" : "string",
"value" : ""
}
}, {
"key" : "requestedItemName",
"value" : {
VMware, Inc. 75
Programming Guide
"type" : "string",
"value" : "test-blueprint"
}
.
.
.
}, {
"key" : "requestLease"
}, {
"key" : "requestedBy",
"value" : {
"type" : "string",
"value" : "fritz@example.mycompany.com"
}
} ]
}
},
"status" : "Active",
"availableActions" : [ ]
}

Syntax for Constructing a JSON File to Approve a Machine Request

You can specify a JSON file in your vRealize Automation REST API command line input. For example, when you enter a command to approve a machine request, you can include the name of a JSON file that contains all the parameters required to approve the request and complete the work item.
Template JSON File Values
Copy the following template to start constructing a properly formatted JSON file in a text editor. Replace the highlighted values with your obtained work item details. After you create the JSON file, you can include it, or its contents, when you approve a submitted machine request. See Syntax for Approving a
Submitted Machine Request.
{
"formData": {
"entries": [
{
"key": "source-source-provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-source-provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 512
VMware, Inc. 76
Programming Guide
}
},
{
"key": "source-source-provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-businessJustification",
"value": {
"type": "string",
"value": "solves abx request"
}
},
{
"key": "source-source-provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 0
}
}
]
},
"workItemId": "5e3e9519-78ea-4409-a52c-e4aa3bc56511",
"workItemActionId": "com.mycompany.csp.core.approval.action.approve"
}
Certain parameters are available to use in the JSON template.
Table 51. JSON Template Value Table
JSON File Parameter Name Description of Value
workItemId Specifies the value of the corresponding work item ID obtained from the
work item list.
source-source-provider­Cafe.Shim.VirtualMachine.NumberOfInstances value
source-source-provider-VirtualMachine.Memory.Size Specifies the amount of memory requested in GB.
source-source-provider-VirtualMachine.CPU.Count Specifies the number of CPUs requested.
source-businessJustification Specifies the text description of reason for request.
source-source-provider-VirtualMachine.LeaseDays Specifies the number of days to lease.
workItemActionId To approve a request, include the approve statement, for example
Specifies the number of instances requested.
com.mycompany.csp.core.approval.action.approve..
To reject a request, include the reject statement, for example com.mycompany.csp.core.approval.action.reject.
VMware, Inc. 77
Programming Guide
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",
"value": 1
}
},
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
},
{
"key": "provider-VirtualMachine.LeaseDays",
VMware, Inc. 78
Programming Guide
"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 Approving a Submitted Machine Request

PUT /api/workitems/{id} approves a submitted work item request to complete the request. To construct the approval command, you add work item and work item form details to a JSON file, and call that JSON file from the command line. Use a template to correctly format the JSON file content.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/workitem-service/api/workitems/workitem_ID
$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.
VMware, Inc. 79
Programming Guide
Parameter Description
$token Specifies a valid HTTP bearer token with necessary credentials.
workitem_ID Specifies the unique identifier of a work item. See Syntax for Listing
Work Items.
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. This property does not exist when you query for a single profile.
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.
assignedOrCompletedD
Specifies the date to be displayed on UI.
ate
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.
status Specifies the status of the work item.
completedBy Specifies the principal ID of user who completed the work item.
VMware, Inc. 80
Programming Guide
Property Description
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: Example: curl Command
Approve a submitted machine request by specifying its work item ID and using a JSON file named
approve.json to pass arguments to the command line.
curl -X PUT --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json
Error Conditions
If the same request is submitted a second time, the following error response is received:
Command failed [Rest Error]: {Status code: 400}, {Error code: 12005} ,
{Error Source: null}, {Error Msg: Work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511
is in COMPLETED state. Requested operation cannot be performed.}, {System Msg:
Work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511 is in COMPLETED state. Requested
operation cannot be performed.}
If a user who is not authorized to approve the request submits the request, the following error response is received:
Command failed [Rest Error]: {Status code: 400}, {Error code: 12017} ,
{Error Source: null}, {Error Msg: User fritz@example.mycompany.com not authorized to
complete work item with ID 5e3e9519-78ea-4409-a52c-e4aa3bc56511.}, {System Msg:
User fritz@example.mycompany.com not authorized to complete Work item with id
5e3e9519-78ea-4409-a52c-e4aa3bc56511.}

Syntax for Updating Price Information

POST /api/blueprints/{id}/costs/upfront of the composition service, updates and displays price information for a deployment. The price of a deployment is based on which blueprint you request plus details of the specific request. For example, if the blueprint allows for a range of CPU, memory, or storage values, the price depends on the value requested.
VMware, Inc. 81
Programming Guide
Input
Use the supported input parameters to control the command output.
Note Price is referred to as cost in API commands and output.
Parameter Description
URL https://$vRA/composition-
service/api/blueprints/$BlueprintId/costs/upfront
Method Post
$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP Body Specifies the blueprint ID for the blueprint for which you are
requesting price information and other information.
n
Blueprint ID: Specifies the blueprint ID.
n
requestedFor: The user for whom this request is being made. Must be the fully qualified user ID.
n
subTenantId: Specifies the subtenant ID associated with the blueprint
n
requestData: Specifies data that identifies the blueprint further.
n
entries
n
Key: The name of the machine on which the blueprint resides.
n
value: Specifies key-value pairs that further identify the blueprint, such as the type of the value, the componentType ID for the item, the classID of the value, and where the blueprint resides. In turn, each entry contains an array of key-value pairs that identify the type of data used to compute the price that is to be displayed.
n
Values: Specifies an array of type filters.
n
Entries: Specifies a list of key-value pairs that specify the values to be used in computing the price. For example, the cluster, CPU, and allocated memory to use.
Output
The command output contains property names and values based on the command input parameters.
Property Description
setupFee Specifies the one time setup fee associated with the component.
totalEstimatedLeasePriceInfo Specifies the minimum price and maximum price for the lease
period.
averageDailyPriceInfo Specifies the average daily price, which depends on the
reservation available for the component.
VMware, Inc. 82
Programming Guide
Property Description
count Specifies the instance count of the component.
memory Specifies memory requested for this component.
additional Specifies the additional price, if any, associated with the
component.
cpu Specifies the cpu requested for the component.
storage Specifies the storage requested for the component.
componentId Specifies the component ID, or total price of the deployment.
Example: curl Command
The following sample command updates and displays the price of a sample blueprint with one node. The HTTP body is included as part of the command line input.
Note Price is referred to as cost in API commands and output.
curl -- insecure -H “Content Type: application/json”
-H "Authorization: Bearer $token"
https://$vRA/composition-service/api/blueprints/$BlueprintId/costs/upfront"
{
"blueprintId": "myblueprintId",
"requestedFor": "fritz@coke.sqa-horizon.local",
"subTenantId": "7a961949-13c4-4f3d-9010-66db8da6c51e",
"requestData": {
"entries": [
{
"key": "vSphere_Machine_1",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"classId": "Blueprint.Node",
"typeFilter": "phanisimple*vSphere_Machine_1",
"values": {
"entries": [
{
"key": "_cluster",
"value": {
"type": "integer",
"value": 3
}
},
{
"key": "cpu",
"value": {
"type": "integer",
"value": 2
}
},
{
VMware, Inc. 83
Programming Guide
"key": "memory",
"value": {
"type": "integer",
"value": 2048
}
}
]
}
}
}
]
}
}
Example: JSON Output for a Blueprint Price Update
[{"componentId":"vSphere_Machine_1",
"setupFee":"$0.00",
"totalEstimatedLeasePriceInfo":{"min":50.0543225806451601,"max":
50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":{"min":16.6847741935483867,"max":16.6847741935483867,"displayString":"$16.68"},
"count":3
"fieldMap":{"setup_fee":{"min":0,"max":0,"displayString":"$0.00"},
"memory":{"min":8.00,"max":8.00,"displayString":"$8.00"},
"additional":{"min":8.6847741935483867,"max":8.6847741935483867,"displayString":"$8.68"},
"cpu":{"min":0.0,"max":0.0,"displayString":"$0.00"},
"storage":{"min":0,"max":0,"displayString":"$0.00"}}},
{"componentId":"Total","setupFee":"","totalEstimatedLeasePriceInfo":
{"min":50.0543225806451601,"max":50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":{"min":16.6847741935483867,"max":16.6847741935483867,"displayString":"$16.68"},
"count":3,"fieldMap":{}}]
VMware, Inc. 84

Listing Provisioned Resources 6

You use the catalog service to list provisioned resources.
The catalog service is designed to be used by consumers and providers of the service catalog. For example, a consumer might want to list resources provisioned by a provider. The consumer can also list the resources in multiple ways.
Each example for this use case lists a curl command with respective JSON response, plus input and output parameters. The same set of prerequisites applies to each example.
This chapter includes the following topics:
n

Prerequisites for Listing Provisioned Resources

n

Display Your Provisioned Resources Example

n
Display Provisioned Resources by Resource Type Example
n
Display All Available Resource Types Example
n
Display Provisioned Resources by Business Groups You Manage Example
n
View Machine Details Example
Prerequisites for Listing Provisioned Resources
Satisfy the following conditions before performing any tasks for this use case.
n
Log in to vRealize Automation as a business group manager.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Display Your Provisioned Resources Example
GET /api/consumer/resources/{id} displays a list of all the provisioned resources that you own.
VMware, Inc.
85
Programming Guide
curl Command
The following example displays all applicable provisioned resources.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resources/?page=1&limit=n&$orderby=name
JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ {
"@type" : "link",
"rel" : "next",
"href" : "https://vra152-009-067.mycompany.com/catalog-service/api/consumer/resources/?
page=2&limit=1"
} ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "c24e8c75-c201-489c-b51c-8d7009c23563",
"iconId" : "Travel_100.png",
"resourceTypeRef" : {
"id" : "com.mycompany.mystuff.samples.travel.packageType",
"label" : "Reservation"
},
"name" : "example",
"description" : "asd",
"status" : "ACTIVE",
"catalogResource" : {
"id" : "6fddafcd-bc3d-4753-8a2a-5fa3f78a5a90",
"label" : "example"
},
"requestId" : "55e7fcf3-4c77-4b11-a442-1f282333ac91",
"providerBinding" : {
"bindingId" : "1",
"providerRef" : {
"id" : "f60f5d1e-d6e9-4d98-9c48-f70a3e405346",
"label" : "travel-service"
}
},
}
Input
Use the supported input parameters to control the command output.
VMware, Inc. 86
Programming Guide
Parameter Description
URL https://$vRA/catalog-service/api/consumer/resources/
$vRA Specifies the appliance name and fully qualified domain name,
or IP address of the vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$page Specifies a page number.
$limit Specifies the number of entries to display on a page. Maximum
value is 5000. If not specified, defaults to 20.
For information regarding limits to the number of elements displayed, see Example: Retrieve 10,000 Resources Ordered
By Name.
$orderby Specifies how to order multiple comma-separated properties
sorted in ascending or descending order. Values include:
n
$orderby=id
n
$orderby=name
n
$orderby=dateCreated
n
$orderby=lastUpdated
n
$orderby=status
n
$orderby=description
$top Specifies the number of returned entries from the top of the
response (total number per page in relation to skip).
$skip Specifies the number of entries to skip.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
VMware, Inc. 87
Programming Guide
Property Description
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time price.
costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.
costToDate Displays an optional rate of the current price charges for the resource. This parameter is deprecated.
totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is deprecated.
expenseMonthToDate The expense of the resource from the beginning of the month to the current date. This value is updated
daily by vRealize Business for Cloud.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
Example: Retrieve 10,000 Resources Ordered By Name
Since the catalog service limits the number of elements that can be retrieved with a single API call to 5000, retrieving 10,000 resources requires two calls. The first call displays the first 5000 elements and the second call displays the second 5000 elements. You can make the two calls by specifying either the page and limit values or the skip and top values.
Specifying page and limit values, you make the following two calls.
curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"
-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?page=1&limit=5000&
$orderby=name"
curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"
-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?page=2&limit=5000&
$orderby=name"
Specifying skip and top values, you make the following two calls.
curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"
-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?$skip=0&$top=5000&
$orderby=name"
curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"
-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?$skip=5000&
$top=5000&$orderby=name"
If both page and limit values and skip and top values are specified, the skip and top values take priority.
VMware, Inc. 88
Programming Guide

Display Provisioned Resources by Resource Type Example

GET /api/consumer/resourcesTypes/{id} displays a list of the provisioned resources that you own filtered by machine resource type.
curl Command
The following example displays the provisioned resources by resource type.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$vRA/catalog-service/api/consumer/resourceTypes/Infrastructure.Machine/?page=1&limit=n&
$orderby=id
JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "3bfde906-81b9-44c3-8c2d-07d2c9768168",
"iconId" : "cafe_default_icon_genericCatalogResource",
"resourceTypeRef" : {
"id" : "Infrastructure.Virtual",
"label" : "Virtual Machine"
},
"name" : "test2",
"description" : null,
"status" : "ACTIVE",
"catalogResource" : {
"id" : "e2f397be-72ad-4ec4-a688-c017560fa1a3",
"label" : "test-blueprint"
},
"requestId" : "b013d2fa-4ba4-416c-b46b-98bb8cc7b076",
"providerBinding" : {
"bindingId" : "8a4581a0-84f9-4e80-9af6-75d79633e382",
"providerRef" : {
"id" : "6918cd49-b737-467f-94bf-d14d52c78fba",
"label" : "iaas-service"
}
},
"owners" : [ {
"tenantName" : "MYCOMPANY",
"ref" : "fritz@example.mycompany.com",
"type" : "USER",
"value" : "Fritz Arbeiter"
} ],
"organization" : {
"tenantRef" : "MYCOMPANY",
VMware, Inc. 89
Programming Guide
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
}
The output includes the following highlighted items:
n
Resource ID. 3bfde906-81b9-44c3-8c2d-07d2c9768168 corresponds to a provisioned machine owned by the logged-in user. The resource IDs are used in requests to retrieve the details for the corresponding machines.
n
subtenantRef ID. eab762cb-6e75-4379-83ef-171a71c9f00e corresponds to the business group of the logged-in user. If the user who is logged-in is also the manager of the business group, the subtenantRef ID is used to get resources from all business groups that the user manages.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/catalog-service/api/consumer/resourceTypes
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
page Specifies a page number.
limit Specifies the number of entries to display on a page. Maximum value is 5000. If not specified,
defaults to 20.
For information regarding limits to the number of elements displayed, see Example: Retrieve
10,000 Resources Ordered By Name.
$orderby Specifies how to order multiple comma-separated properties sorted in ascending or descending
order. Values include:
n
$orderby=id
n
$orderby=name
n
$orderby=dateCreated
n
$orderby=lastUpdated
n
$orderby=status
n
$orderby=description
top Specifies the number of returned entries from the top of the response (total number per page in
relation to skip).
skip Specifies the number of entries to skip.
Filter by the following resource types:
n
Infrastructure.Machine
n
Infrastructure.AppServic
VMware, Inc. 90
Programming Guide
n
Infrastructure.Cloud
n
Infrastructure.Physical
n
Infrastructure.vApp
n
Infrastructure.Virtual
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time price.
costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.
costToDate Displays an optional rate of the current price charges for the resource. This parameter is deprecated.
totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is deprecated.
expenseMonthToDate The expense of the resource from the beginning of the month to the current date. This value is updated
daily by vRealize Business for Cloud.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
VMware, Inc. 91
Programming Guide

Display All Available Resource Types Example

GET /api/consumer/resourcesTypes displays all the resource types that are available on the system.
curl Command
The following example displays all available resource types.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resourceTypes
JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ResourceType",
"id" : "Infrastructure.Machine",
"name" : "Machine",
"pluralizedName" : "Machines",
"description" : "The common parent type for all types of machines",
"primary" : true,
"schema" : {
"classId" : "Infrastructure.Machine.Schema",
"typeFilter" : null
},
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/catalog-service/api/consumer/resourceTypes
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
VMware, Inc. 92
Programming Guide
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time price.
costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.
costToDate Displays an optional rate of the current price charges for the resource. This parameter is deprecated.
totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is deprecated.
expenseMonthToDate The expense of the resource from the beginning of the month to the current date. This value is updated
daily by vRealize Business for Cloud.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
VMware, Inc. 93
Programming Guide
Example: curl Command
The following example command displays all available resource types.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resourceTypes
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ResourceType",
"id" : "Infrastructure.Machine",
"name" : "Machine",
"pluralizedName" : "Machines",
"description" : "The common parent type for all types of machines",
"primary" : true,
"schema" : {
"classId" : "Infrastructure.Machine.Schema",
"typeFilter" : null
},
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}

Display Provisioned Resources by Business Groups You Manage Example

GET /api/consumer/resources/types/{resourceTypeId} displays all of the provisioned resources that are owned by the business groups that you manage. You can optionally filter the list by business group name.
VMware, Inc. 94
Programming Guide
curl Command
The following example displays the provisioned resources of one or more business groups.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resources/types/Infrastructure.Machine/?page=1&limit=n&
$orderby=id desc&$filter=((organization/subTenant/id eq 'subtenantID_group1') or
(organization/subTenant/id eq ''subtenantID_group2') … )"
JSON Output
In the following command input, the subtenant IDs correspond to business groups that are managed by the user who is logged-in.
rest get catalog-service --u "consumer/resources/types/Infrastructure.Machine/?page=1&limit=2&
$orderby=dateCreated desc&$filter=((organization/subTenant/id eq
'eab762cb-6e75-4379-83ef-171a71c9f00e') or (organization/subTenant/id eq 'fa995528-e289-455e-a0e6-
c2da8b0e1bf9') or (organization/subTenant/id eq '699efe66-fe6e-4e34-96e8-52a34f338d20') or
(organization/subTenant/id eq '4d949784-e93e-4538-accb-6a0a464e4a4b'))"
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "3bfde906-81b9-44c3-8c2d-07d2c9768168",
"iconId" : "cafe_default_icon_genericCatalogResource",
"resourceTypeRef" : {
"id" : "Infrastructure.Virtual",
"label" : "Virtual Machine"
},
"name" : "test2",
"description" : null,
"status" : "ACTIVE",
"catalogResource" : {
"id" : "e2f397be-72ad-4ec4-a688-c017560fa1a3",
"label" : "test-blueprint"
},
"requestId" : "b013d2fa-4ba4-416c-b46b-98bb8cc7b076",
"providerBinding" : {
"bindingId" : "8a4581a0-84f9-4e80-9af6-75d79633e382",
"providerRef" : {
"id" : "6918cd49-b737-467f-94bf-d14d52c78fba",
"label" : "iaas-service"
}
},
"owners" : [ {
"tenantName" : "MYCOMPANY",
"ref" : "fritz@example.mycompany.com",
VMware, Inc. 95
Programming Guide
"type" : "USER",
"value" : "Fritz Arbeiter"
} ],
"organization" : {
"tenantRef" : "MYCOMPANY",
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
"dateCreated" : "2014-09-19T21:19:37.541Z",
"lastUpdated" : "2014-09-19T21:19:40.888Z",
"hasLease" : true,
"lease" : {
"start" : "2014-09-19T21:18:57.000Z"
},
"leaseForDisplay" : null,
"hasCosts" : true,
"costs" : {
"leaseRate" : {
"type" : "moneyTimeRate",
"cost" : {
"type" : "money",
"currencyCode" : "USD",
"amount" : 0.0
},
"basis" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 1
}
}
},
"costToDate" : {
"type" : "money",
"currencyCode" : "USD",
"amount" : 0.0
},
"totalCost" : null,
"childResources" : [ ],
"operations" : [ {
"name" : "Reprovision",
"description" : "Reprovision a machine.",
"iconId" : "machineReprovision.png",
"type" : "ACTION",
"id" : "a1caee9b-d67f-41e8-a7b3-131616a0f6ac",
"extensionId" : null,
"providerTypeId" : "com.mycompany.csp.iaas.blueprint.service",
"bindingId" : "Infrastructure.Machine.Action.Reprovision",
"hasForm" : false,
"formScale" : null
} ],
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
VMware, Inc. 96
Programming Guide
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}
},
"resourceData" : {
"entries" : [ {
"key" : "Expire",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineGroupName",
"value" : {
"type" : "string",
"value" : "MyTestAgentBusinessGroup"
}
}, {
"key" : "NETWORK_LIST",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ {
"type" : "complex",
"componentTypeId" : "com.mycompany.csp.component.iaas.proxy.provider",
"componentId" : null,
"classId" : "vra.api.model.NetworkViewModel",
"typeFilter" : null,
"values" : {
"entries" : [ {
"key" : "NETWORK_MAC_ADDRESS",
"value" : {
"type" : "string",
"value" : "56:52:4d:e7:46:d4"
}
}, {
"key" : "NETWORK_NAME",
"value" : {
"type" : "string",
"value" : "Test Agent-network-1"
}
} ]
}
} ]
}
}, {
"key" : "SNAPSHOT_LIST",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ ]
}
}, {
"key" : "ConnectViaRdp",
"value" : {
VMware, Inc. 97
Programming Guide
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStatus",
"value" : {
"type" : "string",
"value" : "On"
}
}, {
"key" : "PowerOff",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "DISK_VOLUMES",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ {
"type" : "complex",
"componentTypeId" : "com.mycompany.csp.component.iaas.proxy.provider",
"componentId" : null,
"classId" : "vra.api.model.DiskInputModel",
"typeFilter" : null,
"values" : {
"entries" : [ {
"key" : "DISK_CAPACITY",
"value" : {
"type" : "integer",
"value" : 1
}
}, {
"key" : "DISK_DRIVE",
"value" : {
"type" : "string",
"value" : "c"
}
}, {
"key" : "DISK_INPUT_ID",
"value" : {
"type" : "string",
"value" : "DISK_INPUT_ID1"
}
} ]
}
} ]
}
}, {
"key" : "MachineBlueprintName",
"value" : {
"type" : "string",
"value" : "test-blueprint"
}
VMware, Inc. 98
Programming Guide
}, {
"key" : "Suspend",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reboot",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reprovision",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStorage",
"value" : {
"type" : "integer",
"value" : 1
}
}, {
"key" : "MachineDailyCost",
"value" : {
"type" : "decimal",
"value" : 0.0
}
}, {
"key" : "Destroy",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineType",
"value" : {
"type" : "string",
"value" : "Virtual"
}
}, {
"key" : "InstallTools",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Shutdown",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
VMware, Inc. 99
Programming Guide
"key" : "ChangeLease",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "machineId",
"value" : {
"type" : "string",
"value" : "8a4581a0-84f9-4e80-9af6-75d79633e382"
}
}, {
"key" : "MachineMemory",
"value" : {
"type" : "integer",
"value" : 0
}
}, {
"key" : "MachineGuestOperatingSystem"
}, {
"key" : "MachineName",
"value" : {
"type" : "string",
"value" : "test2"
}
}, {
"key" : "MachineDestructionDate"
}, {
"key" : "MachineCPU",
"value" : {
"type" : "integer",
"value" : 1
}
}, {
"key" : "MachineInterfaceType",
"value" : {
"type" : "string",
"value" : "Test"
}
}, {
"key" : "MachineReservationName",
"value" : {
"type" : "string",
"value" : "Test Agent-Res-1"
}
}, {
"key" : "Reconfigure",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "EXTERNAL_REFERENCE_ID"
}, {
"key" : "MachineExpirationDate"
VMware, Inc. 100
Loading...