VMware vRealize Automation - 7.2 Programming Guide

Programming Guide
vRealize Automation 7.2
This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
EN-002326-00
Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
hp://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2008–2016 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

Contents

vRealize Automation Programming Guide 5
Overview of the vRealize Automation REST API 7
1
REST API Authentication 9
2
Using HTTP Bearer Tokens 9
Congure the Duration of an HTTP Bearer Token 9
Request an HTTP Bearer Token 10
Validate an HTTP Bearer Token 12
Delete an HTTP Bearer Token 13
REST API Use Cases 15
3
Create a Tenant 16
Syntax for Displaying Your Current Tenants 18
Syntax for Requesting a New Tenant 20
Syntax for Listing All Tenant Identity Stores 23
Syntax for Linking an Identity Store to the Tenant 25
Syntax for Searching LDAP or Active Directory for a User 29
Syntax for Assigning a User to a Role 30
Syntax for Displaying all Roles Assigned to a User 31
Request a Machine 33
Syntax for Listing Shared and Private Catalog Items 35
Syntax for Geing Information for a Catalog Item 38
Syntax for Geing a Template Request for a Catalog Item 41
Syntax for Requesting a Machine 44
Syntax for Viewing Details of a Machine Request 47
Approve a Machine Request 50
Syntax for Listing Work Items 51
Syntax for Geing Work Item Details 57
Syntax for Constructing a JSON File to Approve a Machine Request 62
Syntax for Approving a Submied Machine Request 65
Syntax for Updating Cost Information 67
List Provisioned Resources 69
Syntax for Displaying Your Provisioned Resources 70
Syntax for Displaying Provisioned Resources by Resource Type 72
Syntax for Displaying All Available Resource Types 75
Syntax for Displaying Provisioned Resources by Business Groups You Manage 76
Syntax for Viewing Machine Details 84
Manage Provisioned Deployments 87
Syntax for Geing Deployment Details 89
Syntax for Navigating to the Children of a Deployed Resource 92
VMware, Inc.
3
Programming Guide
Working with Reservations 101
Working with Reservation Policies 265
Working with Key Pairs 274
Working with Network Proles 287
Get a List of Available IP Ranges for an IPAM Provider 316
Import and Export Content 334
Perform a Day 2 Action: Power O 98
Perform a Day 2 Action: Change Lease 100
Create a Reservation 101
Display a List of Reservations 244
Update a Reservation 254
Delete a Reservation 264
List Reservation Policies 265
Create a Reservation Policy 268
Display a Reservation Policy by ID 270
Update a Reservation Policy 271
Delete a Reservation Policy 273
Get a Key Pair List 274
Create a Key Pair 279
Query a Key Pair 281
Update a Key Pair 283
Delete a Key Pair 285
Get a Network Prole List 287
Create a Network Prole 303
Query a Network Prole 307
Update a Network Prole 313
Delete a Network Prole 315
Syntax for Listing Supported Content Types 335
Syntax for Listing Available Content 339
Syntax for Filtering Content by Content Type 342
Syntax for Creating a Package for Export 343
Syntax for Listing Packages in the Content Service 345
Syntax for Exporting a Package 347
Syntax for Validating a Content Bundle Before Importing 348
Syntax for Importing a Package 350
Understanding Blueprint Schema 351
Manage XaaS Content with Import and Export 353
Related Tools and Documentation 357
4
Using the vRealize Automation API Reference 357
View Reference Information for an API 358
Using vRealize CloudClient 358
Using Third Party Tools 358
Filtering and Formaing REST API
5
Information 361
Index 363
4 VMware, Inc.

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 congure and manage vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on common use cases. For related information about all available REST API services, see in vRealize Automation API Reference at hps://www.vmware.com/support/pubs/vcac-pubs.html.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For denitions of terms as they are used in VMware technical documentation, go to
hps://www.vmware.com/support/pubs/vcac-pubs.html.
VMware, Inc.
5
Programming Guide
Overview of the vRealize Automation
REST API 1
The vRealize Automation REST API provides consumer, administrator, and provider-level access to the service catalog with the same services that support the vRealize Automation console user interface. You can perform vRealize Automation functions programmatically by using REST API service calls.
The vRealize Automation REST API oers 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 Conguration Service Create, read, update and delete endpoint types, endpoint
categories, and endpoints.
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.
VMware, Inc. 7
Programming Guide
Table 11. vRealize Automation REST API Services (Continued)
Service Description
IP Address Management Service Allocate and deallocate IP addresses from IP address management
Licensing Service Retrieve permissions and post serial keys.
Management Service (Reclamation Service) Retrieve work item forms, callbacks, and tasks. Manage endpoint
Network Service Access and manage application network and security seings for
Notication Service Congure and send notications for several types of events such as
Orchestration Gateway Service Provides a gateway to VMware Realize Orchestrator (vRO) for
Extensibility (Plug-in) Service Retrieve, create, update, and delete a resource. Retrieve an
Portal Service Retrieve, create, update, and delete a portal resource.
Properties Service Manage custom properties, property groups, and property
Reservation Service Retrieve, create, update, and delete a reservation or reservation
Software Services Triggers the execution life cycle of software components using the
vRA Orchestrator Service Manage vRealize Orchestrator actions, tasks, packages, and
Work Item Service Retrieve, create, update, complete, cancel, and delete a work item.
XaaS Service Manages XaaS elements such as forms, endpoints, XaaS blueprints,
(IPAM) providers.
details including tenant, password, user name, and endpoint URL. Retrieve performance metrics. Retrieve and cancel reclamation requests.
creating and conguring NAT and routed networks; creating load balancers; and adding and conguring security groups, security tags and security policies for application components.
the successful completion of a catalog request or a required approval.
services running on vRealize Automation. By using the gateway, consumers of the API can access a vRO instance, and initiate workows or script actions without having to deal directly with the vRO APIs.
extension. Retrieve license notications.
denitions. Properties specify items that can be added to blueprints to trigger vRealize Orchestrator actions.
policy.
software agent, registers software agents, and manages the creation, modication and deletion of software componentsoftware component types, software resource requests, and nodes (machines).
workows. Browse system and plug-in inventories.
Also retrieve form data, metadata, detail forms, and submission forms from service providers.
tenants, vRealize Orchestrator imports, workows, and work items.
The advanced designer service selection on the vRealize Automation API Reference landing page selects the documentation for the XaaS service.
When a service request contains a resource URL, the rst part of the URL identies the service and the last part identies the resource. For example, the following resource URL identies the catalog service and the providers resource:
https://$host/component-registry/api/services
For more information about all the vRealize Automation REST API service calls, see “Using the vRealize
Automation API Reference,” on page 357 and the vRealize Automation API Reference in your
vRealize Automation installation.
8 VMware, Inc.

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 congure the token with a dierent duration.

Using HTTP Bearer Tokens

You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You create a request header with the curl command or with some other utility.
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 calls:
https://$vra_server/identity/api/tokens

Configure the Duration of an HTTP Bearer Token

You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties le on the vRealize Automation appliance.
The eective 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 congured duration, or at the end of the congured duration of the SAML token, whichever comes rst. For example, if the congured 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 conguration seing on the SSO server determines the duration of SAML tokens.
VMware, Inc.
9
Programming Guide
Prerequisites
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specied
n
when you deployed the appliance.
The /etc/vcac/security.properties le on the appliance must be editable.
n
Procedure
1 Open the /etc/vcac/security.properties le for editing.
2 Add the following lines to the le, 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 le.
4 Log out of the vRealize Automation appliance.
The new value applies the next time someone requests an HTTP bearer token.

Request an HTTP Bearer Token

You use an HTTP bearer token to authenticate a vRealize Automation REST API consumer request .
A consumer request must specify the correct component registry service and resource. For example, the URL to obtain an HTTP bearer token must specify the identity service and token resource.
The HTTP bearer token expires in 24 hours by default. See “Congure the Duration of an HTTP Bearer
Token,” on page 9 for information on how to set the duration.
For related information, see “Syntax for Requesting an HTTP Bearer Token,” on page 11.
Prerequisites
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a role,
n
log in as a tenant administrator.
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Procedure
Enter a curl command in the following format, replacing the variables with the correct values.
u
The variable $vRA used in this example represents the host name.domain name of the vRealize Automation server, for example, mycompany.mktg.mydomain.com.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}'
https://$vRA/identities/api/tokens
For example, enter the following command line:
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"TenantAdminUser @example.com","password":"password","tenant":"MYCOMPANY"}'
https://vra.mycompany.com/identities/api/tokens
The command returns a response header with a status code and, if your request is successful, an HTTP bearer token.
10 VMware, Inc.
Chapter 2 REST API Authentication
For example, the following sample output displays based on the command input:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Thur, 16 Jul 2015 23:59:59 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 324
Date: Wed, 15 Jul 2015 13:04:50 GMT
{
"expires":"2015-16-01T13:09:45.619Z",
"id":"MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLmNvb
TplMDViNGU0NGM2ZWU0MWQ1OWEwMTNmZGExNTQwZjNlNGM3YTBlM2I5MDhlYWZjYjY1ZjhiODI2OTg4ODU3M2UwOTUwOWRk
MjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==",
"tenant":"MYCOMPANY"
}
What to do next
Include the HTTP bearer token in your REST API service calls. You can store the token in a variable such as $AUTH and then use the variable in your requests.
Syntax for Requesting an HTTP Bearer Token
An HTTP bearer token is required by the REST client to use the vRealize Automation REST API. You can obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
A consumer request must specify the correct component registry service and resource. For example, the URL to obtain an HTTP bearer token must contain the identity service and token resource values.
Input Description
host host name.domain name of the vRealize Automation server, for example,
mycompany.mktg.mydomain.com.
usrname Species the tenant administrator user name.
passwd Species the tenant administrator password.
tenantURLtoken Species the tenant URL token determined by the system administrator when
creating the tenant, for example, support.
Output
The following information is displayed as a result of your HTTP bearer token request.
Output Description
expires Contains the ISO 8601 timestamp indicating when the token expires.
id Contains the HTTP bearer token to use in Authorization header in subsequent
requests.
tenant Displays the tenant ID associated with the token.
Response Status Codes
One of the following codes are displayed as a result of your HTTP bearer token request.
Programming Guide
Status Code Description
200 OK Your request succeeded and the resource was updated. The
400 BAD REQUEST The data you provided in the POST failed validation.
401 UNAUTHORIZED The request could not authenticate the user or
Example: curl Command
You can enter the following command line format to request an HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"usrname",
"password":"passwd","tenant":"tenantURLtoken"}' https://$host/identity/api/tokens
When your request succeeds, the system returns the 200 OK status code, the expiration date and time of the token, and the HTTP bearer token. After receiving the bearer token, you can include it in your request headers.

