Syntax for Linking an Identity Store to the Tenant 29
Syntax for Searching LDAP or Active Directory for a User 33
Syntax for Assigning a User to a Role 35
Syntax for Displaying all Roles Assigned to a User 36
Request a Machine 38
Syntax for Listing Shared and Private Catalog Items 40
Syntax for Getting Information for a Catalog Item 43
Syntax for Getting a Template Request for a Catalog Item 47
Syntax for Requesting a Machine 51
Syntax for Viewing Details of a Machine Request 54
Approve a Machine Request 57
Syntax for Listing Work Items 58
Syntax for Getting Work Item Details 65
Syntax for Constructing a JSON File to Approve a Machine Request 69
Syntax for Approving a Submitted Machine Request 73
Syntax for Updating Cost Information 75
List Provisioned Resources 78
Syntax for Displaying Your Provisioned Resources 79
Syntax for Displaying Provisioned Resources by Resource Type 81
Syntax for Displaying All Available Resource Types 84
Syntax for Displaying Provisioned Resources by Business Groups You Manage 86
Syntax for Viewing Machine Details 93
VMware, Inc.
3
Programming Guide
Manage Provisioned Deployments 97
Working with Reservations 112
Working with Reservation Policies 285
Working with Key Pairs 296
Working with Network Profiles 310
Get a List of Available IP Ranges for an IPAM Provider 342
Import and Export Content 359
Syntax for Getting Deployment Details 99
Syntax for Navigating to the Children of a Deployed Resource 103
Perform a Day 2 Action: Power Off 109
Perform a Day 2 Action: Change Lease 111
Create a Reservation 113
Display a List of Reservations 263
Update a Reservation 274
Delete a Reservation 283
List Reservation Policies 285
Create a Reservation Policy 288
Display a Reservation Policy by ID 290
Update a Reservation Policy 292
Delete a Reservation Policy 294
Get a Key Pair List 296
Create a Key Pair 301
Query a Key Pair 304
Update a Key Pair 305
Delete a Key Pair 308
Get a Network Profile List 311
Create a Network Profile 327
Query a Network Profile 332
Update a Network Profile 338
Delete a Network Profile 341
Syntax for Listing Supported Content Types 362
Syntax for Listing Available Content 365
Syntax for Filtering Content by Content Type 369
Syntax for Creating a Package for Export 371
Syntax for Listing Packages in the Content Service 372
Syntax for Exporting a Package 374
Syntax for Validating a Content Bundle Before Importing 375
Syntax for Importing a Package 377
Understanding Blueprint Schema 379
Manage XaaS Content with Import and Export 381
VMware, Inc. 4
Programming Guide
Related Tools and Documentation385
4
Using the vRealize Automation API Reference 385
View Reference Information for an API 386
Using vRealize CloudClient 386
Using Third Party Tools 387
Filtering and Formatting REST API Information389
5
VMware, Inc. 5
vRealize Automation Programming Guide
The Programming Guide provides information about the vRealize Automation REST APIs, including how
to use the REST API services and resources, create HTTP bearer tokens for authentication and
authorization, and construct REST API service calls.
Intended Audience
This information is intended for administrators and programmers who want to configure and manage
vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on
common use cases. For related information about all available REST API services, see in vRealizeAutomation API Reference at https://www.vmware.com/support/pubs/vcac-pubs.html.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For
definitions of terms as they are used in VMware technical documentation, go to
The vRealize Automation REST API provides consumer, administrator, and provider-level access to the
service catalog with the same services that support the vRealize Automation console user interface. You
can perform vRealize Automation functions programmatically by using REST API service calls.
The vRealize Automation REST API offers the following services and functions.
Branding ServiceChange the background and text colors, company logo, company name,
product name, tenant name, and other resources in the console.
Catalog ServiceRetrieve 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 ServiceAccess and manage all services and serves as the central view for all
service lookups.
Composition ServiceAllows vRealize Automation services to register application components,
which the composition service manages so that they can be used in
composite blueprints.
Content Management ServiceAccess and manage the content controller and package controller for
export and import processes. This includes export and import for
blueprints and software.
Endpoint Configuration ServiceCreate, read, update and delete endpoint types, endpoint categories, and
endpoints.
Event Broker ServiceProvide a central location and a consistent way of recording events and
querying for events.
Forms ServiceUsed internally by the vRealize Automation system to create, read,
update and delete (perform CRUD operations on) request forms for XaaS
components.
IaaS Proxy Provider ServiceRun 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.
VMware, Inc. 7
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
ServiceDescription
Identity ServiceManage tenants, business groups, SSO and custom groups, users, and
identity stores.
IP Address Management ServiceAllocate and deallocate IP addresses from IP address management
(IPAM) providers.
Licensing ServiceRetrieve permissions and post serial keys.
Management Service (Reclamation Service)Retrieve work item forms, callbacks, and tasks. Manage endpoint details
including tenant, password, user name, and endpoint URL. Retrieve
performance metrics. Retrieve and cancel reclamation requests.
Network ServiceAccess and manage application network and security settings for
creating and configuring NAT and routed networks; creating load
balancers; and adding and configuring security groups, security tags and
security policies for application components.
Notification ServiceConfigure and send notifications for several types of events such as the
successful completion of a catalog request or a required approval.
Orchestration Gateway ServiceProvides a gateway to VMware Realize Orchestrator (vRO) for services
running on vRealize Automation. By using the gateway, consumers of the
API can access a vRO instance, and initiate workflows or script actions
without having to deal directly with the vRO APIs.
Extensibility (Plug-in) ServiceRetrieve, create, update, and delete a resource. Retrieve an extension.
Retrieve license notifications.
Portal ServiceRetrieve, create, update, and delete a portal resource.
Properties ServiceManage custom properties, property groups, and property definitions.
Properties specify items that can be added to blueprints to trigger
vRealize Orchestrator actions.
Reservation ServiceRetrieve, create, update, and delete a reservation or reservation policy.
Software ServicesTriggers the execution life cycle of software components using the
software agent, registers software agents, and manages the creation,
modification and deletion of software componentsoftware component
types, software resource requests, and nodes (machines).
vRA Orchestrator ServiceManage vRealize Orchestrator actions, tasks, packages, and workflows.
Browse system and plug-in inventories.
Work Item ServiceRetrieve, create, update, complete, cancel, and delete a work item. Also
retrieve form data, metadata, detail forms, and submission forms from
service providers.
XaaS ServiceManages XaaS elements such as forms, endpoints, XaaS blueprints,
tenants, vRealize Orchestrator imports, workflows, and work items.
The advanced designer service selection on the vRealize Automation APIReference landing page selects the documentation for the XaaS service.
VMware, Inc. 8
Programming Guide
When a service request contains a resource URL, the first part of the URL identifies the service and the
last part identifies the resource. For example, the following resource URL identifies the catalog service
and the providers resource:
https://$host/component-registry/api/services
For more information about all the vRealize Automation REST API service calls, see Using the vRealize
Automation API Reference and the vRealize Automation API Reference in your vRealize Automation
installation.
VMware, Inc. 9
REST API Authentication2
In the REST API, vRealize Automation requires HTTP bearer tokens in request headers for authentication
of consumer requests. A consumer request applies to tasks that you can perform in the
vRealize Automation console, such as requesting a machine.
To acquire an HTTP bearer token, you authenticate with an identity service that manages the
communication with the SSO server. The identity service returns an HTTP bearer token that you include
in all request headers until the token expires, or you delete it. An HTTP bearer token expires in 24 hours
by default, but you can configure the token with a different duration.
Using HTTP Bearer Tokens
You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You
create a request header with the curl command or with some other utility.
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.
MethodURLDescription
POST/tokensAuthenticate the user with the identity service /tokens and
generate a new token.
HEAD/tokens/tokenIDValidate the token tokenID.
DELETE/tokens/tokenIDDelete 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 file on the
vRealize Automation appliance.
VMware, Inc.
10
Programming Guide
The effective duration or lifetime of an HTTP bearer token depends on the duration of its corresponding
SAML token, which the SSO server creates at request time. An HTTP bearer token expires when it
reaches the end of its configured duration, or at the end of the configured duration of the SAML token,
whichever comes first. For example, if the configured duration is three days for the HTTP bearer token
and two days for the SAML token, the HTTP bearer token expires in two days. A configuration setting on
the SSO server determines the duration of SAML tokens.
Prerequisites
n
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specified
when you deployed the appliance.
n
The /etc/vcac/security.properties file on the appliance must be editable.
Procedure
1Open the /etc/vcac/security.properties file for editing.
2Add the following lines to the file, where N is an integer specifying the duration of the token in hours.
identity.basic.token.lifetime.hours=N
#The number is in hours.
3Save and close the file.
4Log out of the vRealize Automation appliance.
The new value applies the next time someone requests an HTTP bearer token.
Request an HTTP Bearer Token
You use an HTTP bearer token to authenticate a vRealize Automation REST API consumer request .
A consumer request must specify the correct component registry service and resource. For example, the
URL to obtain an HTTP bearer token must specify the identity service and token resource.
The HTTP bearer token expires in 24 hours by default. See Configure the Duration of an HTTP Bearer
Token for information on how to set the duration.
For related information, see Syntax for Requesting an HTTP Bearer Token.
Prerequisites
n
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a
role, log in as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc. 11
Programming Guide
Procedure
u
Enter a curl command in the following format, replacing the variables with the correct values.
The variable $vRA used in this example represents the host name.domain name of the
vRealize Automation server, for example, mycompany.mktg.mydomain.com.
Include the HTTP bearer token in your REST API service calls. You can store the token in a variable such
as $AUTH and then use the variable in your requests.
Syntax for Requesting an HTTP Bearer Token
An HTTP bearer token is required by the REST client to use the vRealize Automation REST API. You can
obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 12
Programming Guide
A consumer request must specify the correct component registry service and resource. For example, the
URL to obtain an HTTP bearer token must contain the identity service and token resource values.
InputDescription
hosthost name.domain name of the vRealize Automation server, for example,
mycompany.mktg.mydomain.com.
usrnameSpecifies the tenant administrator user name.
passwdSpecifies the tenant administrator password.
tenantURLtokenSpecifies 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.
OutputDescription
expiresContains the ISO 8601 timestamp indicating when the token expires.
idContains the HTTP bearer token to use in Authorization header in subsequent requests.
tenantDisplays the tenant ID associated with the token.
Response Status Codes
One of the following codes are displayed as a result of your HTTP bearer token request.
Status CodeDescription
200 OKYour request succeeded and the resource was updated. The
response body contains the full representation of the resource.
400 BAD REQUESTThe data you provided in the POST failed validation. Inspect the
response body for details.
401 UNAUTHORIZEDThe request could not authenticate the user or authentication
credentials required.
Example: curl Command
You can enter the following command line format to request an HTTP bearer token.
When your request succeeds, the system returns the 200 OK status code, the expiration date and time of
the token, and the HTTP bearer token. After receiving the bearer token, you can include it in your request
headers.
VMware, Inc. 13
Programming Guide
Validate an HTTP Bearer Token
You can validate an existing HTTP bearer token.
Prerequisites
n
Request an HTTP Bearer Token.
Procedure
u
Create the request to validate the HTTP bearer token, as in the following example.
The system returns one of the following status codes.
VMware, Inc. 14
Programming Guide
Status CodeDescription
204 NO CONTENTThe request succeeded. The resource has been deleted.
401 UNAUTHORIZEDYou must have authentication credentials to access the resource. All requests must be
authenticated.
403 FORBIDDENYour authentication credentials do not provide sufficient access to the resource.
404 NOT FOUNDCould not locate the resource based on the specified URI.
405 METHOD NOT ALLOWEDThe DELETE method is not supported for the resource.
500 SERVER ERRORCould not create or update the resource because of an internal server error.
VMware, Inc. 15
REST API Use Cases3
Available use cases provide the prerequisite, command line options and format, and sample results to
help you perform a variety of vRealize Automation functions, such as requesting a machine or creating a
reservation.
You can find information about all of the available vRealize Automation REST API calls in the vRealizeAutomation API Reference zip file located in the vRealize Automation Documentation Center. The use
cases provide samples of calls that you might commonly use and descriptions of example inputs and
outputs relative to those calls.
n
Create a Tenant
You can use the REST API identity service to create a vRealize Automation tenant and perform
related functions. Perform the tasks required to create a tenant with the REST API in sequence. For
information about creating and working with tenants and roles by using thevRealize Automation
application user interface, see the Tenant Administration and IaaS Configuration documentation.
n
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.
n
Approve a Machine Request
You can use a sequence of REST API workitem service commands to approve a machine request.
n
List Provisioned Resources
You can use the REST API catalog service to log in to vRealize Automation and display a full or
filtered list of your provisioned resources .
n
Manage Provisioned Deployments
You can use the REST API catalog service to log in to vRealize Automation and view information
about provisioned resources .
n
Working with Reservations
You can work with the REST API reservation service to perform a variety of functions, such as
creating and updating reservations.
VMware, Inc.
16
Programming Guide
n
Working with Reservation Policies
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.
n
Working with Key Pairs
You can work with the keyValuePair data element of the REST API workitem service to list, create,
and update key pairs.
n
Working with Network Profiles
You can use the vRealize Automation IaaS proxy provider service and IPAM service REST API to
create, list, and update network profiles.
n
Get a List of Available IP Ranges for an IPAM Provider
You can query a specified IPAM provider endpoint for a list of the available IP address ranges
configured on the IPAM provider device.
n
Import and Export Content
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 Configuration documentation.
Prerequisites
n
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity
server.
n
Verify that the identity server details required for the JSON template are available.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
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.
n
Syntax for Requesting a New Tenant
You can use the REST API identity service to submit a request for a tenant. You can specify request
parameters using JSON command line input or by calling an existing JSON file from the command
line.
VMware, Inc. 17
Programming Guide
n
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.
n
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.
n
Syntax for Searching LDAP or Active Directory for a User
You can use the vRealize Automation REST API identity service to search the configured LDAP
directory, Active Directory, or Native Active Directory for a user.
n
Syntax for Assigning a User to a Role
You can use the REST API identity service to assign a user to a role.
n
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.
Procedure
1Use the identity service to display all the available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
2Submit a request for a new tenant and either call a JSON file that contains tenant request parameters
or specify those parameters using inline text. The first example uses a JSON file as input. The
second example uses inline text as input.
The first example calls the following sample newTenant.json file.
--data
'{"@type":"Tenant","id":"development","urlName":"development","
name":
"DevelopmentTenant","description":"Tenant for all
developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'
3List 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.
Use the following command to call the example JSON text file and link an identity store to a tenant.
The command also tests that vRealize Automation can connect to the identity store successfully. If
the command finishes successfully, vRealize Automation succeeded in connecting to the identity
store.
6Assign 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
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.
VMware, Inc. 20
Programming Guide
ParameterDescription
URLhttps://$host/identity/api/tenants
$hostSpecifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 21
Programming Guide
ParameterDescription
LinksSpecifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
Specifies the application or service that determines the
other names.
n
href
Specifies the URL that produces the result.
ContentSpecifies an array of data rows, each of which represents one of
the tenant objects returned in a pageable list. Each tenant object
can contain the following information:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
Specifies the name of the tenant as it appears in URLs.
n
Name:
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
Specifies the primary contact email address.
n
Password:
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
MetadataSpecifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
VMware, Inc. 22
Programming Guide
Example: curl Command
The following example command displays all available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
Format the XML output to improve its readability. For information about formatting output, see Chapter 5
Filtering and Formatting REST API Information.
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "Tenant",
"id" : "vsphere.local",
"urlName" : "vsphere.local",
"name" : "vsphere.local",
"description" : null,
"contactEmail" : null,
"password" : null,
"defaultTenant" : true
}, {
"@type" : "Tenant",
"id" : "MYCOMPANY",
"urlName" : "MYCOMPANY",
"name" : "QETenant",
"description" : "Test tenant",
"contactEmail" : null,
"password" : "defaultPwd#1",
"defaultTenant" : false
} ],
"metadata" : {
"size" : 19,
"totalElements" : 2,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
Syntax for Requesting a New Tenant
You can use the REST API identity service to submit a request for a tenant. You can specify request
parameters using JSON command line input or by calling an existing JSON file from the command line.
VMware, Inc. 23
Programming Guide
Input
Use the supported input parameters to control the command output.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
$hostSpecifies the host name and fully qualified domain name or IP address
of the vRealize Automation identity server.
$tenantIdSpecifies the ID of the tenant.
$tenantURLSpecifies the URL of the tenant.
$tenantNameSpecifies the name of the tenant.
$descriptionSpecifies a description of the tenant.
$emailAddressSpecifies the contact email address for the tenant.
JSON Input File Template
To simplify command line input, create a JSON file and call that file from the command line. To create a
JSON file, copy the following template to a new text file. To maintain formatting, use an XML editor.
Replace the italicized variables in the template with your specific values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 24
Programming Guide
ParameterDescription
LinksSpecifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
Specifies the application or service that determines the
other names.
n
href
Specifies the URL that produces the result.
ContentSpecifies an array of data rows, each of which represents one of
the tenant objects returned in a pageable list. Each tenant object
can contain the following information:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
Specifies the name of the tenant as it appears in URLs.
n
Name:
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
Specifies the primary contact email address.
n
Password:
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
MetadataSpecifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
VMware, Inc. 25
Programming Guide
Example: curl Command
Submit a request for a new tenant and either call a JSON file that contains tenant request parameters or
specify those parameters using inline text. The first example uses a JSON file as input. The second
example uses inline text as input.
The first example calls the following sample newTenant.json file.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Example 1: Use the following example to call the above newTenant.json file, which contains parameters
for the tenant request.
"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.
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.
The following example command calls the example JSON text file and links an identity store to a tenant.
The command also tests that vRealize Automation can connect to the identity store successfully. If the
command finishes successfully,vRealize Automation succeeded in connecting to the identity store.
The following output indicates that an identity store is not linked to the specified tenant. To resolve the
problem, correct the identity store and connection details in the JSON input file and rerun the command.
Source: null}, {Error Msg: Cannot connect to the directory service.}, {System
Msg: 90027-Connection to directory service can’t be established}
Syntax for Searching LDAP or Active Directory for a User
You can use the vRealize Automation REST API identity service to search the configured LDAP directory,
Active Directory, or Native Active Directory for a user.
Input
Use the supported input parameters to control the command output.
$hostSpecifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
$tenantIdSpecifies the ID of the tenant.
$principalIdSpecifies the ID of the user in name@domain format.
$roleIdSpecifies the ID of the user role.
Example: curl Command
The following example command string submits a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the required
JSON payload. See Syntax for Searching LDAP or Active Directory for a User for more information about
getting the user name and domain values.
"description" : "Entitle services, catalog items and actions to all users within a tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "FILE_EDIT_TENANT",
"name" : "Manage Tenant Files",
"description" : "Upload and delete files belonging to this tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "TENANT_USER_DATA_MANAGEMENT",
"name" : "Manage user data (requests, items, tasks etc) within a tenant.",
"description" : "Manage user created objects belonging to the tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "TENANT_ADMIN_ROLE_ASSIGNMENT",
"name" : "Tenant Administrator Role Assignment",
"description" : "Assign the tenant administrator role to other users.",
"prereqAdminPermissions" : null
}, {
"id" : "GUI_MY_TENANT_TUG_MANAGEMENT",
"name" : "My Tenant Identity Stores, Groups and Users Administration User Interfaces",
"description" : "Access my tenant identity stores, groups and users administration GUIs.",
"prereqAdminPermissions" : null
} ]
} ],
"metadata" : {
"size" : 20,
VMware, Inc. 37
Programming Guide
"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.
For example, catalog-service/api/consumer/entitledCatalogItems/ dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template. Users can employ the returned template, either as is or
modified, 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
n
Log in to vRealize Automation as a consumer and current business group user.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
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 specific business group. Also, this service
retrieves a list of all shared and private catalog items that can be viewed, including their business
groups.
n
Syntax for Getting Information for a Catalog Item
You can use the REST API catalog service to get information about a specific catalog item if desired.
n
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 different types of machine requests.
VMware, Inc. 38
Programming Guide
n
Syntax for Requesting a Machine
You can use the REST API catalog service to submit a machine request.
n
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.
Procedure
1List 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.
The template request returned in preceding step is specific to the catalog item that corresponds to
your template request. The fields and default values are populated based on the configuration of the
underlying blueprint.
VMware, Inc. 39
Programming Guide
Review the contents of the template and edit the values if you want to change them from the default
prior to submitting the request. For example, you can specify a value for the description field or
change the values for the machine resources if the blueprint allows for a range.
The status information is particularly noteworthy in the request details. The phase field 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 specific business group. Also, this service retrieves
a list of all shared and private catalog items that can be viewed, including their business groups.
Input
Use the supported input parameters to control the command output.
$hostSpecifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
page numberThe page number. Default is 1.
limitThe number of entries per page. The default is 20.
VMware, Inc. 40
Programming Guide
ParameterDescription
$orderbyMultiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
$topSets the number of returned entries from the top of the response
$skipSets the number of entries to skip.
$filterBoolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
serviceId(Optional) Query parameter to filter the returned catalog items by one specific service.
onBehalfOf(Optional) Query parameter that provides the value of the user ID when making a request on
behalf of another user.
VMware, Inc. 41
Programming Guide
Output
The command output contains property names and values based on the command input parameters.
PropertyDescription
outputResourceTypeRefSpecifies the type of the resource that results from requesting the catalog item.
catalogItemIdSpecifies the catalog item identifier.
nameSpecifies the user friendly name of the catalog item. Specifies the property type is string.
descriptionSpecifies a short description of the catalog item. Specifies the property type is string.
catalogItemTypeRefSpecifies the type of the catalog item.
serviceRefSpecifies the catalog service that contains the catalog item.
iconIdSpecifies the associated icon representing this item.
isNoteworthySpecifies if the catalog item should be highlighted to users for a period of time.
dateCreatedSpecifies the date that this item was created in the catalog.
lastUpdatedDateSpecifies the date that this item was last updated in the catalog.
entitledOrganizationsSpecifies 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.
You can use the REST API catalog service to get information about a specific catalog item if desired.
REST API Catalog Service
The REST API supports OData filtering. For more information about supported OData filters, refer to the
vRealize Automation API Reference, particularly the REST API Tips page located at
https://$host/component-registry/services/docs/odata.html.
VMware, Inc. 43
Programming Guide
For specific information about catalog service filters, 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.
$hostSpecifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
page numberThe page number. Default is 1.
limitThe number of entries per page. The default is 20.
$orderbyMultiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
$topSets the number of returned entries from the top of the response
$skipSets the number of entries to skip.
VMware, Inc. 44
Programming Guide
ParameterDescription
$filterBoolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/id - filter based on catalog item icon ID.
serviceId(Optional) Query parameter to filter the returned catalog items by one specific service.
onBehalfOf(Optional) Query parameter that provides the value of the user ID when making a request on
behalf of another user.
Output
The command output contains property names and values based on the command input parameters.
PropertyDescription
outputResourceTypeRefSpecifies the type of the resource that results from requesting the catalog item.
catalogItemIdSpecifies the catalog item identifier.
nameSpecifies the user friendly name of the catalog item. Specifies the property type is string.
descriptionSpecifies a short description of the catalog item. Specifies the property type is string.
catalogItemTypeRefSpecifies the type of the catalog item.
serviceRefSpecifies the catalog service that contains the catalog item.
iconIdSpecifies the associated icon representing this item.
isNoteworthySpecifies if the catalog item should be highlighted to users for a period of time.
dateCreatedSpecifies the date that this item was created in the catalog.
lastUpdatedDateSpecifies the date that this item was last updated in the catalog.
entitledOrganizationsThe list of organizations in which the current user can consume the catalog item.
VMware, Inc. 45
Programming Guide
Example Curl Command
The following example command retrieves information about all the available shared catalog items of the
type ConsumerEntitledCatalogItemView.
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 different types of machine requests.
Overview
In the entitledCatalogItemViews response, there is a link field that contains a value similar to the
following:
This URL is a HATEOAS link for a template request for this catalog item. The rel field provides a
description of the link (request template) and indicates the HTTP method to use with the URI in the href
field (GET). By using these HATEOAS links, you can make follow-on API calls without having to consult
the API documentation for the URI syntax or construct the links programmatically.
Review and Edit the Template Request
The returned template request is specific to the applicable catalog item. The fields and default values are
populated based on the configuration of the underlying blueprint.
You can review the contents of the template and optionally edit the values if you want to change them
from the default prior to submitting the request. For example, you can specify a value for the description
field or change the values for the machine resources if the blueprint allows for a range.
VMware, Inc. 47
Programming Guide
Input
Use the supported input parameters to control the command output.
ParameterDescription
idThe UUID of the catalog item.
Output
The command output contains property names and values based on the command input parameters.
PropertyDescription
entitledOrganizationsThe list of organizations in which the current user can consume the catalog item.
catalogItemIdSpecifies the catalog item identifier.
Example Curl Command
The following example command retrieves the catalog item with an ID of dc808d12-3786-4f7c-b5a1d5f997c8ad66.
requestDataContains a map of the provider-specific field-value pairs collected for this request.
retriesRemaningSpecifies the number of attempts remaining to move this request from its current state to the
next state in the request workflow.
Some state transitions require calls to external services. These calls may fail due to transient
errors such as momentary network errors. In these cases, the catalog will retry the call a
number of times before failing.
This property defines the number of retries remaining for the current state transition. When it
reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset to
the default number of retries for every new operation that is triggered.
requestedItemNameSpecifies the item name.
VMware, Inc. 52
Programming Guide
PropertyDescription
requestedItemDescriptionSpecifies the item description.
componentsReturns the list of components associated with the request. The provider supplies this 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 Getting a Template Request for a Catalog Item, locate a link field that
contains a value similar to the following:
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 field
corresponds to the status displayed in the Requests tab in the interface. You can rerun this command
multiple times to monitor the state of a machine request.
Table 3‑1. Request Phase Status
PhaseDescriptionEnd State?
UNSUBMITTEDRequest was saved but not submitted.No
PENDING_PRE_APPROVALRequest is subject to approval - pre-provisioning approval required. No
IN_PROGRESSRequest is in progress, machine is being provisioned.No
PENDING_POST_APPROVALRequest is subject to approval, post-provisioning approval
required.
SUCCESSFULRequest completed successfully. The machine is available under
provisioned resources on the Items tab.
FAILEDRequest failed.Yes
REJECTEDRequest approval was rejected and will not complete.Yes
No
Yes
Input
Use the supported input parameters to control the command output.
requestDataContains a map of the provider-specific field-value pairs collected for this request.
retriesRemaningSpecifies the number of attempts remaining to move this request from its current state to the
next state in the request workflow.
Some state transitions require calls to external services. These calls may fail due to transient
errors such as momentary network errors. In these cases, the catalog will retry the call a
number of times before failing.
This property defines the number of retries remaining for the current state transition. When it
reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset to
the default number of retries for every new operation that is triggered.
requestedItemNameSpecifies the item name.
VMware, Inc. 55
Programming Guide
PropertyDescription
requestedItemDescriptionSpecifies the item description.
componentsReturns 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.
"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
n
Log in to vRealize Automation as an approver with at least one of the following qualifications:
n
You are designated as an approver in an approval policy.
n
You belong to a group which has been designated as an approval group in an approval policy.
n
You are designated as a delegate for someone who is an approver.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
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.
n
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.
n
Syntax for Constructing a JSON File to Approve a Machine Request
You can specify a JSON file in your vRealize Automation REST API command line input. For
example, when you enter a command to approve a machine request, you can include the name of a
JSON file that contains all the parameters required to approve the request and complete the work
item.
n
Syntax for Approving a Submitted Machine Request
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 file, and call that JSON file from the command line. Use a template to correctly format the
JSON file content.
VMware, Inc. 57
Programming Guide
n
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 specific request. For
example, if the blueprint allows for a range of CPU, memory, or storage values, the cost depends on
the value requested.
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.
Syntax for Constructing a JSON File to Approve a Machine
Request
You can specify a JSON file in your vRealize Automation REST API command line input. For example,
when you enter a command to approve a machine request, you can include the name of a JSON file that
contains all the parameters required to approve the request and complete the work item.
VMware, Inc. 69
Programming Guide
Template JSON File Values
Copy the following template to start constructing a properly formatted JSON file in a text editor. Replace
the highlighted values with your obtained work item details. After you create the JSON file, you can
include it, or its contents, when you approve a submitted machine request. See Syntax for Approving a
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 file,
and call that JSON file from the command line. Use a template to correctly format the JSON file content.
Input
Use the supported input parameters to control the command output.
{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 specific 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.
ParameterDescription
URL
MethodPost
$hostSpecifies the host name and fully qualified domain name or IP
//$host/composition-
service/api/blueprints/$BlueprintId/costs/upfront
address of the vRealize Automation identity server.
VMware, Inc. 75
Programming Guide
ParameterDescription
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
HTTP BodySpecifies the blueprint ID for the blueprint for which you are
requesting cost information and other information.
n
Blueprint ID: Specifies the blueprint ID.
n
requestedFor: The user for whom this request is being made.
Must be the fully qualified user ID.
n
subTenantId: Specifies the subtenant ID associated with the
blueprint
n
requestData: Specifies data that identifies the blueprint further.
n
entries
n
Key: The name of the machine on which the blueprint
resides.
n
value: Specifies key-value pairs that further identify the
blueprint, such as the type of the value, the
componentType ID for the item, the classID of the
value, and where the blueprint resides. In turn, each
entry contains an array of key-value pairs that identify
the type of data used to compute the cost that is to be
displayed.
n
Values: Specifies an array of type filters.
n
Entries: Specifies a list of key-value pairs that
specify the values to be used in computing the 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.
PropertyDescription
setupFeeSpecifies the one time setup fee associated with the component.
totalLeasePriceInfoSpecifies the minimum cost and maximum cost for the lease
period.
averageDailyPriceInfoSpecifies the average daily price, which depends on the
reservation available for the component.
countSpecifies the instance count of the component.
memorySpecifies memory requested for this component.
additionalSpecifies the additional cost, if any, associated with the
component.
cpuSpecifies the cpu requested for the component.
storageSpecifies the storage requested for the component.
componentIdSpecifies the component ID, or total cost of the deployment.
VMware, Inc. 76
Programming Guide
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.
You can use the REST API catalog service to log in to vRealize Automation and display a full or filtered
list of your provisioned resources .
Prerequisites
n
Log in to vRealize Automation as a business group manager.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the business group subtenant ID values to specify on the command line. See Syntax for
Displaying Your Provisioned Resources.
n
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.
n
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 filtered by machine resource type.
n
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.
n
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 filter the list by business group name.
VMware, Inc. 78
Programming Guide
n
Syntax for Viewing Machine Details
You can use the vRealize Automation REST API catalog service to display the machine details for a
provisioned machine.
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.
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 filter the list by business group name.
Input
Use the supported input parameters to control the command output.
You can use the vRealize Automation REST API catalog service to display the machine details for a
provisioned machine.
VMware, Inc. 93
Programming Guide
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:
See Syntax for Viewing Details of a Machine Request.
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 3‑3. HATEOAS Link Functions as Defined by rel Field
LinkDescription
GET: Catalog ItemURI to get the catalog item details (as described in sections 3.2.1 and
3.2.2) from which this catalog item was provisioned.
GET: RequestURI to get the request details that provisioned this item.
$hostSpecifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
$resourceIDSpecifies a resource ID. See Syntax for Displaying Your Provisioned Resources to view all of
your requests and search for a request ID.
managedOnlyIf true, the returned requests are from the user's managed subtenants.
pageSpecifies a page number.
limitSpecifies the number of entries to display on a page.
VMware, Inc. 94
Programming Guide
ParameterDescription
$orderbySpecifies how to order multiple comma-separated properties sorted in ascending or descending
order.
$topSpecifies the number of returned entries from the top of the response (total number per page in
relation to skip).
$skipSpecifies the number of entries to skip.
filterContains 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.
PropertyDescription
idSpecifies the unique identifier of this resource.
iconIdSpecifies an icon for this request based on the requested object type.
resourceTypeRefSpecifies the resource type.
nameSpecifies the resource name.
descriptionSpecifies the resource description.
statusSpecifies the resource status.
catalogItemSpecifies the catalog item that defines the service this resource is based on.
requestIdSpecifies the request ID that provisioned this resource.
providerBindingSpecifies the provider binding.
ownersSpecies the owners of this resource.
organizationSpecifies the subtenant or tenant that owns this resource.
dateCreatedSpecifies the data and time at which the resource was created.
lastUpdatedSpecifies the date and time at which the resource was most recently modified.
hasLeaseReturns true if the resource is subject to a lease.
leaseDisplays the resource's current lease as start and end time stamps.
leaseForDisplaySpecifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCostsReturns true if the resource is subject to per-time costs.
costsDisplays an optional rate of the cost charges for the resource.
costToDateDisplays an optional rate of the current cost charges for the resource.
totalCostDisplays an optional rate of the cost charges for the entire lease period.
parentResourceRefDisplays the parent of this resource.
childResourcesDisplays the children of this resource.
operationsSpecifies the sequence of available operations that can be performed on this resource.
formsSpecifies the forms used to render this resource.
resourceDataDisplays the extended provider-defined properties of the resource.
VMware, Inc. 95
Programming Guide
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.
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.
n
Log in to vRealize Automation as a business group manager.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc. 97
Programming Guide
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the business group subtenant ID values to specify on the command line. See Syntax for
Getting Deployment Details.
n
Syntax for Getting Deployment Details
You can use the REST API catalog service to identify provisioned items from a given request.
n
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 configured on the blueprint canvas.
n
Perform a Day 2 Action: Power Off
You can use the REST API catalog service to perform a power off action. For simple actions that
require no user input, the process is straightforward.
n
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 submitting the request.
You can modify the HATEOAS links to complete more complex day 2 actions that require user
input, such as changing a lease. Use a command like the following to get the template for the
resource action request.
You can use the REST API catalog service to identify provisioned items from a given request.
VMware, Inc. 99
Programming Guide
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:
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 3‑4. HATEOAS Link Deployment Details Functions
LinkDescription
GET: Catalog ItemURI to get the catalog item details from which this catalog item was
provisioned. See Syntax for Viewing Details of a Machine Request.
GET: RequestURI to get the request details that provisioned this item.