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:
hp://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:
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
Contents
vRealize Automation Programming Guide5
Overview of the vRealize Automation REST API7
1
REST API Authentication9
2
Using HTTP Bearer Tokens 9
Congure 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 Cases15
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 Geing Information for a Catalog Item 38
Syntax for Geing 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 Geing Work Item Details 57
Syntax for Constructing a JSON File to Approve a Machine Request 62
Syntax for Approving a Submied 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 Geing 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 Proles 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 Prole List 287
Create a Network Prole 303
Query a Network Prole 307
Update a Network Prole 313
Delete a Network Prole 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 Documentation357
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 Formaing REST API
5
Information361
Index363
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 congure 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 AutomationAPI Reference at hps://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 denitions
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 oers the following services and functions.
Table 1‑1. vRealize Automation REST API Services
ServiceDescription
Approval ServiceRetrieve, create, update, and delete approval policies, policy types,
policy instances, and policy requests.
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 Conguration 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.
Identity ServiceManage tenants, business groups, SSO and custom groups, users,
and identity stores.
VMware, Inc. 7
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
ServiceDescription
IP Address Management ServiceAllocate and deallocate IP addresses from IP address management
Licensing ServiceRetrieve permissions and post serial keys.
Management Service (Reclamation Service)Retrieve work item forms, callbacks, and tasks. Manage endpoint
Network ServiceAccess and manage application network and security seings for
Notication ServiceCongure and send notications for several types of events such as
Orchestration Gateway ServiceProvides a gateway to VMware Realize Orchestrator (vRO) for
Extensibility (Plug-in) ServiceRetrieve, create, update, and delete a resource. Retrieve an
Portal ServiceRetrieve, create, update, and delete a portal resource.
Properties ServiceManage custom properties, property groups, and property
Reservation ServiceRetrieve, create, update, and delete a reservation or reservation
Software ServicesTriggers the execution life cycle of software components using the
vRA Orchestrator ServiceManage vRealize Orchestrator actions, tasks, packages, and
Work Item ServiceRetrieve, create, update, complete, cancel, and delete a work item.
XaaS ServiceManages 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 conguring NAT and routed networks; creating load
balancers; and adding and conguring 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
workows or script actions without having to deal directly with the
vRO APIs.
extension. Retrieve license notications.
denitions. Properties specify items that can be added to blueprints
to trigger vRealize Orchestrator actions.
policy.
software agent, registers software agents, and manages the
creation, modication and deletion of software componentsoftware
component types, software resource requests, and nodes
(machines).
workows. Browse system and plug-in inventories.
Also retrieve form data, metadata, detail forms, and submission
forms from service providers.
tenants, vRealize Orchestrator imports, workows, and work items.
The advanced designer service selection on the vRealize AutomationAPI Reference landing page selects the documentation for the XaaS
service.
When a service request contains a resource URL, the rst part of the URL identies the service and the last
part identies the resource. For example, the following resource URL identies 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 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 congure the token with a dierent 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.propertiesle on the
vRealize Automation appliance.
The eective 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 congured duration, or at the end of the congured duration of the SAML token, whichever
comes rst. For example, if the congured 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 congurationseing 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 specied
n
when you deployed the appliance.
The /etc/vcac/security.propertiesle on the appliance must be editable.
n
Procedure
1Open the /etc/vcac/security.propertiesle for editing.
2Add 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.
3Save and close the le.
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 “Congure 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 qualied 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.
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.
InputDescription
hosthost name.domain name of the vRealize Automation server, for example,
mycompany.mktg.mydomain.com.
usrnameSpecies the tenant administrator user name.
passwdSpecies the tenant administrator password.
tenantURLtokenSpecies 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.
VMware, Inc. 11
Programming Guide
Status CodeDescription
200 OKYour request succeeded and the resource was updated. The
400 BAD REQUESTThe data you provided in the POST failed validation.
401 UNAUTHORIZEDThe request could not authenticate the user or
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.
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.
The system returns one of the following status codes.
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 sucient access to the resource.
404 NOT FOUNDCould not locate the resource based on the specied 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. 13
Programming Guide
14 VMware, Inc.
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 nd information about all of the available vRealize Automation REST API calls in the vRealizeAutomation 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 Conguration 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 Proles 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 proles.
Get a List of Available IP Ranges for an IPAM Provider on page 316
n
You can query a specied IPAM provider endpoint for a list of the available IP address ranges
congured 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 Conguration 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 qualied 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 congured LDAP
directory, Active Directory, or Native Active Directory for a user.
16 VMware, Inc.
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
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 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.jsonle.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
ExamplesCommand
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.
--data
'{"@type":"Tenant","id":"development","urlName":"developmen
t","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 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.
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 domainexample.mycompany.com to the tenant administrator role. It provides empty braces for the required JSON
payload.
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.
ParameterDescription
URLhps://$host/identity/api/tenants
$hostSpecies the host name and fully qualied domain name or IP address
of the vRealize Automation identity server.
$tokenSpecies 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.
ParameterDescription
LinksSpecies an array of link objects, each of which contains the
following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
ContentSpecies 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
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
MetadataSpecies the following paging-related data:
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a
single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species 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 formaing output, see Chapter 5,
“Filtering and Formaing 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.
$tokenSpecies a valid HTTP bearer token with necessary credentials.
$hostSpecies the host name and fully qualied domain name or IP
address of the vRealize Automation identity server.
$tenantIdSpecies the ID of the tenant.
$tenantURLSpecies the URL of the tenant.
$tenantNameSpecies the name of the tenant.
$descriptionSpecies a description of the tenant.
$emailAddressSpecies 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 formaing, use an XML editor. Replace
the italicized variables in the template with your specic values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 21
Programming Guide
ParameterDescription
LinksSpecies an array of link objects, each of which contains the
ContentSpecies an array of data rows, each of which represents
MetadataSpecies the following paging-related data:
following parts:
rel
n
Species 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 prole.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species 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
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species 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: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a
single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species 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.
22 VMware, Inc.
Chapter 3 REST API Use Cases
The rst example calls the following sample newTenant.jsonle.
{
"@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.jsonle, 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 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.
The following output indicates that an identity store is not linked to the specied tenant. To resolve the
problem, correct the identity store and connection details in the JSON input le 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 congured LDAP directory,
Active Directory, or Native Active Directory for a user.
Input
Use the supported input parameters to control the command output.
"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 modied, to create
an appropriate request. The user then POSTs, or PUTs, the request to the target API. For example, catalog-
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 qualied 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 specic 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 Geing Information for a Catalog Item on page 38
n
You can use the REST API catalog service to get information about a specic catalog item if desired.
Syntax for Geing 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 dierent 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
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 specic to the catalog item that corresponds to your
template request. The elds and default values are populated based on the conguration 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 submiing 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.
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 specic 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.
You can use the REST API catalog service to get information about a specic 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
For specic 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.
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 dierent types of machine requests.
Overview
In the entitledCatalogItemViews response, there is a link eld that contains a value similar to the following:
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 hrefeld (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 specic to the applicable catalog item. The elds and default values are
populated based on the conguration 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 submiing 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.
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.
catalogItemIdSpecies the catalog item identier.
VMware, Inc. 41
Programming Guide
Example Curl Command
The following example command retrieves the catalog item with an ID of dc808d12-3786-4f7c-b5a1-
requestDataContains a map of the provider-speciceld-value pairs collected for this request.
retriesRemaningSpecies the number of aempts remaining to move this request from its current state to
requestedItemNameSpecies the item name.
requestedItemDescriptionSpecies the item description.
componentsReturns 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 workow.
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 denes 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 Geing a Template Request for a Catalog Item,” on page 41, locate a link
eld 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 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 3‑1. Request Phase Status
PhaseDescriptionEnd State?
UNSUBMITTEDRequest was saved but not submied.No
PENDING_PRE_APPROVALRequest is subject to approval - pre-provisioning approval
required.
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
No
Yes
Input
Use the supported input parameters to control the command output.
requestDataContains a map of the provider-speciceld-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 Locationeld of the response header if you submied
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
PropertyDescription
retriesRemaningSpecies the number of aempts remaining to move this request from its current state to
the next state in the request workow.
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 denes 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.
requestedItemNameSpecies the item name.
requestedItemDescriptionSpecies 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
Log in to vRealize Automation as an approver with at least one of the following qualications:
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 qualied 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 Geing 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 Submied 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.
50 VMware, Inc.
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 specic 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 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 formaed 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 submied machine request. See “Syntax for Approving a Submied
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.
{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 specic 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
$hostSpecies the host name and fully qualied domain name or IP
$tokenSpecies a valid HTTP bearer token with necessary
HTTP BodySpecies the blueprint ID for the blueprint for which you are
address of the vRealize Automation identity server.
credentials.
requesting cost information and other information.
n
Blueprint ID: Species the blueprint ID.
n
requestedFor: The user for whom this request is being
made. Must be the fully qualied user ID.
n
subTenantId: Species the subtenant ID associated with
the blueprint
n
requestData: Species data that identies the blueprint
further.
n
entries
n
Key: The name of the machine on which the
blueprint resides.
n
value: Species 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: Species an array of type lters.
n
Entries: Species 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
PropertyDescription
setupFeeSpecies the one time setup fee associated with the
totalLeasePriceInfoSpecies the minimum cost and maximum cost for the
averageDailyPriceInfoSpecies the average daily price, which depends on the
countSpecies the instance count of the component.
memorySpecies memory requested for this component.
additionalSpecies the additional cost, if any, associated with the
cpuSpecies the cpu requested for the component.
storageSpecies the storage requested for the component.
componentIdSpecies 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.
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 qualied 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.
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 lter 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.
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,” 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 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
GET: RequestURI to get the request details that provisioned this item.
$hostSpecies the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$tokenSpecies a valid HTTP bearer token with necessary credentials.
$resourceIDSpecies 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.
managedOnlyIf true, the returned requests are from the user's managed subtenants.
pageSpecies a page number.
limitSpecies the number of entries to display on a page.
$orderbySpecies how to order multiple comma-separated properties sorted in ascending or
descending order.
$topSpecies 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
ParameterDescription
$skipSpecies the number of entries to skip.
lterContains 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
idSpecies the unique identier of this resource.
iconIdSpecies an icon for this request based on the requested object type.
resourceTypeRefSpecies the resource type.
nameSpecies the resource name.
descriptionSpecies the resource description.
statusSpecies the resource status.
catalogItemSpecies the catalog item that denes the service this resource is based on.
requestIdSpecies the request ID that provisioned this resource.
providerBindingSpecies the provider binding.
ownersSpecies the owners of this resource.
organizationSpecies the subtenant or tenant that owns this resource.
dateCreatedSpecies the data and time at which the resource was created.
lastUpdatedSpecies the date and time at which the resource was most recently modied.
hasLeaseReturns true if the resource is subject to a lease.
leaseDisplays the resource's current lease as start and end time stamps.
leaseForDisplaySpecies the resource's current lease, #getLease, with time units synchronized with
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.
operationsSpecies the sequence of available operations that can be performed on this resource.
formsSpecies the forms used to render this resource.
resourceDataDisplays the extended provider-dened 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.
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 qualied 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 Geing
n
Deployment Details,” on page 89.
Syntax for Geing 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 congured 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.
VMware, Inc. 87
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 submiing the request.
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:
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,” on page 47.
GET: RequestURI to get the request details that provisioned this item.
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 congured 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 3‑6. HATEOAS Link Functions as Defined by rel Field
This POST command returns a response indicating success or failure, such as HTTP/1.1 201 CREATED for
success.
VMware, Inc. 99
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 submiing 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.
2Edit 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...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.