Validate an HTTP Bearer Token

response body contains the full representation of the resource.
Inspect the response body for details.
authentication credentials required.
You can validate an existing HTTP bearer token.
Prerequisites
“Request an HTTP Bearer Token,” on page 10.
n
Procedure
Create the request to validate the HTTP bearer token, as in the following example.
u
HEAD
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OT
g4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA
==
Accept: application/json
The system returns one of the following status codes.
Status Code Description
204 NO CONTENT The request succeeded.
401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must
be authenticated.
403 FORBIDDEN Your authentication credentials do not provide sucient access to the resource.
404 NOT FOUND Could not locate the resource based on the specied 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.
12 VMware, Inc.
Chapter 2 REST API Authentication

Delete an HTTP Bearer Token

You can delete an HTTP bearer token.
Prerequisites
“Request an HTTP Bearer Token,” on page 10.
n
Procedure
Create the request to delete the HTTP bearer token, as in the following example.
u
DELETE
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OT
g4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA
==
Accept: application/json
The system returns one of the following status codes.
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 sucient access to the resource.
404 NOT FOUND Could not locate the resource based on the specied URI.
405 METHOD NOT ALLOWED The DELETE method is not supported for the resource.
500 SERVER ERROR Could not create or update the resource because of an internal server error.
VMware, Inc. 13
Programming Guide
14 VMware, Inc.

REST API Use Cases 3

Available use cases provide the prerequisite, command line options and format, and sample results to help you perform a variety of vRealize Automation functions, such as requesting a machine or creating a reservation.
You can nd information about all of the available vRealize Automation REST API calls in the vRealize Automation API Reference zip le located in the vRealize Automation Documentation Center. The use cases provide samples of calls that you might commonly use and descriptions of example inputs and outputs relative to those calls.
Create a Tenant on page 16
n
You can use the REST API identity service to create a vRealize Automation tenant and perform related functions. Perform the tasks required to create a tenant with the REST API in sequence. For information about creating and working with tenants and roles by using thevRealize Automation application user interface, see the Tenant Administration and IaaS Conguration documentation.
Request a Machine on page 33
n
You can use REST API catalog service commands to complete a variety of tasks related to requesting a machine. This procedure provides sample command line syntax for machine request tasks. Supporting information regarding available input and output parameters, command-line entry samples, and sample JSON output samples is available in the subsequent topics that explain syntax for the various tasks.
VMware, Inc.
Approve a Machine Request on page 50
n
You can use a sequence of REST API workitem service commands to approve a machine request.
List Provisioned Resources on page 69
n
You can use the REST API catalog service to log in to vRealize Automation and display a full or ltered list of your provisioned resources .
Manage Provisioned Deployments on page 87
n
You can use the REST API catalog service to log in to vRealize Automation and view information about provisioned resources .
Working with Reservations on page 101
n
You can work with the REST API reservation service to perform a variety of functions, such as creating and updating reservations.
Working with Reservation Policies on page 265
n
You can use the vRealize Automation REST API to work with the reservation service to perform a variety of functions, such as creating and updating reservation policies.
15
Programming Guide
Working with Key Pairs on page 274
n
You can work with the keyValuePair data element of the REST API workitem service to list, create, and update key pairs.
Working with Network Proles on page 287
n
You can use the vRealize Automation IaaS proxy provider service and IPAM service REST API to create, list, and update network proles.
Get a List of Available IP Ranges for an IPAM Provider on page 316
n
You can query a specied IPAM provider endpoint for a list of the available IP address ranges congured on the IPAM provider device.
Import and Export Content on page 334
n
You can use the REST API content management service to import and export content, such as blueprints, between vRealize Automation systems.

Create a Tenant

You can use the REST API identity service to create a vRealize Automation tenant and perform related functions. Perform the tasks required to create a tenant with the REST API in sequence. For information about creating and working with tenants and roles by using thevRealize Automation application user interface, see the Tenant Administration and IaaS Conguration documentation.
Prerequisites
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity
n
server.
Verify that the identity server details required for the JSON template are available.
n
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2,
n
“REST API Authentication,” on page 9.
Syntax for Displaying Your Current Tenants on page 18
n
You can use the REST API identity service to list of all the vRealize Automation tenants in your system.
Syntax for Requesting a New Tenant on page 20
n
You can use the REST API identity service to submit a request for a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON le from the command line.
Syntax for Listing All Tenant Identity Stores on page 23
n
You can use the REST API identity service to list all available identity stores for a named vRealize Automation tenant, such as the default tenant vsphere.local.
Syntax for Linking an Identity Store to the Tenant on page 25
n
You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory identity store to the vRealize Automation tenant.
Syntax for Searching LDAP or Active Directory for a User on page 29
n
You can use the vRealize Automation REST API identity service to search the congured LDAP directory, Active Directory, or Native Active Directory for a user.
Chapter 3 REST API Use Cases
Syntax for Assigning a User to a Role on page 30
n
You can use the REST API identity service to assign a user to a role.
Syntax for Displaying all Roles Assigned to a User on page 31
n
You can use the REST API identity service to display all of the roles assigned to a user.
Procedure
1 Use the identity service to display all the available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
2 Submit a request for a new tenant and either call a JSON le that contains tenant request parameters or
specify those parameters using inline text. The rst example uses a JSON le as input. The second example uses inline text as input.
The rst example calls the following sample newTenant.json le.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Examples Command
Example 1
Call the above newTenant.json file, which contains parameters for the tenant request.
Example 2
Specify the parameters for the tenant request by using inline text.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token" https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json
curl --insecure -H "Accept: application/json" -H "Content­Type: application/json"
-H "Authorization: Bearer $token"
--data '{"@type":"Tenant","id":"development","urlName":"developmen t","name": "DevelopmentTenant","description":"Tenant for all developers","contactEmail": "admin@mycompany.com","defaultTenant":false}'
3 List all available identity stores for a named tenant, such as the default tenant vsphere.local by using
variables, instead of the full token and host name.domain name.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories
4 Link an LDAP, Active Directory, or Native Active Directory identity store to the tenant by using the
identity service.
Call the following sample ldap.json.txt input le from the command line to specify necessary parameters.
{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
VMware, Inc. 17
Programming Guide
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}
Use the following command to call the example JSON text le and link an identity store to a tenant. The command also tests that vRealize Automation can connect to the identity store successfully. If the command nishes successfully, vRealize Automation succeeded in connecting to the identity store.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
5 Query the congured LDAP directory, Active Directory, or Native Active Directory for a specic user.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/$tenantId/principals/$userId
6 Assign a user to a role with the REST API identity service.
Use the following command string to submit a request to assign the user tony in the domain example.mycompany.com to the tenant administrator role. It provides empty braces for the required JSON payload.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
"https://$host/identity/api/authorization/tenants/development/principals/
susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"
7 Display all of the roles assigned to a user with the identity service.
Use the following command to list all the roles that are assigned to tony@example.mycompany.com.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/authorization/tenants/development/principals/
tony@example.mycompany.com/roles
What to do next

Syntax for Displaying Your Current Tenants

You can use the REST API identity service to list of all the vRealize Automation tenants in your system.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/tenants
$host Species the host name and fully qualied domain name or IP address
of the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
18 VMware, Inc.
Chapter 3 REST API Use Cases
Output
The command output contains property names and values based on the command input parameters.
Parameter Description
Links Species an array of link objects, each of which contains the
following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
Content Species 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:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default tenant (vsphere.local).
Metadata Species the following paging-related data:
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
VMware, Inc. 19
Programming Guide
Example: curl Command
The following example command displays all available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
Format the XML output to improve its readability. For information about formaing output, see Chapter 5,
“Filtering and Formaing REST API Information,” on page 361.
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "Tenant",
"id" : "vsphere.local",
"urlName" : "vsphere.local",
"name" : "vsphere.local",
"description" : null,
"contactEmail" : null,
"password" : null,
"defaultTenant" : true
}, {
"@type" : "Tenant",
"id" : "MYCOMPANY",
"urlName" : "MYCOMPANY",
"name" : "QETenant",
"description" : "Test tenant",
"contactEmail" : null,
"password" : "defaultPwd#1",
"defaultTenant" : false
} ],
"metadata" : {
"size" : 19,
"totalElements" : 2,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}

Syntax for Requesting a New Tenant

You can use the REST API identity service to submit a request for a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON le from the command line.
Input
Use the supported input parameters to control the command output.
20 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId --data @
$inputFileName.json
$token Species a valid HTTP bearer token with necessary credentials.
$host Species the host name and fully qualied domain name or IP
address of the vRealize Automation identity server.
$tenantId Species the ID of the tenant.
$tenantURL Species the URL of the tenant.
$tenantName Species the name of the tenant.
$description Species a description of the tenant.
$emailAddress Species the contact email address for the tenant.
JSON Input File Template
To simplify command line input, create a JSON le and call that le from the command line. To create a JSON le, copy the following template to a new text le. To maintain formaing, use an XML editor. Replace the italicized variables in the template with your specic values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
Parameter Description
Links Species an array of link objects, each of which contains the
Content Species an array of data rows, each of which represents
Metadata Species the following paging-related data:
following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
one of the tenant objects returned in a pageable list. Each tenant object can contain the following information:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default tenant (vsphere.local).
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example: curl Command
Submit a request for a new tenant and either call a JSON le that contains tenant request parameters or specify those parameters using inline text. The rst example uses a JSON le as input. The second example uses inline text as input.
Chapter 3 REST API Use Cases
The rst example calls the following sample newTenant.json le.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Example 1: Use the following example to call the above newTenant.json le, which contains parameters for the tenant request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json
Example 2: Use the following example to specify parameters for the tenant request by using inline text.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
--data '{"@type":"Tenant","id":"development","urlName":"development","name":
"DevelopmentTenant","description":"Tenant for all developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'

Syntax for Listing All Tenant Identity Stores

