Identity Service Examples for Creating a Tenant 25
Syntax for Displaying Your Current Tenants 26
Syntax for Requesting a New Tenant 28
Syntax for Listing All Tenant Identity Stores 31
Syntax for Linking an Identity Store to the Tenant 33
Syntax for Searching LDAP or Active Directory for a User 37
Syntax for Assigning a User to a Role 38
Syntax for Displaying all Roles Assigned to a User 39
VMware, Inc.
Requesting a Machine42
4
Request a Machine 42
Catalog Service Examples for Requesting a Machine 44
Syntax for Listing Shared and Private Catalog Items 44
Syntax for Getting Information for a Catalog Item 48
Syntax for Getting a Template Request for a Catalog Item 52
Syntax for Requesting a Machine 55
Syntax for Viewing Details of a Machine Request 59
3
Programming Guide
Approving a Machine Request63
5
Approve a Machine Request 63
Work Item Service Examples for Approving a Machine Request 64
Syntax for Listing Work Items 65
Syntax for Getting Work Item Details 71
Syntax for Constructing a JSON File to Approve a Machine Request 76
Syntax for Approving a Submitted Machine Request 79
Syntax for Updating Price Information 81
Listing Provisioned Resources85
6
Prerequisites for Listing Provisioned Resources 85
Display Your Provisioned Resources Example 85
Display Provisioned Resources by Resource Type Example 89
Display All Available Resource Types Example 92
Display Provisioned Resources by Business Groups You Manage Example 94
View Machine Details Example 103
Managing Provisioned Deployments107
7
Manage Provisioned Deployments 107
Power Off 108
Change Lease 109
Catalog Service Examples for Managing Provisioned Deployments 111
Syntax for Getting Deployment Details 111
Syntax for Navigating to the Children of a Deployed Resource 115
Working with Reservations122
8
Prerequisites for Working With Reservations 123
Create a Reservation 123
Display a List of Supported Reservation Types 124
Displaying a Schema Definition for a Reservation 127
Get the Business Group ID for a Reservation 153
Get a Compute Resource for the Reservation 155
Getting a Resources Schema by Reservation Type 158
Creating a Reservation By Type 162
Verify a Reservation and Get Reservation Details 173
Display a List of Reservations 181
Update a Reservation 186
Delete a Reservation 191
Service Examples for Working with Reservations 191
Syntax for Displaying a List of Reservations 193
Syntax for Displaying a Schema Definition for a vSphere Reservation 199
VMware, Inc. 4
Programming Guide
Syntax for Displaying a Schema Definition for an Amazon Reservation 206
Syntax for Displaying a Schema Definition for a vCloud Air Reservation 221
Syntax for Getting the Business Group ID for a Reservation 233
Syntax for Getting a Compute Resource for a Reservation 236
Syntax for Getting Resources Schema for a vSphere Reservation 240
Syntax for Getting Resources Schema for an Amazon Reservation 242
Syntax for Getting Resources Schema for a vCloud Air Reservation 245
Syntax for Creating a vSphere Reservation 249
Syntax for Creating an Amazon Reservation 254
Syntax for Creating a vCloud Air Reservation 257
Syntax for Verifying a Reservation and Getting Reservation Details 262
Syntax for Displaying a List of Supported Reservation Types 270
Syntax for Updating a Reservation 275
Syntax for Deleting a Reservation 280
Working with Reservation Policies282
9
Prerequisites for Working with Reservation Policies 282
List Reservation Policies Example 282
Create a Reservation Policy Example 284
Display a Reservation Policy by ID Example 286
Update a Reservation Policy Example 287
Deleting a Reservation Policy Example 288
Working with Key Pairs290
10
Prerequisites for Working with Key Pairs 290
Get a Key Pair List Example 290
Create a Key Pair Example 293
Query a Key Pair Example 296
Update a Key Pair Example 298
Delete a Key Pair Example 299
Working with Network Profiles301
11
Prerequisites for Working With Network Profiles 303
Get a Network Profile List Example 303
Create an External Network Profile Without IPAM Example 312
Create an External Network Profile Using External IPAM Example 314
Query a Network Profile Example 317
Update a Network Profile Example 321
Delete a Network Profile Example 322
Getting a List of Available IP Ranges324
12
Get a List of Available IP Ranges for an IPAM Provider 324
VMware, Inc. 5
Programming Guide
Importing and Exporting Content342
13
Understanding Blueprint Schema 343
Prerequisites for Importing and Exporting Content 345
List Supported Content Types Example 345
List Available Content Example 349
Filter Content by Content Type Example 354
Create a Package for Export Example 355
List Packages in the Content Service Example 356
Export a Package Example 360
Validate a Content Bundle Before Importing example 360
Import a Package Example 363
Export XaaS Content Example 364
Import XaaS Content Example 365
Related Tools and Documentation367
14
Viewing API Reference Information 367
Using vRealize CloudClient 368
Using Third Party Tools 368
Filtering and Formatting REST API Information370
15
VMware, Inc. 6
vRealize Automation Programming Guide
The Programming Guide provides information about the vRealize Automation REST APIs, including how
to use the REST API services and resources, create HTTP bearer tokens for authentication and
authorization, and construct REST API service calls.
Intended Audience
This information is intended for administrators and programmers who want to configure and manage
vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on
common use cases. For related information about all available REST API services, see the vRealizeAutomation API Reference at https://code.vmware.com/apis/vrealize-automation.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For
definitions of terms as they are used in VMware technical documentation, go to
This Programming Guide is updated with each release of the product or when necessary.
This table provides the update history of the Programming Guide.
RevisionDescription
002448-01
002448-00Initial release.
n
Removed Day 2 action terminology from Chapter 7 Managing Provisioned Deployments.
n
Clarified procedure in Viewing API Reference Information.
VMware, Inc. 8
Overview of the
vRealize Automation REST API1
The vRealize Automation REST API provides consumer, administrator, and provider-level access to the
service catalog with the same services that support the vRealize Automation console user interface. You
can perform vRealize Automation functions programmatically by using REST API service calls.
This chapter includes the following topics:
n
REST API Services
n
Using the vRealize Automation REST API
n
About the API Use Cases
REST API Services
The vRealize Automation REST API offers the following services and functions.
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.
VMware, Inc. 9
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
ServiceDescription
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.
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.
Placement ServiceProvides vRealize Automation with recommendations for the placement
of deployments. With cluster health information from an external service
such as vRealize Operations Manager, the service can recommend
reservations to use for the provisioning of blueprint components.
Portal 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 component, software component
types, software resource requests, and nodes (machines).
vRA Orchestrator ServiceManage vRealize Orchestrator actions, tasks, packages, and workflows.
Browse system and plug-in inventories.
VMware, Inc. 10
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
ServiceDescription
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.
Using the vRealize Automation REST API
To make vRealize Automation REST API service calls, you can use a browser application or an HTTP
client program to send requests and review responses.
REST Client Programs
Any client application that can send HTTPS requests is an appropriate tool for developing REST
applications with the vRealize Automation API. The following open-source programs are commonly used:
n
cURL. http://curl.haxx.se
n
Postman application. http://www.getpostman.com
About the API Reference
The vRealize Automation API Reference lists all REST API service calls. It is provided as a Swagger
document and is available in either of the following ways.
n
If vRealize Automation is installed, documentation is available with the product.
n
A list of general services
https://$vRA/component-registry/services/docs
n
A list of installation and configuration services
https://$vRA:5480/config/
$vRA denotes an instance of vRealize Automation.
n
If vRealize Automation is not installed, documentation is available from the APIs section for the
vRealize Automation API at VMware{code} or, https://code.vmware.com/apis/vrealize-automation.
For information about using the vRealize Automation API Reference, see Viewing API Reference
Information.
VMware, Inc. 11
Programming Guide
About the API Use Cases
While the vRealize Automation API Reference contains a menu that lists all REST API service calls, it
does not document use cases. The Programming Guide provides frequently used use cases including
sample requests and responses.
The following REST API use cases provide the prerequisite, command line options and format, and
sample results to help you perform a variety of vRealize Automation functions, such as requesting a
machine or creating a reservation. Each includes service examples that provide syntax for the calls
referenced in the use case.
n
Chapter 3 Creating a Tenant
n
Chapter 4 Requesting a Machine
n
Chapter 5 Approving a Machine Request
n
Chapter 6 Listing Provisioned Resources
n
Chapter 7 Managing Provisioned Deployments
n
Chapter 8 Working with Reservations
n
Chapter 9 Working with Reservation Policies
n
Chapter 10 Working with Key Pairs
n
Chapter 11 Working with Network Profiles
n
Chapter 12 Getting a List of Available IP Ranges
n
Chapter 13 Importing and Exporting Content
curl is used for example requests. Request headers required by the API are included in example requests
that are not fragments of a larger example. The variable $vRA represents the appliance name.domainname of the vRealize Automation server in all URLs.
Most example responses show only those elements and attributes that are relevant to the operation being
discussed. Ellipses (...) indicate omitted content within response bodies.
Postman collections are not used in the API examples, but are available from the Code Samples section
for the vRealize Automation API at VMware{code} or, https://code.vmware.com/apis/vrealize-automation.
VMware, Inc. 12
REST API 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.
This chapter includes the following topics:
n
About HTTP Bearer Tokens
n
Configure the Duration of an HTTP Bearer Token
n
Request an HTTP Bearer Token
n
Validate an HTTP Bearer Token
n
Delete an HTTP Bearer Token
About HTTP Bearer Tokens
You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You
create a request header with the curl command or with some other utility.
You use POST, HEAD, and DELETE methods to manage HTTP bearer tokens.
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 token calls:
https://$vRA/identity/api/tokens
The variable $vRA represents the appliance name.domain name of the vRealize Automation server
such as, vra-appliance-name.company.com.
VMware, Inc.
13
Programming Guide
Configure the Duration of an HTTP Bearer Token
You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties file on the
vRealize Automation appliance.
The effective duration or lifetime of an HTTP bearer token depends on the duration of its corresponding
SAML token, which the SSO server creates at request time. An HTTP bearer token expires when it
reaches the end of its configured duration, or at the end of the configured duration of the SAML token,
whichever comes first. For example, if the configured duration is three days for the HTTP bearer token
and two days for the SAML token, the HTTP bearer token expires in two days. A configuration setting on
the SSO server determines the duration of SAML tokens.
Prerequisites
n
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specified
when you deployed the appliance.
n
The /etc/vcac/security.properties file on the appliance must be editable.
Procedure
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 token expires in 24 hours by default. See Configure the Duration of an HTTP Bearer Token for
information on how to set the duration.
For details regarding input, output, and response codes, see Syntax for Requesting an HTTP Bearer
Token.
VMware, Inc. 14
Programming Guide
Prerequisites
n
Secure a channel between the web browser and the vRealize Automation server. Open a browser
and enter the URL such as:
https://vra-appliance-name.company.com
The system warns that your connection is not private. Click through to confirm the security exception
and establish an SSL handshake.
n
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a
role, log in as a tenant administrator.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance
are available.
Procedure
1Enter the command to request the HTTP bearer token.
In this example, $vRA is an instance of vRealize Automation. The --insecure flag is included so that
the request will return a response even if the traffic is not secured with a trusted certificate.
2Examine the response.
A successful request returns an HTTP bearer token that you include in subsequent API requests.
3For convenience, store the token in a variable.
export token="EXAMPLE-TOKEN-TEXT"
Example: Token Request and Response
The following sample displays output based on the example request.
The id is the bearer token to store for future use.
export token="MTQ5Mj ... M2RmMA=="
VMware, Inc. 15
Programming Guide
If the credentials supplied in the Authorization header are invalid, the response includes status code 401
as in the following output.
<!DOCTYPE html><html><head><title>Error report</title></head><body><h1>HTTP Status 401 -
Authentication required</h1></body></html>
Syntax for Requesting an HTTP Bearer Token
An HTTP bearer token is required by the REST client to use the vRealize Automation REST API. You
obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
ParameterDescription
URLhttps://$vRA/identity/api/tokens
$vRAappliance name.domain name of the vRealize Automation server.
usrnameTenant administrator user name.
passwdTenant administrator password.
tenantURLtokenTenant URL token determined by the system administrator when creating the tenant such
as, support.
Output
The following information is displayed as a result of your HTTP bearer token request.
ParameterDescription
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.
VMware, Inc. 16
Programming Guide
Example: curl Command to Request HTTP Bearer Token
The following example command requests an HTTP bearer token.
The server returns one of the following status codes.
Table 2‑2. Status Codes for Delete a Bearer Token
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.
VMware, Inc. 18
Programming Guide
Table 2‑2. Status Codes for Delete a Bearer Token (Continued)
Status CodeDescription
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. 19
Creating a Tenant3
You use the identity service to create a tenant.
The identity service is comprised of two components: authentication and authorization. The authentication
component manages tenants, groups, users, and identity stores. Creating a tenant is an authentication
example.
Two use cases show how to create a tenant, either with parameters inline or with input values in a JSON
file. After creating a tenant, you can use other service examples to perform additional authentication and
authorization functions.
For general information about creating and working with tenants, see Configuring vRealize Automation in
the vRealize Automation information center.
This chapter includes the following topics:
n
Prerequisites for Creating a Tenant
n
Create a Tenant With Parameters Inline
n
Create a Tenant With a JSON File
n
Identity Service Examples for Creating a Tenant
Prerequisites for Creating a Tenant
Satisfy the following conditions before performing any tasks for this use case.
n
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance
are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Create a Tenant With Parameters Inline
To create a tenant with parameters inline, you first display all available tenants then request a new tenant
with input parameters specified inline.
VMware, Inc.
20
Programming Guide
Prerequisites
In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for the new
tenant.
Procedure
1Use the identity service to display all the available tenants.
To create a tenant with a JSON file, you first display all available tenants then request a new tenant with
input parameters. The input parameters are specified in a separate JSON file that you call from the
request.
Prerequisites
In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for the new
tenant required for the JSON file input.
Procedure
1Use the identity service to display all the available tenants.
Syntax for each service example lists input parameters, output parameters, and curl commands.
n
Syntax for Displaying Your Current Tenants
GET /api/tenants lists all the vRealize Automation tenants in your system.
n
Syntax for Requesting a New Tenant
PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can specify
request parameters using JSON command line input or by calling an existing JSON file from the
command line.
n
Syntax for Listing All Tenant Identity Stores
GET /api/tenants/{tenantId}/directories lists all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.
n
Syntax for Linking an Identity Store to the Tenant
PUT /api/tenants/{tenantId}/directories/{id} links an LDAP, Active Directory, or Native
Active Directory identity store to the vRealize Automation tenant.
n
Syntax for Searching LDAP or Active Directory for a User
GET /api/tenants/{tenantId}/principals/{userId} searches the configured LDAP directory,
Active Directory, or Native Active Directory for a user.
n
Syntax for Assigning a User to a Role
PUT /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/{scope
Id}/roles/{scopeRoleId} assigns a user to a role.
n
Syntax for Displaying all Roles Assigned to a User
GET /api/authorization/tenants/{tenantId}/principals/{principalId}/roles displays
all of the roles assigned to a user.
VMware, Inc. 25
Programming Guide
Syntax for Displaying Your Current Tenants
GET /api/tenants lists all the vRealize Automation tenants in your system.
Input
Use the supported input parameters to control the command output.
ParameterDescription
URLhttps://$vRA/identity/api/tenants
$vRASpecifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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. 26
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.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This parameter is not output when you
query for a single profile.
n
totalPages: Specifies the total number of pages of data available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
Example: curl Command to Display Current Tenants
The following example command displays all available tenants.
The response in JSON lists the current tenants. Format the output to improve its readability. For
information about formatting output, see Chapter 15 Filtering and Formatting REST API Information.
{
"links":[],
"content"[
{
"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
VMware, Inc. 27
Programming Guide
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true
},
{
"@type":"Tenant",
"id":"qe",
"urlName":"qe",
"name":"QETenant",
"description":"Precreated test tenant",
"contactEmail":null,
"password":"",
"defaultTenant":false
}
{
"@type":"Tenant",
"id":"management",
"urlName":"management",
"name":"Management-ITTenant",
"description":"Precreated test tenant",
"contactEmail":null,
"password":"",
"defaultTenant":false
}
],
"metadata":{
"size":20,
"totalElements":3,
"totalPages":1,
"number":1,
"offset":0
}
}
Syntax for Requesting a New Tenant
PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can specify
request parameters using JSON command line input or by calling an existing JSON file from the
command line.
Input
Use the supported input parameters to control the command output.
$vRASpecifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
VMware, Inc. 28
Programming Guide
ParameterDescription
$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.
$passwordOptional password for the new tenant. If blank, no password is required.
JSON Input File Template
To simplify command line input, you can call a JSON file with input parameters from the command line.
You create the JSON file using a text editor, replacing italicized variables in the following template with
your specific values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"password": "$password",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 29
Programming Guide
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.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This parameter is not output when
you query for a single profile.
n
totalPages: Specifies the total number of pages of data available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
Example: curl Command to Request a New Tenant With JSON File
The following sample newTenant.json file contains parameters for the tenant request.
{
"@type" : "Tenant",
"id" : "rainpole",
"urlName" : "rainpole",
"name" : "rainpoleTenant",
"description" : "New Custom Tenant",
"contactEmail" : null,
"password": "",
"defaultTenant" : true
}
VMware, Inc. 30
Programming Guide
The following example command requests a new tenant by calling the newTenant.json file.
GET /api/tenants/{tenantId}/directories lists all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.
Input
Use the supported input parameters to control the command output.
Syntax for Linking an Identity Store to the Tenant
PUT /api/tenants/{tenantId}/directories/{id} links an LDAP, Active Directory, or Native Active
Directory identity store to the vRealize Automation tenant.
Input
Use the supported input parameters to control the command output.
The command also tests that vRealize Automation can connect to the identity store successfully. If the
command finishes successfully,vRealize Automation succeeded in connecting to the identity store.
This response in JSON indicates that an identity store is successfully linked to the specified tenant.
$vRASpecifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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 to Assign a User to a Role
The following example command string submits a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the required
JSON payload. For more information about getting the user name and domain values, see Syntax for
"description" : "Entitle services, catalog items and actions ... users within a tenant.",
"prereqAdminPermissions" : null
},
{
"id" : "FILE_EDIT_TENANT",
"name" : "Manage Tenant Files",
"description" : "Upload and delete files belonging to this tenant.",
"prereqAdminPermissions" : null
},
{
"id" : "TENANT_USER_DATA_MANAGEMENT",
"name" : "Manage user data (requests, items, tasks etc) within a tenant.",
"description" : "Manage user created objects belonging to the tenant.",
"prereqAdminPermissions" : null
},
{
"id" : "TENANT_ADMIN_ROLE_ASSIGNMENT",
"name" : "Tenant Administrator Role Assignment",
"description" : "Assign the tenant administrator role to other users.",
"prereqAdminPermissions" : null
},
{
"id" : "GUI_MY_TENANT_TUG_MANAGEMENT",
"name" : "My Tenant Identity Stores, Groups and Users Administration User Interfaces",
"description" : "Access my tenant identity stores, groups ... users administration GUIs.",
"prereqAdminPermissions" : null
}
],
"metadata" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
VMware, Inc. 41
Requesting a Machine4
You use the catalog service to perform tasks related to requesting a machine.
The catalog service is comprised APIs for the consumer, service providers, and service administrators. It
is designed to be used by consumers and providers of the service catalog. For example, a consumer
would request a catalog item such as a machine. The service provider would fulfill the request.
The catalog service includes Hypermedia as the Engine of Application State (HATEOAS) links. The links
function as templates that you can use to complete common tasks supported by the API.
For example, if you submit a template request for a given context, such as: catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1d5f997c8ad66/requests/template. You use the returned template, either as-is or modified, to create arequest that you POST or PUT to the target API, such as: catalog-
For details regarding input and output for this request, see Syntax for Listing Shared and Private
Catalog Items.
2Examine the response to find the catalogItemId
3Get a template request for a catalog item.
Use the catalogItemId to submit the template request for this catalog item. In this example, the
catalogItemId is dc808d12-3786-4f7c-b5a1-d5f997c8ad66.
For details regarding input and output for this request, see Syntax for Getting a Template Request for
a Catalog Item.
A template request for the catalog item is created. The fields and default values are populated based
on the configuration of the underlying blueprint. By default, requestMachine.json is the name of the
template request.
4Review and edit the template request.
Review the contents of the template request and edit the values if you want to change them from the
default prior to submitting the request for a machine. For example, you can specify a value for the
description field or change the values for the machine resources if the blueprint allows for a range.
For details regarding input and output for this request see Syntax for Requesting a Machine.
VMware, Inc. 43
Programming Guide
6(Optional) View the details of your request.
You can perform a GET on the URI in the Location header to retrieve the updated request details. In
this example, the URI-in-Location-header is 7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
For details regarding input and output for this request, see Syntax for Viewing Details of a Machine
Request.
Catalog Service Examples for Requesting a Machine
Syntax for each service example lists input parameters, output parameters, and curl commands.
n
Syntax for Listing Shared and Private Catalog Items
GET /api/consumer/entitledCatalogItemViews retrieves a list of all shared viewable catalog
items for the current user. Shared catalog items do not belong to a specific business group. This
service also retrieves a list of all shared and private catalog items that can be viewed, including their
business groups.
n
Syntax for Getting Information for a Catalog Item
GET /api/consumer/entitledCatalogItemViews/{id} gets information about a specific catalog
item.
n
Syntax for Getting a Template Request for a Catalog Item
GET /api/consumer/entitledCatalogItems/{id}/requests/template retrieves a template
request for a specific catalog item. VMware supplies a number of templates to help you create
different types of machine requests.
n
Syntax for Requesting a Machine
POST /api/consumer/entitledCatalogItems/{id}/requests submits a request for a specific
catalog item with input provided in a JSON file.
n
Syntax for Viewing Details of a Machine Request
GET /api/consumer/requests/{requestId} provides the details of a machine request, where
requestId is the URI in the Location header.
Syntax for Listing Shared and Private Catalog Items
GET /api/consumer/entitledCatalogItemViews retrieves a list of all shared viewable catalog items
for the current user. Shared catalog items do not belong to a specific business group. This service also
retrieves a list of all shared and private catalog items that can be viewed, including their business groups.
Input
Use the supported input parameters to control the command output.
$vRASpecifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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. 45
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.
entitledOrganizationsSpecifies the organizations in which the catalog item can be consumed by the current user.
VMware, Inc. 46
Programming Guide
Example: curl Command to List All Shared Catalog Items
The following example command retrieves information about all shared catalog items of type
Example: curl Command to Locate the Details of a Specific Catalog Item
To search for specific catalog item, add the $catalogItemId. The following example command retrieves
information about a catalog item with the name $catalogItemName.
GET /api/consumer/entitledCatalogItemViews/{id} gets information about a specific catalog item.
REST API Catalog Service
The REST API supports OData filtering. For more information about supported OData filters, refer to the
vRealize Automation API Reference, particularly the REST API Tips page located at
https://$vRA/component-registry/services/docs/odata.html.
For specific information about catalog service filters, see the "Important Notes About catalog-service and
OData Queries" topic located at https://$vRA/catalog-service/api/docs/index.html.
Input
Use the supported input parameters to control the command output.
$vRASpecifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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. 49
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. 50
Programming Guide
Example: curl Command to Get Information for a Catalog Item
The following example command retrieves information catalog item with the name $filter=name+eq+
%27$catalogItemName%27.
Syntax for Getting a Template Request for a Catalog Item
GET /api/consumer/entitledCatalogItems/{id}/requests/template retrieves a template request
for a specific catalog item. VMware supplies a number of templates to help you create different types of
machine requests.
Overview
In the entitledCatalogItemViews response, a link field contains a value similar to the following.
This URL is a HATEOAS link for a template request for this catalog item. The rel field provides a
description of the link (request template) and indicates the HTTP method to use with the URI in the href
field (GET). By using these HATEOAS links, you can make follow-on API calls without having to consult
the API documentation for the URI syntax or construct the links programmatically.
Review and Edit the Template Request
The returned template request is specific to the applicable catalog item. The fields and default values are
populated based on the configuration of the underlying blueprint.
You can review the contents of the template and optionally edit the values if you want to change them
from the default prior to submitting the request. For example, you can specify a value for the description
field or change the values for the machine resources if the blueprint allows for a range.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 52
Programming Guide
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 to Get a Template Request for a Catalog Item
The following example command retrieves a template request for the catalog item with ID
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.
requestedItemDescriptionSpecifies the item description.
componentsReturns the list of components associated with the request. The provider supplies this list of components
after request initialization.
VMware, Inc. 57
Programming Guide
Example: curl Command to Request a Machine
To construct your request, refer to the entitledCatalogItemViews response received when you ran the
request described in Syntax for Getting a Template Request for a Catalog Item, locate a link field that
contains a value similar to the following:
GET /api/consumer/requests/{requestId} provides the details of a machine request, where
requestId is the URI in the Location header.
Request Status
Typically, the request status information is the most important part of request details. The phase field
corresponds to the status displayed in the Requests tab in the interface. You can rerun this command
multiple times to monitor the state of a machine request.
Table 4‑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. 60
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 View the Details of the Machine Request
The following example command displays details of a request.
"requestedItemDescription": "Linux blueprint for API demo",
VMware, Inc. 61
Programming Guide
"stateName": "Successful",
"approvalStatus": "POST_APPROVED",
"executionStatus": "STOPPED",
"waitingStatus": "NOT_WAITING",
"phase": "SUCCESSFUL",
"catalogItemRef": {
"id": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"label": "Linux"
}
}
Note In the request details, the phase field corresponds to the status that is displayed in the Requests
tab in the user interface.
VMware, Inc. 62
Approving a Machine Request5
You use a series of work item service commands to approve a machine request.
Basic components of the work item service are the work item and the assignment. The work item service
provides a standard way to present work items to users. For example, a user can view all work items and
select the item to perform such as approving a machine request.
This chapter includes the following topics:
n
Approve a Machine Request
n
Work Item Service Examples for Approving a Machine Request
Approve a Machine Request
To approve a machine request, you first get a work item ID, then specify the ID in the approval.
Prerequisites
n
Log in to vRealize Automation as an approver with at least one of the following qualifications:
n
You are designated as an approver in an approval policy.
n
You belong to a group which has been designated as an approval group in an approval policy.
n
You are designated as a delegate for someone who is an approver.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance
are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
For details regarding input and output for this request, see Syntax for Approving a Submitted Machine
Request.
If the command is successful, the HTTP status is 201 Created. If the command is not successful, the
HTTP status is 204 No Content.
Work Item Service Examples for Approving a Machine
Request
Syntax for each service example lists input parameters, output parameters, and curl commands.
n
Syntax for Listing Work Items
GET /api/workitems lists the unique IDs of all available work items.
n
Syntax for Getting Work Item Details
GET /api/workitems/{id} retrieves the details of a pending work item. You need these details to
submit a completion request.
VMware, Inc. 64
Programming Guide
n
Syntax for Constructing a JSON File to Approve a Machine Request
You can specify a JSON file in your vRealize Automation REST API command line input. For
example, when you enter a command to approve a machine request, you can include the name of a
JSON file that contains all the parameters required to approve the request and complete the work
item.
n
Syntax for Approving a Submitted Machine Request
PUT /api/workitems/{id} approves a submitted work item request to complete the request. To
construct the approval command, you add work item and work item form details to a JSON file, and
call that JSON file from the command line. Use a template to correctly format the JSON file content.
n
Syntax for Updating Price Information
POST /api/blueprints/{id}/costs/upfront of the composition service, updates and displays
price information for a deployment. The price of a deployment is based on which blueprint you
request plus details of the specific request. For example, if the blueprint allows for a range of CPU,
memory, or storage values, the price depends on the value requested.
Syntax for Listing Work Items
GET /api/workitems lists the unique IDs of all available work items.
Inputs
Use the supported input parameters to control the command output.
ParameterDescription
URLhttps://$vRA/workitem-service/api/workitems
$vRASpecifies the appliance name and fully qualified domain name, or IP address of
the vRealize Automation 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.
PropertyDescription
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 property does not exist when you
query for a single profile.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
n
href: Specifies the URL that produces the result.
work itemNumberDisplays a reference number for the work item.
idSpecifies the unique identifier of this resource.
versionDisplays the object version number.
VMware, Inc. 65
Programming Guide
PropertyDescription
assigneesDisplays the list of work item assignees.
subTenantIdOptionally associates the work item with a specific business group granting users with management
responsibilities over that business group permission to see the approval.
tenantIdSpecifies the tenant ID for the work item.
callbackEntityIdSpecifies the callback entity ID for the work item.
work itemTypeSpecifies the work item type for the work item.
completedDateSpecifies the date when the work item was completed.
assignedDateSpecifies the date when the work item was assigned.
createdDateSpecifies the created date of this instance.
assignedOrCompletedD
ate
formUrlSpecifies the URL from which the layout for this work item can be retrieved.
serviceIdSpecifies the service ID that generated this work item instance.
work itemRequestSpecifies the corresponding work item request object.
statusSpecifies the status of the work item.
completedBySpecifies the principal ID of user who completed the work item.
availableActionsContains a list of relevant work item actions.
MetadataSpecifies the paging-related data:
Specifies the date to be displayed on UI.
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
Example: curl Command
The following example command retrieves all the available work item IDs.
Syntax for Constructing a JSON File to Approve a Machine
Request
You can specify a JSON file in your vRealize Automation REST API command line input. For example,
when you enter a command to approve a machine request, you can include the name of a JSON file that
contains all the parameters required to approve the request and complete the work item.
Template JSON File Values
Copy the following template to start constructing a properly formatted JSON file in a text editor. Replace
the highlighted values with your obtained work item details. After you create the JSON file, you can
include it, or its contents, when you approve a submitted machine request. See Syntax for Approving a
PUT /api/workitems/{id} approves a submitted work item request to complete the request. To
construct the approval command, you add work item and work item form details to a JSON file, and call
that JSON file from the command line. Use a template to correctly format the JSON file content.
Input
Use the supported input parameters to control the command output.
{Error Source: null}, {Error Msg: User fritz@example.mycompany.com not authorized to
complete work item with ID 5e3e9519-78ea-4409-a52c-e4aa3bc56511.}, {System Msg:
User fritz@example.mycompany.com not authorized to complete Work item with id
5e3e9519-78ea-4409-a52c-e4aa3bc56511.}
Syntax for Updating Price Information
POST /api/blueprints/{id}/costs/upfront of the composition service, updates and displays price
information for a deployment. The price of a deployment is based on which blueprint you request plus
details of the specific request. For example, if the blueprint allows for a range of CPU, memory, or storage
values, the price depends on the value requested.
VMware, Inc. 81
Programming Guide
Input
Use the supported input parameters to control the command output.
Note Price is referred to as cost in API commands and output.
ParameterDescription
URLhttps://$vRA/composition-
service/api/blueprints/$BlueprintId/costs/upfront
MethodPost
$vRASpecifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
HTTP BodySpecifies the blueprint ID for the blueprint for which you are
requesting price information and other information.
n
Blueprint ID: Specifies the blueprint ID.
n
requestedFor: The user for whom this request is being made.
Must be the fully qualified user ID.
n
subTenantId: Specifies the subtenant ID associated with the
blueprint
n
requestData: Specifies data that identifies the blueprint further.
n
entries
n
Key: The name of the machine on which the blueprint
resides.
n
value: Specifies key-value pairs that further identify the
blueprint, such as the type of the value, the
componentType ID for the item, the classID of the
value, and where the blueprint resides. In turn, each
entry contains an array of key-value pairs that identify
the type of data used to compute the price that is to be
displayed.
n
Values: Specifies an array of type filters.
n
Entries: Specifies a list of key-value pairs that
specify the values to be used in computing the
price. For example, the cluster, CPU, and allocated
memory to use.
Output
The command output contains property names and values based on the command input parameters.
PropertyDescription
setupFeeSpecifies the one time setup fee associated with the component.
totalEstimatedLeasePriceInfoSpecifies the minimum price and maximum price for the lease
period.
averageDailyPriceInfoSpecifies the average daily price, which depends on the
reservation available for the component.
VMware, Inc. 82
Programming Guide
PropertyDescription
countSpecifies the instance count of the component.
memorySpecifies memory requested for this component.
additionalSpecifies the additional price, 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 price of the deployment.
Example: curl Command
The following sample command updates and displays the price of a sample blueprint with one node. The
HTTP body is included as part of the command line input.
Note Price is referred to as cost in API commands and output.
You use the catalog service to list provisioned resources.
The catalog service is designed to be used by consumers and providers of the service catalog. For
example, a consumer might want to list resources provisioned by a provider. The consumer can also list
the resources in multiple ways.
Each example for this use case lists a curl command with respective JSON response, plus input and
output parameters. The same set of prerequisites applies to each example.
This chapter includes the following topics:
n
Prerequisites for Listing Provisioned Resources
n
Display Your Provisioned Resources Example
n
Display Provisioned Resources by Resource Type Example
n
Display All Available Resource Types Example
n
Display Provisioned Resources by Business Groups You Manage Example
n
View Machine Details Example
Prerequisites for Listing Provisioned Resources
Satisfy the following conditions before performing any tasks for this use case.
n
Log in to vRealize Automation as a business group manager.
n
Verify that the appliance name and fully qualified domain name of the vRealize Automation instance
are available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Display Your Provisioned Resources Example
GET /api/consumer/resources/{id} displays a list of all the provisioned resources that you own.
VMware, Inc.
85
Programming Guide
curl Command
The following example displays all applicable provisioned resources.
$vRASpecifies the appliance name and fully qualified domain name,
or IP address of the vRealize Automation server.
$tokenSpecifies a valid HTTP bearer token with necessary credentials.
$pageSpecifies a page number.
$limitSpecifies the number of entries to display on a page. Maximum
value is 5000. If not specified, defaults to 20.
For information regarding limits to the number of elements
displayed, see Example: Retrieve 10,000 Resources Ordered
By Name.
$orderbySpecifies how to order multiple comma-separated properties
sorted in ascending or descending order. Values include:
n
$orderby=id
n
$orderby=name
n
$orderby=dateCreated
n
$orderby=lastUpdated
n
$orderby=status
n
$orderby=description
$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.
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.
VMware, Inc. 87
Programming Guide
PropertyDescription
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 price.
costsDisplays an optional rate of the price charges for the resource. This parameter is deprecated.
costToDateDisplays an optional rate of the current price charges for the resource. This parameter is deprecated.
totalCostDisplays an optional rate of the price charges for the entire lease period. This parameter is deprecated.
expenseMonthToDateThe expense of the resource from the beginning of the month to the current date. This value is updated
daily by vRealize Business for Cloud.
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.
Example: Retrieve 10,000 Resources Ordered By Name
Since the catalog service limits the number of elements that can be retrieved with a single API call to
5000, retrieving 10,000 resources requires two calls. The first call displays the first 5000 elements and the
second call displays the second 5000 elements. You can make the two calls by specifying either the page
and limit values or the skip and top values.
Specifying page and limit values, you make the following two calls.
The output includes the following highlighted items:
n
Resource ID. 3bfde906-81b9-44c3-8c2d-07d2c9768168 corresponds to a provisioned machine
owned by the logged-in user. The resource IDs are used in requests to retrieve the details for the
corresponding machines.
n
subtenantRef ID. eab762cb-6e75-4379-83ef-171a71c9f00e corresponds to the business group of
the logged-in user. If the user who is logged-in is also the manager of the business group, the
subtenantRef ID is used to get resources from all business groups that the user manages.
Input
Use the supported input parameters to control the command output.
Display Provisioned Resources by Business Groups You
Manage Example
GET /api/consumer/resources/types/{resourceTypeId} displays all of the provisioned resources
that are owned by the business groups that you manage. You can optionally filter the list by business
group name.
VMware, Inc. 94
Programming Guide
curl Command
The following example displays the provisioned resources of one or more business groups.