You can use the REST API identity service to list all available identity stores for a named vRealize Automation tenant, such as the default tenant vsphere.local.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId/directories
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 23
Programming Guide
Parameter Description
Links Species an array of link objects, each of which contains the
Content Species an array of data rows, each of which represents
Metadata Species the following paging-related data:
following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
one of the tenant objects returned in a pageable list. Each tenant object can contain the following information:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default tenant (vsphere.local).
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example: curl Command
The following example command lists the identity stores by using variables, instead of the full token and host name.domain name.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories
24 VMware, Inc.
Chapter 3 REST API Use Cases
Example: JSON Output
The following JSON output is returned based on the command input.
HTTP/1.1 200 OK
Server: Apache-Beach/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Wed, 31 Dec 1969 23:59:59 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 830
Date: Sat, 01 Feb 2014 13:07:54 GMT
{"links":[],
"content":[
{"@type":"IdentityStore",
"domain":"vcac.mycompany.com",
"name":"openLDAPPromocom",
"description":null,
"alias":"promocom.com",
"type":"LDAP",
"userNameDn":"cn=promocomadmin,ou=promocom,dc=vcac,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com"
},
{"@type":"IdentityStore",
"domain":"example.mycompany.com",
"name":"openLDAPDemo",
"description":null,
"alias":"example.com",
"type":"LDAP",
"userNameDn":"cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com"
}],
"metadata":{
"size":20,
"totalElements":2,
"totalPages":1,
"number":1,
"offset":0
}
}

Syntax for Linking an Identity Store to the Tenant

You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory identity store to the vRealize Automation tenant.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 25
Programming Guide
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId/directories/$domainName --data
$host Species the host name and fully qualied domain name or IP address of
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
userId Species the ID of the user in the form name@domain.
$domainAlias Species the domain alias.
$domainName Species the domain of the identity store.
$grpBaseSearchDn Species the group search base Distinguished Name.
$identityStoreName Species a description of the new tenant.
$password Species the password.
$identityStoreType Species the identity store type for the tenant. The following values are
$identityServerUrl Species the URL of the identity server.
$usrBaseSearchDn Species the user search base Distinguished Name.
$usrNameDn Species the Distinguished Name for the login user.
@$inputFileName.json
the vRealize Automation identity server.
supported:
LDAP
n
AD
n
NATIVE_AD
n
JSON Input File Template
Use this template to create a JSON input le. Replace the variables in the template with actual values in the le.
{
"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.
26 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
Links Species an array of link objects, each of which contains the
following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
Content Species 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:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default tenant (vsphere.local).
Metadata Species the following paging-related data:
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example JSON Input File
Call the following sample ldap.json.txt input le from the command line to specify necessary parameters.
{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
VMware, Inc. 27
Programming Guide
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}
Example: curl Command
The following example command calls the example JSON text le and links an identity store to a tenant. The command also tests that vRealize Automation can connect to the identity store successfully. If the command nishes successfully,vRealize Automation succeeded in connecting to the identity store.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$host/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
Example: JSON Output
This output indicates that an identity store is successfully linked to the specied 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
Chapter 3 REST API Use Cases
Keep-Alive = timeout=15, max=100
Connection = Keep-Alive
}
Successful
Unlinked Identity Store Error
The following output indicates that an identity store is not linked to the specied tenant. To resolve the problem, correct the identity store and connection details in the JSON input le and rerun the command.
Command failed [Rest Error]: {Status code: 400}, {Error code: 90027} , {Error
Source: null}, {Error Msg: Cannot connect to the directory service.}, {System
Msg: 90027-Connection to directory service can’t be established}

Syntax for Searching LDAP or Active Directory for a User

You can use the vRealize Automation REST API identity service to search the congured 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 hps://$host/identity/api/tenants/$tenantId/principals/$userId
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
$userId Species the ID of the user in the form name@domain.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines the other names.
n
href
n
Species the URL that produces the result.
@type Species the user name.
rstName Species the rst name of the user.
lastName Species the last name of the user.
description Species the description of the user.
emailAddress Species the email address of the user.
locked Species the Boolean ag indicating if the user is locked out.
VMware, Inc. 29
Programming Guide
Property Description
disabled Species the Boolean ag indicating if the user is disabled.
principalId Species the principal ID of the user in username@domain format.
tenantName Species the name of tenant to which user belongs.
name Species the rst and last name concatenated.
Example: curl Command
The following example command queries the congured LDAP directory for a specic user.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/$tenantId/principals/$userId
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "User",
"firstName" : "Tony",
"lastName" : "Anteater",
"emailAddress" : "tony@example.mycompany.com",
"locked" : false,
"disabled" : false,
"principalId" : {
"domain" : "example.mycompany.com",
"name" : "susan"
},
"tenantName" : "MYCOMPANY1",
"name" : "Tony Anteater"
} ]
}

Syntax for Assigning a User to a Role

You can use the REST API identity service to assign a user to a role.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/authorization/tenants/$tenantId/principals/$princi
palId/roles/roleId
$host Species the host name and fully qualied domain name or IP address of
the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
$principalId Species the ID of the user in name@domain format.
$roleId Species the ID of the user role.
30 VMware, Inc.
Chapter 3 REST API Use Cases
Example: curl Command
The following example command string submits a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the required JSON
payload. See “Syntax for Searching LDAP or Active Directory for a User,” on page 29 for more information about geing the user name and domain values.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
"https://$host/identity/api/authorization/tenants/development/principals/
susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"
Example: JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status statement.

Syntax for Displaying all Roles Assigned to a User

You can use the REST API identity service to display all of the roles assigned to a user.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/authorization/tenants/$tenantId/principals/$princi
palId/roles
$token Species a valid HTTP bearer token with necessary credentials.
$host Species the host name and fully qualied domain name or IP address of
the vRealize Automation identity server.
$tenantId Species the ID of the tenant.
principalId Species the ID of the user in the form name@domain.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Species the role ID.
name Species the role name.
description Species the role description.
status Species the status of this role.
assignedPermissions Species the set of permissions that are implied by this role assignment.
Example: curl Command
The following example command lists all the roles that are assigned to tony@example.mycompany.com.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/authorization/tenants/development/principals/
tony@example.mycompany.com/roles
Programming Guide
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "SystemRole",
"id" : "ABX_TENANT_ADMIN",
"name" : "Tenant Administrator",
"description" : "ABX Tenant Administrator",
"assignedPermissions" : [ {
"id" : "CATALOG_CONSUME_TENANT_MGMT",
"name" : "Catalog Consume Tenant Management",
"description" : "Consume services, resources and manage requests on
behalf of any user within a Tenant",
"prereqAdminPermissions" : null
}, {
"id" : "MY_TENANT_MANAGEMENT",
"name" : "My Tenant Management",
"description" : "Manage my tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "CATALOG_AUTHOR_TENANT",
"name" : "Catalog Tenant-level Author",
"description" : "Create, update and publish services, catalog items and actions shared across a
Tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "GUI_MY_TENANT_MANAGEMENT",
"name" : "My Tenant Administration User Interface",
"description" : "Access my tenant administration GUI.",
"prereqAdminPermissions" : null
}, {
"id" : "CATALOG_ENTITLE_TENANT",
"name" : "Catalog Tenant-level Entitlement Management",
"description" : "Entitle services, catalog items and actions to all users within a tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "FILE_EDIT_TENANT",
"name" : "Manage Tenant Files",
"description" : "Upload and delete files belonging to this tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "TENANT_USER_DATA_MANAGEMENT",
"name" : "Manage user data (requests, items, tasks etc) within a tenant.",
"description" : "Manage user created objects belonging to the tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "TENANT_ADMIN_ROLE_ASSIGNMENT",
"name" : "Tenant Administrator Role Assignment",
"description" : "Assign the tenant administrator role to other users.",
"prereqAdminPermissions" : null
}, {
"id" : "GUI_MY_TENANT_TUG_MANAGEMENT",
32 VMware, Inc.
"name" : "My Tenant Identity Stores, Groups and Users Administration User Interfaces",
"description" : "Access my tenant identity stores, groups and users administration GUIs.",
"prereqAdminPermissions" : null
} ]
} ],
"metadata" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0

Request a Machine

You can use REST API catalog service commands to complete a variety of tasks related to requesting a machine. This procedure provides sample command line syntax for machine request tasks. Supporting information regarding available input and output parameters, command-line entry samples, and sample JSON output samples is available in the subsequent topics that explain syntax for the various tasks.
The REST API catalog service includes Hypermedia as the Engine of Application State (HATEOAS) links that function as templates to assist users in completing common tasks that are supported by the API. They typical scenario for using a template is for the user to submit a template request for a given context.
Chapter 3 REST API Use Cases
For example, catalog-service/api/consumer/entitledCatalogItems/ dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests/template. Users can employ the returned template, either as is or modied, to create
an appropriate request. The user then POSTs, or PUTs, the request to the target API. For example, catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests.
This procedure provides sample command line syntax for approving a machine request. Supporting information regarding available input and output parameters, command-line entry samples, and sample JSON output samples is available.
Prerequisites
Log in to vRealize Automation as a consumer and current business group user.
n
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2,
n
“REST API Authentication,” on page 9.
Syntax for Listing Shared and Private Catalog Items on page 35
n
You can use the REST API catalog service to retrieve a list of all shared viewable catalog items for the current user. Shared catalog items do not belong to a specic business group. Also, this service retrieves a list of all shared and private catalog items that can be viewed, including their business groups.
Syntax for Geing Information for a Catalog Item on page 38
n
You can use the REST API catalog service to get information about a specic catalog item if desired.
Syntax for Geing a Template Request for a Catalog Item on page 41
n
You can use the REST API catalog service to request catalog items. VMware supplies a number of templates to help you create dierent types of machine requests.
Syntax for Requesting a Machine on page 44
n
You can use the REST API catalog service to submit a machine request.
VMware, Inc. 33
Programming Guide
Syntax for Viewing Details of a Machine Request on page 47
n
You can use the vRealize Automation REST API catalog service to view the details of a machine request.
Procedure
1 List all shared catalog items in the catalog.
You can browse the API and use HATEOAS links to navigate to additional API calls that are relevant to the current context.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItemViews
Accept: application/json
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$host/catalog-service/api/consumer/entitledCatalogItems
Alternatively, you can also search for a catalog item by name by substituting $catalogItemName with
$catalogItemId.
2 Locate the details of a specic catalog item by name.
Note that the vRealize Automation API supports OData ltering.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItemViews?$filter=name+eq+%27$catalogItemName%27
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token
https://$host/catalog-service/api/consumer/entitledCatalogItems
3 Get a template request for a catalog item.
This request uses a HATEOAS link for a template request for this catalog item.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token
https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests/template
Accept: application/json
4 Review and edit the template request.
The template request returned in preceding step is specic to the catalog item that corresponds to your template request. The elds and default values are populated based on the conguration of the underlying blueprint.
Review the contents of the template and edit the values if you want to change them from the default prior to submiing the request. For example, you can specify a value for the description eld or change the values for the machine resources if the blueprint allows for a range.
5 Submit the request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests --verbose --data
@C:/Temp/requestMachine.json
{
$contentsOfTemplateFromPrecedingSections
}
34 VMware, Inc.
Chapter 3 REST API Use Cases
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.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b
Accept: application/json
The status information is particularly noteworthy in the request details. The phase eld corresponds to the status that is displayed in the Requests tab in the user interface.

Syntax for Listing Shared and Private Catalog Items

You can use the REST API catalog service to retrieve a list of all shared viewable catalog items for the current user. Shared catalog items do not belong to a specic business group. Also, this service retrieves a list of all shared and private catalog items that can be viewed, including their business groups.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/catalogItems
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species 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:
name - lter based on catalog item name.
n
status - lter based on catalog item status.
n
service/id - lter based on catalog item service id.
n
service/name - lter based on catalog item service name.
n
organization/subTenant/id - lter based on catalog item business group ID, which
n
you can nd in the catalogItem payload under organization > subtenantRef
organization/subTenant/name - lter based on catalog item business group name,
n
which you can nd in catalogItem payload under organization >subtenantLabel
outputResourceType/id - lter based on catalog item output resource type ID, for
n
example : Infrastructure.Virtual
outputResourceType/name - Filter based on catalog item output resource type
n
name, for example: "VirtualMavhine".
catalogItemType/id - lter based on catalog item type ID, for example:
n
"Infrastructure.Virtual".
catalogItemType/name - lter based on catalog item type name, for example:
n
"VirtualMachine".
icon/id - lter based on catalog item icon ID.
n
$top Sets the number of returned entries from the top of the response
$skip Sets the number of entries to skip.
VMware, Inc. 35
Programming Guide
Parameter Description
$lter Boolean expression for whether a particular entry should be included in the response.
serviceId (Optional) Query parameter to lter the returned catalog items by one specic service.
onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a
Valid OData properties include the following:
name - lter based on catalog item name.
n
status - lter based on catalog item status.
n
service/id - lter based on catalog item service id.
n
service/name - lter based on catalog item service name.
n
organization/subTenant/id - lter based on catalog item business group ID, which
n
you can nd in the catalogItem payload under organization > subtenantRef
organization/subTenant/name - lter based on catalog item business group name,
n
which you can nd in catalogItem payload under organization >subtenantLabel
outputResourceType/id - lter based on catalog item output resource type ID, for
n
example : Infrastructure.Virtual
outputResourceType/name - Filter based on catalog item output resource type
n
name, for example: "VirtualMavhine".
catalogItemType/id - lter based on catalog item type ID, for example:
n
"Infrastructure.Virtual".
catalogItemType/name - lter based on catalog item type name, for example:
n
"VirtualMachine".
icon/id - lter based on catalog item icon ID.
n
request on behalf of another user.
Output
The command output contains property names and values based on the command input parameters.
Property Description
outputResourceTypeRef Species the type of the resource that results from requesting the catalog item.
catalogItemId Species the catalog item identier.
name Species the user friendly name of the catalog item. Species the property type is
string.
description Species a short description of the catalog item. Species the property type is string.
catalogItemTypeRef Species the type of the catalog item.
serviceRef Species the catalog service that contains the catalog item.
iconId Species the associated icon representing this item.
isNoteworthy Species if the catalog item should be highlighted to users for a period of time.
dateCreated Species the date that this item was created in the catalog.
lastUpdatedDate Species the date that this item was last updated in the catalog.
entitledOrganizations Species the organizations in which the catalog item can be consumed by the current
user.
Example Curl Command
The following example command retrieves information about all the available shared catalog items of the type ConsumerEntitledCatalogItemView.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItemViews
Chapter 3 REST API Use Cases
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$host/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"
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
VMware, Inc. 37
Programming Guide
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Getting Information for a Catalog Item

You can use the REST API catalog service to get information about a specic catalog item if desired.
REST API Catalog Service
The REST API supports OData ltering. For more information about supported OData lters, refer to the vRealize Automation API Reference, particularly the REST API Tips page located at
https://$host/component-registry/services/docs/odata.html.
For specic information about catalog service lters, see the "Important Notes About catalog-service and OData Queries" topic located at https://$host/catalog-service/api/docs/index.html.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/catalogItems
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species 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:
name - lter based on catalog item name.
n
status - lter based on catalog item status.
n
service/id - lter based on catalog item service id.
n
service/name - lter based on catalog item service name.
n
organization/subTenant/id - lter based on catalog item business group ID, which
n
you can nd in the catalogItem payload under organization > subtenantRef
organization/subTenant/name - lter based on catalog item business group name,
n
which you can nd in catalogItem payload under organization >subtenantLabel
outputResourceType/id - lter based on catalog item output resource type ID, for
n
example : Infrastructure.Virtual
outputResourceType/name - Filter based on catalog item output resource type
n
name, for example: "VirtualMavhine".
catalogItemType/id - lter based on catalog item type ID, for example:
n
"Infrastructure.Virtual".
catalogItemType/name - lter based on catalog item type name, for example:
n
"VirtualMachine".
icon/id - lter based on catalog item icon ID.
n
$top Sets the number of returned entries from the top of the response
$skip Sets the number of entries to skip.
38 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
$lter Boolean expression for whether a particular entry should be included in the response.
Valid OData properties include the following:
name - lter based on catalog item name.
n
status - lter based on catalog item status.
n
service/id - lter based on catalog item service id.
n
service/name - lter based on catalog item service name.
n
organization/subTenant/id - lter based on catalog item business group ID, which
n
you can nd in the catalogItem payload under organization > subtenantRef
organization/subTenant/name - lter based on catalog item business group name,
n
which you can nd in catalogItem payload under organization >subtenantLabel
outputResourceType/id - lter based on catalog item output resource type ID, for
n
example : Infrastructure.Virtual
outputResourceType/name - Filter based on catalog item output resource type
n
name, for example: "VirtualMavhine".
catalogItemType/id - lter based on catalog item type ID, for example:
n
"Infrastructure.Virtual".
catalogItemType/name - lter based on catalog item type name, for example:
n
"VirtualMachine".
icon/id - lter based on catalog item icon ID.
n
serviceId (Optional) Query parameter to lter the returned catalog items by one specic 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 Species the type of the resource that results from requesting the catalog item.
catalogItemId Species the catalog item identier.
name Species the user friendly name of the catalog item. Species the property type is
string.
description Species a short description of the catalog item. Species the property type is string.
catalogItemTypeRef Species the type of the catalog item.
serviceRef Species the catalog service that contains the catalog item.
iconId Species the associated icon representing this item.
isNoteworthy Species if the catalog item should be highlighted to users for a period of time.
dateCreated Species the date that this item was created in the catalog.
lastUpdatedDate Species 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.
Example Curl Command
The following example command retrieves information about all the available shared catalog items of the type ConsumerEntitledCatalogItemView.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItemViews
Programming Guide
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$host/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"
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
Chapter 3 REST API Use Cases
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Getting a Template Request for a Catalog Item

You can use the REST API catalog service to request catalog items. VMware supplies a number of templates to help you create dierent types of machine requests.
Overview
In the entitledCatalogItemViews response, there is a link eld that contains a value similar to the following:
{
"@type":"link",
"href":"https://$host/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 eld provides a description of the link (request template) and indicates the HTTP method to use with the URI in the href eld (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 specic to the applicable catalog item. The elds and default values are populated based on the conguration 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 submiing the request. For example, you can specify a value for the description eld 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.
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 Species the catalog item identier.
VMware, Inc. 41
Programming Guide
Example Curl Command
The following example command retrieves the catalog item with an ID of dc808d12-3786-4f7c-b5a1-
d5f997c8ad66.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template
Example: JSON Output
The following JSON output is returned based on the command input.
{
"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",
"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": [
{
Chapter 3 REST API Use Cases
"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,
"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"
}
}
],
Programming Guide
"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

You can use the REST API catalog service to submit a machine request.
Prepare you Request
Going back to the entitledCatalogItemViews response, locate a link eld that contains a value similar to the following:
{
"@type":"link",
"href":"https://$host/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.
Chapter 3 REST API Use Cases
Parameter Description
URL hps://$host/catalog-service/api/consumer/requests/requestId
$host Species the host name and fully qualied domain name or IP address of
the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
catalogItemId The identier 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 qualied
user ID. Typically this is provided by the REST URI when making an entitledCatalogItem provisioning request.
businessGroupId The business group identier associated with the request. Typically this is
provided via the REST URI when making the request.
description The catalog item description.
reasons
data Context-specic 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 Species the item state, such as submied.
approvalStatus Species a status indicating whether this request has been approved, rejected, or is still
pending some form of approval.
waitingStatus Species a status indicating whether this request is waiting on any external users or
services before it is able to progress.
requestNumber Species a more user-friendly identier for this request.
executionStatus Species the current execution status of the request.
stateName Species the localized state name.
phase Species the current phase of the request, which is more coarse grained and easier for
users to understand.
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
description Contains a brief description of this request.
reasons Species the business reasons entered by the requestor or owner of this request.
requestedFor Species the ID of the user for whom this request is logged.
requestedBy Species the ID of the user who actually submied the request
organization Subtenant and/or tenant owner of this request.
requestorEntitlementId Specied the value of the requestorEntitlement seing.
preApprovalId Species the ID of the preApproval seing.
postApprovalId Species the ID of the approval generated for the post-provisioning workow step.
dateCreated Species the date when this request was sent to the catalog.
lastUpdated Species the date when this request was last updated.
VMware, Inc. 45
Programming Guide
Property Description
dateSubmied Species the date when this request was rst submied.
dateApproved Species the date when this request was approved.
dateCompleted Species the date when this request was completed.
quote Contains a quote made by the provider dening the estimated cost(s) associated with
requestCompletion Contains additional request completion information.
requestData Contains a map of the provider-specic eld-value pairs collected for this request.
retriesRemaning Species the number of aempts remaining to move this request from its current state to
requestedItemName Species the item name.
requestedItemDescription Species the item description.
components Returns the list of components associated with the request. The provider supplies this
the request and/or any resources provisioned as a result of the request.
the next state in the request workow.
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 denes 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.
list of components after request initialization.
Example: Curl Command
To construct your request, refer to the entitledCatalogItemViews response received when you ran the request described in “Syntax for Geing a Template Request for a Catalog Item,” on page 41, locate a link eld that contains a value similar to the following:
{
"@type":"link",
"href":"https://$host/catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/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://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/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 le or inline text as input.
{
Accept = application/json
Content-Type = application/json
Content-Length = 2806
46 VMware, Inc.
Chapter 3 REST API Use Cases
}
Response Headers
{
Date = Wed, 03 Dec 2014 20:58:34 GMT
ETag = "0"
Location = https://$host/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

Syntax for Viewing Details of a Machine Request

You can use the vRealize Automation REST API catalog service to view the details of a machine request.
Request Status
Typically, the request status information is the most important part of request details. The phase eld 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 31. Request Phase Status
Phase Description End State?
UNSUBMITTED Request was saved but not submied. No
PENDING_PRE_APPROVAL Request is subject to approval - pre-provisioning approval
required.
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
No
Yes
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/requests/$requestId
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
VMware, Inc. 47
Programming Guide
Parameter Description
$token Species a valid HTTP bearer token with necessary credentials.
$requestId Species the request ID. See “Syntax for Displaying Your Provisioned Resources,” on
Output
The command output contains property names and values based on the command input parameters.
Property Description
version Displays the object version number.
state Species the item state, such as submied.
approvalStatus Species a status indicating whether this request has been approved, rejected, or is still
waitingStatus Species a status indicating whether this request is waiting on any external users or
requestNumber Species a more user-friendly identier for this request.
executionStatus Species the current execution status of the request.
stateName Species the localized state name.
phase Species the current phase of the request, which is more coarse grained and easier for
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
description Contains a brief description of this request.
reasons Species the business reasons entered by the requestor or owner of this request.
requestedFor Species the ID of the user for whom this request is logged.
requestedBy Species the ID of the user who actually submied the request
organization Subtenant and/or tenant owner of this request.
requestorEntitlementId Specied the value of the requestorEntitlement seing.
preApprovalId Species the ID of the preApproval seing.
postApprovalId Species the ID of the approval generated for the post-provisioning workow step.
dateCreated Species the date when this request was sent to the catalog.
lastUpdated Species the date when this request was last updated.
dateSubmied Species the date when this request was rst submied.
dateApproved Species the date when this request was approved.
dateCompleted Species the date when this request was completed.
quote Contains a quote made by the provider dening the estimated cost(s) associated with
requestCompletion Contains additional request completion information.
requestData Contains a map of the provider-specic eld-value pairs collected for this request.
page 70 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 eld of the response header if you submied the request with the –headers ag.
pending some form of approval.
services before it is able to progress.
users to understand.
the request and/or any resources provisioned as a result of the request.
48 VMware, Inc.
Chapter 3 REST API Use Cases
Property Description
retriesRemaning Species the number of aempts remaining to move this request from its current state to
the next state in the request workow.
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 denes 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 Species the item name.
requestedItemDescription Species 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
The following example command displays details of a request.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token
https://$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b
Example: JSON Output
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
VMware, Inc. 49
Programming Guide
},
"requestData": {
$detailsOfSubmittedRequest
},
"retriesRemaining": 3,
"requestedItemName": "Linux",
"requestedItemDescription": "Linux blueprint for API demo",
"stateName": "Successful",
"approvalStatus": "POST_APPROVED",
"executionStatus": "STOPPED",
"waitingStatus": "NOT_WAITING",
"phase": "SUCCESSFUL",
"catalogItemRef": {
"id": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"label": "Linux"
}
}

Approve a Machine Request

You can use a sequence of REST API workitem service commands to approve a machine request.
Prerequisites
Log in to vRealize Automation as an approver with at least one of the following qualications:
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 host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2,
n
“REST API Authentication,” on page 9.
Syntax for Listing Work Items on page 51
n
You can use the vRealize Automation REST API workitem service to list the unique IDs of all available work items.
Syntax for Geing Work Item Details on page 57
n
You can use the vRealize Automation REST API workitem service to display the details of a pending work item. You need these details to submit a completion request.
Syntax for Constructing a JSON File to Approve a Machine Request on page 62
n
You can specify a JSON le 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 le that contains all the parameters required to approve the request and complete the work item.
Syntax for Approving a Submied Machine Request on page 65
n
You can approve a work item request to complete the request by using the vRealize Automation REST API. To construct the approval command, you add work item and work item form details to a JSON le, and call that JSON le from the command line. Use a template to correctly format the JSON le content.
Chapter 3 REST API Use Cases
Syntax for Updating Cost Information on page 67
n
You can use the composition service to update and display cost information for a deployment. The cost of a deployment is based on which blueprint you request plus details of the specic request. For example, if the blueprint allows for a range of CPU, memory, or storage values, the cost depends on the value requested.
Procedure
1 List all available work item IDs.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$host/workitem-service/api/workitems
2 Get details for a specic work item ID.
For example, get the details for work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511
3 Construct a JSON le that contains the work item ID information that you need to approve a machine
request.
a Copy the appropriate JSON input le template to a new le in an XML editor that maintains
formaing.
b Substitute the input variables in the template with the values you obtained for your specic work
item ID, for example 5e3e9519-78ea-4409-a52c-e4aa3bc56511.
c Save the le with a new name, for example, approve.json.
4 Approve the submied machine request by specifying the work item ID and including the JSON le as
part of the command line.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json
If the command is successful, the HTTP status is 201 Created. If the command is not successful, the HTTP status is 204 No Content.

Syntax for Listing Work Items

You can use the vRealize Automation REST API workitem service to list the unique IDs of all available work items.
Inputs
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/workitem-service/api/workitems
$host Species the host name and fully qualied domain name or IP address of
the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
VMware, Inc. 51
Programming Guide
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
work itemNumber Displays a reference number for the work item.
id Species the unique identier 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 specic business group granting users with
tenantId Species the tenant ID for the work item.
callbackEntityId Species the callback entity ID for the work item.
work itemType Species the work item type for the work item.
completedDate Species the date when the work item was completed.
assignedDate Species the date when the work item was assigned.
createdDate Species the created date of this instance.
assignedOrCompletedDate Species the date to be displayed on UI.
formUrl Species the URL from which the layout for this work item can be retrieved.
serviceId Species the service ID that generated this work item instance.
work itemRequest Species the corresponding work item request object.
status Species the status of the work item.
completedBy Species the principal ID of user who completed the work item.
availableActions Contains a list of relevant work item actions.
Metadata Species the paging-related data:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines the other names.
n
href
n
Species the URL that produces the result.
management responsibilities over that business group permission to see the approval.
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
totalPages: Species the total number of pages of data available.
n
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
52 VMware, Inc.
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://$host/workitem-service/api/workitems
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "WorkItem",
"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" : [ {
Chapter 3 REST API Use Cases
Programming Guide
"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
}, {
"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,
54 VMware, Inc.
"forms" : {
"workItemDetails" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemNotification" : {
"type" : "external",
"formId" : "travel.itinerary.details"
}
}
},
.
.
.
"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" : {
Chapter 3 REST API Use Cases
Programming Guide
"type" : "string",
"value" : "tony@example.mycompany.com"
}
}, {
"key" : "requestReasons"
}, {
"key" : "requestedItemName",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestInstanceId",
"value" : {
"type" : "string",
"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",
"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
}
}
Chapter 3 REST API Use Cases

Syntax for Getting Work Item Details

You can use the vRealize Automation REST API workitem service to display 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 hps://$host/workitem-service/api/workitems/workitem_ID
$host Species the host name and fully qualied domain name or IP address of
the vRealize Automation identity server.
VMware, Inc. 57
Programming Guide
Parameter Description
$token Species a valid HTTP bearer token with necessary credentials.
workitem_ID Species the unique identier of a work item. See “Syntax for Listing Work
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
work itemNumber Displays a reference number for the work item.
id Species the unique identier 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 specic business group granting users with
tenantId Species the tenant ID for the work item.
callbackEntityId Species the callback entity ID for the work item.
work itemType Species the work item type for the work item.
completedDate Species the date when the work item was completed.
assignedDate Species the date when the work item was assigned.
createdDate Species the created date of this instance.
assignedOrCompletedDate Species the date to be displayed on UI.
formUrl Species the URL from which the layout for this work item can be retrieved.
serviceId Species the service ID that generated this work item instance.
work itemRequest Species the corresponding work item request object.
status Species the status of the work item.
completedBy Species the principal ID of user who completed the work item.
availableActions Contains a list of relevant work item actions.
Metadata Species the paging-related data:
Items,” on page 51.
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines the other names.
n
href
n
Species the URL that produces the result.
management responsibilities over that business group permission to see the approval.
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
totalPages: Species the total number of pages of data available.
n
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
58 VMware, Inc.
Chapter 3 REST API Use Cases
Example: curl Command
The following example command retrieves the necessary details for the specied work item.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511
Example: JSON Output
The following JSON output is returned based on the command input.
To view the contents of a JSON output le, for example workItemDetails.json, use the ! command with
more in UNIX or type in Windows.
(UNIX) vcac-shell>! more workItemDetails.json
n
(Windows) vcac-shell> ! CMD /C type workItemDetails.json
n
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",
"stateName" : "Rejected",
"icon" : {
"id" : "61c6da67-1164-421d-b575-10a245c89e10",
"name" : "rejected.png",
"contentType" : "image/png",
"image" : null
}
VMware, Inc. 59
Programming Guide
} ],
"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" : {
"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" : {
"type" : "string",
"value" : "test-blueprint"
}
Chapter 3 REST API Use Cases
.
.
.
VMware, Inc. 61
Programming Guide
}, {
"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 le 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 le 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 formaed JSON le in a text editor. Replace the highlighted values with your obtained work item details. After you create the JSON le, you can include it, or its contents, when you approve a submied machine request. See “Syntax for Approving a Submied
Machine Request,” on page 65.
{
"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
}
},
{
"key": "source-source-provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-businessJustification",
"value": {
Chapter 3 REST API Use Cases
"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 32. JSON Template Value Table
JSON File Parameter Name Description of Value
workItemId Species 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
source-source-provider-VirtualMachine.CPU.Count Species the number of CPUs requested.
source-businessJustication Species the text description of reason for request.
source-source-provider-VirtualMachine.LeaseDays Species the number of days to lease.
workItemActionId To approve a request, include the approve statement, for example
Species the number of instances requested.
Species the amount of memory requested in GB.
com.mycompany.csp.core.approval.action.approve..
To reject a request, include the reject statement, for example com.mycompany.csp.core.approval.action.reject.
Example: JSON Input File
Use the following JSON input le sample when constructing a le.
{
"@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": [{
Programming Guide
"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",
"value": {
"type": "integer",
"value": 30
}
},
{
"key": "provider-__Notes",
"value": {
"type": "string",
"value": "MYCOMPANY machine"
}
},
{
"key": "provider-VirtualMachine.Disk0.Size",
"value": {
"type": "string",
"value": "1"
}
},
64 VMware, Inc.
Chapter 3 REST API Use Cases
{
"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

You can approve a work item request to complete the request by using the vRealize Automation REST API. To construct the approval command, you add work item and work item form details to a JSON le, and call that JSON le from the command line. Use a template to correctly format the JSON le content.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/workitem-service/api/workitems/workitem_ID
$host Species the host name and fully qualied domain name or IP
address of the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary
credentials.
workitem_ID Species the unique identier of a work item. See “Syntax for
Listing Work Items,” on page 51.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
Species the application or service that determines the other names.
n
href
n
Species the URL that produces the result.
work itemNumber Displays a reference number for the work item.
id Species the unique identier of this resource.
VMware, Inc. 65
Programming Guide
Property Description
version Displays the object version number.
assignees Displays the list of work item assignees.
subTenantId Optionally associates the work item with a specic business group granting users with
tenantId Species the tenant ID for the work item.
callbackEntityId Species the callback entity ID for the work item.
work itemType Species the work item type for the work item.
completedDate Species the date when the work item was completed.
assignedDate Species the date when the work item was assigned.
createdDate Species the created date of this instance.
assignedOrCompletedDate Species the date to be displayed on UI.
formUrl Species the URL from which the layout for this work item can be retrieved.
serviceId Species the service ID that generated this work item instance.
work itemRequest Species the corresponding work item request object.
status Species the status of the work item.
completedBy Species the principal ID of user who completed the work item.
availableActions Contains a list of relevant work item actions.
Metadata Species the paging-related data:
management responsibilities over that business group permission to see the approval.
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
totalPages: Species the total number of pages of data available.
n
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example: Example: curl Command
Approve a submied machine request by specifying its work item ID and using a JSON le named
approve.json to pass arguments to the command line.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/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 submied 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.}
Chapter 3 REST API Use Cases
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 Cost Information

You can use the composition service to update and display cost information for a deployment. The cost of a deployment is based on which blueprint you request plus details of the specic request. For example, if the blueprint allows for a range of CPU, memory, or storage values, the cost depends on the value requested.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL
Method Post
$host Species the host name and fully qualied domain name or IP
$token Species a valid HTTP bearer token with necessary
HTTP Body Species the blueprint ID for the blueprint for which you are
//$host/composition­service/api/blueprints/$BlueprintId/costs/upfront
address of the vRealize Automation identity server.
credentials.
requesting cost information and other information.
n
Blueprint ID: Species the blueprint ID.
n
requestedFor: The user for whom this request is being made. Must be the fully qualied user ID.
n
subTenantId: Species the subtenant ID associated with the blueprint
n
requestData: Species data that identies the blueprint further.
n
entries
n
Key: The name of the machine on which the blueprint resides.
n
value: Species 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 cost that is to be displayed.
n
Values: Species an array of type lters.
n
Entries: Species a list of key-value pairs that specify the values to be used in computing the cost. 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.
VMware, Inc. 67
Programming Guide
Property Description
setupFee Species the one time setup fee associated with the
totalLeasePriceInfo Species the minimum cost and maximum cost for the
averageDailyPriceInfo Species the average daily price, which depends on the
count Species the instance count of the component.
memory Species memory requested for this component.
additional Species the additional cost, if any, associated with the
cpu Species the cpu requested for the component.
storage Species the storage requested for the component.
componentId Species the component ID, or total cost of the deployment.
Example: curl Command
The following sample command updates and displays the cost of a sample blueprint with one node. The HTTP body is included as part of the command line input.
component.
lease period.
reservation available for the component.
component.
curl -- insecure -H “Content Type: application/json”
-H "Authorization: Bearer $token"
https://$host/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
}
68 VMware, Inc.
Chapter 3 REST API Use Cases
},
{
"key": "memory",
"value": {
"type": "integer",
"value": 2048
}
}
]
}
}
}
]
}
}
Example: JSON Output for a Blueprint Cost Update
[{"componentId":"vSphere_Machine_1",
"setupFee":"$0.00",
"totalLeasePriceInfo":{"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":"","totalLeasePriceInfo":
{"min":50.0543225806451601,"max":50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":{"min":16.6847741935483867,"max":
16.6847741935483867,"displayString":"$16.68"},
"count":3,"fieldMap":{}}]

List Provisioned Resources

You can use the REST API catalog service to log in to vRealize Automation and display a full or ltered list of your provisioned resources .
Prerequisites
Log in to vRealize Automation as a business group manager.
n
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2,
n
“REST API Authentication,” on page 9.
Obtain the business group subtenant ID values to specify on the command line. See “Syntax for
n
Displaying Your Provisioned Resources,” on page 70.
Syntax for Displaying Your Provisioned Resources on page 70
n
You can use the REST API catalog service to display a list of all the provisioned resources that you own.
VMware, Inc. 69
Programming Guide
Syntax for Displaying Provisioned Resources by Resource Type on page 72
n
You can use the REST API catalog service to display a list of the provisioned resources that you own ltered by machine resource type.
Syntax for Displaying All Available Resource Types on page 75
n
You can use the REST API catalog service to display all the resource types that are available on the system.
Syntax for Displaying Provisioned Resources by Business Groups You Manage on page 76
n
You can use the REST API catalog service to display all of the provisioned resources that are owned by the business groups that you manage. You can optionally lter the list by business group name.
Syntax for Viewing Machine Details on page 84
n
You can use the vRealize Automation REST API catalog service to display the machine details for a provisioned machine.
Procedure
1 Display a list of all the provisioned resources.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/?page=n&limit=n
2 Display a list of the provisioned resources ltered by machine resource type.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/resourceTypes/Infrastructure.Machine/?
page=1&limit=1
3 Display all the resource types that are available on the system.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resourceTypes
4 Display all of the provisioned resources that are owned by the business groups. Optionally, lter the list
by business group name.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/types/Infrastructure.Machine/?
page=1&limit=2&$orderby=dateCreated desc&$filter=((organization/subTenant/id eq
'subtenantID_group1') or (organization/subTenant/id eq ''subtenantID_group2') … )"
5 Display the machine details for a provisioned machine.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/resources/resourceID/

Syntax for Displaying Your Provisioned Resources

You can use the REST API catalog service to display a list of all the provisioned resources that you own.
Input
Use the supported input parameters to control the command output.
70 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
URL hps://$host/catalog-service/api/consumer/resources
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species 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
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
resourceTypeRef Species the resource type.
name Species the resource name.
description Species the resource description.
status Species the resource status.
catalogItem Species the catalog item that denes the service this resource is based on.
requestId Species the request ID that provisioned this resource.
providerBinding Species the provider binding.
owners Species the owners of this resource.
organization Species the subtenant or tenant that owns this resource.
dateCreated Species the data and time at which the resource was created.
lastUpdated Species the date and time at which the resource was most recently modied.
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 Species the resource's current lease, #getLease, with time units synchronized with
#getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Species the sequence of available operations that can be performed on this resource.
forms Species the forms used to render this resource.
resourceData Displays the extended provider-dened properties of the resource.
Example: curl Command
The following example command displays all applicable provisioned resources.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/?page=n&limit=n
Programming Guide
Example: 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"
}
},
}

Syntax for Displaying Provisioned Resources by Resource Type

You can use the REST API catalog service to display a list of the provisioned resources that you own ltered by machine resource type.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/resourceType
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
Filter by the following resource types:
Infrastructure.Machine
n
72 VMware, Inc.
Chapter 3 REST API Use Cases
Infrastructure.AppServic
n
Infrastructure.Cloud
n
Infrastructure.Physical
n
Infrastructure.vApp
n
Infrastructure.Virtual
n
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
resourceTypeRef Species the resource type.
name Species the resource name.
description Species the resource description.
status Species the resource status.
catalogItem Species the catalog item that denes the service this resource is based on.
requestId Species the request ID that provisioned this resource.
providerBinding Species the provider binding.
owners Species the owners of this resource.
organization Species the subtenant or tenant that owns this resource.
dateCreated Species the data and time at which the resource was created.
lastUpdated Species the date and time at which the resource was most recently modied.
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 Species the resource's current lease, #getLease, with time units synchronized with
#getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Species the sequence of available operations that can be performed on this resource.
forms Species the forms used to render this resource.
resourceData Displays the extended provider-dened properties of the resource.
Example: curl Command
The following example command displays the provisioned resources by resource type.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
https://$host/catalog-service/api/consumer/resourceTypes/Infrastructure.Machine/?page=1&limit=1
Programming Guide
Example: JSON Output
In this example, the highlighted 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.
Also in this example, the subtenantRef ID (eab762cb-6e75-4379-83ef-171a71c9f00e) corresponds to the business group of the logged-in user. If the logged-in user is also the manager of the business group, the subtenantRef ID is used to get resources from all business groups that the user manages.
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",
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
}
74 VMware, Inc.
Chapter 3 REST API Use Cases

Syntax for Displaying All Available Resource Types

You can use the REST API catalog service to display all the resource types that are available on the system.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/resourceTypes
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species 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
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
resourceTypeRef Species the resource type.
name Species the resource name.
description Species the resource description.
status Species the resource status.
catalogItem Species the catalog item that denes the service this resource is based on.
requestId Species the request ID that provisioned this resource.
providerBinding Species the provider binding.
owners Species the owners of this resource.
organization Species the subtenant or tenant that owns this resource.
dateCreated Species the data and time at which the resource was created.
lastUpdated Species the date and time at which the resource was most recently modied.
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 Species the resource's current lease, #getLease, with time units synchronized with
#getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Species the sequence of available operations that can be performed on this resource.
VMware, Inc. 75
Programming Guide
Property Description
forms Species the forms used to render this resource.
resourceData Displays the extended provider-dened properties of the resource.
Example: curl Command
The following example command displays all available resource types.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/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
}

Syntax for Displaying Provisioned Resources by Business Groups You Manage

You can use the REST API catalog service to display all of the provisioned resources that are owned by the business groups that you manage. You can optionally lter the list by business group name.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/resources/type
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
76 VMware, Inc.
Chapter 3 REST API Use Cases
Property Description
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
resourceTypeRef Species the resource type.
name Species the resource name.
description Species the resource description.
status Species the resource status.
catalogItem Species the catalog item that denes the service this resource is based on.
requestId Species the request ID that provisioned this resource.
providerBinding Species the provider binding.
owners Species the owners of this resource.
organization Species the subtenant or tenant that owns this resource.
dateCreated Species the data and time at which the resource was created.
lastUpdated Species the date and time at which the resource was most recently modied.
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 Species the resource's current lease, #getLease, with time units synchronized with
#getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Species the sequence of available operations that can be performed on this resource.
forms Species the forms used to render this resource.
resourceData Displays the extended provider-dened properties of the resource.
Example: curl Command
The following example command displays the provisioned resources of one or more business groups.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/types/Infrastructure.Machine/?
page=1&limit=2&$orderby=dateCreated desc&$filter=((organization/subTenant/id eq
'subtenantID_group1') or (organization/subTenant/id eq ''subtenantID_group2') … )"
Example: JSON Output
The following JSON output is returned based on the command input.
Programming Guide
For the following command input, the specied subtenant IDs correspond to business groups that are managed by the logged-in user.
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",
"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" : {
78 VMware, Inc.
"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",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}
},
"resourceData" : {
"entries" : [ {
"key" : "Expire",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineGroupName",
"value" : {
"type" : "string",
"value" : "MyTestAgentBusinessGroup"
}
}, {
Chapter 3 REST API Use Cases
VMware, Inc. 79
Programming Guide
"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" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStatus",
"value" : {
"type" : "string",
"value" : "On"
}
}, {
"key" : "PowerOff",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "DISK_VOLUMES",
"value" : {
Chapter 3 REST API Use Cases
"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"
}
}, {
"key" : "Suspend",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reboot",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reprovision",
"value" : {
"type" : "boolean",
"value" : true
}
VMware, Inc. 81
Programming Guide
}, {
"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
}
}, {
"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
}
}, {
82 VMware, Inc.
"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"
}, {
"key" : "Reset",
"value" : {
"type" : "boolean",
"value" : true
}
} ]
}
} ],
"metadata" : {
"size" : 2,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
Chapter 3 REST API Use Cases
Programming Guide

Syntax for Viewing Machine Details

You can use the vRealize Automation REST API catalog service to display the machine details for a provisioned machine.
Using the API to Get Deployment Details
You can use the REST API to view deployed machine details by appending /resourceViews to the request details URI that you generated when you retrieved request details. So the syntax the GET statement would read as follows:
http://$host/catalog-service/api/consumer/requests/$requestId/resourceViews
See “Syntax for Viewing Details of a Machine Request,” on page 47.
In addition to general information about the provisioned deployment--such as its name, description, and ID--the response contains additional HATEOAS links that enable you to obtain additional details and information.
Table 33. HATEOAS Link Functions as Defined by rel Field
Link Description
GET: Catalog Item URI to get the catalog item details (as described in sections 3.2.1 and
GET: Request URI to get the request details that provisioned this item.
GET:Template
{com.vmware.csp.component.cafe.composition@r esource.action.deployment.$actionName
POST:
{com.vmware.csp.component.cafe.composition@r esource.action.deployment.$actionName
GET: Child Resources If the deployment contains child resources (nodes specied in the
3.2.2) from which this catalog item was provisioned.
URI to get a template request for a specic action that you can perform on this resource. Typically, on a deployment the action will be Delete.
URI to which to post the request to perform an action, based on the corresponding template.
composite blueprint), this is the URI to get a list of the resourceViews for the children of this deployment.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/resources/$resourceId
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$resourceID Species a resource ID. See “Syntax for Displaying Your Provisioned Resources,” on
page 70 to view all of your requests and search for a request ID.
managedOnly If true, the returned requests are from the user's managed subtenants.
page Species a page number.
limit Species the number of entries to display on a page.
$orderby Species how to order multiple comma-separated properties sorted in ascending or
descending order.
$top Species the number of returned entries from the top of the response (total number per
page in relation to skip).
84 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
$skip Species the number of entries to skip.
lter Contains a Boolean expression to determine if a particular entry is included in the
response.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Species the unique identier of this resource.
iconId Species an icon for this request based on the requested object type.
resourceTypeRef Species the resource type.
name Species the resource name.
description Species the resource description.
status Species the resource status.
catalogItem Species the catalog item that denes the service this resource is based on.
requestId Species the request ID that provisioned this resource.
providerBinding Species the provider binding.
owners Species the owners of this resource.
organization Species the subtenant or tenant that owns this resource.
dateCreated Species the data and time at which the resource was created.
lastUpdated Species the date and time at which the resource was most recently modied.
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 Species the resource's current lease, #getLease, with time units synchronized with
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Species the sequence of available operations that can be performed on this resource.
forms Species the forms used to render this resource.
resourceData Displays the extended provider-dened properties of the resource.
#getCosts.
Example: curl Command
The following example command displays machine details for a provisioned machine, where the provisioned machine ID is 7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token
http://$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews
VMware, Inc. 85
Programming Guide
Example: JSON Output
In the following example, the provisioned machine resourceID value specied in the command line was 7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$host/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests"
},
{
"@type": "link",
"rel": "GET: Child Resources",
"href": "https://$host/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27"
}
],
"resourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Linux-80813151",
"description": null,
"status": null,
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"catalogItemLabel": "Linux",
"requestId": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"resourceType":
"{com.vmware.csp.component.cafe.composition@resource.type.deployment.name}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:51:36.368Z",
"lastUpdated": "2015-07-29T13:55:35.963Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": null,
"hasChildren": true,
"data": {}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Chapter 3 REST API Use Cases

Manage Provisioned Deployments

You can use the REST API catalog service to log in to vRealize Automation and view information about provisioned resources .
Prerequisites
Note The vRealize Automation REST API does not support custom resource actions template API calls. However, you can perform custom resource actions programmatically by using the vRealize Automation Cloud Client.
Log in to vRealize Automation as a business group manager.
n
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2,
n
“REST API Authentication,” on page 9.
Obtain the business group subtenant ID values to specify on the command line. See “Syntax for Geing
n
Deployment Details,” on page 89.
Syntax for Geing Deployment Details on page 89
n
You can use the REST API catalog service to identify provisioned items from a given request.
Syntax for Navigating to the Children of a Deployed Resource on page 92
n
Use the GET: Child Resources link to retrieve a list of the child nodes of a deployment, including virtual machines, networks, and other objects you may have congured on the design canvas.
Perform a Day 2 Action: Power O on page 98
n
You can use the REST API catalog service to perform a power o action. For simple actions that require no user input, the process is straightforward.
Programming Guide
Perform a Day 2 Action: Change Lease on page 100
n
You can use the REST API catalog service to change a lease. For actions that require user input, you may need to edit the template prior to submiing the request.
Procedure
1 Display a list of all provisioned resources.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
http://
$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews
The output from this command includes HATEOAS links that enable you to quickly obtain additional information about specic deployed resources.
2 Use the GET: Child Resources HATEOAS link to retrieve a list of child nodes of a deployment.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https:// $host
/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27
3 In addition, you can use the HATEOAS links to complete day 2 actions.
You can use a command like the following to get the template for the resource action request and
n
use it to power o a machine.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-
b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template
Then POST the unmodied template to the corresponding URI.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token"https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}
You can modify the HATEOAS links to complete more complex day 2 actions that require user
n
input, such as changing a lease. Use a command like the following to get the template for the resource action request.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template
88 VMware, Inc.
After you edit the template as desired, you can POST it to the corresponding URI.
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {
"provider-ExpirationDate": "2015-07-29T16:44:13.846Z"
}
}

Syntax for Getting Deployment Details

You can use the REST API catalog service to identify provisioned items from a given request.
Chapter 3 REST API Use Cases
Accessing Links to Provisioned Items
You can access links to provisioned items from a given request by appending /resourceViews to the request details URI. For instance, you can edit the example request URI from as follows:
http://$host/catalog-service/api/consumer/requests/$requestId/resourceViews
In addition to the general information about the provisioned deployment returned in the response, such as its name, description and ID, the response contains additional HATEOAS links.
Table 34. HATEOAS Link Deployment Details Functions
Link Description
GET: Catalog Item URI to get the catalog item details from which this catalog item
was provisioned. See “Syntax for Viewing Details of a Machine
Request,” on page 47.
GET: Request URI to get the request details that provisioned this item.
GET:Template
{com.vmware.csp.component.cafe.composition@res ource.action.deployment.$actionName
POST:
{com.vmware.csp.component.cafe.composition@res ource.action.deployment.$actionName
GET: Child Resources If the deployment contains child resources, such as nodes specied
URI to get a template request for a specic action that you can perform on this resource. Typically, on a deployment, the action will be Delete.
URI to which to post the request to perform an action, based on the corresponding template.
in the composite blueprint, this is the URI to get a list of the resourceViews for the children of this deployment.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 89
Programming Guide
Parameter Description
URL hps://$host/catalog-service/api/consumer/resources/$resourceId
$host Species the host name and fully qualied domain name or IP address of the
$token Species a valid HTTP bearer token with necessary credentials.
id UUID of a request.
page Species a page number.
limit Species the number of entries to display on a page.
$orderby Species how to order multiple comma-separated properties sorted in ascending or
$top Species the number of returned entries from the top of the response (total number per
$skip Species the number of entries to skip.
lter Contains a Boolean expression to determine if a particular entry is included in the
Output
vRealize Automation identity server.
descending order.
page in relation to skip).
response.
The command output contains property names and values based on the command input parameters.
Table 35. Output Parameters
Property Description
resourceId The unique identier of the resource.
iconId Species an icon for this request based on the requested object type.
name The user friendly name of the resource.
description An extended user friendly description of the resource.
status The status of the resource. For example, On, O, etc.
catalogItemId The identier of the catalog item associated with this provisioned resource.
catalogItemLabel The label of the catalog item associated with this provisioned resource.
requestId The unique identier of the request that created this provisioned resource.
businessGroupId The unique identier of the business group that owns this resource.
tenantId The unique identier of the tenant that owns this resource.
owners The owner of this resource.
resourceType The type identier of this resource. For example, Virtual Machine.
parentResourceId The unique identier of the parent resource. Used for child resources of a multi-
machine resource.
hasChildren Returns trun if this resource has child resources. Used if this is a multi-machine
resource.
dateCreated The date and time at which the resource was created.
lastUpdated The date and time at which the resource was most recently modied.
lease The current lease of the resource.
costs An optional rate card of the costs and charges levied against the resource.
costToDate An optional rate card of the existing costs and charges levied against the resource.
90 VMware, Inc.
Chapter 3 REST API Use Cases
Table 35. Output Parameters (Continued)
Property Description
totalCost An optional rate card of the costs and charges levied for the entire lease period.
data The extended, provider dened properties of the resource.
Example Curl Command
This example retrieves all children of the resource with an ID of 7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
http:// $host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews
Example: JSON Output
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$host/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests"
},
{
"@type": "link",
"rel": "GET: Child Resources",
"href": "https://$host/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27"
}
Programming Guide
],
"resourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Linux-80813151",
"description": null,
"status": null,
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"catalogItemLabel": "Linux",
"requestId": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"resourceType":
"{com.vmware.csp.component.cafe.composition@resource.type.deployment.name}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:51:36.368Z",
"lastUpdated": "2015-07-29T13:55:35.963Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": null,
"hasChildren": true,
"data": {}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Navigating to the Children of a Deployed Resource

Use the GET: Child Resources link to retrieve a list of the child nodes of a deployment, including virtual machines, networks, and other objects you may have congured on the design canvas.
Using the REST API to Get Additional Deployment Information
In addition to general information about the provisioned resource, the response contains additional HATEOAS links that enable you to obtain additional details and information about each returned child resource.
92 VMware, Inc.
Chapter 3 REST API Use Cases
Table 36. HATEOAS Link Functions as Defined by rel Field
Link Description
GET: Parent Resource
GET:Template
{com.vmware.csp.component.cafe.composition@res ource.action.deployment.$actionName
POST:
{com.vmware.csp.component.cafe.composition@res ource.action.deployment.$actionName
URI to get the resourceView for the parent item. See “Syntax for
Geing Deployment Details,” on page 89.
URI to get a template request for a specic action that you can perform on this resource.
URI to which to post the request to perform an action, based on the corresponding template.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/catalog-service/api/consumer/resources/$resourceId
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$resourceID Species a resource ID. See “Syntax for Geing Deployment Details,” on page 89 to
view all of your requests and search for a request ID.
managedOnly If true, the returned requests are from the user's managed subtenants.
page Species a page number.
limit Species the number of entries to display on a page.
$orderby Species how to order multiple comma-separated properties sorted in ascending or
descending order.
$top Species the number of returned entries from the top of the response (total number per
page in relation to skip).
$skip Species the number of entries to skip.
lter Contains a Boolean expression to determine if a particular entry is included in the
response.
Output
The command output contains property names and values based on the command input parameters.
Table 37. Output Parameters
Property Description
resourceId The unique identier of the resource.
iconId Species an icon for this request based on the requested object type.
name The user friendly name of the resource.
description An extended user friendly description of the resource.
status The status of the resource. For example, On, O, etc.
catalogItemId The identier of the catalog item associated with this provisioned resource.
catalogItemLabel The label of the catalog item associated with this provisioned resource.
requestId The unique identier of the request that created this provisioned resource.
VMware, Inc. 93
Programming Guide
Table 37. Output Parameters (Continued)
Property Description
businessGroupId The unique identier of the business group that owns this resource.
tenantId The unique identier of the tenant that owns this resource.
owners The owner of this resource.
resourceType The type identier of this resource. For example, Virtual Machine.
parentResourceId The unique identier of the parent resource. Used for child resources of a multi-
hasChildren Returns trun if this resource has child resources. Used if this is a multi-machine
dateCreated The date and time at which the resource was created.
lastUpdated The date and time at which the resource was most recently modied.
lease The current lease of the resource.
costs An optional rate card of the costs and charges levied against the resource.
costToDate An optional rate card of the existing costs and charges levied against the resource.
totalCost An optional rate card of the costs and charges levied for the entire lease period.
data The extended, provider dened properties of the resource.
machine resource.
resource.
Example Curl Command
This example retrieves all children of the resource with an ID of c4d3db3e-e397-44-a1c9-0ecebdba12f4%27.
$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https:// $host /catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27
Example: JSON Output
The validation output displays the validation status of each content item within the package.
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Parent Resource",
"href": "https://$host/catalog-service/api/consumer/resourceViews/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/catalog-
service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template"
},
{
Chapter 3 REST API Use Cases
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/catalog-
service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/catalog-
service/api/consumer/resources/dd37b7a1-829c-4773-b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-
b964-37bb5d57be38/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/catalog-
service/api/consumer/resources/dd37b7a1-829c-4773-b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-
b964-37bb5d57be38/requests"
}
],
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "DEMO-002",
"description": null,
"status": "On",
"catalogItemId": null,
"catalogItemLabel": null,
"requestId": null,
"resourceType":
"{com.vmware.csp.component.iaas.proxy.provider@resource.type.registration.name.Infrastructure.Vir
tual}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:54:58.804Z",
"lastUpdated": "2015-07-29T13:55:01.371Z",
"lease": {
"start": "2015-07-29T13:51:33.000Z"
},
"costs": {
"leaseRate": {
"type": "moneyTimeRate",
"cost": {
"type": "money",
"currencyCode": "USD",
"amount": 0
},
"basis": {
"type": "timeSpan",
Programming Guide
"unit": "DAYS",
"amount": 1
}
}
},
"costToDate": {
"type": "money",
"currencyCode": "USD",
"amount": 0
},
"totalCost": null,
"parentResourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"hasChildren": false,
"data": {
"ChangeLease": true,
"ConnectViaRdp": true,
"ConnectViaVmrc": true,
"DISK_VOLUMES": [
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.DiskInputModel",
"typeFilter": null,
"data": {
"DISK_CAPACITY": 6,
"DISK_INPUT_ID": "DISK_INPUT_ID1"
}
},
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.DiskInputModel",
"typeFilter": null,
"data": {
"DISK_CAPACITY": 6,
"DISK_INPUT_ID": "DISK_INPUT_ID2"
}
}
],
"Destroy": true,
"EXTERNAL_REFERENCE_ID": "vm-38153",
"Expire": true,
"IS_COMPONENT_MACHINE": false,
"MachineBlueprintName": "system_blueprint_vsphere",
"MachineCPU": 1,
"MachineDailyCost": 0,
"MachineDestructionDate": null,
"MachineExpirationDate": null,
"MachineGroupName": "Demo Group",
"MachineGuestOperatingSystem": null,
"MachineInterfaceDisplayName": "vSphere (vCenter)",
"MachineInterfaceType": "vSphere",
"MachineMemory": 4096,
"MachineName": "DEMO-002",
"MachineReservationName": "vCenter55",
96 VMware, Inc.
Chapter 3 REST API Use Cases
"MachineStorage": 12,
"MachineType": "Virtual",
"NETWORK_LIST": [
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.NetworkViewModel",
"typeFilter": null,
"data": {
"NETWORK_MAC_ADDRESS": "00:50:56:ba:6b:85",
"NETWORK_NAME": "VM Network SQA"
}
}
],
"PowerOff": true,
"Reboot": true,
"Reconfigure": true,
"Reprovision": true,
"Reset": true,
"SNAPSHOT_LIST": [],
"Shutdown": true,
"Suspend": true,
"ip_address": "10.118.194.213",
"machineId": "f3579990-a3c4-4e17-9593-1f8893636876"
}
},
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Parent Resource",
"href": "https://$host/catalog-service/api/consumer/resourceViews/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.network.service@resource.action.destroy.name,
[{{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastruc
ture.Network.Network.Existing}}]}",
"href": "https://$host/catalog-service/api/consumer/resources/f735b57a-
fe6f-4108-876f-1c1055ca2cec/actions/ec5c522d-7b5b-4d0b-b9f2-1aedf01a2f0c/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.network.service@resource.action.destroy.name,
[{{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastruc
ture.Network.Network.Existing}}]}",
"href": "https://$host/catalog-service/api/consumer/resources/f735b57a-
fe6f-4108-876f-1c1055ca2cec/actions/ec5c522d-7b5b-4d0b-b9f2-1aedf01a2f0c/requests"
}
],
"resourceId": "f735b57a-fe6f-4108-876f-1c1055ca2cec",
VMware, Inc. 97
Programming Guide
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Existing Network",
"description": null,
"status": null,
"catalogItemId": null,
"catalogItemLabel": null,
"requestId": null,
"resourceType":
"{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastruct
ure.Network.Network.Existing}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:55:14.095Z",
"lastUpdated": "2015-07-29T13:55:17.315Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"hasChildren": false,
"data": {
"Description": " ",
"Name": "Existing Network"
}
}
],
"metadata": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Perform a Day 2 Action: Power Off

You can use the REST API catalog service to perform a power o action. For simple actions that require no user input, the process is straightforward.
This command leverages the links for the power o action from the command used in the “Syntax for
Navigating to the Children of a Deployed Resource,” on page 92 example.
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template"
},
{
"@type": "link",
"rel": "POST:
Chapter 3 REST API Use Cases
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests"
}
Procedure
1 Get the template for the resource action request.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template
This example command returns a response.
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}
2 Use a POST command to send the template without modication to the corresponding URI.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token"https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}
This POST command returns a response indicating success or failure, such as HTTP/1.1 201 CREATED for success.
Programming Guide

Perform a Day 2 Action: Change Lease

You can use the REST API catalog service to change a lease. For actions that require user input, you may need to edit the template prior to submiing the request.
This command leverages the links for the change lease action from the command used in the “Syntax for
Navigating to the Children of a Deployed Resource,” on page 92 example.
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
Procedure
1 Get the template for the resource action request.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template
This example command returns a response.
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {
"provider-ExpirationDate": "2015-07-29T16:44:13.846Z"
}
}
2 Edit the template as desired. The template is populated with default values. In this example, the value
of provider-ExpirationDate is set to the time at which the template was requested in UTC. Edit this value (for example, to change the expiration to a month from now).
100 VMware, Inc.
Loading...