Programming Guide

19 DEC 2019
vRealize Automation 7.6
Programming Guide

You can find the most up-to-date technical documentation on the VMware website at:

https://docs.vmware.com/

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com

©
Copyright 2008-2019 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware, Inc. 2
 Contents

vRealize Automation Programming Guide 8

Updated Information 9

1 Overview of the vRealize Automation REST API 10

REST API Services 10
Using the vRealize Automation REST API 13
About the API Use Cases 13

2 REST API Authentication 15

About HTTP Bearer Tokens 15
Configure the Duration of an HTTP Bearer Token 16
Request an HTTP Bearer Token 16
Syntax for Requesting an HTTP Bearer Token 18
Validate an HTTP Bearer Token 19
Delete an HTTP Bearer Token 20

3 Creating a Tenant 22
Prerequisites for Creating a Tenant 22
Create a Tenant With Parameters Inline 22
Create a Tenant With a JSON File 25
Identity Service Examples for Creating a Tenant 27
Syntax for Displaying Your Current Tenants 28
Syntax for Requesting a New Tenant 30
Syntax for Listing All Tenant Identity Stores 33
Syntax for Linking an Identity Store to the Tenant 35
Syntax for Searching LDAP or Active Directory for a User 39
Syntax for Assigning a User to a Role 41
Syntax for Displaying all Roles Assigned to a User 41

4 Requesting a Machine 45
Request a Machine 45
Catalog Service Examples for Requesting a Machine 47
Syntax for Listing Shared and Private Catalog Items 47
Syntax for Getting Information for a Catalog Item 51
Syntax for Getting a Template Request for a Catalog Item 55
Syntax for Requesting a Machine 59
Syntax for Viewing Details of a Machine Request 62

VMware, Inc. 3
Programming Guide

5 Approving a Machine Request 67

Approve a Machine Request 67
Work Item Service Examples for Approving a Machine Request 68
Syntax for Listing Work Items 69
Syntax for Getting Work Item Details 75
Syntax for Constructing a JSON File to Approve a Machine Request 80
Syntax for Approving a Submitted Machine Request 84
Syntax for Updating Price Information 86

6 Listing Provisioned Resources 90

Prerequisites for Listing Provisioned Resources 90
Display Your Provisioned Resources Example 90
Display Provisioned Resources by Resource Type Example 94
Display All Available Resource Types Example 97
Display Provisioned Resources by Business Groups You Manage Example 100
View Machine Details Example 108

7 Managing Provisioned Deployments 113

Manage Provisioned Deployments 113
Machine States and Entitlements for Day 2 Actions 114
Power Off 115
Change Lease 117
Catalog Service Examples for Managing Provisioned Deployments 118
Syntax for Getting Deployment Details 118
Syntax for Navigating to the Children of a Deployed Resource 122

8 Working with Reservations 130

Prerequisites for Working With Reservations 131
Create a Reservation 131
Display a List of Supported Reservation Types 132
Displaying a Schema Definition for a Reservation 135
Get the Business Group ID for a Reservation 161
Get a Compute Resource for the Reservation 163
Getting a Resources Schema by Reservation Type 165
Creating a Reservation By Type 170
Verify a Reservation and Get Reservation Details 180
Display a List of Reservations 188
Update a Reservation 193
Delete a Reservation 198
Service Examples for Working with Reservations 198
Syntax for Displaying a List of Reservations 200

VMware, Inc. 4
Programming Guide

Syntax for Displaying a Schema Definition for a vSphere Reservation 206

Syntax for Displaying a Schema Definition for an Amazon Reservation 213
Syntax for Displaying a Schema Definition for a vCloud Air Reservation 228
Syntax for Getting the Business Group ID for a Reservation 240
Syntax for Getting a Compute Resource for a Reservation 243
Syntax for Getting Resources Schema for a vSphere Reservation 247
Syntax for Getting Resources Schema for an Amazon Reservation 250
Syntax for Getting Resources Schema for a vCloud Air Reservation 253
Syntax for Creating a vSphere Reservation 256
Syntax for Creating an Amazon Reservation 261
Syntax for Creating a vCloud Air Reservation 264
Syntax for Verifying a Reservation and Getting Reservation Details 269
Syntax for Displaying a List of Supported Reservation Types 278
Syntax for Updating a Reservation 283
Syntax for Deleting a Reservation 288

9 Working with Reservation Policies 290

Prerequisites for Working with Reservation Policies 290
List Reservation Policies Example 290
Create a Reservation Policy Example 292
Display a Reservation Policy by ID Example 294
Update a Reservation Policy Example 295
Deleting a Reservation Policy Example 296

10 Working with Key Pairs 298

Prerequisites for Working with Key Pairs 298
Get a Key Pair List Example 298
Create a Key Pair Example 301
Query a Key Pair Example 304
Update a Key Pair Example 306
Delete a Key Pair Example 307

11 Working with Network Profiles 309

Prerequisites for Working With Network Profiles 310
Get a Network Profile List Example 310
Create an External Network Profile Without IPAM Example 320
Create an External Network Profile Using External IPAM Example 322
Query a Network Profile Example 324
Update a Network Profile Example 329
Delete a Network Profile Example 330

VMware, Inc. 5
Programming Guide

12 Getting a List of Available IP Ranges 332

Get a List of Available IP Ranges for an IPAM Provider 332

13 Importing and Exporting Content 350

Understanding Blueprint Schema 351
Prerequisites for Importing and Exporting Content 354
List Supported Content Types Example 354
List Available Content Example 358
Filter Content by Content Type Example 363
Create a Package for Export Example 364
List Packages in the Content Service Example 366
Export a Package Example 369
Validate a Content Bundle Before Importing example 369
Import a Package Example 372
Export XaaS Content Example 374
Import XaaS Content Example 375

14 Updating Tenancy on a Security Object 377

Update the Tenancy for a Security Group 377
Network Service Examples for Updating Tenancy 378
Syntax for Retrieving Security Groups 379
Syntax for Updating a Tenant ID 380

15 Triggering an Active Directory Synchronization 384

Trigger Sync to an Active Directory 384
Identity Service Examples for Triggering Active Directory Synchronization 385
Syntax for Retrieving Directories 386
Syntax for Synchronizing the Active Directory 387
Syntax for Checking the Synchronization Process 388

16 Retrieving Health Test Results 390

Retrieve Health Test Results 390
Health Broker Proxy Server Examples to Obtain Test Results 393
Syntax for Requesting a Health Services Token 394
Syntax to Retrieve a List of Configurations 394
Syntax to Filter for Latest Execution of a Configuration 395
Syntax to Find All Individual Results 397

17 Using SNMP to Monitor vRealize Automation 401

Configuring Local SNMP 402
Configure Global SNMP 403

VMware, Inc. 6
Programming Guide

18 Related Tools and Documentation 407

Using vRealize CloudClient 407
Enabling vRealize CloudClient Multi-Factor Authentication for vRealize Automation Users
407
Using Third Party Tools 411

19 Filtering and Formatting REST API Information 413

VMware, Inc. 7
vRealize Automation Programming Guide

The Programming Guide provides information about the vRealize Automation REST APIs,
including how to use the REST API services and resources, create HTTP bearer tokens for
authentication and authorization, and construct REST API service calls.

Intended Audience
This information is intended for administrators and programmers who want to configure and
manage vRealize Automation programmatically using the vRealize Automation REST API. The
guide focuses on common use cases. For related information about all available REST API
services, see the vRealize Automation API Reference at https://code.vmware.com/apis/vrealize-
automation.

VMware, Inc. 8
Updated Information

This Programming Guide is updated with each release of the product or when necessary.

This table provides the update history of the Programming Guide.

Revision Description

19 DEC 2019 Added content regarding Machine States and Entitlements for Day 2 Actions.

15 NOV 2019 Added Chapter 17 Using SNMP to Monitor vRealize Automation.

24 APR 2019 Corrected syntax in command to obtain existing client secret in Creating the New OAuth2 Client .

20 SEP 2018 Initial release.

VMware, Inc. 9
Overview of the vRealize
Automation REST API 1
The vRealize Automation REST API provides consumer, administrator, and provider-level access
to the service catalog with the same services that support the vRealize Automation console user
interface. You can perform vRealize Automation functions programmatically by using REST API
service calls.

This chapter includes the following topics:

n REST API Services

n Using the vRealize Automation REST API

n About the API Use Cases

REST API Services

The vRealize Automation REST API offers the following services and functions.

Table 1-1. vRealize Automation REST API Services

Service Description

Advanced Designer Service The advanced designer service selection on the vRealize
Automation API Reference landing page selects the
documentation for the XaaS service.
Manages XaaS elements such as forms, endpoints, XaaS
blueprints, tenants, vRealize Orchestrator imports, workflows, and
work items.

Approval Service Retrieve, create, update, and delete approval policies, policy
types, policy instances, and policy requests.

Branding Service Change the background and text colors, company logo, company
name, product name, tenant name, and other resources in the
console.

Catalog Service Retrieve global and entitled catalog items, and entitlements for
a catalog item and its service that the current user can review.
A consumer can retrieve, edit, and submit a request form for a
catalog item. A provider can retrieve, register, update, and delete
catalog items. Provision and manage systems.

Component Registry Service Access and manage all services and serves as the central view for
all service lookups.

VMware, Inc. 10
Programming Guide

Table 1-1. vRealize Automation REST API Services (continued)

Service Description

Composition Service Allows vRealize Automation services to register application

components, which the composition service manages so that they
can be used in composite blueprints.

Container Service Request provisioning of an application, described through a high-

level definition or blueprint. The Provisioning service reduces
to a model of resources with code to run, requirements, and
relationships.

Content Service Access and manage the content controller and package controller
for export and import processes. This includes export and import
for blueprints and software.

Endpoint Configuration Service Create, read, update and delete endpoint types, endpoint
categories, and endpoints.

Event Broker Service Provide a central location and a consistent way of recording
events and querying for events.

Extensibility Service Manage extensions, plugins, and wizard states.

Forms Service Used internally by the vRealize Automation system to create,

read, update, and delete (perform CRUD operations on) request
forms for XaaS components.

IaaS Proxy Provider Service Run a proxy service that acts as a bridge between the service
catalog and the IaaS provider to call other services, such as
the catalog service, composition service, reservation service, and
event broker service.

Identity Service Manage tenants, business groups, SSO and custom groups, users,
and identity stores.

IP Address Management Service Allocate and deallocate IP addresses from IP address

management (IPAM) providers.

Licensing Service Retrieve permissions and post serial keys.

Network Service Access and manage application network and security settings for
creating and configuring NAT and routed networks; creating load
balancers; and adding and configuring security groups, security
tags and security policies for application components.

Notification Service Configure and send notifications for several types of events such
as the successful completion of a catalog request or a required
approval.

Orchestration (o11n) Gateway Service Provides a gateway to VMware Realize Orchestrator (vRO) for
services running on vRealize Automation. By using the gateway,
consumers of the API can access a vRO instance, and initiate
workflows or script actions without having to deal directly with
the vRO APIs.

VMware, Inc. 11
Programming Guide

Table 1-1. vRealize Automation REST API Services (continued)

Service Description

Placement Service Provides vRealize Automation with recommendations for the

placement of deployments. With cluster health information from
an external service such as vRealize Operations Manager, the
service suggests reservations to use for the provisioning of
blueprint components.

Portal Service Retrieve, create, update, and delete a portal resource.

Properties Service Manage custom properties, property groups, and property

definitions. Properties specify items that can be added to
blueprints to trigger vRealize Orchestrator actions.

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.

Reservation Service Retrieve, create, update, and delete a reservation or reservation

policy.

Software Service Triggers the execution life cycle of software components using
the software agent, registers software agents, and manages
the creation, modification and deletion of software component,
software component types, software resource requests, and
nodes (machines).

vRA Orchestrator Service Manage vRealize Orchestrator actions, tasks, packages, and
workflows. Browse system and plug-in inventories.

Work Item Service Retrieve, create, update, complete, cancel, and delete a work
item. Also retrieve form data, metadata, detail forms, and
submission forms from service providers.

In addition, the vRealize Health Broker is used to execute integration level tests. It runs
application health checks and can be queried to provide the status of individual tests so that
health issues are identified early.

API References
API services are installed with the product. References are available with the following URLs.

n To access a list of general services in the vRealize Automation API Explorer.

https://$vRA/component-registry/services/docs#!/apis

n To access a list of installation and configuration services as a Swagger document.

https://$vRA:5480/config/

n To access a list of health broker services as a Swagger document.

https://$vRA:8090/discovery/swagger

VMware, Inc. 12
Programming Guide

$vRA denotes an instance of vRealize Automation.

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 Applications

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 applications are
commonly used:

n cURL. http://curl.haxx.se

n Postman application. http://www.getpostman.com

Ensuring Backwards Compatibility

If a client deployed with an earlier version of the catalog service REST API is making a call to a
server running a later version of the API, you must include a version header in the request so that
the server correctly recognizes the client and sends a compatible response.

In the following example, the client running version 6.2 of the catalog service REST API is making
a call to a server running a later version of the API.

curl --insecure -H "version:6.2" -H "Accept: application/json" -H "Content-Type: application/

json" -H
"Authorization: Bearer $token" https://$vRA/catalog-service/api/consumer/requests/
7aaf9bafaa4e-
47c4-997b-edd7c7983a5b

About the API Use Cases

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

VMware, Inc. 13
Programming Guide

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

n Chapter 14 Updating Tenancy on a Security Object

n Chapter 15 Triggering an Active Directory Synchronization

n Chapter 16 Retrieving Health Test Results

n Chapter 17 Using SNMP to Monitor vRealize Automation

curl is used for example requests. Request headers required by the API are included in
example requests that are not fragments of a larger example. The variable $vRA represents
the appliance name.domain name of the vRealize Automation server in all URLs. The variable
$tenantId identifies a tenant for the endpoint. Many examples use a fictional tenant identified as
rainpole.

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. 14
REST API Authentication
2
In the REST API, vRealize Automation requires HTTP bearer tokens in request headers for
authentication of consumer requests. A consumer request applies to tasks that you can perform
in the vRealize Automation console, such as requesting a machine.

To acquire an HTTP bearer token, you authenticate with an identity service that manages the
communication with the SSO server. The identity service returns an HTTP bearer token that you
include in all request headers until the token expires, or you delete it. An HTTP bearer token
expires in 24 hours by default, but you can configure the token with a different duration.

This chapter includes the following topics:

n About HTTP Bearer Tokens

n Configure the Duration of an HTTP Bearer Token

n Request an HTTP Bearer Token

n Validate an HTTP Bearer Token

n Delete an HTTP Bearer Token

About HTTP Bearer Tokens

You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation
console. You create a request header with the curl command or with some other utility.

You use POST, HEAD, and DELETE methods to manage HTTP bearer tokens.

Method URL Description

POST /tokens Authenticate the user with the identity service /tokens and
generate a new token.

HEAD /tokens/tokenID Validate the token tokenID.

DELETE /tokens/tokenID Delete the token tokenID.

Use the following root URL for HTTP bearer token calls:

https://$vRA/identity/api/tokens

VMware, Inc. 15
Programming Guide

The variable $vRA represents the appliance name.domain name of the vRealize Automation
server such as, vra-appliance-name.company.com.

Configure the Duration of an HTTP Bearer Token

You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties file on the
vRealize Automation appliance.

The effective duration or lifetime of an HTTP bearer token depends on the duration of its
corresponding SAML token, which the SSO server creates at request time. An HTTP bearer
token expires when it reaches the end of its configured duration, or at the end of the configured
duration of the SAML token, whichever comes first. For example, if the configured duration is
three days for the HTTP bearer token and two days for the SAML token, the HTTP bearer token
expires in two days. A configuration setting on the SSO server determines the duration of SAML
tokens.

Prerequisites

n Log in to the vRealize Automation appliance with SSH as root. The password is the one you
specified when you deployed the appliance.

n The /etc/vcac/security.properties file on the appliance must be editable.

Procedure

1 Open the /etc/vcac/security.properties file for editing.

2 Add the following lines to the file, where N is an integer specifying the duration of the token
in hours.

identity.basic.token.lifetime.hours=N
#The number is in hours.

3 Save and close the file.

4 Log out of the vRealize Automation appliance.

Results

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.

VMware, Inc. 16
Programming Guide

For details regarding input, output, and response codes, see Syntax for Requesting an HTTP
Bearer Token.

Prerequisites

n Secure a channel between the web browser and the vRealize Automation server. Open a
browser and enter the URL such as:

https://vra-appliance-name.company.com

The system warns that your connection is not private. Click through to confirm the security
exception and establish an SSL handshake.

n Log in to vRealize Automation using the applicable credentials. For example, to assign a user
to a role, log in as a tenant administrator.

n Verify that the appliance name and fully qualified domain name of the vRealize Automation
instance are available.

Procedure

1 Enter the command to request the HTTP bearer token.

curl --insecure -H "Accept: application/json" -H 'Content-Type:

application/json' --data '{"username":"[email protected]","password":"vra-user-
password","tenant":"company.com"}' https://$vRA/identity/api/tokens

In this example, $vRA is an instance of vRealize Automation. The --insecure flag is included
so that the request will return a response even if the traffic is not secured with a trusted
certificate.

2 Examine the response.

A successful request returns an HTTP bearer token that you include in subsequent API
requests.

3 For convenience, store the token in a variable.

export token="EXAMPLE-TOKEN-TEXT"

Example: Token Request and Response

The following sample displays output based on the example request.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data

'{"username":"[email protected]","password":"vra-user-password","tenant":"company.com"}'
https://$vRA/identity/api/tokens
{"expires":"2017-04-14T04:46:43.000Z","id":"MTQ5Mj ... M2RmMA==","tenant":"company.com"}

The id is the bearer token to store for future use.

export token="MTQ5Mj ... M2RmMA=="

VMware, Inc. 17
Programming Guide

If the credentials supplied in the Authorization header are invalid, the response includes status
code 401 as in the following output.

<!DOCTYPE html><html><head><title>Error report</title></head><body><h1>HTTP Status 401 -

Authentication required</h1></body></html>

Syntax for Requesting an HTTP Bearer Token

An HTTP bearer token is required by the REST client to use the vRealize Automation REST API.
You obtain a bearer token by authenticating to the identity service.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tokens

$vRA appliance name.domain name of the vRealize Automation server.

usrname Tenant administrator user name.

passwd Tenant administrator password.

tenantURLtoken Tenant URL token determined by the system administrator when creating the
tenant such as, support.

Output
The following information is displayed as a result of your HTTP bearer token request.

Parameter Description

expires Contains the ISO 8601 timestamp indicating when the token expires.

id Contains the HTTP bearer token to use in Authorization header in subsequent

requests.

tenant Displays the tenant ID associated with the token.

Response Status Codes

One of the following codes are displayed as a result of your HTTP bearer token request.

VMware, Inc. 18
Programming Guide

Status Code Description

200 OK Your request succeeded and the resource was updated.

The response body contains the full representation of the
resource.

400 BAD REQUEST The data you provided in the POST failed validation.
Inspect the response body for details.

401 UNAUTHORIZED The request could not authenticate the user or

authentication credentials required.

Example: curl Command to Request HTTP Bearer Token

The following example command requests an HTTP bearer token.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'

--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}' https://$vRA/
identity/api/tokens

When your request succeeds, the system returns the expiration date and time of the token, and
the HTTP bearer token.

Validate an HTTP Bearer Token

You can validate an existing HTTP bearer token.

Prerequisites

n Request an HTTP Bearer Token.

Procedure

1 Enter the command to validate the HTTP bearer token.

curl --insecure -I -H "Accept: application/json" -H "Authorization: Bearer $token" -H

"Cache-Control: no-cache" "https://$vRA/identity/api/tokens/$token"

2 Examine the response.

A successful request returns status code 204.

Example: Validate Token Request and Response

The following sample displays output based on the example request.

curl --insecure -I -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-

Control: no-cache" "https://$vRA/identity/api/tokens/$token"
HTTP/1.1 204
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains

VMware, Inc. 19
Programming Guide

X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Date: Thu, 13 Apr 2017 21:56:02 GMT
X-Frame-Options: SAMEORIGIN

The server returns one of the following status codes.

Table 2-1. Status Codes for Validate a Bearer Token

Status Code Description

204 NO CONTENT The request succeeded.

401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must
be authenticated.

403 FORBIDDEN Your authentication credentials do not provide sufficient access to the resource.

404 NOT FOUND Could not locate the resource based on the specified URI.

405 METHOD NOT ALLOWED The HEAD method is not supported for the resource.

500 SERVER ERROR Could not create or update the resource because of an internal server error.

Delete an HTTP Bearer Token

You can delete an HTTP bearer token.

Prerequisites

n Request an HTTP Bearer Token.

Procedure

1 Enter the command to delete the HTTP bearer token, as in the following example.

curl --insecure -X DELETE -H "Accept: application/json" -H "Authorization: Bearer $token"

-H "Cache-Control: no-cache" "https://$vRA/identity/api/tokens/$token"

2 Examine the response.

A successful request returns status code 204.

Example: Delete Token Request and Response

The following sample displays output based on the example request.

curl --insecure -X DELETE -H "Accept: application/json" -H "Authorization: Bearer $token" -H

"Cache-Control: no-cache" "https://$vRA/identity/api/tokens/$token"
204 NO CONTENT

The server returns one of the following status codes.

VMware, Inc. 20
Programming Guide

Table 2-2. Status Codes for Delete a Bearer Token

Status Code Description

204 NO CONTENT The request succeeded. The resource has been deleted.

401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must
be authenticated.

403 FORBIDDEN Your authentication credentials do not provide sufficient access to the resource.

404 NOT FOUND Could not locate the resource based on the specified URI.

405 METHOD NOT ALLOWED The DELETE method is not supported for the resource.

500 SERVER ERROR Could not create or update the resource because of an internal server error.

VMware, Inc. 21
Creating a Tenant
3
You use the identity service to create a tenant.

The identity service is comprised of two components: authentication and authorization. The
authentication component manages tenants, groups, users, and identity stores. Creating a tenant
is an authentication example.

Two use cases show how to create a tenant, either with parameters inline or with input values
in a JSON file. After creating a tenant, you can use other service examples to perform additional
authentication and authorization functions.

For general information about creating and working with tenants, see Configuring vRealize
Automation in the vRealize Automation information center.

This chapter includes the following topics:

n Prerequisites for Creating a Tenant

n Create a Tenant With Parameters Inline

n Create a Tenant With a JSON File

n Identity Service Examples for Creating a Tenant

Prerequisites for Creating a Tenant

Satisfy the following conditions before performing any tasks for this use case.

n Log in to vRealize Automation as a system administrator or 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. 22
Programming Guide

Prerequisites

In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for
the new tenant.

Procedure

1 Use the identity service to display all the available tenants.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://

$vRA/identity/api/tenants

For details regarding input and output of this sample, see Syntax for Displaying Your Current
Tenants .

2 Examine the response to verify that the tenant you plan to create is not listed.

See the output of the request to display all tenants Create a Tenant With Parameters Inline.

3 Submit a request for a new tenant with parameters inline.

curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant","descriptio
n":"New Custom Tenant","contactEmail":"[email protected]","defaultTenant":false}'

For details regarding input and output of this sample, see Syntax for Requesting a New
Tenant

4 Use the identity service to display all the available tenants again.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://

$vRA/identity/api/tenants

5 Examine the response to verify that the tenant you requested is listed.

See the output of the request to verify the new tenant is created Create a Tenant With
Parameters Inline.

Example: Create a Tenant With Parameters Inline

The following sample output for Step 1 lists three tenants.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://$vRA/

identity/api/tenants
{
"links":[],
"content"[
{"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",

VMware, Inc. 23
Programming Guide

"defaultTenant":true},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...}
],
"metadata":{"size":20,"totalElements":3,"totalPages":1,"number":1,"offset":0}
}

The following sample output for Step 3 shows that the tenant named rainpole has been created.

curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant","description":
"New Custom Tenant","contactEmail":"[email protected]","defaultTenant":false}'
{
"id":"rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"[email protected]",
"defaultTenant":false
}

The following sample output for Step 4 lists four tenants including rainpole.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://$vRA/

identity/api/tenants
{
"links":[],
"content":[
{"@type":"Tenant",
"id":"vsphere.local",
...},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...},
{"@type":"Tenant",
"id":"rainpole",
...}
],
"metadata":{"size":20,"totalElements":4,"totalPages":1,"number":1,"offset":0}
}

VMware, Inc. 24
Programming Guide

Create a Tenant With a JSON File

To create a tenant with a JSON file, you first display all available tenants then request a new
tenant with input parameters. The input parameters are specified in a separate JSON file that you
call from the request.

Prerequisites

In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for
the new tenant required for the JSON file input.

Procedure

1 Use the identity service to display all the available tenants.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://

$vRA/identity/api/tenants

For details regarding input and output of this sample, see Syntax for Displaying Your Current
Tenants .

2 Examine the response to verify that the tenant you plan to create is not listed.

See the output of the request to display all tenants Create a Tenant With a JSON File.

3 Create a JSON file for the new tenant request to call.

The newTenant.json file contains information about the new tenant.

{
"@type":"Tenant",
"id":"rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"[email protected]",
"defaultTenant":false
}

4 Submit a request for a new tenant that calls the JSON file.

curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type:application/json" -H

"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data @C:/Temp/
newTenant.json

For details regarding input and output of this sample, see Syntax for Requesting a New
Tenant

5 Use the identity service to display all the available tenants again.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://

$vRA/identity/api/tenants

VMware, Inc. 25
Programming Guide

6 Examine the response to verify that the tenant you requested is listed.

See the output of the request to verify the new tenant is created Create a Tenant With a
JSON File.

Example: Create a Tenant With a JSON File

The following sample output for Step 1 lists three tenants.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://$vRA/

identity/api/tenants
{
"links":[],
"content"[
{"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...}
],
"metadata":{"size":20,"totalElements":3,"totalPages":1,"number":1,"offset":0}
}

The following sample output for Step 4, shows that the tenant named rainpole has been created.

curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type:application/json"

-H "Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data @C:/Temp/
newTenant.json
{
"id": "rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"[email protected]",
"password":"",
"defaultTenant":false
}

The following sample output for Step 5 lists four tenants including rainpole.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://$vRA/

identity/api/tenants
{
"links":[],
"content":[

VMware, Inc. 26
Programming Guide

{"@type":"Tenant",
"id":"vsphere.local",
...},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...},
{"@type":"Tenant",
"id":"rainpole",
...}
],
"metadata":{"size":20,"totalElements":4,"totalPages":1,"number":1,"offset":0}
}

Identity Service Examples for Creating a Tenant

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

n Syntax for Displaying Your Current Tenants

GET /api/tenants lists all the vRealize Automation tenants in your system.

n Syntax for Requesting a New Tenant

PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can
specify request parameters using JSON command line input or by calling an existing JSON
file from the command line.

n Syntax for Listing All Tenant Identity Stores

GET /api/tenants/{tenantId}/directories lists all available identity stores for a
named vRealize Automation tenant, such as the default tenant vsphere.local.

n Syntax for Linking an Identity Store to the Tenant

PUT /api/tenants/{tenantId}/directories/{id} links an LDAP, Active Directory, or
Native Active Directory identity store to the vRealize Automation tenant.

n Syntax for Searching LDAP or Active Directory for a User

GET /api/tenants/{tenantId}/principals/{userId} searches the configured LDAP
directory, Active Directory, or Native Active Directory for a user.

n Syntax for Assigning a User to a Role

PUT /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/
{scopeId}/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. 27
Programming Guide

Syntax for Displaying Your Current Tenants

GET /api/tenants lists all the vRealize Automation tenants in your system.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 28
Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This parameter does
not appear when you query a single profile.
n First, Previous, Next, and Last refer to corresponding pages of pageable
lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects
returned in a pageable list. Each tenant object can contain the following information:
n Id: Specifies the unique tenant identifier.
n urlName: Specifies the name of the tenant as it appears in URLs.
n Name: Specifies the name of the tenant for display purposes.
n description: Specifies the long description of the tenant.
n contactEmail: Specifies the primary contact email address.
n Password: Unused
n defaultTenant: Is set to True if the corresponding tenant is the default tenant
(vsphere.local).

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not output
when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not output
when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Example: curl Command to Display Current Tenants

The following example command displays all available tenants.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://$vRA/

identity/api/tenants

VMware, Inc. 29
Programming Guide

The response in JSON lists the current tenants. Format the output to improve its readability.
For information about formatting output, see Chapter 19 Filtering and Formatting REST API
Information.

{
"links":[],
"content"[
{
"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"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.

VMware, Inc. 30
Programming Guide

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants/$tenantId --data @$inputFileName.json

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

$tenantURL Specifies the URL of the tenant.

$tenantName Specifies the name of the tenant.

$description Specifies a description of the tenant.

$emailAddress Specifies the contact email address for the tenant.

$password Optional password for the new tenant. If blank, no password is required.

JSON Input File Template

To simplify command line input, you can call a JSON file with input parameters from the
command line. You create the JSON file using a text editor, replacing italicized variables in the
following template with your specific values.

{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"password": "$password",
"defaultTenant" : false
}

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 31
Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This parameter does
not appear when you query a single profile.
n First, Previous, Next, and Last refer to corresponding pages of pageable
lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects
returned in a pageable list. Each tenant object can contain the following information:
n Id: Specifies the unique tenant identifier.
n urlName: Specifies the name of the tenant as it appears in URLs.
n Name: Specifies the name of the tenant for display purposes.
n description: Specifies the long description of the tenant.
n contactEmail: Specifies the primary contact email address.
n Password: Unused
n defaultTenant: Is set to True if the corresponding tenant is the default tenant
(vsphere.local).

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not output
when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

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
}

The following example command requests a new tenant by calling the newTenant.json file.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token" https://

$vRA/identity/api/tenants/rainpole --data @C:\Temp\newTenant.json

VMware, Inc. 32
Programming Guide

Example: curl Command to Request a New Tenant With Parameters Inline

The following example command requests a new tenant with input parameters specified inline.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json"

-H "Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant",
"description":"New Custom Tenant","contactEmail":null,"defaultTenant":false}'

Syntax for Listing All Tenant Identity Stores

GET /api/tenants/{tenantId}/directories lists all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants/$tenantId/directories

$vRA Specifies the appliance name and fully qualified domain name, or IP address of
the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 33
Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This parameter
does not appear when you query a single profile.
n First, Previous, Next, and Last refer to corresponding pages of
pageable lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant
objects returned in a pageable list. Each tenant object can contain the following
information:
n Id: Specifies the unique tenant identifier.
n urlName: Specifies the name of the tenant as it appears in URLs.
n Name: Specifies the name of the tenant for display purposes.
n description: Specifies the long description of the tenant.
n contactEmail: Specifies the primary contact email address.
n Password: Unused
n defaultTenant: Is set to True if the corresponding tenant is the default tenant
(vsphere.local).

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not
output when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not
output when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Example: curl Command to List All Identity Stores for the Tenant
The following example command lists the identity stores.

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' -H

"Authorization: Bearer $token” https://$vRA/identity/api/tenants/MYCOMPANY/directories

The following JSON output is returned based on the command input.

{
"links":[],

VMware, Inc. 34
Programming Guide

"content":[
{
"@type":"IdentityStore",
"domain":"vcac.mycompany.com",
"name":"openLDAPPromocom",
"description":null,
"alias":"promocom.com",
"type":"LDAP",
"userNameDn":"cn=promocomadmin,ou=promocom,dc=vcac,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com"
},
{
"@type":"IdentityStore",
"domain":"example.mycompany.com",
"name":"openLDAPDemo",
"description":null,
"alias":"example.com",
"type":"LDAP",
"userNameDn":"cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com"
}
],
"metadata":{
"size":20,
"totalElements":2,
"totalPages":1,
"number":1,
"offset":0
}
}

Syntax for Linking an Identity Store to the Tenant

PUT /api/tenants/{tenantId}/directories/{id} links an LDAP, Active Directory, or Native
Active Directory identity store to the vRealize Automation tenant.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants/$tenantId/directories/$domainName --data

@$inputFileName.json

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

VMware, Inc. 35
Programming Guide

Parameter Description

$tenantId Specifies the ID of the tenant.

userId Specifies the ID of the user in the form name@domain.

$domainAlias Specifies the domain alias.

$domainName Specifies the domain of the identity store.

$grpBaseSearchDn Specifies the group search base Distinguished Name.

$identityStoreName Specifies a description of the new tenant.

$password Specifies the password.

$identityStoreType Specifies the identity store type for the tenant. The following values are supported:
n LDAP
n AD
n NATIVE_AD

$identityServerUrl Specifies the URL of the identity server.

$usrBaseSearchDn Specifies the user search base Distinguished Name.

$usrNameDn Specifies the Distinguished Name for the login user.

JSON Input File Template

Use this template to create a JSON input file. Replace the variables in the template with actual
values in the file.

{
"alias": "$domainAlias",
"domain": "$domainName",
"groupBaseSearchDn": "$grpBaseSearchDn",
"name": "$identityStoreName",
"password": "$password",
"type": "$identityStoreType",
"url": "$identityServerUrl",
"userBaseSearchDn": "$usrBaseSearchDn",
"userNameDn": "$usrNameDn"
}

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 36
Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This parameter
does not appear when you query a single profile.
n First, Previous, Next, and Last refer to corresponding pages of
pageable lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant
objects returned in a pageable list. Each tenant object can contain the following
information:
n Id: Specifies the unique tenant identifier.
n urlName: Specifies the name of the tenant as it appears in URLs.
n Name: Specifies the name of the tenant for display purposes.
n description: Specifies the long description of the tenant.
n contactEmail: Specifies the primary contact email address.
n Password: Unused
n defaultTenant: Is set to True if the corresponding tenant is the default tenant
(vsphere.local).

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not
output when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not
output when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Example: curl Command to Link an Identity Store to a Tenant

The following sample ldap.json.txt file contains parameters for the tenant request.

{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

VMware, Inc. 37
Programming Guide

"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}

The following example command links an identity store to a tenant by calling the example JSON
text file.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token” https://

$vRA/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt

The command also tests that vRealize Automation can connect to the identity store successfully.
If the command finishes successfully,vRealize Automation succeeded in connecting to the identity
store.

This response in JSON indicates that an identity store is successfully linked to the specified
tenant.

Request Headers
{
Content-Type = application/json
Accept = application/json
Content-Length = 413
Accept-Charset = big5, big5-hkscs, euc-jp, euc-kr, gb18030, gb2312, gbk,
ibm-thai, ibm00858, ibm01140, ibm01141, ibm01142, ibm01143, ibm01144, ibm01145,
ibm01146, ibm01147, ibm01148, ibm01149, ibm037, ibm1026, ibm1047, ibm273, ibm277,
ibm278, ibm280, ibm284, ibm285, ibm290, ibm297, ibm420, ibm424, ibm437, ibm500,
ibm775, ibm850, ibm852, ibm855, ibm857, ibm860, ibm861, ibm862, ibm863, ibm864,
ibm865, ibm866, ibm868, ibm869, ibm870, ibm871, ibm918, iso-2022-cn, iso-2022-jp,
iso-2022-jp-2, iso-2022-kr, iso-8859-1, iso-8859-13, iso-8859-15, iso-8859-2,
iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9,
jis_x0201, jis_x0212-1990, koi8-r, koi8-u, shift_jis, tis-620, us-ascii, utf-16,
utf-16be, utf-16le, utf-32, utf-32be, utf-32le, utf-8, windows-1250, windows-1251,
windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257,
windows-1258, windows-31j, x-big5-hkscs-2001, x-big5-solaris, x-compound_text,
x-euc-jp-linux, x-euc-tw, x-eucjp-open, x-ibm1006, x-ibm1025, x-ibm1046, x-ibm1097,
x-ibm1098, x-ibm1112, x-ibm1122, x-ibm1123, x-ibm1124, x-ibm1364, x-ibm1381,
x-ibm1383, x-ibm300, x-ibm33722, x-ibm737, x-ibm833, x-ibm834, x-ibm856, x-ibm874,
x-ibm875, x-ibm921, x-ibm922, x-ibm930, x-ibm933, x-ibm935, x-ibm937, x-ibm939,
x-ibm942, x-ibm942c, x-ibm943, x-ibm943c, x-ibm948, x-ibm949, x-ibm949c, x-ibm950,
x-ibm964, x-ibm970, x-iscii91, x-iso-2022-cn-cns, x-iso-2022-cn-gb, x-iso-8859-11,
x-jis0208, x-jisautodetect, x-johab, x-macarabic, x-maccentraleurope, x-maccroatian,
x-maccyrillic, x-macdingbat, x-macgreek, x-machebrew, x-maciceland, x-macroman,
x-macromania, x-macsymbol, x-macthai, x-macturkish, x-macukraine, x-ms932_0213,
x-ms950-hkscs, x-ms950-hkscs-xp, x-mswin-936, x-pck, x-sjis_0213, x-utf-16le-bom,
x-utf-32be-bom, x-utf-32le-bom, x-windows-50220, x-windows-50221, x-windows-874,
x-windows-949, x-windows-950, x-windows-iso2022jp
}
Response Headers
{
Date = Wed, 29 Oct 2014 22:41:57 GMT
Content-Type = application/json;charset=UTF-8
Content-Length = 0
Vary = Accept-Encoding,User-Agent

VMware, Inc. 38
Programming Guide

Keep-Alive = timeout=15, max=100

Connection = Keep-Alive
}
Successful

Unlinked Identity Store Error

If an identity store is not linked to the specified tenant, the response includes status code 400
such as in the following output.

Command failed [Rest Error]: {Status code: 400}, {Error code: 90027} , {Error
Source: null}, {Error Msg: Cannot connect to the directory service.}, {System
Msg: 90027-Connection to directory service can’t be established}

To resolve the problem, correct the identity store and connection details in the JSON input file
and rerun the command.

Syntax for Searching LDAP or Active Directory for a User

GET /api/tenants/{tenantId}/principals/{userId} searches the configured LDAP
directory, Active Directory, or Native Active Directory for a user.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants/$tenantId/principals/$userId

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

$userId Specifies the ID of the user in the form name@domain.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 39
Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This parameter does
not appear when you query a single profile.
n First, Previous, Next, and Last refer to corresponding pages of pageable
lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

@type Specifies the user name.

firstName Specifies the first name of the user.

lastName Specifies the last name of the user.

description Specifies the description of the user.

emailAddress Specifies the email address of the user.

locked Specifies the Boolean flag indicating if the user is locked out.

disabled Specifies the Boolean flag indicating if the user is disabled.

principalId Specifies the principal ID of the user in username@domain format.

tenantName Specifies the name of tenant to which user belongs.

name Specifies the first and last name concatenated.

Example: curl Command to Search LDAP or Active Directory for a User

The following example command queries the configured LDAP directory for a specific user.

curl --insecure -H "Accept:text/xml" -H "Authorization: Bearer $token" https://$vRA/

identity/api/tenants/$tenantId/principals/$userId

The following JSON output is returned based on the command input.

{
"links" : [ ],
"content" : [
{
"@type" : "User",
"firstName" : "Tony",
"lastName" : "Anteater",
"emailAddress" : "[email protected]",
"locked" : false,
"disabled" : false,
"principalId" :
{
"domain" : "example.mycompany.com",

VMware, Inc. 40
Programming Guide

"name" : "susan"
},
"tenantName" : "MYCOMPANY1",
"name" : "Tony Anteater"
}
]
}

Syntax for Assigning a User to a Role

PUT /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/
{scopeId}/roles/{scopeRoleId} assigns a user to a role.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/authorization/tenants/$tenantId/principals/$principalId/roles/
roleId

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the vRealize
Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

$principalId Specifies the ID of the user in name@domain format.

$roleId Specifies the ID of the user role.

Example: curl Command to Assign a User to a Role

The following example command string submits a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the
required JSON payload. For more information about getting the user name and domain values,
see Syntax for Searching LDAP or Active Directory for a User .

curl --insecure -H "Content-Type: application/json" -H "Authorization:

Bearer $token" "https://$vRA/identity/api/authorization/tenants/development/principals/
[email protected]/roles/CSP_TENANT_ADMIN/" --data "{}"

If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Syntax for Displaying all Roles Assigned to a User

GET /api/authorization/tenants/{tenantId}/principals/{principalId}/roles
displays all of the roles assigned to a user.

VMware, Inc. 41
Programming Guide

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/authorization/tenants/$tenantId/principals/$principalId/roles

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

principalId Specifies the ID of the user in the form name@domain.

Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

id Specifies the role ID.

name Specifies the role name.

description Specifies the role description.

status Specifies the status of this role.

assignedPermissions Specifies the set of permissions that are implied by this role assignment.

Example: curl Command to Display all Roles Assigned to a User

The following example command lists all the roles that are assigned to
[email protected].

curl --insecure -H "Content-Type: application/json" -H "Authorization:

Bearer $token" https://$vRA/identity/api/authorization/tenants/development/principals/
[email protected]/roles

The following JSON output is returned based on the command input.

{
"links" : [ ],
"content" : [
{
"@type" : "SystemRole",
"id" : "ABX_TENANT_ADMIN",
"name" : "Tenant Administrator",
"description" : "ABX Tenant Administrator",

VMware, Inc. 42
Programming Guide

"assignedPermissions" : [ {
"id" : "CATALOG_CONSUME_TENANT_MGMT",
"name" : "Catalog Consume Tenant Management",
"description" : "Consume services, resources and manage requests ... within a
Tenant",
"prereqAdminPermissions" : null
},
{
"id" : "MY_TENANT_MANAGEMENT",
"name" : "My Tenant Management",
"description" : "Manage my tenant.",
"prereqAdminPermissions" : null
},
{
"id" : "CATALOG_AUTHOR_TENANT",
"name" : "Catalog Tenant-level Author",
"description" : "Create, update and publish services, catalog ... across a Tenant.",
"prereqAdminPermissions" : null
},
{
"id" : "GUI_MY_TENANT_MANAGEMENT",
"name" : "My Tenant Administration User Interface",
"description" : "Access my tenant administration GUI.",
"prereqAdminPermissions" : null
},
{
"id" : "CATALOG_ENTITLE_TENANT",
"name" : "Catalog Tenant-level Entitlement Management",
"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

VMware, Inc. 43
Programming Guide

GUIs.",
"prereqAdminPermissions" : null
}
],
"metadata" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}

VMware, Inc. 44
Requesting a Machine
4
You use the catalog service to perform tasks related to requesting a machine.

The catalog service is comprised APIs for the consumer, service providers, and service
administrators. It is designed to be used by consumers and providers of the service catalog.
For example, a consumer would request a catalog item such as a machine. The service provider
would fulfill the request.

The catalog service includes Hypermedia as the Engine of Application State (HATEOAS) links.
The links function as templates that you can use to complete common tasks supported by the
API.

For example, if you submit a template request for a given context,

such as: catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests/template. You use the returned template, either as-is or modified, to
create a request that you POST or PUT to the target API, such as: catalog-service/api/
consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests.

This chapter includes the following topics:

n Request a Machine

n Catalog Service Examples for Requesting a Machine

Request a Machine
To request a machine, you first list all shared catalog items to find the machine, then make the
request for that item using a template.

Prerequisites

n Log in to vRealize Automation as a consumer or current business group user.

n Verify that the appliance name and fully qualified domain name of the vRealize Automation
instance are available.

n Verify that you have a valid HTTP bearer token that matches your login credentials. See
Chapter 2 REST API Authentication.

VMware, Inc. 45
Programming Guide

Procedure

1 List all shared catalog items in the catalog.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/

json" -H "Authorization: Bearer $token" https://$vRA/catalog-service/api/consumer/
entitledCatalogItemViews

For details regarding input and output for this request, see Syntax for Listing Shared and
Private Catalog Items .

2 Examine the response to find the catalogItemId

3 Get a template request for a catalog item.

Use the catalogItemId to submit the template request for this catalog item. In this example,
the catalogItemId is dc808d12-3786-4f7c-b5a1-d5f997c8ad66.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/

json" -H "Authorization: Bearer $token" https://$vRA/catalog-service/api/consumer/
entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template

For details regarding input and output for this request, see Syntax for Getting a Template
Request for a Catalog Item.

A template request for the catalog item is created. The fields and default values
are populated based on the configuration of the underlying blueprint. By default,
requestMachine.json is the name of the template request.

4 Review and edit the template request.

Review the contents of the template request and edit the values if you want to change
them from the default prior to submitting the request for a machine. For example, you can
specify a value for the description field or change the values for the machine resources if the
blueprint allows for a range.

5 Submit the request for a machine.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”
https://$vRA/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests --verbose --data
@C:/Temp/requestMachine.json
{
$contentsOfTemplateFromPrecedingSections
}

For details regarding input and output for this request see Syntax for Requesting a Machine .

VMware, Inc. 46
Programming Guide

6 (Optional) View the details of your request.

You can perform a GET on the URI in the Location header to retrieve the updated
request details. In this example, the URI-in-Location-header is 7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b

For details regarding input and output for this request, see Syntax for Viewing Details of a
Machine Request .

Catalog Service Examples for Requesting a Machine

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

n Syntax for Listing Shared and Private Catalog Items

GET /api/consumer/entitledCatalogItemViews retrieves a list of all shared viewable
catalog items for the current user. Shared catalog items do not belong to a specific business
group. This service also retrieves a list of all shared and private catalog items that can be
viewed, including their business groups.

n Syntax for Getting Information for a Catalog Item

GET /api/consumer/entitledCatalogItemViews/{id} gets information about a specific
catalog item.

n Syntax for Getting a Template Request for a Catalog Item

GET /api/consumer/entitledCatalogItems/{id}/requests/template retrieves a
template request for a specific catalog item. VMware supplies a number of templates to
help you create different types of machine requests.

n Syntax for Requesting a Machine

POST /api/consumer/entitledCatalogItems/{id}/requests submits a request for a
specific catalog item with input provided in a JSON file.

n Syntax for Viewing Details of a Machine Request

GET /api/consumer/requests/{requestId} provides the details of a machine request,
where requestId is the URI in the Location header.

Syntax for Listing Shared and Private Catalog Items

GET /api/consumer/entitledCatalogItemViews retrieves a list of all shared viewable catalog
items for the current user. Shared catalog items do not belong to a specific business group. This
service also retrieves a list of all shared and private catalog items that can be viewed, including
their business groups.

VMware, Inc. 47
Programming Guide

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

page number The page number. Default is 1.

limit The number of entries per page. The default is 20.

$orderby Multiple comma-separated properties sorted in ascending or descending order. Valid

OData properties include the following:
n name - filter based on catalog item name.
n status - filter based on catalog item status.
n service/id - filter based on catalog item service id.
n service/name - filter based on catalog item service name.
n organization/subTenant/id - filter based on catalog item business group ID, which
you can find in the catalogItem payload under organization > subtenantRef
n organization/subTenant/name - filter based on catalog item business group
name, which you can find in catalogItem payload under organization
>subtenantLabel
n outputResourceType/id - filter based on catalog item output resource type ID, for
example : Infrastructure.Virtual
n outputResourceType/name - Filter based on catalog item output resource type
name, for example: "VirtualMachine".
n catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n icon/id - filter based on catalog item icon ID.

$top Sets the number of returned entries from the top of the response

$skip Sets the number of entries to skip.

VMware, Inc. 48
Programming Guide

Parameter Description

$filter Boolean expression for whether a particular entry should be included in the response.
Valid OData properties include the following:
n name - filter based on catalog item name.
n status - filter based on catalog item status.
n service/id - filter based on catalog item service id.
n service/name - filter based on catalog item service name.
n organization/subTenant/id - filter based on catalog item business group ID, which
you can find in the catalogItem payload under organization > subtenantRef
n organization/subTenant/name - filter based on catalog item business group
name, which you can find in catalogItem payload under organization
>subtenantLabel
n outputResourceType/id - filter based on catalog item output resource type ID, for
example : Infrastructure.Virtual
n outputResourceType/name - Filter based on catalog item output resource type
name, for example: "VirtualMachine".
n catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n icon/id - filter based on catalog item icon ID.

serviceId (Optional) Query parameter to filter the returned catalog items by one specific service.

onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a
request on behalf of another user.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.

catalogItemId Specifies the catalog item identifier.

name Specifies the user friendly name of the catalog item. Specifies the property type is
string.

description Specifies a short description of the catalog item. Specifies the property type is string.

catalogItemTypeRef Specifies the type of the catalog item.

serviceRef Specifies the catalog service that contains the catalog item.

iconId Specifies the associated icon representing this item.

isNoteworthy Specifies if the catalog item should be highlighted to users for a period of time.

dateCreated Specifies the date that this item was created in the catalog.

VMware, Inc. 49
Programming Guide

Property Description

lastUpdatedDate Specifies the date that this item was last updated in the catalog.

entitledOrganizations Specifies the organizations in which the catalog item can be consumed by the current
user.

Example: curl Command to List All Shared Catalog Items

The following example command retrieves information about all shared catalog items of type
ConsumerEntitledCatalogItemView.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/
entitledCatalogItemViews

If backward compatibility is required, use the following example command instead.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/
entitledCatalogItems

The following JSON output is returned based on the command input.

{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
}
],
"entitledOrganizations": [
{
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
}
],
"catalogItemId": "dc808d12-3786-4f7c-b5a1-d5f997c8ad66",
"name": "Linux",
"description": "Linux blueprint for API demo",

VMware, Inc. 50
Programming Guide

"isNoteworthy": false,
"dateCreated": "2015-07-29T03:54:28.141Z",
"lastUpdatedDate": "2015-07-29T12:46:56.405Z",
"iconId": "cafe_default_icon_genericCatalogItem",
"catalogItemTypeRef": {
"id": "com.vmware.csp.component.cafe.composition.blueprint",
"label": "Composite Blueprint"
},
"serviceRef": {
"id": "057d4095-95f1-47da-b14b-641ac9010c97",
"label": "Infrastructure Services"
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Example: curl Command to Locate the Details of a Specific Catalog Item

To search for specific catalog item, add the $catalogItemId. The following example command
retrieves information about a catalog item with the name $catalogItemName.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/
entitledCatalogItemViews?$filter=name+eq+%27$catalogItemName%27

Syntax for Getting Information for a Catalog Item

GET /api/consumer/entitledCatalogItemViews/{id} gets information about a specific
catalog item.

REST API Catalog Service

The REST API supports OData filtering. For more information about supported OData filters, see
the Important Notes About catalog-service and OData Queries section located on the Overview
page of the Catalog Service API.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 51
Programming Guide

Parameter Description

URL https://$vRA/catalog-service/api/consumer/entitledCatalogItemViews/{id}

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

page number The page number. Default is 1.

limit The number of entries per page. The default is 20.

$orderby Multiple comma-separated properties sorted in ascending or descending order. Valid

OData properties include the following:
n name - filter based on catalog item name.
n status - filter based on catalog item status.
n service/id - filter based on catalog item service id.
n service/name - filter based on catalog item service name.
n organization/subTenant/id - filter based on catalog item business group ID, which
you can find in the catalogItem payload under organization > subtenantRef
n organization/subTenant/name - filter based on catalog item business group
name, which you can find in catalogItem payload under organization
>subtenantLabel
n outputResourceType/id - filter based on catalog item output resource type ID, for
example : Infrastructure.Virtual
n outputResourceType/name - Filter based on catalog item output resource type
name, for example: "VirtualMachine".
n catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n icon/id - filter based on catalog item icon ID.

$top Sets the number of returned entries from the top of the response

$skip Sets the number of entries to skip.

VMware, Inc. 52
Programming Guide

Parameter Description

$filter Boolean expression for whether a particular entry should be included in the response.
Valid OData properties include the following:
n name - filter based on catalog item name.
n status - filter based on catalog item status.
n service/id - filter based on catalog item service id.
n service/name - filter based on catalog item service name.
n organization/subTenant/id - filter based on catalog item business group ID, which
you can find in the catalogItem payload under organization > subtenantRef
n organization/subTenant/name - filter based on catalog item business group
name, which you can find in catalogItem payload under organization
>subtenantLabel
n outputResourceType/id - filter based on catalog item output resource type ID, for
example : Infrastructure.Virtual
n outputResourceType/name - Filter based on catalog item output resource type
name, for example: "VirtualMachine".
n catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n icon/id - filter based on catalog item icon ID.

serviceId (Optional) Query parameter to filter the returned catalog items by one specific service.

onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a
request on behalf of another user.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.

catalogItemId Specifies the catalog item identifier.

name Specifies the user friendly name of the catalog item. Specifies the property type is
string.

description Specifies a short description of the catalog item. Specifies the property type is string.

catalogItemTypeRef Specifies the type of the catalog item.

serviceRef Specifies the catalog service that contains the catalog item.

iconId Specifies the associated icon representing this item.

isNoteworthy Specifies if the catalog item should be highlighted to users for a period of time.

dateCreated Specifies the date that this item was created in the catalog.

VMware, Inc. 53
Programming Guide

Property Description

lastUpdatedDate Specifies the date that this item was last updated in the catalog.

entitledOrganizations The list of organizations in which the current user can consume the catalog item.

Example: curl Command to Get Information for a Catalog Item

The following example command retrieves information catalog item with the name
$filter=name+eq+%27$catalogItemName%27.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/
entitledCatalogItemViews?$filter=name+eq+%27$catalogItemName%27

The following JSON output is returned based on the command input.

{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
}
],
"entitledOrganizations": [
{
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
}
],
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"name": "Linux",
"description": "Linux blueprint for API demo",
"isNoteworthy": false,
"dateCreated": "2015-07-29T03:54:28.141Z",
"lastUpdatedDate": "2015-07-29T12:46:56.405Z",
"iconId": "cafe_default_icon_genericCatalogItem",
"catalogItemTypeRef": {
"id": "com.vmware.csp.component.cafe.composition.blueprint",
"label": "Composite Blueprint"

VMware, Inc. 54
Programming Guide

},
"serviceRef": {
"id": "057d4095-95f1-47da-b14b-641ac9010c97",
"label": "Infrastructure Services"
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Getting a Template Request for a Catalog Item

GET /api/consumer/entitledCatalogItems/{id}/requests/template retrieves a template
request for a specific catalog item. VMware supplies a number of templates to help you create
different types of machine requests.

Overview
In the entitledCatalogItemViews response, a link field contains a value similar to the following.

{
"@type":"link",
"href":"https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template",
"rel":"GET: Request Template"
}

This URL is a HATEOAS link for a template request for this catalog item. The rel field provides
a description of the link (request template) and indicates the HTTP method to use with the
URI in the href field (GET). By using these HATEOAS links, you can make follow-on API calls
without having to consult the API documentation for the URI syntax or construct the links
programmatically.

Review and Edit the Template Request

The returned template request is specific to the applicable catalog item. The fields and default
values are populated based on the configuration of the underlying blueprint.

VMware, Inc. 55
Programming Guide

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.

Parameter Description

id The UUID of the catalog item.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

entitledOrganizations The list of organizations in which the current user can consume the catalog item.

catalogItemId Specifies the catalog item identifier.

Example: curl Command to Get a Template Request for a Catalog Item

The following example command retrieves a template request for the catalog item with ID
dc808d12-3786-4f7c-b5a1-d5f997c8ad66.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token” https://$vRA/catalog-service/api/consumer/
entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template

The following JSON output is returned based on the command input.

Note Price is referred to as cost in API commands and output.

{
"type": "com.vmware.vcac.catalog.domain.request.CatalogItemProvisioningRequest",
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"requestedFor": "[email protected]",
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"description": null,
"reasons": null,
"data": {
"Existing_Network_1": {
"componentTypeId": "com.vmware.csp.component.cafe.composition",
"componentId": null,
"classId": "Blueprint.Component.Declaration",
"typeFilter": "LinuxDemo*Existing_Network_1",
"data": {
"_cluster": 1,

VMware, Inc. 56
Programming Guide

"_hasChildren": false,
"description": null,
"name": "Existing Network",
"networkname": "Existing Network",
"subnetmask": "255.255.255.0"
}
},
"vSphere-Linux": {
"componentTypeId": "com.vmware.csp.component.cafe.composition",
"componentId": null,
"classId": "Blueprint.Component.Declaration",
"typeFilter": "LinuxDemo*vSphere-Linux",
"data": {
"Cafe.Shim.VirtualMachine.MaxCost": 0,
"Cafe.Shim.VirtualMachine.MinCost": 0,
"_cluster": 1,
"_hasChildren": false,
"action": "FullClone",
"allow_storage_policies": false,
"archive_days": 0,
"blueprint_type": "1",
"cpu": 1,
"custom_properties": [],
"daily_cost": 0,
"datacenter_location": null,
"description": null,
"disks": [
{
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Compute.Machine.MachineDisk",
"typeFilter": null,
"data": {
"capacity": 6,
"id": 0,
"initial_location": "",
"is_clone": false,
"label": "",
"storage_reservation_policy": "",
"userCreated": true,
"volumeId": 0
}
}
],
"display_location": false,
"guest_customization_specification": null,
"lease_days": 0,
"machine_actions": [
"DESTROY",
"POWER_ON",
"CONNECT_RDP_SSH",
"REPROVISION",
"POWER_CYCLE",
"EXPIRE",
"SUSPEND",

VMware, Inc. 57
Programming Guide

"CONNECT_REMOTE_CONSOLE",
"CONNECT_USING_VDI"
],
"machine_prefix": {
"componentId": null,
"classId": "Infrastructure.Compute.MachinePrefix",
"id": "Use group default"
},
"max_network_adapters": 0,
"max_per_user": 0,
"max_volumes": 60,
"memory": 4096,
"nics": [
{
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Compute.Machine.Nic",
"typeFilter": null,
"data": {
"address": "",
"assignment_type": "DHCP",
"custom_properties": null,
"id": 0,
"load_balancing": "",
"network_profile": "Existing Network"
}
}
],
"number_of_instances": 1,
"os_arch": "x86_64",
"os_distribution": null,
"os_type": "Linux",
"os_version": null,
"platform_name": "vsphere",
"platform_type": "virtual",
"property_groups": [
null
],
"provisioning_workflow": {
"componentId": null,
"classId": "Infrastructure.Compute.ProvisioningWorkflow",
"id": "CloneWorkflow"
},
"reservation_policy": {
"componentId": null,
"classId": "Infrastructure.Reservation.Policy.ComputeResource",
"id": "None"
},
"security_groups": [],
"security_tags": [],
"source_machine": null,
"source_machine_external_snapshot": null,
"source_machine_name": "cbpcentos_63_x86",
"source_machine_vmsnapshot": null,
"storage": 6

VMware, Inc. 58
Programming Guide

}
}
}
}

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.

Prepare your Request

From the entitledCatalogItemViews response, locate the link field that contains a value similar to
the following:

{
"@type":"link",
"href":"https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests",
"rel":"POST: Submit Request"
}

Use the information in this response to edit the template construct the URI to request the desired
catalog item using a POST command.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
$catalogId/requests

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

catalogItemId The identifier of a catalog item. Typically, this is provided by users via the
REST URI when making an entitledCatalogItem provisioning request.

requestedFor The user for whom this request is being made. Must be the fully qualified
user ID. Typically this is provided by the REST URI when making an
entitledCatalogItem provisioning request.

businessGroupId The business group identifier associated with the request. Typically this is
provided via the REST URI when making the request.

description The catalog item description.

reasons

data Context-specific properties. Obtain the consumerEntitledCatalogItem

template request to identify the properties available for a given context.

VMware, Inc. 59
Programming Guide

Output
The command output contains property names and values based on the command input
parameters.

Property Description

version Displays the object version number.

state Specifies the item state, such as submitted.

approvalStatus Specifies a status indicating whether this request has been approved, rejected, or is still
pending some form of approval.

waitingStatus Specifies a status indicating whether this request is waiting on any external users or services
before it is able to progress.

requestNumber Specifies a more user-friendly identifier for this request.

executionStatus Specifies the current execution status of the request.

stateName Specifies the localized state name.

phase Specifies the current phase of the request, which is more coarse grained and easier for users to
understand.

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

description Contains a brief description of this request.

reasons Specifies the business reasons entered by the requestor or owner of this request.

requestedFor Specifies the ID of the user for whom this request is logged.

requestedBy Specifies the ID of the user who actually submitted the request

organization Subtenant and/or tenant owner of this request.

requestorEntitlement Specified the value of the requestorEntitlement setting.

Id

preApprovalId Specifies the ID of the preApproval setting.

postApprovalId Specifies the ID of the approval generated for the post-provisioning workflow step.

dateCreated Specifies the date when this request was sent to the catalog.

lastUpdated Specifies the date when this request was last updated.

dateSubmitted Specifies the date when this request was first submitted.

dateApproved Specifies the date when this request was approved.

dateCompleted Specifies the date when this request was completed.

quote Contains a quote made by the provider defining the estimated price(es) associated with the
request and/or any resources provisioned as a result of the request.

VMware, Inc. 60
Programming Guide

Property Description

requestCompletion Contains additional request completion information.

requestData Contains a map of the provider-specific field-value pairs collected for this request.

retriesRemaning Specifies the number of attempts remaining to move this request from its current state to the
next state in the request workflow.
Some state transitions require calls to external services. These calls may fail due to transient
errors such as momentary network errors. In these cases, the catalog will retry the call a
number of times before failing.
This property defines the number of retries remaining for the current state transition. When it
reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset
to the default number of retries for every new operation that is triggered.

requestedItemName Specifies the item name.

requestedItemDescri Specifies the item description.

ption

components Returns the list of components associated with the request. The provider supplies this list of
components after request initialization.

Example: curl Command to Request a Machine

To construct your request, refer to the entitledCatalogItemViews response received when you
ran the request described in Syntax for Getting a Template Request for a Catalog Item, locate a
link field that contains a value similar to the following:

{
"@type":"link",
"href":"https://$vRA/catalog-service/api/consumer/entitledCatalogItems/
f89fcbbf-7716-4a61-addd-a822dd4206f6/requests",
"rel":"POST: Submit Request"
}

The following example command submits a machine request using appropriately edited template
content from the entitledCatalogItemViews response.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”
https://$vRA/catalog-service/api/consumer/entitledCatalogItems/f89fcbbf-7716-4a61-addd-
a822dd4206f6/requests
{
$contentsOfTemplateFromPrecedingSections
}

VMware, Inc. 61
Programming Guide

Example: Output with Request and Response Headers

The following sample displays the request and response headers and the command output. Use
the indicated JSON text file or inline text as input.

{
Accept = application/json
Content-Type = application/json
Content-Length = 2806
}
Response Headers
{
Date = Wed, 03 Dec 2014 20:58:34 GMT
ETag = "0"
Location = https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b
{
$requestObjectDetails
}

Content-Type = application/json;charset=UTF-8
Content-Length = 0
Vary = Accept-Encoding,User-Agent
Keep-Alive = timeout=15, max=100
Connection = Keep-Alive
}
null

Syntax for Viewing Details of a Machine Request

GET /api/consumer/requests/{requestId} provides the details of a machine request, where
requestId is the URI in the Location header.

Request Status
Typically, the request status information is the most important part of request details. The phase
field corresponds to the status displayed in the Requests tab in the interface. You can rerun this
command multiple times to monitor the state of a machine request.

Table 4-1. Request Phase Status

Phase Description End State?

UNSUBMITTED Request was saved but not submitted. No

PENDING_PRE_APPROVAL Request is subject to approval - pre-provisioning approval No

required.

IN_PROGRESS Request is in progress, machine is being provisioned. No

PENDING_POST_APPROVAL Request is subject to approval, post-provisioning approval No

required.

VMware, Inc. 62
Programming Guide

Table 4-1. Request Phase Status (continued)

Phase Description End State?

SUCCESSFUL Request completed successfully. The machine is available Yes

under provisioned resources on the Items tab.

FAILED Request failed. Yes

REJECTED Request approval was rejected and will not complete. Yes

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/requests/$requestId

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$requestId Specifies the request ID. See Display Your Provisioned Resources Example to view all
of your requests and search for a request ID.
The required request ID is located at the end of the Location URL in the response
header.
The request ID is located in the Location field of the response header if you
submitted the request with the –headers flag.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

version Displays the object version number.

state Specifies the item state, such as submitted.

approvalStatus Specifies a status indicating whether this request has been approved, rejected, or is still
pending some form of approval.

waitingStatus Specifies a status indicating whether this request is waiting on any external users or services
before it is able to progress.

requestNumber Specifies a more user-friendly identifier for this request.

executionStatus Specifies the current execution status of the request.

stateName Specifies the localized state name.

phase Specifies the current phase of the request, which is more coarse grained and easier for users to
understand.

VMware, Inc. 63
Programming Guide

Property Description

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

description Contains a brief description of this request.

reasons Specifies the business reasons entered by the requestor or owner of this request.

requestedFor Specifies the ID of the user for whom this request is logged.

requestedBy Specifies the ID of the user who actually submitted the request

organization Subtenant and/or tenant owner of this request.

requestorEntitlement Specified the value of the requestorEntitlement setting.

Id

preApprovalId Specifies the ID of the preApproval setting.

postApprovalId Specifies the ID of the approval generated for the post-provisioning workflow step.

dateCreated Specifies the date when this request was sent to the catalog.

lastUpdated Specifies the date when this request was last updated.

dateSubmitted Specifies the date when this request was first submitted.

dateApproved Specifies the date when this request was approved.

dateCompleted Specifies the date when this request was completed.

quote Contains a quote made by the provider defining the estimated price(es) associated with the
request and/or any resources provisioned as a result of the request.

requestCompletion Contains additional request completion information.

requestData Contains a map of the provider-specific field-value pairs collected for this request.

retriesRemaning Specifies the number of attempts remaining to move this request from its current state to the
next state in the request workflow.
Some state transitions require calls to external services. These calls may fail due to transient
errors such as momentary network errors. In these cases, the catalog will retry the call a
number of times before failing.
This property defines the number of retries remaining for the current state transition. When it
reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset
to the default number of retries for every new operation that is triggered.

requestedItemName Specifies the item name.

requestedItemDescri Specifies the item description.

ption

components Returns the list of components associated with the request. The provider supplies this list of
components after request initialization.

VMware, Inc. 64
Programming Guide

Example: curl Command to View the Details of the Machine Request

The following example command displays details of a request.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”

https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b

The following sample output contains information about the catalog item request 7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b.

{
"@type": "CatalogItemRequest",
"id": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"iconId": "cafe_default_icon_genericCatalogItem",
"version": 6,
"requestNumber": 8,
"state": "SUCCESSFUL",
"description": "API test",
"reasons": null,
"requestedFor": "[email protected]",
"requestedBy": "[email protected]",
"organization": {
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
},
"requestorEntitlementId": "1b409157-152c-43c4-b4cc-1cdef7f6adf8",
"preApprovalId": null,
"postApprovalId": null,
"dateCreated": "2015-07-29T13:50:33.689Z",
"lastUpdated": "2015-07-29T13:55:35.951Z",
"dateSubmitted": "2015-07-29T13:50:33.689Z",
"dateApproved": null,
"dateCompleted": "2015-07-29T13:55:35.949Z",
"quote": {},
"requestCompletion": {
"requestCompletionState": "SUCCESSFUL",
"completionDetails": null
},
"requestData": {
$detailsOfSubmittedRequest
},
"retriesRemaining": 3,
"requestedItemName": "Linux",
"requestedItemDescription": "Linux blueprint for API demo",
"stateName": "Successful",
"approvalStatus": "POST_APPROVED",
"executionStatus": "STOPPED",
"waitingStatus": "NOT_WAITING",
"phase": "SUCCESSFUL",
"catalogItemRef": {
"id": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",

VMware, Inc. 65
Programming Guide

"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. 66
Approving a Machine Request
5
You use a series of work item service commands to approve a machine request.

Basic components of the work item service are the work item and the assignment. The work item
service provides a standard way to present work items to users. For example, a user can view all
work items and select the item to perform such as approving a machine request.

This chapter includes the following topics:

n Approve a Machine Request

n Work Item Service Examples for Approving a Machine Request

Approve a Machine Request

To approve a machine request, you first get a work item ID, then specify the ID in the approval.

Prerequisites

n Log in to vRealize Automation as an approver with at least one of the following qualifications:

n You are designated as an approver in an approval policy.

n You belong to a group which has been designated as an approval group in an approval
policy.

n You are designated as a delegate for someone who is an approver.

n Verify that the appliance name and fully qualified domain name of the vRealize Automation
instance are available.

n Verify that you have a valid HTTP bearer token that matches your login credentials. See
Chapter 2 REST API Authentication.

Procedure

1 List all available work item IDs.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems

For details regarding input and output for this request, see Syntax for Listing Work Items.

VMware, Inc. 67
Programming Guide

2 Examine the response to find the workItemId

3 Get details for a specific work item ID.

Use the workItemId to get the details for this work item. In this example, the workItemId is
5e3e9519-78ea-4409-a52c-e4aa3bc56511.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511

For details regarding input and output for this request, see Syntax for Getting Work Item
Details.

4 Construct a JSON file that contains the work item ID information that you need to approve a
machine request.

a Copy the appropriate JSON input file template to a new file in an XML editor that
maintains formatting.

b Substitute the input variables in the template with the values you obtained for your
specific work item ID, for example 5e3e9519-78ea-4409-a52c-e4aa3bc56511.

c Save the file with a new name, for example, approve.json.

For details regarding input and output for this request, see Syntax for Constructing a JSON
File to Approve a Machine Request.

5 Approve the submitted machine request by specifying the work item ID and including the
JSON file as part of the command line.

curl --insecure -H "Content-Type:application/json"

-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json

For details regarding input and output for this request, see Syntax for Approving a Submitted
Machine Request.

Results

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.

VMware, Inc. 68
Programming Guide

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.

n Syntax for Constructing a JSON File to Approve a Machine Request

You can specify a JSON file in your vRealize Automation REST API command line input. For
example, when you enter a command to approve a machine request, you can include the
name of a JSON file that contains all the parameters required to approve the request and
complete the work item.

n Syntax for Approving a Submitted Machine Request

PUT /api/workitems/{id} approves a submitted work item request to complete the
request. To construct the approval command, you add work item and work item form details
to a JSON file, and call that JSON file from the command line. Use a template to correctly
format the JSON file content.

n Syntax for Updating Price Information

POST /api/blueprints/{id}/costs/upfront of the composition service, updates and
displays price information for a deployment. The price of a deployment is based on which
blueprint you request plus details of the specific request. For example, if the blueprint allows
for a range of CPU, memory, or storage values, the price depends on the value requested.

Syntax for Listing Work Items

GET /api/workitems lists the unique IDs of all available work items.

Inputs
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/workitem-service/api/workitems

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 69
Programming Guide

Property Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

work itemNumber Displays a reference number for the work item.

id Specifies the unique identifier of this resource.

version Displays the object version number.

assignees Displays the list of work item assignees.

subTenantId Optionally associates the work item with a specific business group granting users with
management responsibilities over that business group permission to see the approval.

tenantId Specifies the tenant ID for the work item.

callbackEntityId Specifies the callback entity ID for the work item.

work itemType Specifies the work item type for the work item.

completedDate Specifies the date when the work item was completed.

assignedDate Specifies the date when the work item was assigned.

createdDate Specifies the created date of this instance.

assignedOrComplete Specifies the date to be displayed on UI.

dDate

formUrl Specifies the URL from which the layout for this work item can be retrieved.

serviceId Specifies the service ID that generated this work item instance.

work itemRequest Specifies the corresponding work item request object.

status Specifies the status of the work item.

completedBy Specifies the principal ID of user who completed the work item.

availableActions Contains a list of relevant work item actions.

Metadata Specifies the paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

VMware, Inc. 70
Programming Guide

Example: curl Command

The following example command retrieves all the available work item IDs.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”
https://$vRA/workitem-service/api/workitems

Example: JSON Output

The following JSON output is returned based on the command input.

Note Price is referred to as cost in API commands and output.

{
"links" : [ ],
"content" : [ {
"@type" : "WorkItem",
"id" : "1755ef1a-d6f0-4901-9ecd-d03352ae4a05",
"version" : 1,
"workItemNumber" : 1,
"assignees" : [ {
"principalId" : "[email protected]",
"principalType" : "USER"
} ],
"tenantId" : "MYCOMPANY",
"callbackEntityId" : "1",
"workItemType" : {
"id" : "com.mycompany.cafe.samples.travel.workItem",
"name" : "Workspace Assignment",
"pluralizedName" : "Workspace Assignments",
"description" : "Location Specific Workspace Assignment",
"serviceTypeId" : "com.mycompany.cafe.samples.travel.api",
"actions" : [ {
"id" : "com.mycompany.cafe.samples.travel.workItem.complete",
"name" : "Reserve Workspace",
"stateName" : "Completed",
"icon" : {
"id" : "baa623db-0ca0-4db7-af41-9a301bc9e152",
"name" : "Complete Action Icon",
"contentType" : "image/png",
"image" : null
}
}, {
"id" : "com.mycompany.cafe.samples.travel.workItem.cancel",
"name" : "Workspace Unavailable",
"stateName" : "Cancelled",
"icon" : {
"id" : "b03f994a-e1ec-4aae-8fae-e747ed680a5e",
"name" : "Cancel Action Icon",
"contentType" : "image/png",
"image" : null
}

VMware, Inc. 71
Programming Guide

} ],
"completeByEmail" : true,
"commentsField" : null,
"listView" : {
"columns" : [ {
"id" : "duration",
"label" : "Duration",
"description" : "The length of stay, measured in days.",
"dataType" : {
"type" : "primitive",
"typeId" : "INTEGER"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
}, {
"id" : "location",
"label" : "Destination",
"description" : "The destination to which travel is being requested.",
"dataType" : {
"type" : "ref",
"componentTypeId" : null,
"componentId" : null,
"classId" : "location",
"typeFilter" : null,
"label" : null
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
}, {
"id" : "arrivalDate",
"label" : "Arrival Date",
"description" : "The date of arrival at the destination",
"dataType" : {
"type" : "primitive",
"typeId" : "DATE_TIME"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,

VMware, Inc. 72
Programming Guide

"isMultiValued" : false
} ],
"defaultSequence" : [ "location", "arrivalDate", "duration" ]
},
"version" : 3,
"forms" : {
"workItemDetails" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemNotification" : {
"type" : "external",
"formId" : "travel.itinerary.details"
}
}
},

.
.
.

"completedDate" : null,
"assignedDate" : "2014-02-20T23:55:31.600Z",
"createdDate" : "2014-02-20T23:55:31.600Z",
"assignedOrCompletedDate" : "2014-02-20T23:55:31.600Z",
"serviceId" : "2af18227-6a00-49e9-a76b-96de3ee767d2",
"workItemRequest" : {
"itemId" : "531660fd-b540-4946-9917-38c023b61c02",
"itemName" : "test travel 1",
"itemDescription" : "test travel 1",
"itemRequestor" : "[email protected]",
"itemCost" : 0.0,
"itemData" : {
"entries" : [ {
"key" : "requestLeaseTotal",
"value" : {
"type" : "money",
"currencyCode" : null,
"amount" : 1065.0
}
}, {
"key" : "approvalId",
"value" : {
"type" : "string",
"value" : "7a8b6054-1922-4f82-9266-245dffaa957c"
}
}, {
"key" : "requestClassId",
"value" : {
"type" : "string",

VMware, Inc. 73
Programming Guide

"value" : "request"
}
}, {
"key" : "requestedFor",
"value" : {
"type" : "string",
"value" : "[email protected]"
}
}, {
"key" : "requestReasons"
}, {
"key" : "requestedItemName",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestInstanceId",
"value" : {
"type" : "string",
"value" : "1cfe7177-74e3-4d68-a559-ea17587022ca"
}
}, {
"key" : "requestRef",
"value" : {
"type" : "string",
"value" : "15"
}
}, {
"key" : "requestedItemDescription",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestLeaseRate",
"value" : {
"type" : "moneyTimeRate",
"cost" : {
"type" : "money",
"currencyCode" : null,
"amount" : 213.0
},
"basis" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 1
}
}
}, {
"key" : "requestingServiceId",
"value" : {
"type" : "string",
"value" : "f91d044a-04f9-4b96-8542-375e3e4e1dc1"
}

VMware, Inc. 74
Programming Guide

}, {
"key" : "policy",
"value" : {
"type" : "string",
"value" : "test travel approval policy"
}
}, {
"key" : "phase",
"value" : {
"type" : "string",
"value" : "Pre Approval"
}
}, {
"key" : "requestDescription",
"value" : {
"type" : "string",
"value" : "t"
}
}, {
"key" : "requestLease",
"value" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 5
}
}, {
"key" : "requestedBy",
"value" : {
"type" : "string",
"value" : "[email protected]"
}
} ]
}
},
"status" : "Active",
"availableActions" : [ ]
} ],
"metadata" : {
"size" : 20,
"totalElements" : 7,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}

Syntax for Getting Work Item Details

GET /api/workitems/{id} retrieves the details of a pending work item. You need these details
to submit a completion request.

VMware, Inc. 75
Programming Guide

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/workitem-service/api/workitems/workitem_ID

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

workitem_ID Specifies the unique identifier of a work item. See Syntax for Listing Work
Items.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

work itemNumber Displays a reference number for the work item.

id Specifies the unique identifier of this resource.

version Displays the object version number.

assignees Displays the list of work item assignees.

subTenantId Optionally associates the work item with a specific business group granting users with
management responsibilities over that business group permission to see the approval.

tenantId Specifies the tenant ID for the work item.

callbackEntityId Specifies the callback entity ID for the work item.

work itemType Specifies the work item type for the work item.

completedDate Specifies the date when the work item was completed.

assignedDate Specifies the date when the work item was assigned.

createdDate Specifies the created date of this instance.

assignedOrComplete Specifies the date to be displayed on UI.

dDate

VMware, Inc. 76
Programming Guide

Property Description

formUrl Specifies the URL from which the layout for this work item can be retrieved.

serviceId Specifies the service ID that generated this work item instance.

work itemRequest Specifies the corresponding work item request object.

status Specifies the status of the work item.

completedBy Specifies the principal ID of user who completed the work item.

availableActions Contains a list of relevant work item actions.

Metadata Specifies the paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Example: curl Command

The following example command retrieves the necessary details for the specified work item.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511

Example: JSON Output

The following JSON output is returned based on the command input.

Note Price is referred to as cost in API commands and output.

To view the contents of a JSON output file, for example workItemDetails.json, use the !
command with more in UNIX or type in Windows.

n (UNIX) vcac-shell>! more workItemDetails.json

n (Windows) vcac-shell> ! CMD /C type workItemDetails.json

vcac-shell> ! more workItemDetails.json

{
"id" : "5e3e9519-78ea-4409-a52c-e4aa3bc56511",
"version" : 0,
"workItemNumber" : 8,
"assignees" : [ {
"principalId" : "[email protected]",
"principalType" : "USER"
} ],
"subTenantId" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"tenantId" : "MYCOMPANY",

VMware, Inc. 77
Programming Guide

"callbackEntityId" : "069dc3ce-a260-4d6a-b191-683141c994c0",
"workItemType" : {
"id" : "com.mycompany.csp.core.approval.workitem.request",
"name" : "Approval",
"pluralizedName" : "Approvals",
"description" : "",
"serviceTypeId" : "com.mycompany.csp.core.cafe.approvals",
"actions" : [ {
"id" : "com.mycompany.csp.core.approval.action.approve",
"name" : "Approve",
"stateName" : "Approved",
"icon" : {
"id" : "c192b6a7-5b35-4a3b-8593-107ffcf8c3a8",
"name" : "approved.png",
"contentType" : "image/png",
"image" : null
}
}, {
"id" : "com.mycompany.csp.core.approval.action.reject",
"name" : "Reject",
"stateName" : "Rejected",
"icon" : {
"id" : "61c6da67-1164-421d-b575-10a245c89e10",
"name" : "rejected.png",
"contentType" : "image/png",
"image" : null
}
} ],
"completeByEmail" : true,
"commentsField" : "businessJustification",
"listView" : {
"columns" : [ {
"id" : "requestedItemName",
"label" : "Requested Item",
"description" : "",
"dataType" : {
"type" : "primitive",
"typeId" : "STRING"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
},

.
.
.

{
"id" : "requestLease",

VMware, Inc. 78
Programming Guide

"label" : "Lease",
"description" : "",
"dataType" : {
"type" : "primitive",
"typeId" : "TIME_SPAN"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
} ],
"defaultSequence" : [ "requestRef", "requestedItemName", "requestedFor",
"requestLease", "requestLeaseRate", "requestLeaseTotal" ]
},
"version" : 1,
"forms" : {
"workItemDetails" : {
"type" : "external",
"formId" : "approval.details"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "approval.submission"
},
"workItemNotification" : {
"type" : "external",
"formId" : "approval.notification"
}
}
},
"completedDate" : null,
"assignedDate" : "2014-02-25T01:26:07.153Z",
"createdDate" : "2014-02-25T01:26:07.153Z",
"assignedOrCompletedDate" : "2014-02-25T01:26:07.153Z",
"serviceId" : "2af18227-6a00-49e9-a76b-96de3ee767d2",
"workItemRequest" : {
"itemId" : "069dc3ce-a260-4d6a-b191-683141c994c0",
"itemName" : "test-blueprint",
"itemDescription" : "",
"itemRequestor" : "[email protected]",
"itemCost" : 0.0,
"itemData" : {
"entries" : [ {
"key" : "requestLeaseTotal"
}, {
"key" : "approvalId",
"value" : {
"type" : "string",
"value" : "469c11ae-ed27-4790-baf1-c6839f35d474"
}
}, {

VMware, Inc. 79
Programming Guide

"key" : "requestClassId",
"value" : {
"type" : "string",
"value" : "request"
}
}, {
"key" : "requestedFor",
"value" : {
"type" : "string",
"value" : "[email protected]"
}
}, {
"key" : "requestReasons",
"value" : {
"type" : "string",
"value" : ""
}
}, {
"key" : "requestedItemName",
"value" : {
"type" : "string",
"value" : "test-blueprint"
}

.
.
.

}, {
"key" : "requestLease"
}, {
"key" : "requestedBy",
"value" : {
"type" : "string",
"value" : "[email protected]"
}
} ]
}
},
"status" : "Active",
"availableActions" : [ ]
}

Syntax for Constructing a JSON File to Approve a Machine Request

You can specify a JSON file in your vRealize Automation REST API command line input. For
example, when you enter a command to approve a machine request, you can include the name
of a JSON file that contains all the parameters required to approve the request and complete the
work item.

VMware, Inc. 80
Programming Guide

Template JSON File Values

Copy the following template to start constructing a properly formatted JSON file in a text editor.
Replace the highlighted values with your obtained work item details. After you create the JSON
file, you can include it, or its contents, when you approve a submitted machine request. See
Syntax for Approving a Submitted Machine Request.

{
"formData": {
"entries": [
{
"key": "source-source-provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-source-provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 512
}
},
{
"key": "source-source-provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-businessJustification",
"value": {
"type": "string",
"value": "solves abx request"
}
},
{
"key": "source-source-provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 0
}
}
]
},
"workItemId": "5e3e9519-78ea-4409-a52c-e4aa3bc56511",
"workItemActionId": "com.mycompany.csp.core.approval.action.approve"
}

Certain parameters are available to use in the JSON template.

VMware, Inc. 81
Programming Guide

Table 5-1. JSON Template Value Table

JSON File Parameter Name Description of Value

workItemId Specifies the value of the corresponding work item ID obtained

from the work item list.

source-source-provider- Specifies the number of instances requested.

Cafe.Shim.VirtualMachine.NumberOfInstances
value

source-source-provider- Specifies the amount of memory requested in GB.

VirtualMachine.Memory.Size

source-source-provider-VirtualMachine.CPU.Count Specifies the number of CPUs requested.

source-businessJustification Specifies the text description of reason for request.

source-source-provider-VirtualMachine.LeaseDays Specifies the number of days to lease.

workItemActionId To approve a request, include

the approve statement, for example
com.mycompany.csp.core.approval.action.approve..
To reject a request, include the reject statement, for example
com.mycompany.csp.core.approval.action.reject.

Example: JSON Input File

Use the following JSON input file sample when constructing a file.

{
"@type": "CatalogItemRequest",
"catalogItemRef": {
"id": "65fbca06-a28e-46f3-bced-c6e5fb3a66f9"
},
"organization": {
"tenantRef": "MYCOMPANY",
"subtenantRef": "cccd7a7e-5283-416b-beb0-45eb4e924dcb"
},
"requestedFor": "[email protected]",
"state": "SUBMITTED",
"requestNumber": 0,
"requestData": {
"entries": [{
"key": "provider-blueprintId",
"value": {
"type": "string",
"value": "e16edcf9-6a10-4bc7-98e2-a33361aeb857"
}
},
{
"key": "provider-provisioningGroupId",
"value": {
"type": "string",
"value": "cccd7a7e-5283-416b-beb0-45eb4e924dcb"
}

VMware, Inc. 82
Programming Guide

},
{
"key": "requestedFor",
"value": {
"type": "string",
"value": "[email protected]"
}
},
{
"key": "provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
},
{
"key": "provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 30
}
},
{
"key": "provider-__Notes",
"value": {
"type": "string",
"value": "MYCOMPANY machine"
}
},
{
"key": "provider-VirtualMachine.Disk0.Size",
"value": {
"type": "string",
"value": "1"
}
},
{
"key": "provider-VirtualMachine.Disk0.Letter",
"value": {
"type": "string",
"value": "C"
}
},
{
"key": "provider-VirtualMachine.Disk0.Label",
"value": {
"type": "string",
"value": "main"

VMware, Inc. 83
Programming Guide

}
}]
}
}

Syntax for Approving a Submitted Machine Request

PUT /api/workitems/{id} approves a submitted work item request to complete the request.
To construct the approval command, you add work item and work item form details to a JSON
file, and call that JSON file from the command line. Use a template to correctly format the JSON
file content.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/workitem-service/api/workitems/workitem_ID

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

workitem_ID Specifies the unique identifier of a work item. See Syntax for
Listing Work Items.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service that determines the other names.
n href: Specifies the URL that produces the result.

work itemNumber Displays a reference number for the work item.

id Specifies the unique identifier of this resource.

version Displays the object version number.

assignees Displays the list of work item assignees.

subTenantId Optionally associates the work item with a specific business group granting users with
management responsibilities over that business group permission to see the approval.

VMware, Inc. 84
Programming Guide

Property Description

tenantId Specifies the tenant ID for the work item.

callbackEntityId Specifies the callback entity ID for the work item.

work itemType Specifies the work item type for the work item.

completedDate Specifies the date when the work item was completed.

assignedDate Specifies the date when the work item was assigned.

createdDate Specifies the created date of this instance.

assignedOrComplete Specifies the date to be displayed on UI.

dDate

formUrl Specifies the URL from which the layout for this work item can be retrieved.

serviceId Specifies the service ID that generated this work item instance.

work itemRequest Specifies the corresponding work item request object.

status Specifies the status of the work item.

completedBy Specifies the principal ID of user who completed the work item.

availableActions Contains a list of relevant work item actions.

Metadata Specifies the paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Example: Example: curl Command

Approve a submitted machine request by specifying its work item ID and using a JSON file
named approve.json to pass arguments to the command line.

curl -X PUT --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"
https://$vRA/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json

Error Conditions
If the same request is submitted a second time, the following error response is received:

Command failed [Rest Error]: {Status code: 400}, {Error code: 12005} ,
{Error Source: null}, {Error Msg: Work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511
is in COMPLETED state. Requested operation cannot be performed.}, {System Msg:

VMware, Inc. 85
Programming Guide

Work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511 is in COMPLETED state. Requested

operation cannot be performed.}

If a user who is not authorized to approve the request submits the request, the following error
response is received:

Command failed [Rest Error]: {Status code: 400}, {Error code: 12017} ,
{Error Source: null}, {Error Msg: User [email protected] not authorized to
complete work item with ID 5e3e9519-78ea-4409-a52c-e4aa3bc56511.}, {System Msg:
User [email protected] 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.

Input
Use the supported input parameters to control the command output.

Note Price is referred to as cost in API commands and output.

Parameter Description

URL https://$vRA/composition-service/api/blueprints/
$BlueprintId/costs/upfront

Method Post

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

VMware, Inc. 86
Programming Guide

Parameter Description

$token Specifies a valid HTTP bearer token with necessary

credentials.

HTTP Body Specifies the blueprint ID for the blueprint for which you are
requesting price information and other information.
n Blueprint ID: Specifies the blueprint ID.

n requestedFor: The user for whom this request is being

made. Must be the fully qualified user ID.
n subTenantId: Specifies the subtenant ID associated with
the blueprint
n requestData: Specifies data that identifies the blueprint
further.
n entries

n Key: The name of the machine on which the

blueprint resides.
n value: Specifies key-value pairs that further
identify the blueprint, such as the type of the
value, the componentType ID for the item, the
classID of the value, and where the blueprint
resides. In turn, each entry contains an array of
key-value pairs that identify the type of data used
to compute the price that is to be displayed.
n Values: Specifies an array of type filters.

n Entries: Specifies a list of key-value pairs that

specify the values to be used in computing
the price. For example, the cluster, CPU, and
allocated memory to use.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

setupFee Specifies the one time setup fee associated with the
component.

totalEstimatedLeasePriceInfo Specifies the minimum price and maximum price for the
lease period.

averageDailyPriceInfo Specifies the average daily price, which depends on the

reservation available for the component.

count Specifies the instance count of the component.

memory Specifies memory requested for this component.

additional Specifies the additional price, if any, associated with the

component.

cpu Specifies the cpu requested for the component.

VMware, Inc. 87
Programming Guide

Property Description

storage Specifies the storage requested for the component.

componentId Specifies the component ID, or total price of the

deployment.

Example: curl Command

The following sample command updates and displays the price of a sample blueprint with one
node. The HTTP body is included as part of the command line input.

Note Price is referred to as cost in API commands and output.

curl -- insecure -H “Content Type: application/json”

-H "Authorization: Bearer $token"
https://$vRA/composition-service/api/blueprints/$BlueprintId/costs/upfront"

{
"blueprintId": "myblueprintId",
"requestedFor": "[email protected]",
"subTenantId": "7a961949-13c4-4f3d-9010-66db8da6c51e",
"requestData": {
"entries": [
{
"key": "vSphere_Machine_1",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"classId": "Blueprint.Node",
"typeFilter": "phanisimple*vSphere_Machine_1",
"values": {
"entries": [
{
"key": "_cluster",
"value": {
"type": "integer",
"value": 3
}
},
{
"key": "cpu",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "memory",
"value": {
"type": "integer",
"value": 2048
}

VMware, Inc. 88
Programming Guide

}
]
}
}
}
]
}
}

Example: JSON Output for a Blueprint Price Update

[{"componentId":"vSphere_Machine_1",
"setupFee":"$0.00",
"totalEstimatedLeasePriceInfo":
{"min":50.0543225806451601,"max":50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":
{"min":16.6847741935483867,"max":16.6847741935483867,"displayString":"$16.68"},
"count":3
"fieldMap":{"setup_fee":{"min":0,"max":0,"displayString":"$0.00"},
"memory":{"min":8.00,"max":8.00,"displayString":"$8.00"},
"additional":{"min":8.6847741935483867,"max":8.6847741935483867,"displayString":"$8.68"},
"cpu":{"min":0.0,"max":0.0,"displayString":"$0.00"},
"storage":{"min":0,"max":0,"displayString":"$0.00"}}},
{"componentId":"Total","setupFee":"","totalEstimatedLeasePriceInfo":
{"min":50.0543225806451601,"max":50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":
{"min":16.6847741935483867,"max":16.6847741935483867,"displayString":"$16.68"},
"count":3,"fieldMap":{}}]

VMware, Inc. 89
Listing Provisioned Resources
6
You use the catalog service to list provisioned resources.

The catalog service is designed to be used by consumers and providers of the service catalog.
For example, a consumer might want to list resources provisioned by a provider. The consumer
can also list the resources in multiple ways.

Each example for this use case lists a curl command with respective JSON response, plus input
and output parameters. The same set of prerequisites applies to each example.

This chapter includes the following topics:

n Prerequisites for Listing Provisioned Resources

n Display Your Provisioned Resources Example

n Display Provisioned Resources by Resource Type Example

n Display All Available Resource Types Example

n Display Provisioned Resources by Business Groups You Manage Example

n View Machine Details Example

Prerequisites for Listing Provisioned Resources

Satisfy the following conditions before performing any tasks for this use case.

n Log in to vRealize Automation as a business group manager.

n Verify that the appliance name and fully qualified domain name of the vRealize Automation
instance are available.

n Verify that you have a valid HTTP bearer token that matches your login credentials. See
Chapter 2 REST API Authentication.

Display Your Provisioned Resources Example

GET /api/consumer/resources/{id} displays a list of all the provisioned resources that you
own.

VMware, Inc. 90
Programming Guide

curl Command
The following example displays all applicable provisioned resources.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resources/?page=1&limit=n&$orderby=name

JSON Output
The following JSON output is returned based on the command input.

{
"links" : [ {
"@type" : "link",
"rel" : "next",
"href" : "https://vra152-009-067.mycompany.com/catalog-service/api/consumer/resources/?
page=2&limit=1"
} ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "c24e8c75-c201-489c-b51c-8d7009c23563",
"iconId" : "Travel_100.png",
"resourceTypeRef" : {
"id" : "com.mycompany.mystuff.samples.travel.packageType",
"label" : "Reservation"
},
"name" : "example",
"description" : "asd",
"status" : "ACTIVE",
"catalogResource" : {
"id" : "6fddafcd-bc3d-4753-8a2a-5fa3f78a5a90",
"label" : "example"
},
"requestId" : "55e7fcf3-4c77-4b11-a442-1f282333ac91",
"providerBinding" : {
"bindingId" : "1",
"providerRef" : {
"id" : "f60f5d1e-d6e9-4d98-9c48-f70a3e405346",
"label" : "travel-service"
}
},
…
}

Input
Use the supported input parameters to control the command output.

VMware, Inc. 91
Programming Guide

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resources/

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

$page Specifies a page number.

$limit Specifies the number of entries to display on a page.

Maximum value is 5000. If not specified, defaults to 20.
For information regarding limits to the number of
elements displayed, see Retrieve 10,000 Resources
Ordered By Name.

$orderby Specifies how to order multiple comma-separated

properties sorted in ascending or descending order.
Values include:
n $orderby=id
n $orderby=name
n $orderby=dateCreated
n $orderby=lastUpdated
n $orderby=status
n $orderby=description

$top Specifies the number of returned entries from the top of

the response (total number per page in relation to skip).

$skip Specifies the number of entries to skip.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

resourceTypeRef Specifies the resource type.

name Specifies the resource name.

description Specifies the resource description.

status Specifies the resource status.

catalogItem Specifies the catalog item that defines the service this resource is based on.

requestId Specifies the request ID that provisioned this resource.

VMware, Inc. 92
Programming Guide

Property Description

providerBinding Specifies the provider binding.

owners Species the owners of this resource.

organization Specifies the subtenant or tenant that owns this resource.

dateCreated Specifies the data and time at which the resource was created.

lastUpdated Specifies the date and time at which the resource was most recently modified.

hasLease Returns true if the resource is subject to a lease.

lease Displays the resource's current lease as start and end time stamps.

leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.

hasCosts Returns true if the resource is subject to per-time price.

costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.

costToDate Displays an optional rate of the current price charges for the resource. This parameter is
deprecated.

totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is
deprecated.

expenseMonthToD The expense of the resource from the beginning of the month to the current date. This value is
ate updated daily by vRealize Business for Cloud.

parentResourceRef Displays the parent of this resource.

childResources Displays the children of this resource.

operations Specifies the sequence of available operations that can be performed on this resource.

forms Specifies the forms used to render this resource.

resourceData Displays the extended provider-defined properties of the resource.

Example: Retrieve 10,000 Resources Ordered By Name

Since the catalog service limits the number of elements that can be retrieved with a single API
call to 5000, retrieving 10,000 resources requires two calls. The first call displays the first 5000
elements and the second call displays the second 5000 elements. You can make the two calls by
specifying either the page and limit values or the skip and top values.

Specifying page and limit values, you make the following two calls.

curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"

-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?
page=1&limit=5000&$orderby=name"
curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"
-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?
page=2&limit=5000&$orderby=name"

VMware, Inc. 93
Programming Guide

Specifying skip and top values, you make the following two calls.

curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"

-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?
$skip=0&$top=5000&$orderby=name"
curl --insecure -H "Content-Type: application/json" -H "Accept: application/json"
-H "Authorization: $AUTH" "https://$vRA/catalog-service/api/consumer/resources/?
$skip=5000&$top=5000&$orderby=name"

If both page and limit values and skip and top values are specified, the skip and top values take
priority.

Display Provisioned Resources by Resource Type Example

GET /api/consumer/resourcesTypes/{id} displays a list of the provisioned resources that
you own filtered by machine resource type.

curl Command
The following example displays the provisioned resources by resource type.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”
https://$vRA/catalog-service/api/consumer/resourceTypes/Infrastructure.Machine/?
page=1&limit=n&$orderby=id

JSON Output
The following JSON output is returned based on the command input.

{
"links" : [ ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "3bfde906-81b9-44c3-8c2d-07d2c9768168",
"iconId" : "cafe_default_icon_genericCatalogResource",
"resourceTypeRef" : {
"id" : "Infrastructure.Virtual",
"label" : "Virtual Machine"
},
"name" : "test2",
"description" : null,
"status" : "ACTIVE",
"catalogResource" : {
"id" : "e2f397be-72ad-4ec4-a688-c017560fa1a3",
"label" : "test-blueprint"
},
"requestId" : "b013d2fa-4ba4-416c-b46b-98bb8cc7b076",
"providerBinding" : {
"bindingId" : "8a4581a0-84f9-4e80-9af6-75d79633e382",
"providerRef" : {
"id" : "6918cd49-b737-467f-94bf-d14d52c78fba",

VMware, Inc. 94
Programming Guide

"label" : "iaas-service"
}
},
"owners" : [ {
"tenantName" : "MYCOMPANY",
"ref" : "[email protected]",
"type" : "USER",
"value" : "Fritz Arbeiter"
} ],
"organization" : {
"tenantRef" : "MYCOMPANY",
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
…
}

The output includes the following highlighted items:

n Resource ID. 3bfde906-81b9-44c3-8c2d-07d2c9768168 corresponds to a provisioned

machine owned by the logged-in user. The resource IDs are used in requests to retrieve
the details for the corresponding machines.

n subtenantRef ID. eab762cb-6e75-4379-83ef-171a71c9f00e corresponds to the business

group of the logged-in user. If the user who is logged-in is also the manager of the business
group, the subtenantRef ID is used to get resources from all business groups that the user
manages.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resourceTypes

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

page Specifies a page number.

limit Specifies the number of entries to display on a page. Maximum value is 5000. If not
specified, defaults to 20.
For information regarding limits to the number of elements displayed, see Retrieve
10,000 Resources Ordered By Name.

VMware, Inc. 95
Programming Guide

Parameter Description

$orderby Specifies how to order multiple comma-separated properties sorted in ascending or

descending order. Values include:
n $orderby=id
n $orderby=name
n $orderby=dateCreated
n $orderby=lastUpdated
n $orderby=status
n $orderby=description

top Specifies the number of returned entries from the top of the response (total number
per page in relation to skip).

skip Specifies the number of entries to skip.

Filter by the following resource types:

n Infrastructure.Machine

n Infrastructure.AppServic

n Infrastructure.Cloud

n Infrastructure.Physical

n Infrastructure.vApp

n Infrastructure.Virtual

Output
The command output contains property names and values based on the command input
parameters.

Property Description

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

resourceTypeRef Specifies the resource type.

name Specifies the resource name.

description Specifies the resource description.

status Specifies the resource status.

catalogItem Specifies the catalog item that defines the service this resource is based on.

requestId Specifies the request ID that provisioned this resource.

providerBinding Specifies the provider binding.

owners Species the owners of this resource.

VMware, Inc. 96
Programming Guide

Property Description

organization Specifies the subtenant or tenant that owns this resource.

dateCreated Specifies the data and time at which the resource was created.

lastUpdated Specifies the date and time at which the resource was most recently modified.

hasLease Returns true if the resource is subject to a lease.

lease Displays the resource's current lease as start and end time stamps.

leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.

hasCosts Returns true if the resource is subject to per-time price.

costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.

costToDate Displays an optional rate of the current price charges for the resource. This parameter is
deprecated.

totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is
deprecated.

expenseMonthToD The expense of the resource from the beginning of the month to the current date. This value is
ate updated daily by vRealize Business for Cloud.

parentResourceRef Displays the parent of this resource.

childResources Displays the children of this resource.

operations Specifies the sequence of available operations that can be performed on this resource.

forms Specifies the forms used to render this resource.

resourceData Displays the extended provider-defined properties of the resource.

Display All Available Resource Types Example

GET /api/consumer/resourcesTypes displays all the resource types that are available on the
system.

curl Command
The following example displays all available resource types.

curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token" https://

$vRA/catalog-service/api/consumer/resourceTypes

JSON Output
The following JSON output is returned based on the command input.

{
"links" : [ ],

VMware, Inc. 97
Programming Guide

"content" : [ {
"@type" : "ResourceType",
"id" : "Infrastructure.Machine",
"name" : "Machine",
"pluralizedName" : "Machines",
"description" : "The common parent type for all types of machines",
"primary" : true,
"schema" : {
"classId" : "Infrastructure.Machine.Schema",
"typeFilter" : null
},
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resourceTypes

$vRA Specifies the appliance name and fully qualified domain name, or IP address of
the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

resourceTypeRef Specifies the resource type.

name Specifies the resource name.

description Specifies the resource description.

status Specifies the resource status.

catalogItem Specifies the catalog item that defines the service this resource is based on.

requestId Specifies the request ID that provisioned this resource.

VMware, Inc. 98
Programming Guide

Property Description

providerBinding Specifies the provider binding.

owners Species the owners of this resource.

organization Specifies the subtenant or tenant that owns this resource.

dateCreated Specifies the data and time at which the resource was created.

lastUpdated Specifies the date and time at which the resource was most recently modified.

hasLease Returns true if the resource is subject to a lease.

lease Displays the resource's current lease as start and end time stamps.

leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.

hasCosts Returns true if the resource is subject to per-time price.

costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.

costToDate Displays an optional rate of the current price charges for the resource. This parameter is
deprecated.

totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is
deprecated.

expenseMonthToD The expense of the resource from the beginning of the month to the current date. This value is
ate updated daily by vRealize Business for Cloud.

parentResourceRef Displays the parent of this resource.

childResources Displays the children of this resource.

operations Specifies the sequence of available operations that can be performed on this resource.

forms Specifies the forms used to render this resource.

resourceData Displays the extended provider-defined properties of the resource.

Example: curl Command

The following example command displays all available resource types.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resourceTypes

Example: JSON Output

The following JSON output is returned based on the command input.

{
"links" : [ ],
"content" : [ {
"@type" : "ResourceType",

VMware, Inc. 99
Programming Guide

"id" : "Infrastructure.Machine",
"name" : "Machine",
"pluralizedName" : "Machines",
"description" : "The common parent type for all types of machines",
"primary" : true,
"schema" : {
"classId" : "Infrastructure.Machine.Schema",
"typeFilter" : null
},
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}

Display Provisioned Resources by Business Groups You

Manage Example
GET /api/consumer/resources/types/{resourceTypeId} displays all of the provisioned
resources that are owned by the business groups that you manage. You can optionally filter
the list by business group name.

curl Command
The following example displays the provisioned resources of one or more business groups.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token"
https://$vRA/catalog-service/api/consumer/resources/types/Infrastructure.Machine/?
page=1&limit=n&$orderby=id desc&$filter=((organization/subTenant/id eq 'subtenantID_group1')
or (organization/subTenant/id eq ''subtenantID_group2') … )"

JSON Output
In the following command input, the subtenant IDs correspond to business groups that are
managed by the user who is logged-in.

rest get catalog-service --u "consumer/resources/types/Infrastructure.Machine/?

page=1&limit=2&$orderby=dateCreated desc&$filter=((organization/subTenant/id eq
'eab762cb-6e75-4379-83ef-171a71c9f00e') or (organization/subTenant/id eq 'fa995528-e289-455e-
a0e6-c2da8b0e1bf9') or (organization/subTenant/id eq '699efe66-fe6e-4e34-96e8-52a34f338d20')
or (organization/subTenant/id eq '4d949784-e93e-4538-accb-6a0a464e4a4b'))"

The following JSON output is returned based on the command input.

{
"links" : [ ],
"content" : [ {
"@type" : "ConsumerResource",

VMware, Inc. 100

Programming Guide

"id" : "3bfde906-81b9-44c3-8c2d-07d2c9768168",
"iconId" : "cafe_default_icon_genericCatalogResource",
"resourceTypeRef" : {
"id" : "Infrastructure.Virtual",
"label" : "Virtual Machine"
},
"name" : "test2",
"description" : null,
"status" : "ACTIVE",
"catalogResource" : {
"id" : "e2f397be-72ad-4ec4-a688-c017560fa1a3",
"label" : "test-blueprint"
},
"requestId" : "b013d2fa-4ba4-416c-b46b-98bb8cc7b076",
"providerBinding" : {
"bindingId" : "8a4581a0-84f9-4e80-9af6-75d79633e382",
"providerRef" : {
"id" : "6918cd49-b737-467f-94bf-d14d52c78fba",
"label" : "iaas-service"
}
},
"owners" : [ {
"tenantName" : "MYCOMPANY",
"ref" : "[email protected]",
"type" : "USER",
"value" : "Fritz Arbeiter"
} ],
"organization" : {
"tenantRef" : "MYCOMPANY",
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
"dateCreated" : "2014-09-19T21:19:37.541Z",
"lastUpdated" : "2014-09-19T21:19:40.888Z",
"hasLease" : true,
"lease" : {
"start" : "2014-09-19T21:18:57.000Z"
},
"leaseForDisplay" : null,
"hasCosts" : true,
"costs" : {
"leaseRate" : {
"type" : "moneyTimeRate",
"cost" : {
"type" : "money",
"currencyCode" : "USD",
"amount" : 0.0
},
"basis" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 1
}
}

VMware, Inc. 101

Programming Guide

},
"costToDate" : {
"type" : "money",
"currencyCode" : "USD",
"amount" : 0.0
},
"totalCost" : null,
"childResources" : [ ],
"operations" : [ {
"name" : "Reprovision",
"description" : "Reprovision a machine.",
"iconId" : "machineReprovision.png",
"type" : "ACTION",
"id" : "a1caee9b-d67f-41e8-a7b3-131616a0f6ac",
"extensionId" : null,
"providerTypeId" : "com.mycompany.csp.iaas.blueprint.service",
"bindingId" : "Infrastructure.Machine.Action.Reprovision",
"hasForm" : false,
"formScale" : null
} ],
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}
},
"resourceData" : {
"entries" : [ {
"key" : "Expire",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineGroupName",
"value" : {
"type" : "string",
"value" : "MyTestAgentBusinessGroup"
}
}, {
"key" : "NETWORK_LIST",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ {
"type" : "complex",
"componentTypeId" : "com.mycompany.csp.component.iaas.proxy.provider",
"componentId" : null,
"classId" : "vra.api.model.NetworkViewModel",
"typeFilter" : null,
"values" : {
"entries" : [ {
"key" : "NETWORK_MAC_ADDRESS",

VMware, Inc. 102

Programming Guide

"value" : {
"type" : "string",
"value" : "56:52:4d:e7:46:d4"
}
}, {
"key" : "NETWORK_NAME",
"value" : {
"type" : "string",
"value" : "Test Agent-network-1"
}
} ]
}
} ]
}
}, {
"key" : "SNAPSHOT_LIST",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ ]
}
}, {
"key" : "ConnectViaRdp",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStatus",
"value" : {
"type" : "string",
"value" : "On"
}
}, {
"key" : "PowerOff",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "DISK_VOLUMES",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ {
"type" : "complex",
"componentTypeId" : "com.mycompany.csp.component.iaas.proxy.provider",
"componentId" : null,
"classId" : "vra.api.model.DiskInputModel",
"typeFilter" : null,
"values" : {
"entries" : [ {
"key" : "DISK_CAPACITY",
"value" : {
"type" : "integer",

VMware, Inc. 103

Programming Guide

"value" : 1
}
}, {
"key" : "DISK_DRIVE",
"value" : {
"type" : "string",
"value" : "c"
}
}, {
"key" : "DISK_INPUT_ID",
"value" : {
"type" : "string",
"value" : "DISK_INPUT_ID1"
}
} ]
}
} ]
}
}, {
"key" : "MachineBlueprintName",
"value" : {
"type" : "string",
"value" : "test-blueprint"
}
}, {
"key" : "Suspend",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reboot",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reprovision",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStorage",
"value" : {
"type" : "integer",
"value" : 1
}
}, {
"key" : "MachineDailyCost",
"value" : {
"type" : "decimal",
"value" : 0.0
}
}, {

VMware, Inc. 104

Programming Guide

"key" : "Destroy",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineType",
"value" : {
"type" : "string",
"value" : "Virtual"
}
}, {
"key" : "InstallTools",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Shutdown",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "ChangeLease",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "machineId",
"value" : {
"type" : "string",
"value" : "8a4581a0-84f9-4e80-9af6-75d79633e382"
}
}, {
"key" : "MachineMemory",
"value" : {
"type" : "integer",
"value" : 0
}
}, {
"key" : "MachineGuestOperatingSystem"
}, {
"key" : "MachineName",
"value" : {
"type" : "string",
"value" : "test2"
}
}, {
"key" : "MachineDestructionDate"
}, {
"key" : "MachineCPU",
"value" : {
"type" : "integer",

VMware, Inc. 105

Programming Guide

"value" : 1
}
}, {
"key" : "MachineInterfaceType",
"value" : {
"type" : "string",
"value" : "Test"
}
}, {
"key" : "MachineReservationName",
"value" : {
"type" : "string",
"value" : "Test Agent-Res-1"
}
}, {
"key" : "Reconfigure",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "EXTERNAL_REFERENCE_ID"
}, {
"key" : "MachineExpirationDate"
}, {
"key" : "Reset",
"value" : {
"type" : "boolean",
"value" : true
}
} ]
}
} ],
"metadata" : {
"size" : 2,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resources/type

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

VMware, Inc. 106

Programming Guide

Parameter Description

$resourceID Specifies a resource ID. See Display Your Provisioned Resources Example to
view all of your requests and search for a request ID.

managedOnly If true, the returned requests are from the user's managed subtenants.

page Specifies a page number.

limit Specifies the number of entries to display on a page. Maximum value is 5000.
If not specified, defaults to 20.
For information regarding limits to the number of elements displayed, see
Retrieve 10,000 Resources Ordered By Name.

$orderby Specifies how to order multiple comma-separated properties sorted in

ascending or descending order. Values include:
n $orderby=id
n $orderby=name
n $orderby=dateCreated
n $orderby=lastUpdated
n $orderby=status
n $orderby=description

top Specifies the number of returned entries from the top of the response (total
number per page in relation to skip).

skip Specifies the number of entries to skip.

$filter Contains a Boolean expression to determine if a particular entry is included in

the response.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

resourceTypeRef Specifies the resource type.

name Specifies the resource name.

description Specifies the resource description.

status Specifies the resource status.

catalogItem Specifies the catalog item that defines the service this resource is based on.

requestId Specifies the request ID that provisioned this resource.

providerBinding Specifies the provider binding.

VMware, Inc. 107

Programming Guide

Property Description

owners Species the owners of this resource.

organization Specifies the subtenant or tenant that owns this resource.

dateCreated Specifies the data and time at which the resource was created.

lastUpdated Specifies the date and time at which the resource was most recently modified.

hasLease Returns true if the resource is subject to a lease.

lease Displays the resource's current lease as start and end time stamps.

leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.

hasCosts Returns true if the resource is subject to per-time price.

costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.

costToDate Displays an optional rate of the current price charges for the resource. This parameter is
deprecated.

totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is
deprecated.

expenseMonthToD The expense of the resource from the beginning of the month to the current date. This value is
ate updated daily by vRealize Business for Cloud.

parentResourceRef Displays the parent of this resource.

childResources Displays the children of this resource.

operations Specifies the sequence of available operations that can be performed on this resource.

forms Specifies the forms used to render this resource.

resourceData Displays the extended provider-defined properties of the resource.

View Machine Details Example

GET /api/consumer/requests/{id}/resourceViews displays the machine details for a
provisioned machine.

curl Command
The following example displays machine details for a provisioned machine with
resourceID=7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.

curl --insecure -H "Content-Type: application/json"

-H "Authorization: Bearer $token”
http://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b/
resourceViews

VMware, Inc. 108

Programming Guide

JSON Output
The following JSON output is returned based on the command input.

{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$vRA/catalog-service/api/consumer/
entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$vRA/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$vRA/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests"
},
{
"@type": "link",
"rel": "GET: Child Resources",
"href": "https://$vRA/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq%20%2
7c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27"
}
],
"resourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Linux-80813151",
"description": null,
"status": null,
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"catalogItemLabel": "Linux",
"requestId": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"resourceType":
"{com.vmware.csp.component.cafe.composition@resource.type.deployment.name}",

VMware, Inc. 109

Programming Guide

"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:51:36.368Z",
"lastUpdated": "2015-07-29T13:55:35.963Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": null,
"hasChildren": true,
"data": {}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Using the API to Get Deployment Details

To view deployed machine details, append /resourceViews to the request details URI that you
generated when you retrieved request details.

http://$vRA/catalog-service/api/consumer/requests/$requestId/resourceViews

See Syntax for Viewing Details of a Machine Request .

In addition to general information about the provisioned deployment such as its name,
description, and ID, the response contains additional HATEOAS links that enable you to obtain
additional details and information.

Table 6-1. HATEOAS Link Functions as Defined by rel Field

Link Description

GET: Catalog Item URI to get the catalog item details (as described in sections 3.2.1
and 3.2.2) from which this catalog item was provisioned.

GET: Request URI to get the request details that provisioned this item.

GET:Template URI to get a template request for a specific action that you can
{com.vmware.csp.component.cafe.composition perform on this resource. Typically, on a deployment the action will
@resource.action.deployment.$actionName be Delete.

VMware, Inc. 110

Programming Guide

Table 6-1. HATEOAS Link Functions as Defined by rel Field (continued)

Link Description

POST: URI to which to post the request to perform an action, based on the
{com.vmware.csp.component.cafe.composition corresponding template.
@resource.action.deployment.$actionName

GET: Child Resources If the deployment contains child resources (nodes specified in
the composite blueprint), this is the URI to get a list of the
resourceViews for the children of this deployment.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resources/$resourceId

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$resourceID Specifies a resource ID. See Display Your Provisioned Resources Example to view all of
your requests and search for a request ID.

managedOnly If true, the returned requests are from the user's managed subtenants.

page Specifies a page number.

limit Specifies the number of entries to display on a page.

$orderby Specifies how to order multiple comma-separated properties sorted in ascending or

descending order.

$top Specifies the number of returned entries from the top of the response (total number
per page in relation to skip).

$skip Specifies the number of entries to skip.

filter Contains a Boolean expression to determine if a particular entry is included in the

response.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

id Specifies the unique identifier of this resource.

iconId Specifies an icon for this request based on the requested object type.

resourceTypeRef Specifies the resource type.

VMware, Inc. 111

Programming Guide

Property Description

name Specifies the resource name.

description Specifies the resource description.

status Specifies the resource status.

catalogItem Specifies the catalog item that defines the service this resource is based on.

requestId Specifies the request ID that provisioned this resource.

providerBinding Specifies the provider binding.

owners Species the owners of this resource.

organization Specifies the subtenant or tenant that owns this resource.

dateCreated Specifies the data and time at which the resource was created.

lastUpdated Specifies the date and time at which the resource was most recently modified.

hasLease Returns true if the resource is subject to a lease.

lease Displays the resource's current lease as start and end time stamps.

leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.

hasCosts Returns true if the resource is subject to per-time price.

costs Displays an optional rate of the price charges for the resource. This parameter is deprecated.

costToDate Displays an optional rate of the current price charges for the resource. This parameter is
deprecated.

totalCost Displays an optional rate of the price charges for the entire lease period. This parameter is
deprecated.

expenseMonthToD The expense of the resource from the beginning of the month to the current date. This value is
ate updated daily by vRealize Business for Cloud.

parentResourceRef Displays the parent of this resource.

childResources Displays the children of this resource.

operations Specifies the sequence of available operations that can be performed on this resource.

forms Specifies the forms used to render this resource.

resourceData Displays the extended provider-defined properties of the resource.

VMware, Inc. 112

Managing Provisioned
Deployments 7
You use the catalog service to manage provisioned deployments.

The catalog service is designed to be used by consumers of the service catalog. For example,
a consumer might want to list all provisioned resources then submit a request to power off a
resource.

This chapter includes the following topics:

n Manage Provisioned Deployments

n Machine States and Entitlements for Day 2 Actions

n Power Off

n Change Lease

n Catalog Service Examples for Managing Provisioned Deployments

Manage Provisioned Deployments

You use the catalog service to log in to vRealize Automation and view information about
provisioned resources.

Prerequisites

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.

Procedure

1 Display a list of all provisioned resources.

$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization:

Bearer $token" http://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews

VMware, Inc. 113

Programming Guide

For details regarding input and output of this sample, see Syntax for Getting Deployment
Details.

2 Examine the response for the HATEOAS links that you need to obtain additional information
about specific deployed resources.

3 Use the GET: Child Resources HATEOAS link to retrieve a list of child nodes of a
deployment.

$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer

$token" https:// $vRA/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq%2
0%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27

For details regarding input and output of this sample, see Syntax for Navigating to the
Children of a Deployed Resource.

What to do next

Use the HATEOS links obtained from retrieving the list of child nodes to perform actions.

n See Power Off.

n See Change Lease.

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 CloudClient.

For additional posts and articles that illustrate methods for performing actions by using the
vRealize Automation REST API or vRealize CloudClient tool, see the Executing Day 2 Actions with
the vRA 7 REST API blog post.

Machine States and Entitlements for Day 2 Actions

The set of Day 2 Operations available to be performed on a machine is dependent on the current
lifecycle state of the machine. For example, the Power Off operation is not available as a Day 2
Operation unless the machine is in lifecycle state On. Similarly, the Connect to Remote Console
Day 2 Operation is not available unless the machine is in state On.

When a Day 2 Operation is requested on a machine, the set of actions or operations allowed on
the machine changes once the machine reaches its destination lifecycle state as a result of the
Day 2 Operation. For example, for a Power Off operation request, the machine state will start at
On. The state of the machine will move to Turning Off and then finally to Off. At that time, and
not before, the Day 2 Operations for the machine will be those which are allowed on a machine
that is in state Off.

In addition to the machine state, you must consider the account used to run the Day 2 actions.
User accounts must be entitled to run the individual actions. Verify that the account you use to
run the actions is entitled to run the requested Day 2 operation.

VMware, Inc. 114

Programming Guide

Note that polling vRealize Automation to obtain the status of the initial Day 2 operation using the
requestId of the operation, can return success even when the machine has not yet reached the
destination state for that Day 2 operation. Attempts to perform a Day 2 operation that is only
available when the machine is in the destination state will fail in those circumstances. To avoid
this scenario, you should:

n Use the API to invoke the initial Day 2 operation.

n Call the catalog service API that returns the set of Day 2 operations available on a machine.

https://$vRA/catalog-service/api/consumer/resources/{{resource-guid}}/actions

n This call should be made in a loop and for a maximum of 10 invocations, starting with a
wait of 2 seconds between successive invocations of this API, with exponential backoff
between each subsequent invocation.

n The execution loop should continue until such time as either the set of allowed operations
on the machine contains the desired Day 2 operation, or the maximum number of
invocations is reached.

n Once the API returns the desired operation as an allowed operation on the machine, the
operation should be invoked.

For more information regarding the vRealize Automation catalog service API see https://
code.vmware.com/apis/417/vra-catalog.

Power Off
You use the catalog service to perform a power off action. For simple actions that require no
user input, the process is straightforward.

This command leverages the links for the power off action from the command used in the Syntax
for Navigating to the Children of a Deployed Resource example.

{
"@type": "link",
"rel": "GET Template: {[email protected]}",
"href": "https://$vRA/api/consumer/resources/dd3...a4a/actions/02ba...e38/requests/
template"
},
{
"@type": "link",
"rel": "POST: {com.vmware..iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$vRA/api/consumer/resources/dd3...a4a/actions/02b...e38/requests"
}

VMware, Inc. 115

Programming Guide

Procedure

1 Get the template for the resource action request.

$curl --insecure -s -H "Content-Type: multipart/form-data" -H "Authorization:

Bearer $token" https://$vRA/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template

2 Examine the response.

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}

3 Edit the template as desired. The template is populated with default values. For example, you
may want to provide custom values for the description and reasons.

4 Use a POST command to send the template without modification to the corresponding URI.

$curl --verbose --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization:

Bearer $token" https://$vRA/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}

Results

This POST command returns a response indicating success or failure. HTTP/1.1 201 CREATED
indicates that the request was submitted successfully.

VMware, Inc. 116

Programming Guide

Change Lease
You use the catalog service to change a lease. For actions that require user input, you may need
to edit the template prior to submitting 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 example.

{
"@type": "link",
"rel": "GET Template: {[email protected]}",
"href": "https://$vRA/api/consumer/resources/dd3...a4a/actions/b5739e30-.../requests/
template"
},
{
"@type": "link",
"rel": "POST: {com.vmware...iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$vRA/api/consumer/resources/dd3...a4a/actions/b5739e30-.../requests"
},

Procedure

1 Get the template for the resource action request.

$curl --insecure -s -H "Content-Type: multipart/form-data" -H "Authorization:

Bearer $token" https://$vRA/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template

2 Examine the response.

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {"provider-ExpirationDate": "2015-07-29T16:44:13.846Z"}
}

3 Edit the template as desired. The template is populated with default values. In this example,
the value of provider-ExpirationDate is set to the time at which the template was requested
in UTC. Edit this value (for example, to change the expiration to a month from now). You may
also want to provide a custom value for the description.

VMware, Inc. 117

Programming Guide

4 Use a POST command to send the template to the corresponding URI.

$curl --verbose --insecure -s -H "Content-Type: multipart/form-data" -H "Authorization:

Bearer $token" https://$vRA/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests
Accept: application/json
Content-Type: application/json
Authorization: Bearer $token
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {"provider-ExpirationDate": "2015-08-29T16:44:13.846Z"}
}

Results

This POST command returns a response indicating success or failure. HTTP/1.1 201 CREATED
indicates that the request was submitted successfully.

Catalog Service Examples for Managing Provisioned

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

n Syntax for Getting Deployment Details

GET /api/consumer/requests/{id}/resourceViews retrieves resources provisioned by
a given request.

n Syntax for Navigating to the Children of a Deployed Resource

GET /api/consumer/resourceViews retrieves a list of the child nodes of a deployment,
including virtual machines, networks, and other objects you may have configured on the
design canvas.

Syntax for Getting Deployment Details

GET /api/consumer/requests/{id}/resourceViews retrieves resources provisioned by a
given request.

Accessing Links to Provisioned Items

You can access links to provisioned items from a given request by appending /resourceViews to
the request details URI. For instance, you can edit the example request URI from as follows:

http://$vRA/catalog-service/api/consumer/requests/$requestId/resourceViews

In addition to the general information about the provisioned deployment returned in the
response, such as its name, description and ID, the response contains additional HATEOAS links.

VMware, Inc. 118

Programming Guide

Table 7-1. HATEOAS Link Deployment Details Functions

Link Description

GET: Catalog Item URI to get the catalog item details from which this catalog item
was provisioned. See Syntax for Viewing Details of a Machine
Request .

GET: Request URI to get the request details that provisioned this item.

GET:Template URI to get a template request for a specific action that you can
{com.vmware.csp.component.cafe.composition@r perform on this resource. Typically, on a deployment, the action
esource.action.deployment.$actionName will be Delete.

POST: URI to which to post the request to perform an action, based on

{com.vmware.csp.component.cafe.composition@r the corresponding template.
esource.action.deployment.$actionName

GET: Child Resources If the deployment contains child resources, such as nodes
specified in the composite blueprint, this is the URI to get a list
of the resourceViews for the children of this deployment.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resources/$resourceId

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

id UUID of a request.

page Specifies a page number.

limit Specifies the number of entries to display on a page.

$orderby Specifies how to order multiple comma-separated properties sorted in ascending or

descending order.

$top Specifies the number of returned entries from the top of the response (total number
per page in relation to skip).

$skip Specifies the number of entries to skip.

filter Contains a Boolean expression to determine if a particular entry is included in the

response.

Output
The command output contains property names and values based on the command input
parameters.

Note Price is referred to as cost in API commands and output.

VMware, Inc. 119

Programming Guide

Table 7-2. Output Parameters

Property Description

resourceId The unique identifier of the resource.

iconId Specifies an icon for this request based on the requested object type.

name The user friendly name of the resource.

description An extended user friendly description of the resource.

status The status of the resource. For example, On, Off, etc.

catalogItemId The identifier of the catalog item associated with this provisioned resource.

catalogItemLabel The label of the catalog item associated with this provisioned resource.

requestId The unique identifier of the request that created this provisioned resource.

businessGroupId The unique identifier of the business group that owns this resource.

tenantId The unique identifier of the tenant that owns this resource.

owners The owner of this resource.

resourceType The type identifier of this resource. For example, Virtual Machine.

parentResourceId The unique identifier of the parent resource. Used for child resources of a multi-
machine resource.

hasChildren Returns trun if this resource has child resources. Used if this is a multi-machine
resource.

dateCreated The date and time at which the resource was created.

lastUpdated The date and time at which the resource was most recently modified.

lease The current lease of the resource.

costs An optional rate card of the prices and charges levied against the resource. This
parameter is deprecated.

costToDate An optional rate card of the existing prices and charges levied against the resource.
This parameter is deprecated

totalCost An optional rate card of the pricess and charges levied for the entire lease period.
This parameter is deprecated.

expenseMonthToDate The expense of the resource from the beginning of the month to the current date.

data The extended, provider defined properties of the resource.

VMware, Inc. 120

Programming Guide

Example Curl Command

This example retrieves all children of the resource with an ID of 7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b.

$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization:

Bearer $token" http://$vRA/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews

Example: JSON Output

{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$vRA/catalog-service/api/consumer/
entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$vRA/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$vRA/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$vRA/catalog-service/api/consumer/resources/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests"
},
{
"@type": "link",
"rel": "GET: Child Resources",
"href": "https://$vRA/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq%20%2
7c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27"
}
],
"resourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Linux-80813151",

VMware, Inc. 121

Programming Guide

"description": null,
"status": null,
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"catalogItemLabel": "Linux",
"requestId": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"resourceType":
"{com.vmware.csp.component.cafe.composition@resource.type.deployment.name}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:51:36.368Z",
"lastUpdated": "2015-07-29T13:55:35.963Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": null,
"hasChildren": true,
"data": {}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Navigating to the Children of a Deployed Resource

GET /api/consumer/resourceViews retrieves a list of the child nodes of a deployment,
including virtual machines, networks, and other objects you may have configured 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.

VMware, Inc. 122

Programming Guide

Table 7-3. HATEOAS Link Functions as Defined by rel Field

Link Description

GET: Parent Resource URI to get the resourceView for the parent item. See Syntax for
Getting Deployment Details.

GET:Template URI to get a template request for a specific action that you can
{com.vmware.csp.component.cafe.composition@r perform on this resource.
esource.action.deployment.$actionName

POST: URI to which to post the request to perform an action, based on

{com.vmware.csp.component.cafe.composition@r the corresponding template.
esource.action.deployment.$actionName

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/catalog-service/api/consumer/resources/$resourceId

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$resourceID Specifies a resource ID. See Syntax for Getting Deployment Details to view all of your
requests and search for a request ID.

managedOnly If true, the returned requests are from the user's managed subtenants.

page Specifies a page number.

limit Specifies the number of entries to display on a page.

$orderby Specifies how to order multiple comma-separated properties sorted in ascending or

descending order.

$top Specifies the number of returned entries from the top of the response (total number
per page in relation to skip).

$skip Specifies the number of entries to skip.

filter Contains a Boolean expression to determine if a particular entry is included in the

response.

Output
The command output contains property names and values based on the command input
parameters.

Note Price is referred to as cost in API commands and output.

VMware, Inc. 123

Programming Guide

Table 7-4. Output Parameters

Property Description

resourceId The unique identifier of the resource.

iconId Specifies an icon for this request based on the requested object type.

name The user friendly name of the resource.

description An extended user friendly description of the resource.

status The status of the resource. For example, On, Off, etc.

catalogItemId The identifier of the catalog item associated with this provisioned resource.

catalogItemLabel The label of the catalog item associated with this provisioned resource.

requestId The unique identifier of the request that created this provisioned resource.

businessGroupId The unique identifier of the business group that owns this resource.

tenantId The unique identifier of the tenant that owns this resource.

owners The owner of this resource.

resourceType The type identifier of this resource. For example, Virtual Machine.

parentResourceId The unique identifier of the parent resource. Used for child resources of a multi-
machine resource.

hasChildren Returns trun if this resource has child resources. Used if this is a multi-machine
resource.

dateCreated The date and time at which the resource was created.

lastUpdated The date and time at which the resource was most recently modified.

lease The current lease of the resource.

costs An optional rate card of the prices and charges levied against the resource. This
parameter is deprecated.

costToDate An optional rate card of the existing prices and charges levied against the resource.
This parameter is deprecated.

totalCost An optional rate card of the prices and charges levied for the entire lease period. This
parameter is deprecated.

expenseMonthToDate The expense of the resource from the beginning of the month until the current date.
This value is updated daily by vRealize Business for Cloud.

data The extended, provider defined properties of the resource.

VMware, Inc. 124

Programming Guide

Example Curl Command

This example retrieves all children of the resource with an ID of c4d3db3e-e397-44ff-
a1c9-0ecebdba12f4%27.

$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"

https:// $vRA/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq%20%2
7c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27

Example: JSON Output

The validation output displays the validation status of each content item within the package.

{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Parent Resource",
"href": "https://$vRA/catalog-service/api/consumer/resourceViews/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$vRA/catalog-service/api/consumer/resources/
dd37b7a1-829c-4773-b5be-b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/
template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$vRA/catalog-service/api/consumer/resources/
dd37b7a1-829c-4773-b5be-b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$vRA/catalog-service/api/consumer/resources/
dd37b7a1-829c-4773-b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/
template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$vRA/catalog-service/api/consumer/resources/
dd37b7a1-829c-4773-b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests"

VMware, Inc. 125

Programming Guide

}
],
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "DEMO-002",
"description": null,
"status": "On",
"catalogItemId": null,
"catalogItemLabel": null,
"requestId": null,
"resourceType":
"{com.vmware.csp.component.iaas.proxy.provider@resource.type.registration.name.Infrastructure.
Virtual}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:54:58.804Z",
"lastUpdated": "2015-07-29T13:55:01.371Z",
"lease": {
"start": "2015-07-29T13:51:33.000Z"
},
"costs": {
"leaseRate": {
"type": "moneyTimeRate",
"cost": {
"type": "money",
"currencyCode": "USD",
"amount": 0
},
"basis": {
"type": "timeSpan",
"unit": "DAYS",
"amount": 1
}
}
},
"costToDate": {
"type": "money",
"currencyCode": "USD",
"amount": 0
},
"totalCost": null,
"parentResourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"hasChildren": false,
"data": {
"ChangeLease": true,
"ConnectViaRdp": true,
"ConnectViaVmrc": true,
"DISK_VOLUMES": [
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.DiskInputModel",

VMware, Inc. 126

Programming Guide

"typeFilter": null,
"data": {
"DISK_CAPACITY": 6,
"DISK_INPUT_ID": "DISK_INPUT_ID1"
}
},
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.DiskInputModel",
"typeFilter": null,
"data": {
"DISK_CAPACITY": 6,
"DISK_INPUT_ID": "DISK_INPUT_ID2"
}
}
],
"Destroy": true,
"EXTERNAL_REFERENCE_ID": "vm-38153",
"Expire": true,
"IS_COMPONENT_MACHINE": false,
"MachineBlueprintName": "system_blueprint_vsphere",
"MachineCPU": 1,
"MachineDailyCost": 0,
"MachineDestructionDate": null,
"MachineExpirationDate": null,
"MachineGroupName": "Demo Group",
"MachineGuestOperatingSystem": null,
"MachineInterfaceDisplayName": "vSphere (vCenter)",
"MachineInterfaceType": "vSphere",
"MachineMemory": 4096,
"MachineName": "DEMO-002",
"MachineReservationName": "vCenter55",
"MachineStorage": 12,
"MachineType": "Virtual",
"NETWORK_LIST": [
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.NetworkViewModel",
"typeFilter": null,
"data": {
"NETWORK_MAC_ADDRESS": "00:50:56:ba:6b:85",
"NETWORK_NAME": "VM Network SQA"
}
}
],
"PowerOff": true,
"Reboot": true,
"Reconfigure": true,
"Reprovision": true,
"Reset": true,
"SNAPSHOT_LIST": [],
"Shutdown": true,
"Suspend": true,

VMware, Inc. 127

Programming Guide

"ip_address": "10.118.194.213",
"machineId": "f3579990-a3c4-4e17-9593-1f8893636876"
}
},
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Parent Resource",
"href": "https://$vRA/catalog-service/api/consumer/resourceViews/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.network.service@resource.action.destroy.name,
[{{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrast
ructure.Network.Network.Existing}}]}",
"href": "https://$vRA/catalog-service/api/consumer/resources/f735b57a-
fe6f-4108-876f-1c1055ca2cec/actions/ec5c522d-7b5b-4d0b-b9f2-1aedf01a2f0c/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.network.service@resource.action.destroy.name,
[{{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrast
ructure.Network.Network.Existing}}]}",
"href": "https://$vRA/catalog-service/api/consumer/resources/f735b57a-
fe6f-4108-876f-1c1055ca2cec/actions/ec5c522d-7b5b-4d0b-b9f2-1aedf01a2f0c/requests"
}
],
"resourceId": "f735b57a-fe6f-4108-876f-1c1055ca2cec",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Existing Network",
"description": null,
"status": null,
"catalogItemId": null,
"catalogItemLabel": null,
"requestId": null,
"resourceType":
"{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastr
ucture.Network.Network.Existing}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:55:14.095Z",
"lastUpdated": "2015-07-29T13:55:17.315Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",

VMware, Inc. 128

Programming Guide

"hasChildren": false,
"data": {
"Description": " ",
"Name": "Existing Network"
}
}
],
"metadata": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

VMware, Inc. 129

Working with Reservations
8
You can work with the REST API reservation service to perform a variety of functions, such as
creating and updating reservations.

The vRealize Automation REST API reservation service supports the following reservation types:

n vSphere (except for FlexClone in vSphere)

n vCloud Air

n vCloud Director

n Amazon

n Hyper-V

n KVM

n Xen

The following reservation types are not supported:

n OpenStack

n Physical reservation

The reservation service is extensible, which allows you to add new reservation types.

A reservation must belong to a business group, also referred to as a subtenant. A business group
can have multiple reservations on the same resources or on different resources.

Note The Reservation API now returns compute resource endpoint names within parentheses.
You may need to update any client code which contains logic that uses compute resource names
to account for this change.

This chapter includes the following topics:

n Prerequisites for Working With Reservations

n Create a Reservation

n Display a List of Reservations

n Update a Reservation

n Delete a Reservation

VMware, Inc. 130

Programming Guide

n Service Examples for Working with Reservations

Prerequisites for Working With Reservations

Satisfy the following conditions before performing any tasks for this use case.

n Log in to vRealize Automation as a fabric group 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 Reservation
You use the reservation service REST API to create a vSphere, Amazon, or vCloud Air
reservation.

Some of the steps required to create a reservation include commands that vary by reservation
type. When performing the step, select the command for your vSphere, Amazon, or vCloud Air
reservation.

Procedure

1 Display a List of Supported Reservation Types

Use the reservation service to display a list of supported reservation types, such as vSphere,
Amazon EC2, or vCloud Air.

2 Displaying a Schema Definition for a Reservation

After you know the supported reservations types, you can display a schema definition for
the vSphere, Amazon EC2, or vCloud Air reservation.

3 Get the Business Group ID for a Reservation

You can use reservation service to get the business group ID for a vRealize Automation
reservation. The business group is also referred to as the subtenant in the API.

4 Get a Compute Resource for the Reservation

You can use the REST API reservation service to obtain compute resources for vRealize
Automation reservations.

5 Getting a Resources Schema by Reservation Type

You can use the vRealize Automation REST API to get a resources schema for any
supported reservation type, including a vSphere, Amazon EC2, or vCloud reservation.

6 Creating a Reservation By Type

You can use the vRealize Automation REST API to create any supported reservation type,
including a vSphere, Amazon EC2, or vCloud reservation.

VMware, Inc. 131

Programming Guide

7 Verify a Reservation and Get Reservation Details

After you create a reservation, you can use the reservation service along with reservation
ID to verify that the reservation exists. You can also use the ID to get information about the
reservation in preparation for updating or deleting it.

Display a List of Supported Reservation Types

Use the reservation service to display a list of supported reservation types, such as vSphere,
Amazon EC2, or vCloud Air.

Procedure

u Display a list of supported vRealize Automation reservation types.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/types

Example: Display a List of Supported Reservation Types

The following sample displays JSON output for a vSphere reservation.

{
"links": [],
"content": [{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.009Z",
"version": 1,
"id": "Infrastructure.Reservation.Virtual.vSphere",
"name": "vSphere",
"description": "vSphere Reservation",
"category": "Virtual",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Virtual.vSphere.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Virtual.vSphere",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.008Z",
"version": 0,
"id": "d248eeee-238c-4e87-9e95-f263b04d113f",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,

VMware, Inc. 132

Programming Guide

"totalPages": 1,
"number": 1,
"offset": 0
}
}

The following sample displays JSON output for an Amazon reservation.

{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.074Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 1,
"id": "Infrastructure.Cloud.Amazon",
"name": "Amazon",
"description": "Amazon Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Cloud.Amazon.form.new"
},
"schemaClassId": "Infrastructure.Cloud.Amazon",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.075Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 0,
"id": "2ef8f47c-045c-4ee4-821d-7b1543ea5f11",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}]
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

The following sample displays JSON output for a vCloud Air reservation.

{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-11-06T10:21:06.010Z",

VMware, Inc. 133

Programming Guide

"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 1,
"id": "Infrastructure.Reservation.Cloud.vCloudAir",
"name": "vCloud",
"description": "vCloud Air Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Cloud.vCloudAir.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Cloud.vCloudAir",
"alertTypes": [
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "cd707ad2-d504-43e2-8002-11ee670dcf41",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "ef96fec4-a607-4944-a0af-fbe7df862ee2",
"name": "memory",
"description": null,
"referenceResourceId": "memory"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "043e0815-9f02-4876-b5ce-ddbedabb8ff6",
"name": "cpu",
"description": null,
"referenceResourceId": "cpu"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "77e90acd-93ab-4bbe-853a-b74923dae70a",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}
]
}, //Omit 7 reservation types here
],
"metadata": {
"size": 20,

VMware, Inc. 134

Programming Guide

"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Displaying a Schema Definition for a Reservation

After you know the supported reservations types, you can display a schema definition for the
vSphere, Amazon EC2, or vCloud Air reservation.

Display a Schema Definition for a vSphere Reservation

You can use the reservation service to display a schema definition for a specific vRealize
Automation reservation type such as a vSphere reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, obtain the schema class ID of the
reservation type to create. See Display a List of Supported Reservation Types.

Procedure

u Display a schema definition for a specific vRealize Automation vSphere reservation type.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Virtual.vSphere/default

Example: Display the Schema Definition for a vSphere Reservation

The following sample displays output based on the request to display the schema definition. This
example includes nine extension fields that are supported for the vSphere type reservation.

{
"fields": [{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]

VMware, Inc. 135

Programming Guide

},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "reservationVCNSTransportZone",
"label": "Transport Zone",
"description": "Transport zone of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkScopes",
"typeFilter": null,
"label": "Transport Zone"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSSecurityGroups",
"label": "Security Groups",
"description": "Security groups of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "SecurityGroups",
"typeFilter": null,
"label": "Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",

VMware, Inc. 136

Programming Guide

"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": true
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"label": "Memory"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "InterfaceTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {

VMware, Inc. 137

Programming Guide

"type": "dynamic",
"customAllowed": false,
"dependencies": []
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"label": "Storage"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",

VMware, Inc. 138

Programming Guide

"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "resourcePool",
"label": "Resource Pool",
"description": "The resource pool for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ResourcePools",
"typeFilter": null,
"label": "Resource Pool"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSRoutedGateways",
"label": "Routed Gateways",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationVCNSRoutedGateway",
"typeFilter": null,
"label": "Routed Gateways"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []

VMware, Inc. 139

Programming Guide

},
"isMultiValued": true
}]
}

Display a Schema Definition for an Amazon Reservation

You can use the reservation service to display a schema definition for a specific vRealize
Automation reservation type such as an Amazon reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, obtain the schema class ID of the
reservation type to create. See Display a List of Supported Reservation Types.

Procedure

u Display a schema definition for an Amazon reservation type.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.Amazon/default

Example: Display the Schema Definition for an Amazon Reservation

The following sample displays output based on the request to display the schema definition. This
example includes nine extension fields that are supported for the Amazon type reservation.

{
"fields": [
{
"id": "securityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

VMware, Inc. 140

Programming Guide

],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "locations",
"label": "Locations",
"description": "The locations",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AvailabilityZone",
"typeFilter": null,
"label": "Availability Zone"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

VMware, Inc. 141

Programming Guide

"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "loadBalancers",
"label": "Load balancers",
"description": "The load balancers",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"

VMware, Inc. 142

Programming Guide

},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"locations",
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "specificKeyPairs",
"label": "Specific key pair",
"description": "The specific key pair",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "KeyPair",
"typeFilter": null,
"label": "Key Pair"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource",
"keyPairs"
]

VMware, Inc. 143

Programming Guide

},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}

VMware, Inc. 144

Programming Guide

},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {

VMware, Inc. 145

Programming Guide

"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPC",
"label": "VPC",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Cloud.Amazon.VPC",
"typeFilter": null,
"label": "VPC",
"schema": {
"fields": [
{
"id": "VPCSubnets",
"label": "Subnets",
"description": "The subnets.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Subnet",
"typeFilter": null,
"label": "Subnet"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {
"type": "integer",
"value": 1
}
}

VMware, Inc. 146

Programming Guide

},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCSecurityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {
"type": "integer",
"value": 1
}
}
},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {

VMware, Inc. 147

Programming Guide

"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCName",
"label": "VPC Name",
"description": "The virtual private cloud.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "VirtualPrivateCloud",
"typeFilter": null,
"label": "Virtual Private Cloud"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPCLoadBalancers",
"label": "Load balancers",
"description": "The load balancers.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {

VMware, Inc. 148

Programming Guide

"type": "dynamic",
"customAllowed": false,
"dependencies": [
"VPCSubnets"
]
},
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": true
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {

VMware, Inc. 149

Programming Guide

"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
}
]
},
"isMultiValued": true
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",

VMware, Inc. 150

Programming Guide

"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "keyPairs",
"label": "Key pair",
"description": "The key pair",
"dataType": {
"type": "primitive",
"typeId": "STRING"
},
"displayAdvice": null,
"permissibleValues": {
"type": "static",
"customAllowed": false,
"values": [
{
"underlyingValue": {
"type": "string",
"value": "Not Specified"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Provisioning Group"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Machine"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Specific Key Pair"
},
"label": null
}
]

VMware, Inc. 151

Programming Guide

},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]

Display a Schema Definition for a vCloud Air Reservation

You can use the reservation service to display a schema definition for a specific reservation type
such as a vCloud Air reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, obtain the schema class ID of the
reservation type to create. See Display a List of Supported Reservation Types.

Procedure

u Display a schema definition for a specific vCloud Air reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRAt/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.vCloudAir/default

Example: Display the Schema Definition for a vCloud Air Reservation

The following sample displays output based on the request to display the schema definition. This
example includes six extension fields that are supported for the vCloud Air type reservation.

{
"fields": [
{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",

VMware, Inc. 152

Programming Guide

"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"label": "Network",
"schema": {
"fields": [
{
"id": "networkPath",
"label": "Network Path",
"description": "Network path of the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Network",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "networkProfile",
"label": "Network Profile",
"description": "The Network Profile",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkProfile",
"typeFilter": null,
"label": "Network Profile"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

VMware, Inc. 153

Programming Guide

]
},
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "allocationModel",
"label": "Allocation Model",
"description": "The allocation model for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

VMware, Inc. 154

Programming Guide

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"label": "Memory",
"schema": {
"fields": [
{
"id": "computeResourceMemoryTotalSizeMB",
"label": "Physical Memory (MB)",
"description": "The physical capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false

VMware, Inc. 155

Programming Guide

},
{
"id": "memoryReservedSizeMb",
"label": "Memory Reservation (MB)",
"description": "The reserved capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {

VMware, Inc. 156

Programming Guide

"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"label": "Storage",
"schema": {
"fields": [
{
"id": "storagePath",
"label": "Storage Path",
"description": "The storage path of the storage",
"dataType": {
"type": "ref",

VMware, Inc. 157

Programming Guide

"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Storage",
"typeFilter": null,
"label": "Storage Path"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservationPriority",
"label": "Priority",
"description": "The reservation priority for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{

VMware, Inc. 158

Programming Guide

"id": "computeResourceStorageTotalSizeGB",
"label": "Total (GB)",
"description": "The total physical capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservedSizeGB",
"label": "This reservation reserved (GB)",
"description": "The reserved capacity size (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "storageEnabled",
"label": "Enabled",
"description": "Whether the storage is enabled to reserve",
"dataType": {
"type": "primitive",
"typeId": "BOOLEAN"
},
"displayAdvice": null,

VMware, Inc. 159

Programming Guide

"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageFreeSizeGB",
"label": "Free (GB)",
"description": "The free capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

VMware, Inc. 160

Programming Guide

"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
}
]
}

Get the Business Group ID for a Reservation

You can use reservation service to get the business group ID for a vRealize Automation
reservation. The business group is also referred to as the subtenant in the API.

When you create a reservation, you must supply the business group ID, also referred to as the
subtenant ID, in the REST command line. Use this procedure to obtain the subTenantId value.

Procedure

u Get business group ID for a vRealize Automation reservation with the reservation service.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants/qe/subtenants

Example: Get the Business Group ID for a Reservation

The following sample displays JSON output for the request.

{
"links": [],
"content": [{
"@type": "Subtenant",
"id": "7d7dbb19-d2dc-44a3-9fc2-7435552c8a05",
"name": "Development",
"description": " Development ",
"subtenantRoles": null,
"extensionData": {

VMware, Inc. 161

Programming Guide

"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": "[email protected]"
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ade5b8d3-decf-405e-bd0b-297f976ef721",
"name": "Finance",
"description": "Finance",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " [email protected] "
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ef58f604-528d-4441-a219-4725bead629b",
"name": "Test Sub Tenant",
"description": "VMPS",
"subtenantRoles": null,
"extensionData": {
"entries": []
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "92926c91-37de-4647-9aee-70b8d557ce8d",
"name": "Quality Engineering",
"description": "created by demo content",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " [email protected] "
}
}]
},
"tenant": "qe"
}],

VMware, Inc. 162

Programming Guide

"metadata": {
"size": 20,
"totalElements": 4,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Get a Compute Resource for the Reservation

You can use the REST API reservation service to obtain compute resources for vRealize
Automation reservations.

Prerequisites

When you create a reservation, you must provide compute resource information that
corresponds to the computeResource parameter.

For example, for a vSphere, Amazon EC2, or vCloud Air reservation type schema definition, the
following permissibleValues field in the compute resource output indicates if the compute
resource is available and if it has any dependencies.

“permissibleValues": {"type": "dynamic","customAllowed": false, "dependencies": []}

Procedure

u Use the following command to get a compute resource.

n Command to get a compute resource for vSphere reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Virtual.vSphere/default/computeResource/values -d “{}”

n Command to get a compute resource for an Amazon EC2 reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.Amazon/default/computeResource/values -d “{}”
Example: curl Command for a vCloud reservation

n Command to get a compute resource for a vCloud reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.vCloud/default/computeResource/values -d “{}”

VMware, Inc. 163

Programming Guide

Example: Get a Compute Resource for the Reservation

The following sample displays JSON output for a vSphere reservation.

{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
},
"label": "VC51-Cluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "a4349488-9a56-4906-83a5-7d8b33c9d435",
"label": "NSX61-RC-ManagementCluster"
},
"label": "NSX61-RC-ManagementCluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "40b151ce-e409-4d2a-8dae-bb456139a660",
"label": "NSX61-RC-ComputeClusterB"
},
"label": "NSX61-RC-ComputeClusterB"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
},
"label": "NSX61-RC-ComputeClusterA"
}]
}

The following sample displays JSON output for an Amazon reservation.

{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,

VMware, Inc. 164

Programming Guide

"classId": "ComputeResource",
"id": "fdfa4b95-9476-4c18-81c5-1c0e5cb1131f",
"label": "EC2 841 Endpoint-us-west-1"
},
"label": "EC2 841 Endpoint-us-west-1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "4e362590-b634-4269-9da4-548260148fa3",
"label": "EC2 841 Endpoint-us-west-2"
},
"label": "EC2 841 Endpoint-us-west-2"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
},
"label": "EC2 841 Endpoint-us-east-1"
}
]
}

The following sample displays JSON output for a vCloud Air reservation.

{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
},
"label": "Engineering Allocation VDC"
}
]
}

Getting a Resources Schema by Reservation Type

You can use the vRealize Automation REST API to get a resources schema for any supported
reservation type, including a vSphere, Amazon EC2, or vCloud reservation.

VMware, Inc. 165

Programming Guide

Get Resources Schema for a vSphere Reservation

You can use the reservation service to display information about available resources, such as
storage and network information, for a vSphere reservation.

Procedure

u Display information about available resources.

The following example command queries resource pool information for the compute resource
cc254a84-95b8-434a-874d-bdfef8e8ad2c.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values -d “{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
}
}]
}
}”

Example: Get Resources Schema for a vSphere Reservation

The following JSON output is returned based on the command input.

{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": " 4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": " CoreDev"
},
"label": " CoreDev"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "1186b5cc-cdef-4afb-8653-0ad41a36c194",
"label": "Documentation"
},
"label": "Documentation"

VMware, Inc. 166

Programming Guide

},
//Omit other resource pool list
]
}

Get Resources Schema for an Amazon Reservation

You can use the reservation service to display resource schema, such as storage and network
information, for an Amazon reservation.

Procedure

u Use the reservation service to display resource schema information for an Amazon
reservation.

The following example command displays storage and network information for the compute
resource with an ID of 9d1a3b5a-7162-4a5a-85b7-ec1b2824f554.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values -d “
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
}]
}
}
”

Example: Get Resources Schema for an Amazon Reservation

The following JSON output is returned based on the command input.

{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "9",
"label": "test1"
},
"label": "test1"
},

VMware, Inc. 167

Programming Guide

{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
},
"label": "default"
}
]
}

Get Resources Schema for a vCloud Air Reservation

You can use the reservation service to display information about available resources, such as
storage and network information, for a vCloud Air reservation.

Procedure

u Use the reservation service to display information about available resources.

The following example command displays storage and network information.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.vCloudAir/default/reservationStorages/values -d “

Example: Get Resources Schema for a vCloud Air Reservation

The following JSON output is returned based on the command input.

{
"values": [
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",

VMware, Inc. 168

Programming Guide

"componentId": null,
"classId": "Storage",
"id": "f4df029b-d475-4f85-ab42-05bddde3f667",
"label": "Low Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 954
}
}
]
}
},
"label": "Low Performance Storage"
},
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
},

VMware, Inc. 169

Programming Guide

"label": "High Performance Storage"

}
]
}

Creating a Reservation By Type

You can use the vRealize Automation REST API to create any supported reservation type,
including a vSphere, Amazon EC2, or vCloud reservation.

Create a vSphere Reservation

You can use the reservation service to create a vSphere reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, perform the following tasks
before creating a reservation.

n Display a list of the reservation types that are supported in the vRealize Automation server.
See Display a List of Supported Reservation Types.

n Obtain the permissible value field information required to create a new reservation. After you
retrieve all permissible value field information, you have the input information required to
create a reservation. See Get Resources Schema for a vSphere Reservation.

Procedure

u Create a vSphere reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations -d
“
{
"name": "TestCreateReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},

VMware, Inc. 170

Programming Guide

{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "custom-Properties-key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "custom-Properties-key2",
"value": {
"type": "string",
"value": "custom-property-value2"

VMware, Inc. 171

Programming Guide

}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15872
}
}]
}
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",

VMware, Inc. 172

Programming Guide

"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 32
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",

VMware, Inc. 173

Programming Guide

"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”

Example: Create a vSphere Reservation

The command output is a URL that includes the new reservation ID, for example https://$vRA/
reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c.

Create an Amazon Reservation

You can use the reservation service to create an Amazon reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, perform the following tasks
before creating a reservation.

n Display a list of the reservation types that are supported in the vRealize Automation server.
See Display a List of Supported Reservation Types.

n Obtain the permissible value field information required to create a new reservation. See Get
Resources Schema for an Amazon Reservation.

Procedure

u Create an Amazon reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations -d “
{
"name": "TestEC2Reservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.Amazon",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": "34d2a612-718e-4814-96c5-225f7f5615a6",
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [

],
"alerts": [
{
"alertPercentLevel": 80,

VMware, Inc. 174

Programming Guide

"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "securityGroups",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
}
]
}
},
{
"key": "loadBalancers",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "ElasticLoadBalancer",
"id": "3",
"label": "test1"
}
]
}

VMware, Inc. 175

Programming Guide

},
{
"key": "locations",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AvailabilityZone",
"id": "10",
"label": "us-east-1a"
}
]
}
},
{
"key": "keyPairs",
"value": {
"type": "string",
"value": "Per Provisioning Group"
}
}
]
}
}”

Example: Create an Amazon Reservation

The output is a sample location URL, including the new Amazon reservation ID.

Location: https://$vRA/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-
b583e4c6d085

Create a vCloud Air Reservation

You can use the vRealize Automation REST API reservation service to create a vCloud Air
reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, perform the following tasks
before creating a reservation.

n Display a list of the reservation types that are supported in the vRealize Automation server.
See Display a List of Supported Reservation Types.

n Obtain the permissible value field information required to create a new reservation. See Get
Resources Schema for a vCloud Air Reservation.

VMware, Inc. 176

Programming Guide

Procedure

u Create a vCloud Air reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations -d “
{
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloudAir",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [

],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"

VMware, Inc. 177

Programming Guide

}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",

VMware, Inc. 178

Programming Guide

"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}

VMware, Inc. 179

Programming Guide

},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}
“

Example: Create a vCloud Air Reservation

The output is a location URL, including the new vCloud Air reservation ID.

Location:
https://$vRA/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-b583e4c6d085

Verify a Reservation and Get Reservation Details

After you create a reservation, you can use the reservation service along with reservation ID
to verify that the reservation exists. You can also use the ID to get information about the
reservation in preparation for updating or deleting it.

Prerequisites

In addition to the Prerequisites for Working With Reservations, perform the following tasks
before creating a reservation.

n Finish creating a new reservation. Obtain the reservation ID from the output URL. See Syntax
for Creating a vSphere Reservation .

VMware, Inc. 180

Programming Guide

n Get the reservation ID if you do not already know it. See Display a List of Reservations.

Procedure

u Use the reservation service to verify that a reservation exists by using the verification ID.

The following example command verifies the existence of a reservation with an ID of

94d74105-831a-4598-8f42-efd590fea15c

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c

Example: Verify a Reservation and Get Reservation Details

The following sample displays JSON output for the request including reservation details.

{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{

VMware, Inc. 181

Programming Guide

"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}

VMware, Inc. 182

Programming Guide

},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",

VMware, Inc. 183

Programming Guide

"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",

VMware, Inc. 184

Programming Guide

"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
Example Output for a vCloud Reservation
{
"id": "bf922450-d495-460d-9dbf-1c09b0692db2",
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloud",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [

],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{

VMware, Inc. 185

Programming Guide

"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}

VMware, Inc. 186

Programming Guide

}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {

VMware, Inc. 187

Programming Guide

"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}

Display a List of Reservations

You can use the reservation service to obtain and display a list of existing reservations to obtain
the required reservation ID value in preparation for updating or deleting a reservation.

VMware, Inc. 188

Programming Guide

Procedure

u Display a list of existing vRealize Automation reservations.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations

Example: Display a List of Reservations

The following sample output lists two vSphere reservations named MyTestReservation1 and
MyTestReservation2.

{
"links": [],
"content": [{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",

VMware, Inc. 189

Programming Guide

"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},

VMware, Inc. 190

Programming Guide

{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2

VMware, Inc. 191

Programming Guide

}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {

VMware, Inc. 192

Programming Guide

"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}],
"metadata": {
"size": 0,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Update a Reservation
You can use the reservation service to update an existing vRealize Automation reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, perform the following tasks
before updating a reservation.

n Obtain the reservation ID of the reservation that you want to update. This information is
required API command input. See Syntax for Displaying a List of Reservations .

n Obtain the reservation field information for the reservation that you want to update. For
example, if you want to change from one compute resource to another, you must obtain
the new compute resource ID and its associated JSON section output. This information is
required API command input. See Syntax for Getting a Compute Resource for a Reservation .

Procedure

u Use the reservation service to update an existing reservation.

The following example command updates a reservation with an ID of

94d74105-831a-4598-8f42-efd590fea15c.

curl –X PUT --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"

VMware, Inc. 193

Programming Guide

https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c –d
“
{
"id": "94d74105-831a-4598-8f42-efd590fea15c",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",

VMware, Inc. 194

Programming Guide

"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "TestNetworkProfile"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",

VMware, Inc. 195

Programming Guide

"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,

VMware, Inc. 196

Programming Guide

"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,

VMware, Inc. 197

Programming Guide

"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”

Example: Update a Reservation

The following output is returned based on the command input.

If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Delete a Reservation
You can use the vRealize Automation REST API reservation service to delete an existing
reservation.

Prerequisites

In addition to the Prerequisites for Working With Reservations, obtain the reservation ID of the
reservation that you want to delete. This information is required API command input. See Syntax
for Displaying a List of Reservations before deleting a reservation.

Procedure

u Use the reservation service to delete the existing reservation.

The following example command deletes a reservation with the ID of

94d74105-831a-4598-8f42-efd590fea15c.

curl –X “Delete” --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c

Example: Delete a Reservation

The following output is returned based on the command input.

If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Service Examples for Working with Reservations

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

VMware, Inc. 198

Programming Guide

Most examples use the reservation service API. You use the identity service API to get the
business group ID for a reservation.

n Syntax for Displaying a List of Reservations

GET /api/reservations displays a list of existing vRealize Automation reservations. You
can use this list to obtain the required reservation ID value in preparation for updating or
deleting a reservation.

n Syntax for Displaying a Schema Definition for a vSphere Reservation

GET /api/data-service/schema/{classId}/default with classId for vSphere,
displays the schema definition for a vSphere reservation.

n Syntax for Displaying a Schema Definition for an Amazon Reservation

GET /api/data-service/schema/{classId}/default with classId for Amazon,
displays the schema definition for an Amazon reservation.

n Syntax for Displaying a Schema Definition for a vCloud Air Reservation

GET /api/data-service/schema/{classId}/default with classId for vCloud Air,
displays the schema definition for a vCloud Air reservation.

n Syntax for Getting the Business Group ID for a Reservation

GET /api/tenants/{tenantId}/subtenants of the identity service API, lists all business
groups. The business group is also referred to as the subtenant in the API. When you create
a reservation, you must provide the business group ID, also referred to as the subtenant ID,
in the REST command line. Use this procedure to obtain the subTenantId value.

n Syntax for Getting a Compute Resource for a Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values
creates a compute resource for a vRealize Automation reservation.

n Syntax for Getting Resources Schema for a vSphere Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values with
a schemaClassId for vSphere, displays information about available resources for a vSphere
reservation, such as storage and network information.

n Syntax for Getting Resources Schema for an Amazon Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values with
a schemaClassId for Amazon, displays resource schema information, such as storage and
network data, for an Amazon reservation.

n Syntax for Getting Resources Schema for a vCloud Air Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values with
a schemaClassId for vCloud Air, displays information about available resources, such as
storage and network information, for a vCloud Air reservation.

VMware, Inc. 199

Programming Guide

n Syntax for Creating a vSphere Reservation

POST /api/reservations with a reservationTypeID for vSphere, creates a vSphere
reservation.

n Syntax for Creating an Amazon Reservation

POST /api/reservations with a reservationTypeID for Amazon, creates an Amazon
reservation.

n Syntax for Creating a vCloud Air Reservation

POST /api/reservations with a reservationTypeID for vCloud Air, creates a vCloud Air
reservation.

n Syntax for Verifying a Reservation and Getting Reservation Details

GET /api/reservations/{id} retrieves a vRealize Automation reservation. After you
create a reservation, you can use the reservation ID to verify that the reservation exists.
You can also use the ID to get information about the reservation in preparation for updating
or deleting it.

n Syntax for Displaying a List of Supported Reservation Types

GET /api/reservations/types displays a list of supported vRealize Automation
reservation types.

n Syntax for Updating a Reservation

PUT /api/reservations/{id} updates an existing reservation with a given ID.

n Syntax for Deleting a Reservation

DELETE /api/reservations/{id} deletes an existing reservation with the given ID.

Syntax for Displaying a List of Reservations

GET /api/reservations displays a list of existing vRealize Automation reservations. You can
use this list to obtain the required reservation ID value in preparation for updating or deleting a
reservation.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

VMware, Inc. 200

Programming Guide

Output
The command output contains property names and values based on the command input
parameters.

Property Description

Links Species an array of link objects, each of which contains the following parts:

rel Specifies the name of the link.

n Self refers to the object which was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service that determines the other names.

href Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects returned
in a pageable list.

Metadata Specifies the paging-related data.

Size Specifies the maximum number of rows per page.

totalElements Specifies the number of rows returned.

totalPages Specifies the total number of pages of data available.

Number Specifies the current page number.

Offset Specifies the number of rows skipped.

Example: curl Command

The following example command displays a list of reservations.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations

Example: JSON Output

The following sample output lists two vSphere reservations, named MyTestReservation1 and
MyTestReservation2. For related information, see Syntax for Verifying a Reservation and
Getting Reservation Details .

You can use the id value for each reservation to update or delete them. For related information,
see Syntax for Updating a Reservation or Syntax for Deleting a Reservation .

{
"links": [],
"content": [{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",

VMware, Inc. 201

Programming Guide

"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,

VMware, Inc. 202

Programming Guide

"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187

VMware, Inc. 203

Programming Guide

}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},

VMware, Inc. 204

Programming Guide

{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}],
"metadata": {
"size": 0,
"totalElements": 1,

VMware, Inc. 205

Programming Guide

"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Displaying a Schema Definition for a vSphere Reservation

GET /api/data-service/schema/{classId}/default with classId for vSphere, displays the
schema definition for a vSphere reservation.

Overview
Each reservation contains several fields. Some fields are common to all reservation types and
some are type-specific. The list of type-specific fields is defined in a schema. Call a data and
schema service to get schema definition information. The data and schema service combines
fetch data and fetch schema REST API calls.

Table 8-1. Fields Common To All Reservation Types

Parameter
Parameter Description Type

Id Specifies the reservation ID. GUID

name Specifies the reservation name. String

reservationType Specifies the reservation type, for String

Id example Infrastructure.Reservation.Virtual.vSphere or
Infrastructure.Reservation.Virtual.Amazon.

tenantId Specifies the tenant ID that contains the reservation. String

subTenantId Specifies the subtenant ID that contains the reservation. GUID

enabled Specifies whether the reservation is enabled. Boolean

priority Specifies the priority of the reservation during VM provisioning. Integer

reservationPolic Specifies the reservation policy ID to bind to this reservation. GUID

yId

alertPolicy Specifies the alert policy of the reservation. The detail schema of this field refers to JSON
the alert policy.

extensionData Contains type-specific fields. The detail schema of this field is retrieved by the data JSON
and schema service.

The following table describes the vSphere reservation types field IDs that appear in the output
schema definitions.

VMware, Inc. 206

Programming Guide

Table 8-2. Extension Fields Supported in vSphere Reservations

Permissible
Field ID Data Type Type Class Value Depends on Field

reservationNetworks Complex Type reservationNetwork Yes computeResource

reservationVCNSTransp Entity Reference NetworkScopes Yes computeResource

ortZone

reservationVCNSSecurit Entity Reference SecurityGroups Yes computeResource

yGroups

reservationMemory Complex Type reservationMemory Yes computeResource

computeResource Entity Reference ComputeResource Yes NA

machineQuota Integer N/A No NA

reservationStorages Complex Type reservationStorage Yes computeResource

resourcePool Entity Reference ResourcePools Yes computeResource

reservationVCNSRouted Complex Type reservationVCNSRoutedGa Yes computeResource

Gateways teway

Note The information in the table is subject to change. Call the data and schema service to
retrieve the latest field information.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/data-service/schema/$schemaclassid/
default

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$schemaclassid Specifies the schema class of the reservation type.

The schema class ID for a vSphere reservation is
Infrastructure.Reservation.Virtual.vSphere.
Each supported reservation type contains specific fields. The supported
fields are defined in the schema. For details, see the reservation service
schema definitions in the vRealize Automation API Reference in the vRealize
Automation documentation center.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 207

Programming Guide

Each field contains an array of data rows. Each data row represents one of the fields defined in
the schema.

Property Description

Id Specifies the unique identifier of this resource.

label Specifies the field label.

dataType Specifies the dataType field value:

n type: Specifies the field value type:
n Self refers to the object that was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of a pageable list.
n Specifies the application or service that determines the other names.
n componentTypeid: Specifies the type ID of the component.
n component: Specifies the unique identifier of the component.
n classId: Specifies the schema class of the field

This property is valid for complex and ref field types only.
n label: Specifies the label of the field data type.

displayAdvice Contains display advice for the field. This property is valid for a user interface element only.

permissibleVal Optional field. If this field is a permissible value list field, define the meta info for the permissible value
ues by using the following options:
n type: Specifies if the permissible value list is dynamic or static.
n customAllowed: Specifies if a custom value is allowed during user input in this field.
n dependencies: Specifies the list of fields that the current field depends on.

state Provides a structure for defining the state of a content construct, for example {@link
LayoutSection}. The element state identifies the field paths in the client data context upon which that
element state depends. For example, the callback facet result indicates that facet evaluation must
be delegated to the server of the object. This evaluation may be dependent on data collected in the
client data context. For example, for a unique machine name, the evaluation requires the proposed
name entered by the user.

dependencies Contains the set of field paths on which the server-side evaluation of the facets depends:
n facets: Provides a higher level view of an {@link Constraint} collection and its current values. All
rendering code should use this class to provide a common place to get the current state of the
field.

If a field is considered in need of server-side evaluation, its facets setting is callback.

If a field is considered mandatory, its facets setting is mandatory.

n isMultiValued: Specifies if the field is a multi-value field, such as a list field.

The state provides a higher level view of an {@link Constraint} collection and its current values.
Rendering code should use this class to provide a common place to get the current state of the
field.

Example: curl Command

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"

VMware, Inc. 208

Programming Guide

https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Virtual.vSphere/default

Example: JSON Output

The schema definition in this example includes 9 extension fields that are supported for the
vSphere type reservation.

{
"fields": [{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "reservationVCNSTransportZone",
"label": "Transport Zone",
"description": "Transport zone of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkScopes",
"typeFilter": null,
"label": "Transport Zone"
},
"displayAdvice": null,

VMware, Inc. 209

Programming Guide

"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSSecurityGroups",
"label": "Security Groups",
"description": "Security groups of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "SecurityGroups",
"typeFilter": null,
"label": "Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": true
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"label": "Memory"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{

VMware, Inc. 210

Programming Guide

"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "InterfaceTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": []
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {

VMware, Inc. 211

Programming Guide

"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"label": "Storage"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "resourcePool",
"label": "Resource Pool",
"description": "The resource pool for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ResourcePools",
"typeFilter": null,
"label": "Resource Pool"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},

VMware, Inc. 212

Programming Guide

"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSRoutedGateways",
"label": "Routed Gateways",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationVCNSRoutedGateway",
"typeFilter": null,
"label": "Routed Gateways"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": true
}]
}

Syntax for Displaying a Schema Definition for an Amazon

Reservation
GET /api/data-service/schema/{classId}/default with classId for Amazon, displays the
schema definition for an Amazon reservation.

Overview
Each reservation contains several fields. Some fields are common to all reservation types and
some are type-specific. The list of type-specific fields is defined in a schema. Call a data and
schema service to get schema definition information. The data and schema service combines
fetch data and fetch schema REST API calls.

Table 8-3. Fields Common To All Reservation Types

Parameter
Parameter Description Type

Id Specifies the reservation ID. GUID

name Specifies the reservation name. String

VMware, Inc. 213

Programming Guide

Table 8-3. Fields Common To All Reservation Types (continued)

Parameter
Parameter Description Type

reservationType Specifies the reservation type, for String

Id example Infrastructure.Reservation.Virtual.vSphere or
Infrastructure.Reservation.Virtual.Amazon.

tenantId Specifies the tenant ID that contains the reservation. String

subTenantId Specifies the subtenant ID that contains the reservation. GUID

enabled Specifies whether the reservation is enabled. Boolean

priority Specifies the priority of the reservation during VM provisioning. Integer

reservationPolic Specifies the reservation policy ID to bind to this reservation. GUID

yId

alertPolicy Specifies the alert policy of the reservation. The detail schema of this field refers to JSON
the alert policy.

extensionData Contains type-specific fields. The detail schema of this field is retrieved by the data JSON
and schema service.

The following table describes the Amazon EC2 reservation types field IDs that appear in the
output schema definitions.

Table 8-4. Extension Fields Supported in Amazon Reservations

Permissible
Field ID Data Type Type Class Value Depends on Field

securityGroups Entity Reference AmazonSecurityGroup Yes computeResource

locations Entity Reference AvailabilityZone Yes computeResource

loadBalancers Entity Reference ElasticLoadBalancer Yes computeResource and

locations

specificKeyPairs Entity Reference KeyPair Yes computeResource

and keyPairs

computeResource Entity Reference ComputeResource Yes NA

VPC Complex Type Infrastructure.Reservation. Yes computeResource

Cloud.Amazon.VPC

machineQuota Integer NA No NA

keyPairs String ResourcePools Yes computeResource

Note The information in the table is subject to change. Call the data and schema service to
retrieve the latest field information.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 214

Programming Guide

Parameter Description

URL https://$vRA/reservation-service/api/data-service/schema/$schemaclassid/
default

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$schemaclassid Specifies the schema class of the reservation type.

The schema class ID for an Amazon reservation is
Infrastructure.Reservation.Cloud.Amazon.
Each supported reservation type contains specific fields. The supported fields
are defined in the schema. For details, see the reservation service schema
definitions in the vRealize Automation API Reference in vRealize Automation
documentation.

Output
The command output contains property names and values based on the command input
parameters.

Each field contains an array of data rows. Each data row represents one of the fields defined in
the schema.

Property Description

Id Specifies the unique identifier of this resource.

label Specifies the field label.

dataType Specifies the dataType field value:

n type: Specifies the field value type:
n Self refers to the object that was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of a pageable list.
n Specifies the application or service that determines the other names.
n componentTypeid: Specifies the type ID of the component.
n component: Specifies the unique identifier of the component.
n classId: Specifies the schema class of the field

This property is valid for complex and ref field types only.
n label: Specifies the label of the field data type.

displayAdvice Contains display advice for the field. This property is valid for a user interface element only.

permissibleVal Optional field. If this field is a permissible value list field, define the meta info for the permissible value
ues by using the following options:
n type: Specifies if the permissible value list is dynamic or static.
n customAllowed: Specifies if a custom value is allowed during user input in this field.
n dependencies: Specifies the list of fields that the current field depends on.

VMware, Inc. 215

Programming Guide

Property Description

state Provides a structure for defining the state of a content construct, for example {@link
LayoutSection}. The element state identifies the field paths in the client data context upon which that
element state depends. For example, the callback facet result indicates that facet evaluation must
be delegated to the server of the object. This evaluation may be dependent on data collected in the
client data context. For example, for a unique machine name, the evaluation requires the proposed
name entered by the user.

dependencies Contains the set of field paths on which the server-side evaluation of the facets depends:
n facets: Provides a higher level view of an {@link Constraint} collection and its current values. All
rendering code should use this class to provide a common place to get the current state of the
field.

If a field is considered in need of server-side evaluation, its facets setting is callback.

If a field is considered mandatory, its facets setting is mandatory.

n isMultiValued: Specifies if the field is a multi-value field, such as a list field.

The state provides a higher level view of an {@link Constraint} collection and its current values.
Rendering code should use this class to provide a common place to get the current state of the
field.

Example: curl Command

The following example command retrieves schema definition information for an Amazon type
reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.Amazon/default

Example: JSON Output

The following JSON output is returned based on the command input.

The schema definition in this example includes 8 extension fields that are supported for the
Amazon EC2 type reservation.

{
"fields": [
{
"id": "securityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,

VMware, Inc. 216

Programming Guide

"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "locations",
"label": "Locations",
"description": "The locations",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",

VMware, Inc. 217

Programming Guide

"componentId": null,
"classId": "AvailabilityZone",
"typeFilter": null,
"label": "Availability Zone"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{

VMware, Inc. 218

Programming Guide

"id": "loadBalancers",
"label": "Load balancers",
"description": "The load balancers",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"locations",
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "specificKeyPairs",
"label": "Specific key pair",
"description": "The specific key pair",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "KeyPair",
"typeFilter": null,

VMware, Inc. 219

Programming Guide

"label": "Key Pair"

},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource",
"keyPairs"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "and",

VMware, Inc. 220

Programming Guide

"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},

VMware, Inc. 221

Programming Guide

"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPC",
"label": "VPC",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Cloud.Amazon.VPC",
"typeFilter": null,
"label": "VPC",
"schema": {
"fields": [
{
"id": "VPCSubnets",
"label": "Subnets",
"description": "The subnets.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Subnet",
"typeFilter": null,
"label": "Subnet"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],

VMware, Inc. 222

Programming Guide

"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {
"type": "integer",
"value": 1
}
}
},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCSecurityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {

VMware, Inc. 223

Programming Guide

"type": "integer",
"value": 1
}
}
},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCName",
"label": "VPC Name",
"description": "The virtual private cloud.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "VirtualPrivateCloud",
"typeFilter": null,
"label": "Virtual Private Cloud"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPCLoadBalancers",
"label": "Load balancers",
"description": "The load balancers.",

VMware, Inc. 224

Programming Guide

"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"VPCSubnets"
]
},
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": true
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "visible",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {

VMware, Inc. 225

Programming Guide

"type": "path",
"path": "locations"
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
}

VMware, Inc. 226

Programming Guide

]
},
"isMultiValued": true
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "keyPairs",
"label": "Key pair",
"description": "The key pair",
"dataType": {
"type": "primitive",
"typeId": "STRING"
},
"displayAdvice": null,
"permissibleValues": {
"type": "static",
"customAllowed": false,
"values": [
{
"underlyingValue": {
"type": "string",
"value": "Not Specified"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Provisioning Group"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Machine"
},

VMware, Inc. 227

Programming Guide

"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Specific Key Pair"
},
"label": null
}
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]

Syntax for Displaying a Schema Definition for a vCloud Air

Reservation
GET /api/data-service/schema/{classId}/default with classId for vCloud Air, displays
the schema definition for a vCloud Air reservation.

Overview
SomevRealize Automation reservation fields are common to all reservation types and some are
type-specific. The list of type-specific fields is defined in a schema. You can call a data and
schema service to get schema definition information. The data and schema service combines
fetch data and fetch schema REST API calls.

Table 8-5. Fields Common To All Reservation Types

Parameter
Parameter Description Type

Id Specifies the reservation ID. GUID

name Specifies the reservation name. String

VMware, Inc. 228

Programming Guide

Table 8-5. Fields Common To All Reservation Types (continued)

Parameter
Parameter Description Type

reservationType Specifies the reservation type, for String

Id example Infrastructure.Reservation.Virtual.vSphere or
Infrastructure.Reservation.Virtual.Amazon.

tenantId Specifies the tenant ID that contains the reservation. String

subTenantId Specifies the subtenant ID that contains the reservation. GUID

enabled Specifies whether the reservation is enabled. Boolean

priority Specifies the priority of the reservation during VM provisioning. Integer

reservationPolic Specifies the reservation policy ID to bind to this reservation. GUID

yId

alertPolicy Specifies the alert policy of the reservation. The detail schema of this field refers to JSON
the alert policy.

extensionData Contains type-specific fields. The detail schema of this field is retrieved by the data JSON
and schema service.

The following table describes the vCloud Air reservation types field IDs that appear in the output
schema definitions.

Table 8-6. Extension Fields Supported in vCloud Reservations

Permissible
Field ID Data Type Type Class Value Depends on Field

reservationNetworks Complex Type Infrastructure.Reservation. Yes computeResource

Network

allocationModel Integer NA No NA

reservationMemory Complex Type Infrastructure.Reservation. No NA

Memory

computeResource Entity Reference ComputeResource Yes NA

machineQuota Integer NA No NA

reservationStorages Complex Type Infrastructure.Reservation. Yes computeResource

Storage

Note The information in the table is subject to change. Call the data and schema service to
retrieve the latest field information.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 229

Programming Guide

Parameter Description

URL https://$vRA/reservation-service/api/data-service/schema/$schemaclassid/
default

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$schemaclassid Specifies the schema class of the reservation type.

The schema class ID for a vCloud Air reservation is
Infrastructure.Reservation.Cloud.vCloudAir.
Each supported reservation type contains specific fields. The supported fields
are defined in the schema. For details, see the reservation service schema
definitions in the vRealize Automation API Reference in vRealize Automation
documentation.

Output
The command output contains property names and values based on the command input
parameters.

Each field contains an array of data rows. Each data row represents one of the fields defined in
the schema.

Property Description

Id Specifies the unique identifier of this resource.

label Specifies the field label.

dataType Specifies the dataType field value:

n type: Specifies the field value type:
n Self refers to the object that was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of a pageable list.
n Specifies the application or service that determines the other names.
n componentTypeid: Specifies the type ID of the component.
n component: Specifies the unique identifier of the component.
n classId: Specifies the schema class of the field

This property is valid for complex and ref field types only.
n label: Specifies the label of the field data type.

displayAdvice Contains display advice for the field. This property is valid for a user interface element only.

permissibleVal Optional field. If this field is a permissible value list field, define the meta info for the permissible value
ues by using the following options:
n type: Specifies if the permissible value list is dynamic or static.
n customAllowed: Specifies if a custom value is allowed during user input in this field.
n dependencies: Specifies the list of fields that the current field depends on.

VMware, Inc. 230

Programming Guide

Property Description

state Provides a structure for defining the state of a content construct, for example {@link
LayoutSection}. The element state identifies the field paths in the client data context upon which that
element state depends. For example, the callback facet result indicates that facet evaluation must
be delegated to the server of the object. This evaluation may be dependent on data collected in the
client data context. For example, for a unique machine name, the evaluation requires the proposed
name entered by the user.

dependencies Contains the set of field paths on which the server-side evaluation of the facets depends:
n facets: Provides a higher level view of an {@link Constraint} collection and its current values. All
rendering code should use this class to provide a common place to get the current state of the
field.

If a field is considered in need of server-side evaluation, its facets setting is callback.

If a field is considered mandatory, its facets setting is mandatory.

n isMultiValued: Specifies if the field is a multi-value field, such as a list field.

The state provides a higher level view of an {@link Constraint} collection and its current values.
Rendering code should use this class to provide a common place to get the current state of the
field.

Example: curl Command

The following example command retrieves schema definition information for a vCloud Air
reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.vCloudAir/default

Example: JSON Output

The schema definition in this example includes 6 extension fields that are supported for the
vCloud Air type reservation.

{
"fields": [
{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"label": "Network",
"schema": {
"fields": [
{
"id": "networkPath",
"label": "Network Path",

VMware, Inc. 231

Programming Guide

"description": "Network path of the reservation",

"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Network",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "networkProfile",
"label": "Network Profile",
"description": "The Network Profile",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkProfile",
"typeFilter": null,
"label": "Network Profile"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],
"facets": [

VMware, Inc. 232

Programming Guide

]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "allocationModel",
"label": "Allocation Model",
"description": "The allocation model for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true

VMware, Inc. 233

Programming Guide

}
}
}
]
},
"isMultiValued": false
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"label": "Memory",
"schema": {
"fields": [
{
"id": "computeResourceMemoryTotalSizeMB",
"label": "Physical Memory (MB)",
"description": "The physical capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "memoryReservedSizeMb",
"label": "Memory Reservation (MB)",
"description": "The reserved capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},

VMware, Inc. 234

Programming Guide

"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [

]
},
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {

VMware, Inc. 235

Programming Guide

"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"label": "Storage",
"schema": {
"fields": [
{
"id": "storagePath",
"label": "Storage Path",
"description": "The storage path of the storage",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Storage",
"typeFilter": null,
"label": "Storage Path"
},
"displayAdvice": null,
"state": {
"dependencies": [

VMware, Inc. 236

Programming Guide

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservationPriority",
"label": "Priority",
"description": "The reservation priority for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageTotalSizeGB",
"label": "Total (GB)",
"description": "The total physical capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {

VMware, Inc. 237

Programming Guide

"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservedSizeGB",
"label": "This reservation reserved (GB)",
"description": "The reserved capacity size (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [

]
},
"isMultiValued": false
},
{
"id": "storageEnabled",
"label": "Enabled",
"description": "Whether the storage is enabled to reserve",
"dataType": {
"type": "primitive",
"typeId": "BOOLEAN"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",

VMware, Inc. 238

Programming Guide

"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageFreeSizeGB",
"label": "Free (GB)",
"description": "The free capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [

],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [

],
"facets": [
{

VMware, Inc. 239

Programming Guide

"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
}
]
}

Syntax for Getting the Business Group ID for a Reservation

GET /api/tenants/{tenantId}/subtenants of the identity service API, lists all business
groups. The business group is also referred to as the subtenant in the API. When you create
a reservation, you must provide the business group ID, also referred to as the subtenant ID, in the
REST command line. Use this procedure to obtain the subTenantId value.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants/$tenantId/subtenants

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$tenantId Specifies the ID of the tenant.

Use to indicate the tenant ID to be queried. Each subtenant, or business
group, must belong to a tenant.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 240

Programming Guide

Property Description

Links Species an array of link objects, each of which contains the following parts:

rel Specifies the name of the link.

n Self refers to the object that was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service determines the other names.

href Specifies the URL which produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects returned
in a pageable list. Each tenant object contains the following information:

@type Constants the ReservationType string.

Id Specifies the unique reservation type identifier.

name Specifies the reservation type name.

description Specifies the reservation type description.

subtenantRoles Specifies the business group roles.

extensionData Specifies the extension data of the business group.

For example, the email address of the vRealize Automation business group manager is
[email protected].

Metadata Specifies the paging-related data.

Size Specifies the maximum number of rows per page.

totalElements Specifies the number of rows returned.

totalPages Specifies the total number of pages of data available.

Number Specifies the current page number.

Offset Specifies the number of rows skipped.

Example: curl Command

The following example command retrieves all available business group, or subtenant, IDs.

insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants/qe/subtenants

Example: JSON Output

In this example, all available business group, or subtenant, IDs are displayed. For related
information about the subtenant ID ef58f604-528d-4441-a219-4725bead629b, see Create a
Reservation.

VMware, Inc. 241

Programming Guide

The following JSON output is returned based on the command input.

{
"links": [],
"content": [{
"@type": "Subtenant",
"id": "7d7dbb19-d2dc-44a3-9fc2-7435552c8a05",
"name": "Development",
"description": " Development ",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": "[email protected]"
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ade5b8d3-decf-405e-bd0b-297f976ef721",
"name": "Finance",
"description": "Finance",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " [email protected] "
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ef58f604-528d-4441-a219-4725bead629b",
"name": "Test Sub Tenant",
"description": "VMPS",
"subtenantRoles": null,
"extensionData": {
"entries": []
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "92926c91-37de-4647-9aee-70b8d557ce8d",
"name": "Quality Engineering",
"description": "created by demo content",
"subtenantRoles": null,

VMware, Inc. 242

Programming Guide

"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " [email protected] "
}
}]
},
"tenant": "qe"
}],
"metadata": {
"size": 20,
"totalElements": 4,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Getting a Compute Resource for a Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values creates a
compute resource for a vRealize Automation reservation.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/data-service/schema/
$schemaclassid/default/$fieldid/values

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$schemaclassid Specifies the schema class ID.

For a vSphere reservation, specify
Infrastructure.Reservation.Virtual.vSphere as the
$schemaclassid value.
For an Amazon EC2 reservation, specify
Infrastructure.Reservation.Cloud.Amazon as the the
$schemaclassid value.
For a vCloud reservation, specify
Infrastructure.Reservation.Cloud.vCloud as the the
$schemaclassid value.

VMware, Inc. 243

Programming Guide

Parameter Description

$fieldId From the schema definition, specifies the schemaclassid of the

compute resource field, which is is computeResource.
Enter computeResource for the $fieldId value.

HTTP body Because the dependencies entry for this permissible value field is
an empty string, provide an empty JSON string "{}" in the HTTP
body.

Output
The command output contains property names and values based on the command input
parameters.

The values section contains an array of data rows, each of which represents one of the
compute resource objects, returned in a pageable list. Each compute resource object contains
the following information.

Property Description

underlyingValue Contains a JSON string representing one permissible value of field.

n type

Specifies one of the following permissible value data types.

n entityRef - Indicates that the object references a vRealize Automation entity.
n complexRef - Indicates that the object is a user-defined complex structure, for
example struct in C or Pojo in Java.
n primary - Indicates the entity type such as string, integer, and so on.
n componentId

Specifies the component ID.

n classId

Specifies the schema class ID of the current data type.

n Id

Specifies the unique compute resource identifier.

label Contains the compute resource label. This value matches the underlyingValue.label.

Example: curl Command for a vSphere reservation

The following command retrieves a compute resource for a vSphere reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Virtual.vSphere/default/computeResource/values -d “{}”

VMware, Inc. 244

Programming Guide

Example: curl Command for an Amazon EC2 reservation

The following command retrieves a compute resource for an Amazon EC2 reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.Amazon/default/computeResource/values -d “{}”

Example: curl Command for a vCloud reservation

The following command retrieves a compute resource for a vCloud reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.vCloud/default/computeResource/values -d “{}”

Example: JSON Output for a vSphere Reservation

In this example, there are 4 available compute resources that you can use to create a
vSphere reservation, for example cc254a84-95b8-434a-874d-bdfef8e8ad2c. Save a copy of the
underlyingValue section of the compute resource that you want to an XML editor and use the
section content later to create a reservation request.

The following JSON output is returned based on the command input.

{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
},
"label": "VC51-Cluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "a4349488-9a56-4906-83a5-7d8b33c9d435",
"label": "NSX61-RC-ManagementCluster"
},
"label": "NSX61-RC-ManagementCluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "40b151ce-e409-4d2a-8dae-bb456139a660",

VMware, Inc. 245

Programming Guide

"label": "NSX61-RC-ComputeClusterB"
},
"label": "NSX61-RC-ComputeClusterB"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
},
"label": "NSX61-RC-ComputeClusterA"
}]
}

Example: JSON Output for an Amazon Reservation

In this example, there are 3 available compute resources that you can use to create an Amazon
EC2 reservation. Save a copy of the underlyingValue section of the compute resource that you
want to an XML editor and use the section content later to create a reservation request.

{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "fdfa4b95-9476-4c18-81c5-1c0e5cb1131f",
"label": "EC2 841 Endpoint-us-west-1"
},
"label": "EC2 841 Endpoint-us-west-1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "4e362590-b634-4269-9da4-548260148fa3",
"label": "EC2 841 Endpoint-us-west-2"
},
"label": "EC2 841 Endpoint-us-west-2"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
},
"label": "EC2 841 Endpoint-us-east-1"
}

VMware, Inc. 246

Programming Guide

]
}

Example: Output for a vCloud Reservation

In this example, there is 1 available compute resource that you can use to create a vCloud
reservation. Save a copy of the underlyingValue section of the compute resource that you
want to an XML editor and use the section content later to create a reservation request.

{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
},
"label": "Engineering Allocation VDC"
}
]
}

Syntax for Getting Resources Schema for a vSphere Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values with a
schemaClassId for vSphere, displays information about available resources for a vSphere
reservation, such as storage and network information.

Overview
This example illustrates how to get a permissible value list for the resourcePool field. You can
use the generated output as input for creating or updating a vSphere reservation.

Table 8-7. Extension Fields Supported in vSphere Reservations

Permissible
Field ID Data Type Type Class Value Depends on Field

reservationNetworks Complex Type reservationNetwork Yes computeResource

reservationVCNSTransp Entity Reference NetworkScopes Yes computeResource

ortZone

reservationVCNSSecurit Entity Reference SecurityGroups Yes computeResource

yGroups

reservationMemory Complex Type reservationMemory Yes computeResource

computeResource Entity Reference ComputeResource Yes NA

machineQuota Integer N/A No NA

reservationStorages Complex Type reservationStorage Yes computeResource

VMware, Inc. 247

Programming Guide

Table 8-7. Extension Fields Supported in vSphere Reservations (continued)

Permissible
Field ID Data Type Type Class Value Depends on Field

resourcePool Entity Reference ResourcePools Yes computeResource

reservationVCNSRouted Complex Type reservationVCNSRoutedGa Yes computeResource

Gateways teway

Note The information in the table is subject to change. Call the data and schema service to
retrieve the latest field information.

For related information, see Syntax for Displaying a Schema Definition for a vSphere
Reservation .

Input
Use the supported input parameters to control the command output.

Input Description

URL https://$vRA/reservation-service/api/data-service/schema/$schemaclassid/default/
$fieldid/values

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$schemaclassid Specifies the schema class ID.

This example illustrates how to use the resourcePool field of a vSphere
reservation type as an example. The schema class ID of a vSphere reservation
is Infrastructure.Reservation.Virtual.vSphere. For this example, the input
value for $schemaclassid is Infrastructure.Reservation.Virtual.vSphere.

$fieldId Specifies the field ID of the resource.

For example, the field ID for the resource pool is resourcePool. For this example,
the input value for $fieldId is resourcePool.

HTTP body Contains information about dependencies.

Because the dependency of this permissible value field is computeResource, you
must provide a dependency definition in the HTTP body.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 248

Programming Guide

Property Description

values An array of data rows, each of which represents one of the resource pool objects
returned in a pageable list. Each resource pool object contains an underlyingValue
and label entry.

underlyingValue JSON string representing one permissible value for a field:

n type -- data type of entityRef, complexRef, or primary
n component ID -- componentID
n classId -- schema class ID of current data type
n id -- unique resource pool ID
n label -- resource pool label

label Specifies the resource pool label. This value matches the underlyingValue value.

Example: curl Command

The following example command returns vSphere reservation storage information.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values -d “{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
}
}]
}
}”

Example: JSON Output

The following JSON output is returned based on the command input.

In the following example output, the CoreDev resource pool is shown. Copy the output
underlyingValue section into an XML editor and use it as input to create or update a
reservation. Note that other REST calls can be used such as reservationNetworks and
reservationStorages to get other resources for the reservation.

{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": " 4e51fabc-19e8-4e79-b413-d52309b3bb62",

VMware, Inc. 249

Programming Guide

"label": " CoreDev"

},
"label": " CoreDev"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "1186b5cc-cdef-4afb-8653-0ad41a36c194",
"label": "Documentation"
},
"label": "Documentation"
},
//Omit other resource pool list
]
}

Syntax for Getting Resources Schema for an Amazon Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values with a
schemaClassId for Amazon, displays resource schema information, such as storage and
network data, for an Amazon reservation.

Overview
This example illustrates how to get a permissible value list for the securityGroups field. You can
use the generated output as input for creating or updating an Amazon reservation.

Table 8-8. Extension Fields Supported in Amazon Reservations

Permissible
Field ID Data Type Type Class Value Depends on Field

securityGroups Entity Reference AmazonSecurityGroup Yes computeResource

locations Entity Reference AvailabilityZone Yes computeResource

loadBalancers Entity Reference ElasticLoadBalancer Yes computeResource and

locations

specificKeyPairs Entity Reference KeyPair Yes computeResource

and keyPairs

computeResource Entity Reference ComputeResource Yes NA

VPC Complex Type Infrastructure.Reservation. Yes computeResource

Cloud.Amazon.VPC

machineQuota Integer NA No NA

keyPairs String ResourcePools Yes computeResource

Note The information in the table is subject to change. Call the data and schema service to
retrieve the latest field information.

VMware, Inc. 250

Programming Guide

For related information, see Syntax for Displaying a Schema Definition for an Amazon
Reservation .

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/data-service/schema/
$schemaclassid/default/$fieldid/values

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$schemaclassid Specifies the schema class ID.

This example illustrates how to use the securityGroups
field of an Amazon reservation type as an example.
The schema class ID of an Amazon reservation
is Infrastructure.Reservation.Cloud.Amazon. For this
example, the input value for $schemaclassid is
Infrastructure.Reservation.Cloud.Amazon.

$fieldId Specifies the field ID of the resource.

For example, the field ID for the resource pool is securityGroups.
For this example, the input value for $fieldId is securityGroups.

HTTP body Contains information about dependencies.

Because the dependency of this permissible value field is
computeResource, you must provide a dependency definition in
the HTTP body.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

values An array of data rows, each of which represents one of the security group objects
returned in a pageable list. Each security group object contains an underlyingValue
and label entry.

underlyingValue JSON string representing one permissible value for a field:

n type -- data type of entityRef, complexRef, or primary
n component ID -- componentID
n classId -- schema class ID of current data type
n id -- unique security group ID
n label -- security group label

label Specifies the security groups label. This value matches the underlyingValue value.

VMware, Inc. 251

Programming Guide

Example: curl Command

The following example command displays resource schema security group information.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values -d “
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
}]
}
}
”

Example: JSON Output

The following JSON output is returned based on the command input.

Copy the output from an underlyingValue section into an XML editor and use it as input to
create or update a reservation.

{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "9",
"label": "test1"
},
"label": "test1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
},
"label": "default"
}
]

VMware, Inc. 252

Programming Guide

Syntax for Getting Resources Schema for a vCloud Air Reservation

POST /api/data-service/schema/{schemaClassId}/default/{fieldId}/values with a
schemaClassId for vCloud Air, displays information about available resources, such as storage
and network information, for a vCloud Air reservation.

Overview
This example illustrates how to get a permissible value list for the reservationStorages field.
Use the generated output as input for creating or updating a vCloud Air reservation.

Table 8-9. Extension Fields Supported in vCloud Reservations

Permissible
Field ID Data Type Type Class Value Depends on Field

reservationNetworks Complex Type Infrastructure.Reservation. Yes computeResource

Network

allocationModel Integer NA No NA

reservationMemory Complex Type Infrastructure.Reservation. No NA

Memory

computeResource Entity Reference ComputeResource Yes NA

machineQuota Integer NA No NA

reservationStorages Complex Type Infrastructure.Reservation. Yes computeResource

Storage

Note The information in the table is subject to change. Call the data and schema service to
retrieve the latest field information.

For related information, see Syntax for Displaying a Schema Definition for a vCloud Air
Reservation .

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/data-service/schema/$schemaclassid/
default/$fieldid/values

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

VMware, Inc. 253

Programming Guide

Parameter Description

$schemaclassid Specifies the schema class ID.

This example illustrates how to use the reservationStorages field of
a reservation type as an example. The schema class ID of a vCloud
Air reservation is Infrastructure.Reservation.Cloud.vCloudAir.
For this example, the input value for $schemaclassid is
Infrastructure.Reservation.Cloud.vCloudAir.

$fieldId Specifies the field ID of the resource.

For example, the field ID for the reservation storage is
reservationStorages. For this example, the input value for $fieldId is
reservationStorages.

HTTP body Contains information about dependencies.

Because the dependency of the permissible value field
reservationStorages is computeResource, you must include a
dependency definition in the HTTP body.

text Empty

dependencyValues JSON string that defines the dependency values

entries key -- Specifies the field ID of dependent field. For this example, enter
computeResource.
value -- Specifies the value of the dependent field. For this example, copy
and paste the vCloud HTTP response obtained by using the Get Compute
Resource task. See Syntax for Getting Resources Schema for a vCloud Air
Reservation .

Output
The command output contains property names and values based on the command input
parameters.

Property Description

values An array of data rows, each of which represents one of the reservation storage
objects returned in a pageable list. Each reservation storage object contains an
underlyingValue and label entry.

underlyingValue JSON string representing one permissible value for a field:

n type -- data type of entityRef, complexRef, or primary
n component ID -- componentID
n classId -- schema class ID of current data type
n id -- unique reservation storage ID
n label --reservation storage label

label Specifies the reservation storage label. This value matches the underlyingValue
value.

VMware, Inc. 254

Programming Guide

Example: curl Command

The following example command returns vCloud Air reservation storage information.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/data-service/schema/
Infrastructure.Reservation.Cloud.vCloudAir/default/reservationStorages/values -d “

Example: JSON Output

The following JSON output is returned based on the command input.

Copy the output from an underlyingValue section into an XML editor and use it as input to
create or update a reservation.

{
"values": [
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "f4df029b-d475-4f85-ab42-05bddde3f667",
"label": "Low Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 954
}
}
]
}
},

VMware, Inc. 255

Programming Guide

"label": "Low Performance Storage"

},
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
},
"label": "High Performance Storage"
}
]
}

Syntax for Creating a vSphere Reservation

POST /api/reservations with a reservationTypeID for vSphere, creates a vSphere
reservation.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 256

Programming Guide

Input Description

URL https://$vRA/reservation-service/api/reservations

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

HTTP body The HTTP body describes the reservation to create and calls the
REST API used to create the reservation.
Compose the HTTP body using one of the following methods:
n Copy the HTTP body from the JSON output from this example
and edit the applicable field values to compose the HTTP body
input for the command line.
n Use the API commands in Syntax for Verifying a Reservation
and Getting Reservation Details , remove the appropriate ID
field from the HTTP response, and edit the field values to
compose the HTTP body input for the command line.

Output
The output URL contains the new reservation ID.

Property Description

status When the reservation is successfully created, the HTTP response

status is 201 created.

Header.Location The HTTP response contains a Location attribute that is formatted

as https://$vRA /reservation-service/api/reservations/$reservationId.

$reservationId Specifies the new reservation ID.

Example: curl Command

The following sample command creates a vSphere reservation. The HTTP body is included as
part of the command line input.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations -d
“
{
"name": "TestCreateReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,

VMware, Inc. 257

Programming Guide

"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "custom-Properties-key0",
"value": {

VMware, Inc. 258

Programming Guide

"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "custom-Properties-key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15872
}
}]
}
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{

VMware, Inc. 259

Programming Guide

"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 32
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}

VMware, Inc. 260

Programming Guide

}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”

Example: JSON Output

The following sample location URL is displayed, including the new vSphere reservation ID.

Location:
https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c

Copy the output response into an XML editor for use in a future procedure, such as updating or
deleting the reservation.

Syntax for Creating an Amazon Reservation

POST /api/reservations with a reservationTypeID for Amazon, creates an Amazon
reservation.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

VMware, Inc. 261

Programming Guide

Parameter Description

$token Specifies a valid HTTP bearer token with necessary credentials.

HTTP body The HTTP body describes the reservation to create and calls the
REST API used to create the reservation.
Compose the HTTP body using one of the following methods:
n Copy the HTTP body from the JSON output from this example
and edit the applicable field values to compose the HTTP body
input for the command line.
n Use the API commands in Syntax for Verifying a Reservation
and Getting Reservation Details , remove the appropriate ID
field from the HTTP response, and edit the field values to
compose the HTTP body input for the command line.

Output
The output URL contains the new reservation ID.

Property Description

status When the reservation is successfully created, the HTTP response

status is 201 created.

Header.Location The HTTP response contains a Location attribute that is formatted

as https://$vRA /reservation-service/api/reservations/$reservationId.

$reservationId Specifies the new reservation ID.

Example: curl Command

The following example command creates an Amazon reservation. The HTTP body is included as
part of the command line input.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations -d “
{
"name": "TestEC2Reservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.Amazon",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": "34d2a612-718e-4814-96c5-225f7f5615a6",
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [

],
"alerts": [
{

VMware, Inc. 262

Programming Guide

"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "securityGroups",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
}
]
}
},
{
"key": "loadBalancers",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "ElasticLoadBalancer",
"id": "3",
"label": "test1"
}
]

VMware, Inc. 263

Programming Guide

}
},
{
"key": "locations",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AvailabilityZone",
"id": "10",
"label": "us-east-1a"
}
]
}
},
{
"key": "keyPairs",
"value": {
"type": "string",
"value": "Per Provisioning Group"
}
}
]
}
}”

Example: JSON Output

The following sample location URL is displayed, including the new Amazon reservation ID.

Location: https://$vRA/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-
b583e4c6d085

Copy the output response into an XML editor for use in a future procedure, such as updating or
deleting the reservation.

Syntax for Creating a vCloud Air Reservation

POST /api/reservations with a reservationTypeID for vCloud Air, creates a vCloud Air
reservation.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations

Method Post

VMware, Inc. 264

Programming Guide

Parameter Description

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

HTTP body The HTTP body describes the reservation to create and calls the
REST API used to create the reservation.
Compose the HTTP body using one of the following methods:
n Copy the HTTP body from the JSON output from this example
and edit the applicable field values to compose the HTTP body
input for the command line.
n Update the formatted reservation information to specify the
new information:
n remove the appropriate ID field from the HTTP response
n edit the field values to compose the HTTP body input for
the command line

For information, see Syntax for Verifying a Reservation and

Getting Reservation Details .

Output
The output URL contains the new reservation ID.

Property Description

status When the reservation is successfully created, the HTTP response

status is 201 created.

Header.Location The HTTP response contains a Location attribute that is formatted

as https://$vRA /reservation-service/api/reservations/$reservationId.

$reservationId Specifies the new reservation ID.

Example: curl Command

The following sample command creates a vCloud Air reservation. The HTTP body is included as
part of the command line input.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations -d “
{
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloudAir",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,

VMware, Inc. 265

Programming Guide

"emailBgMgr": true,
"recipients": [

],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",

VMware, Inc. 266

Programming Guide

"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",

VMware, Inc. 267

Programming Guide

"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},

VMware, Inc. 268

Programming Guide

{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}
“

Example: JSON Output

The output response displays the location URL, including the new vCloud reservation ID.

Location: https://$vRA/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-
b583e4c6d085

Copy the output response into an XML editor for use in a future procedure, such as updating or
deleting the reservation.

Syntax for Verifying a Reservation and Getting Reservation Details

GET /api/reservations/{id} retrieves a vRealize Automation reservation. After you create a
reservation, you can use the reservation ID to verify that the reservation exists. You can also use
the ID to get information about the reservation in preparation for updating or deleting it.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/$reservationId
This is the URL that is generated when you create a reservation
using the REST API. See Syntax for Creating a vSphere
Reservation .

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$reservationId Specifies the unique identifier of the reservation to verify. Obtain

the value from the output generated when you created the
reservation. See Create a Reservation.

VMware, Inc. 269

Programming Guide

Output
The command output contains property names and values based on the command input
parameters.

Property Description

status The HTTP response status is 201 created to indicate that the reservation exists.

Header.Location The HTTP response should contain a location attribute, format as https://$vRA /reservation-
service/api/reservations/$reservationId.

$reservationId The HTTP response should contain a location attribute, formatted as https://$vRA /
reservation-service/api/reservations/$reservationId.

Example: curl Command

In the following example, the reservation ID of 94d74105-831a-4598-8f42-efd590fea15c is the
value you obtained when you created the reservation.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c

Example: JSON Output for a vSphere Reservation

The following JSON output is returned based on the command input.

Copy the output response into an XML editor for future step usage.

{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"

VMware, Inc. 270

Programming Guide

},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",

VMware, Inc. 271

Programming Guide

"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},

VMware, Inc. 272

Programming Guide

{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,

VMware, Inc. 273

Programming Guide

"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}

Example: Example Output for a vCloud Reservation

{
"id": "bf922450-d495-460d-9dbf-1c09b0692db2",
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloud",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [

],

VMware, Inc. 274

Programming Guide

"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [

VMware, Inc. 275

Programming Guide

{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},

VMware, Inc. 276

Programming Guide

{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",

VMware, Inc. 277

Programming Guide

"value": 4096
}
}
]
}
}
}
]
}
}

Syntax for Displaying a List of Supported Reservation Types

GET /api/reservations/types displays a list of supported vRealize Automation reservation
types.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/types

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP address
of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output
The command output contains property names and values based on the command input
parameters.

Property Description

Links Species an array of link objects, each of which contains the following parts:

rel Specifies the name of the link.

n Self refers to the object that was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service that determines the other names.

href Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the objects returned in a
pageable list. Each object contains the following information:

@type Contains the ReservationType string.

createdDate Specifies the create date.

lastUpdated Specifies the last update date.

VMware, Inc. 278

Programming Guide

Property Description

version Displays the object version number.

Id Specifies the unique identifier of this resource.

name Specifies the reservation type name.

description Specifies the reservation type description.

category Specifies the reservation category of Virtual, Cloud or Physical.

serviceTypeId Specifies the vRealize Automation service ID.

tenantId This contains a null value.

FormReference Specifies the user interface form reference. This field is valid for user interface elements only.
n type -- user interface form type
n formId -- user interface form ID

SchemaClassId Specifies the schema class ID of the reservation type. Each supported reservation type
contains specific fields. The supported fields are defined in the schema. For details, see
the reservation service schema definitions in the vRealize Automation API Reference in the
vRealize Automation Documentation Center.

alertTypes Contains the alert type list defined in the reservation type:
n createdDate -- Alert type created date
n lastUpdated -- Alert type last updated date
n version -- Alert type version
n id -- Unique identifier of alert type
n name -- Name of alert type
n description -- Long description of alert type
n referenceResourceId -- Unique identifier of reference resource

Metadata Specifies the paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElements: 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

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/types

The following command contains the example bearer token from Syntax for Requesting an HTTP
Bearer Token.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer
MTQxMTY5OTkxODQyNTpkYmZmYjkzZTgzNjdmOGU0NThjZTp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLnZtd2
FyZS5jb206NDhmNGViNzQ3ZjYxY2YxMzdhNDAxOGY2MDAwOTFlZTJiZWI4MmJmZWU5ZTQ0MTI0YWI1M2U4NGNiOTk0

VMware, Inc. 279

Programming Guide

OTJjZjEwNjdhMzdmZTQ5YWMyMzA2NTA5M2UyNzlhMzI2ZGYxZDhlYTgxYmNkNjM5ZTNiNjIyYmEwYTRhOWJiMGE2ZTI="
https://myVRA.eng.mycompany.com/reservation-service/api/reservations/types

Example: JSON Output for a vSphere Reservation

In the following response, there are 8 reservation types. For the vSphere reservation, the
reservation type ID is Infrastructure.Reservation.Virtual.vSphere, and its schema class
ID is Infrastructure.Reservation.Virtual.vSphere.

{
"links": [],
"content": [{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.009Z",
"version": 1,
"id": "Infrastructure.Reservation.Virtual.vSphere",
"name": "vSphere",
"description": "vSphere Reservation",
"category": "Virtual",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Virtual.vSphere.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Virtual.vSphere",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.008Z",
"version": 0,
"id": "d248eeee-238c-4e87-9e95-f263b04d113f",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

VMware, Inc. 280

Programming Guide

Example: JSON Output for a vCloud Air Reservation

In the following response, there are 8 reservation types. For the vCloud Air reservation, the
reservation type ID is Infrastructure.Reservation.Cloud.vCloudAir and its schema class
ID is Infrastructure.Reservation.Cloud.vCloudAir.

{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 1,
"id": "Infrastructure.Reservation.Cloud.vCloudAir",
"name": "vCloud",
"description": "vCloud Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Cloud.vCloudAir.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Cloud.vCloudAir",
"alertTypes": [
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "cd707ad2-d504-43e2-8002-11ee670dcf41",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "ef96fec4-a607-4944-a0af-fbe7df862ee2",
"name": "memory",
"description": null,
"referenceResourceId": "memory"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "043e0815-9f02-4876-b5ce-ddbedabb8ff6",
"name": "cpu",
"description": null,
"referenceResourceId": "cpu"
},
{

VMware, Inc. 281

Programming Guide

"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "77e90acd-93ab-4bbe-853a-b74923dae70a",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}
]
}, //Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Example: JSON Output for an Amazon Reservation

In the following response, there are 8 reservation types. For the Amazon reservation, the
reservation type ID is Infrastructure.Reservation.Cloud.Amazon and its schema class ID
is Infrastructure.Reservation.Cloud.Amazon.

{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.074Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 1,
"id": "Infrastructure.Cloud.Amazon",
"name": "Amazon",
"description": "Amazon Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Cloud.Amazon.form.new"
},
"schemaClassId": "Infrastructure.Cloud.Amazon",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.075Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 0,
"id": "2ef8f47c-045c-4ee4-821d-7b1543ea5f11",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}]

VMware, Inc. 282

Programming Guide

},//Omit 7 reservation types here

],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Updating a Reservation

PUT /api/reservations/{id} updates an existing reservation with a given ID.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/$reservationId

Method Put

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$reservationId Specifies the unique identifier of the reservation to update. For

information about how to obtain the reservation ID, see Syntax for
Displaying a List of Reservations .

HTTP body Contains the JSON information for the reservation, including the
updated data for the parameters that you want to update.
Most of this JSON string information is obtained by displaying the
existing details of the $reservationId. See Syntax for Verifying a
Reservation and Getting Reservation Details . The rest of the JSON
string information is obtained by using an API command to get the
ID of the parameter you want to update.
For example, to update the reservation to use a different
compute resource than the one currently specified, replace the
computeResource value of the exiting reservation with a new
computeResource value in the command's HTTP input.

Output
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

VMware, Inc. 283

Programming Guide

Example: curl Command

The following example command updates the reservation with an ID of
94d74105-831a-4598-8f42-efd590fea15c to use compute resource ID 047e00f5-5424-4ed2-
a751-4a334aeaff54.

curl –X PUT --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c –d
“
{
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["[email protected]",
"[email protected]"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{

VMware, Inc. 284

Programming Guide

"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "TestNetworkProfile"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}

VMware, Inc. 285

Programming Guide

},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",

"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {

VMware, Inc. 286

Programming Guide

"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}

VMware, Inc. 287

Programming Guide

}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”

Example: JSON Output

If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Syntax for Deleting a Reservation

DELETE /api/reservations/{id} deletes an existing reservation with the given ID.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/$reservationId

Method Delete

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$reservationId Specifies the unique identifier of the reservation to delete. For

information about how to obtain the reservation ID, see Syntax for
Displaying a List of Reservations .

Output
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

VMware, Inc. 288

Programming Guide

Example: curl Command

The following example command deletes a reservation with an ID of 94d74105-831a-4598-8f42-
efd590fea15c.

curl –X “Delete” --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c

Example: JSON Output

If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

VMware, Inc. 289

Working with Reservation Policies
9
You use the reservation service to perform a variety of functions, such as creating and updating
reservation policies.

While many functions are stand-alone, some functions rely on the output of others. For example,
to delete a reservation, you must first obtain the ID of the reservation to delete.

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 Working with Reservation Policies

n List Reservation Policies Example

n Create a Reservation Policy Example

n Display a Reservation Policy by ID Example

n Update a Reservation Policy Example

n Deleting a Reservation Policy Example

Prerequisites for Working with Reservation Policies

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.

List Reservation Policies Example

GET /api/reservations/policies lists existing reservation policies. Use this information to
obtain a reservation policy ID in preparation for updating or deleting the reservation policy.

VMware, Inc. 290

Programming Guide

curl Command
List all available reservation policies.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/policies

JSON Output
The following example output lists two reservation policies, named reservationPolicyTest
and reservationPolicyTest2. Use the id value for each reservation policy to update or delete
them. See Update a Reservation Policy Exampleand Deleting a Reservation Policy Example.

{
"links": [],
"content": [{
"@type": "ReservationPolicy",
"id": "8adafb54-4c85-4478-86f0-b6ae80ab5ca4",
"name": "reservationPolicyTest",
"description": "reservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
},
{
"@type": "reservationPolicy",
"id": "fdd9854b-012e-41d7-ad17-fc73d4395714",
"name": "reservationPolicyTest2",
"description": "reservationPolicyDescTest2",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.Storage"
}],
"metadata": {
"size": 0,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/policies

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

VMware, Inc. 291

Programming Guide

Output
The command output contains property names and values based on the command input
parameters.

Property Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel

Specifies the name of the link.

n Self refers to the object which was returned or requested.
n First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n Specifies the application or service that determines the other names.
n href

Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one of the tenant objects returned
in a pageable list. Each tenant object contains the following information:
n @type. Contains the ReservationPolicy string.
n id. Specifies the unique reservation policy ID.
n name. Specifies the reservation policy name.
n description. Specifies the reservation policy description.

reservationPolicyType Specifies the type of reservation policy. Supported vRealize Automation reservation policy
Id types are Reservation.Policy.ComputeResource and Reservation.Policy.Storage.

Metadata Specifies the paging-related data:

n Size. Specifies the maximum number of rows per page.
n totalElements. 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.

Create a Reservation Policy Example

POST /api/reservations/policies creates a reservation policy.

curl Command
The following example command uses the reservation service to create a new reservation policy.

curl -X POST --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/policies -d “
{
"name": "ABXReservationPolicyTest",
"description": "ABXReservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
“

VMware, Inc. 292

Programming Guide

JSON Output
The following example output contains the HTTP body and a location URL. The output URL
contains the new reservation policy ID, for example 5fd2de36-659f-4beb-97af-77d683feb697.

Location:
https://$vRA/reservation-service/api/reservations/policies/
5fd2de36-659f-4beb-97af-77d683feb697

Copy the location URL from this output to an editor for future use, for example for updating or
deleting the reservation policy.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/policies

Method Post

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

HTTP body Describes the reservation policy to create.

n $name - reservation policy name
n $description - reservation policy description

$reservationPolicyTypeId Specifies the reservation policy type ID. The supported

reservation policy types are Reservation.Policy.ComputeResource and
Reservation.Policy.Storage.

Output
The command output contains property names and values based on the command input
parameters.

The output URL contains the new reservation policy ID.

Property Description

status When the reservation policy is successfully created, the HTTP

response status is 201 created.

Header.Location The HTTP response contains a Location attribute that is

format as https://$vRA /reservation-service/api/reservations/policies/
$reservationPolicyId.

$reservationPolicyId Specifies the new reservation policy ID. Obtain this ID by listing your
available reservation policies.

VMware, Inc. 293

Programming Guide

Display a Reservation Policy by ID Example

GET /api/reservations/policies/{id} displays information about a specific reservation
policy with a reservation policy ID.

curl Command
The following example command retrieves information for the reservation policy with an ID of
8adafb54-4c85-4478-86f0-b6ae80ab5ca4.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/policies/8adafb54-4c85-4478-86f0-
b6ae80ab5ca4

JSON Output
The following sample output displays information for the specified reservation policy ID
8adafb54-4c85-4478-86f0-b6ae80ab5ca4.

{
"id": "8adafb54-4c85-4478-86f0-b6ae80ab5ca4",
"name": "reservationPolicyTest",
"description": "reservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/policies/$id

Method Get

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Example: Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

$id Specifies the reservation policy ID.

$name Specifies the reservation policy name.

VMware, Inc. 294

Programming Guide

Parameter Description

$description Specifies the reservation policy description.

$reservationPolicyTypeId Specifies the reservation policy type ID.

Update a Reservation Policy Example

PUT /api/reservations/policies/{id} updates a reservation policy with a reservation
policy ID.

curl Command
The following example command updates the name and description values for the reservation
policy with an ID of 94d74105-831a-4598-8f42-efd590fea15c.

curl –X PUT --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/policies/94d74105-831a-4598-8f42-
efd590fea15c -d “
{
"id": "94d74105-831a-4598-8f42-efd590fea15c",
"name": "ReservationPolicyTestRename",
"description": "ReservationPolicyDescTestRename",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
“

JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/reservation-service/api/reservations/policies/$id

Method Put

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

VMware, Inc. 295

Programming Guide

Parameter Description

$token Specifies a valid HTTP bearer token with necessary credentials.

HTTP body Describes the reservation policy to update.

To obtain the value, query the reservation policy and copy the
response output to an editor for use as the basis of your command
input. See Display a Reservation Policy by ID Example.
n $id - reservation policy ID
n $name - reservation policy name
n $description - reservation policy description
n $reservationPolicyTypeId - reservation policy type ID

The supported reservation policy types

are Reservation.Policy.ComputeResource and
Reservation.Policy.Storage.

Output
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Deleting a Reservation Policy Example

DELETE /api/reservations/policies/{id} deletes a vRealize Automation reservation policy
with a reservation policy ID.

curl Command
The following example command deletes a reservation policy with an ID of
8adafb54-4c85-4478-86f0-b6ae80ab5ca4.

curl –X “Delete” --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/reservation-service/api/reservations/policies/8adafb54-4c85-4478-86f0-
b6ae80ab5ca4

JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 296

Programming Guide

Parameter Description

URL https://$vRA/reservation-service/api/reservations/policies/$id

Method Delete

$vRA Specifies the appliance name and fully qualified domain name, or IP
address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$id Specifies the reservation policy ID. To obtain the reservation policy ID
to delete, see List Reservation Policies Example.

Output
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.

VMware, Inc. 297

Working with Key Pairs
10
You use the keyValuePair data element of the work-item service to list, create, and update key
pairs.

For information about using the vRealize Automation application user interface to work with key
pairs, see the IaaS Configuration documentation.

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 Working with Key Pairs

n Get a Key Pair List Example

n Create a Key Pair Example

n Query a Key Pair Example

n Update a Key Pair Example

n Delete a Key Pair Example

Prerequisites for Working with Key Pairs

Satisfy the following conditions before performing any tasks for this use case.

n Log in to vRealize Automation as 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.

Get a Key Pair List Example

GET /api/keyPairs gets a list of valid key pairs.

VMware, Inc. 298

Programming Guide

curl Command
The following example command gets a list of valid key pairs.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/keyPairs

JSON Output
The following JSON output is returned based on the command input.

{
"links": [

],
"content": [
{
"@type": "KeyPair",
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey": ""
},
{
"@type": "KeyPair",
"id": 27,
"name": "EC2KeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9Up
lO+YKnAcqUSyXB6PQ3I/
NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/
hKsXKbNSJz+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/
7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/
0SNr2yCzsZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ
17jyQD+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/
l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjvyBqof21y6dhGCd1q48Dkd72QCj6g
GV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g+giB9j4VQOMvC/
uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmRt3P09
FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S+Xyzv
FDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx
4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/
MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/
rQSSolcBfVhbejVpbktJo4YKB7dzSDcJTSw99Uve+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9
SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/
17WCu7mQXMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/
kT+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/
dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeqRNjfOOGgdufIvDqmBB/
klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm+DltRM1Nw3o9WAJjQJ
5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/
dJQyibZAg1yDqyI3sIL3CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz+p5JrIb192STI/
PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ+ZaYfxCc1UKO1AYBGS9ARz5OtYQ
U64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s+N61TPQ9HZuof/

VMware, Inc. 299

Programming Guide

c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/
zGgR9yTOeADIXHWsF4lQyai9MnmEaclHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wf
SIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1
TyJaKIFhhqs6bA6/PH+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/
SpOZ5MPnNjRo+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/
PClR46vQ/
3Iyv5pUGPno+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1X
petxvG9d7L1lU/sgCVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
},//Omit 18 more key pairs
],
"metadata": {
"size": 0,
"totalElements": 20,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/iaas-proxy-provider/api/keyPairs

Method Get

$vRA Specifies the appliance name and fully qualified domain name,
or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 300

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or
requested. This parameter does not appear when you
query a single profile.
n First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n Specifies the application or service that determines
the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one

of the tenant objects returned in a pageable list. Each tenant
object can contain the following information:
n @type: Contains the KeyPair string.
n $id: Specifies the unique identifier of the key pair.
n $name: Specifies the unique identifier of the key pair.
n $computeResourceId: Specifies the compute resource ID
that is binded to the key pair.
n $secretKey: Specifies the secret key for the key pair.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single
profile.
n totalPages: Specifies the total number of pages of data
available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single
profile.
n totalPages: Specifies the total number of pages of data
available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Create a Key Pair Example

POST /api/keyPairs creates a key pair.

VMware, Inc. 301

Programming Guide

curl Command
The following example command creates a key pair.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/keyPairs -d
“
{
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9Up
lO+YKnAcqUSyXB6PQ3I/
NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/
hKsXKbNSJz+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/
7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/
0SNr2yCzsZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ
17jyQD+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/
l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjvyBqof21y6dhGCd1q48Dkd72QCj6g
GV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g+giB9j4VQOMvC/
uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmRt3P09
FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S+Xyzv
FDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx
4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/
MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/
rQSSolcBfVhbejVpbktJo4YKB7dzSDcJTSw99Uve+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9
SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/
17WCu7mQXMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/
kT+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/
dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeqRNjfOOGgdufIvDqmBB/
klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm+DltRM1Nw3o9WAJjQJ
5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/
dJQyibZAg1yDqyI3sIL3CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz+p5JrIb192STI/
PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ+ZaYfxCc1UKO1AYBGS9ARz5OtYQ
U64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s+N61TPQ9HZuof/
c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/
zGgR9yTOeADIXHWsF4lQyai9MnmEaclHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wf
SIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1
TyJaKIFhhqs6bA6/PH+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/
SpOZ5MPnNjRo+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/
PClR46vQ/
3Iyv5pUGPno+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1X
petxvG9d7L1lU/sgCVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“

VMware, Inc. 302

Programming Guide

JSON Output
The output returns an empty HTTP response body and the host information and key pair ID in
the header statement.

Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/keyPairs/56

Copy the location URL into a text editor for future use.

Input
Use the supported input parameters to control the command output.

Input Description

URL https://$vRA/iaas-proxy-provider/api/keyPairs

Method Post

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

HTTP Body Contains the HTTP body of the target key pair.

Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

status If the command is successful, the HTTP status is 201

Created.

Header.Location The http response should contain a Location attribute

with the following format.

https://$vRA/iaas-proxy-provider/api/
keyPairs/$keypairID

$keypairID Specifies the unique identifier of the new key pair.

Example: curl Command

curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/keyPairs -d
“
{
"name": "TestKeyPair",

VMware, Inc. 303

Programming Guide

"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9Up
lO+YKnAcqUSyXB6PQ3I/
NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/
hKsXKbNSJz+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/
7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/
0SNr2yCzsZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ
17jyQD+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/
l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjvyBqof21y6dhGCd1q48Dkd72QCj6g
GV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g+giB9j4VQOMvC/
uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmRt3P09
FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S+Xyzv
FDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx
4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/
MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/
rQSSolcBfVhbejVpbktJo4YKB7dzSDcJTSw99Uve+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9
SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/
17WCu7mQXMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/
kT+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/
dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeqRNjfOOGgdufIvDqmBB/
klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm+DltRM1Nw3o9WAJjQJ
5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/
dJQyibZAg1yDqyI3sIL3CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz+p5JrIb192STI/
PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ+ZaYfxCc1UKO1AYBGS9ARz5OtYQ
U64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s+N61TPQ9HZuof/
c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/
zGgR9yTOeADIXHWsF4lQyai9MnmEaclHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wf
SIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1
TyJaKIFhhqs6bA6/PH+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/
SpOZ5MPnNjRo+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/
PClR46vQ/
3Iyv5pUGPno+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1X
petxvG9d7L1lU/sgCVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“

Example: JSON Output

The output returns an empty HTTP response body and the host information and key pair ID in
the header statement.

Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/keyPairs/56

Copy the location URL into a text editor for future use.

Query a Key Pair Example

GET /api/keyPairs/{id} queries a key pair that is available for the vRealize Automation tenant
administrator.

VMware, Inc. 304

Programming Guide

curl Command
The following example command queries a key pair.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/keyPairs/26

JSON Output
The following JSON output is returned based on the command input.

{
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey": ""
}

Input
Use the supported input parameters to control the command output.

Parameters Description

URL https://$vRA/iaas-proxy-provider/api/keyPairs/$ids

Method Get

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

$id: Specifies the unique identifier of the key pair.

Output
The command output contains property names and values based on the command input
parameters.

Parameters Description

$id: Specifies the unique identifier of the key pair.

$name: Specifies the name of the key pair.

$computeResourceId: Specifies the complete resource ID that is bound to the

key pair.

$secretKey: Specifies the secret key for the key pair.

VMware, Inc. 305

Programming Guide

Update a Key Pair Example

PUT /api/KeyPairs/{id} updates an existing key pair using the vRealize Automation REST API.

curl Command
The following example command updates a key pair.

curl –X PUT --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/keyPairs/26 -d “
{
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9Up
lO+YKnAcqUSyXB6PQ3I/
NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/
hKsXKbNSJz+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/
7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/
0SNr2yCzsZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ
17jyQD+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/
l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjvyBqof21y6dhGCd1q48Dkd72QCj6g
GV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g+giB9j4VQOMvC/
uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmRt3P09
FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S+Xyzv
FDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx
4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/
MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/
rQSSolcBfVhbejVpbktJo4YKB7dzSDcJTSw99Uve+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9
SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/
17WCu7mQXMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/
kT+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/
dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeqRNjfOOGgdufIvDqmBB/
klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm+DltRM1Nw3o9WAJjQJ
5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/
dJQyibZAg1yDqyI3sIL3CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz+p5JrIb192STI/
PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ+ZaYfxCc1UKO1AYBGS9ARz5OtYQ
U64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s+N61TPQ9HZuof/
c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/
zGgR9yTOeADIXHWsF4lQyai9MnmEaclHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wf
SIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1
TyJaKIFhhqs6bA6/PH+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/
SpOZ5MPnNjRo+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/
PClR46vQ/
3Iyv5pUGPno+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1X
petxvG9d7L1lU/sgCVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“

VMware, Inc. 306

Programming Guide

JSON Output
The output contains an empty HTTP response body and the following status code.

204 No Content

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/iaas-proxy-provider/api/keyPairs/$id

Method Put

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

HTTP Body Contains the HTTP body that describes the key pair to
update and what to update in the identified key pair.
n $id: Specifies the unique identifier of the key pair.
n $name: Specifies the unique identifier of the key pair.
n $computeResourceId: Specifies the compute resource
ID that is binded to the key pair.
n $secretKey: Specifies the secret key for the key pair.

Output
The command output contains a status statement.

Parameter Description

status If the command is not successful, the HTTP status is 204

No Content.

Delete a Key Pair Example

DELETE /api/keyPairs/{id} deletes a key pair.

curl Command
The following example command deletes a key pair.

curl –X “Delete” --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/keyPairs/26

VMware, Inc. 307

Programming Guide

JSON Output
The output contains an empty HTTP response body and the following status code.

204 No Content

Input
Use the supported input parameters to control the command output.

Input Description

URL https://$vRA/iaas-proxy-provider/api/keyPairs/$id

Method Delete

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

$id: Specifies the unique identifier of the key pair.

Output
The command output contains a status statement.

Parameter Description

status If the command is not successful, the HTTP status is 204

No Content.

VMware, Inc. 308

Working with Network Profiles
11
You use the IaaS proxy provider service and IPAM service to create, list, and update network
profiles.

You can access the following types of network profile by using the same programming calls.
Different types of network profiles contain different fields.

Network
Profile Type Description

External All network profiles use the elements in the object definition for external network. The network
definition specifies the network address configuration for the network. The external network
definition can specify:
n Existing network addresses configured on the vSphere server. They are the external part of the
NAT and routed networks types. An external network profile can define a range of static IP
addresses available on the external network.
n An endpoint that allows access to IP ranges obtained from the supplied VMware internal IPAM
provider or an external IPAM provider solution that you have imported and registered in vRealize
Orchestrator, such as Infoblox IPAM, and existing network address ranges configured by the
IPAM provider software.
An external network profile with a static IP range is a prerequisite for NAT and routed networks.
When you specify a NAT network profile or a Routed network profile, the base object definition for
the external network profile is used and additional definitions for the NAT or Routed network profiles
are required to complete the profile.

NAT An external network that uses network address translation (NAT) to enable one set of IP addresses
for external communication and another set for internal communications. With one-to-one NAT
networks, every virtual machine is assigned an external IP address from the external network profile
and an internal IP address from the NAT network profile. With one-to-many NAT networks, all
machines share a single IP address from the external network profile for external communication.
A NAT network profile defines local and external networks that use a translation table for mutual
communication.

Routed A routed network represents a routable IP space divided across subnets that are linked together
using Distributed Logical Router (DLR). Every new routed network has the next available subnet
assigned to it and is associated with other routed networks that use the same network profile.
The virtual machines that are provisioned with routed networks that have the same routed network
profile can communicate with each other and the external network.
A routed network profile defines a routable space and available subnets.
For more information about Distributed Logical Router, see NSX Administration Guide available as a
selection from the NSX for vSphere product documentation.

VMware, Inc. 309

Programming Guide

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 Working With Network Profiles

n Get a Network Profile List Example

n Create an External Network Profile Without IPAM Example

n Create an External Network Profile Using External IPAM Example

n Query a Network Profile Example

n Update a Network Profile Example

n Delete a Network Profile Example

Prerequisites for Working With Network Profiles

Satisfy the following conditions before performing any tasks for this use case.

n Log in to vRealize Automation as 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.

Get a Network Profile List Example

GET /api/network/profiles returns a page of current network profiles.

curl Command
The following example command returns a list of network profiles.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/network/profiles

JSON Output
The following JSON output is returned based on the command input.

{
"links": [

],
"content": [
{
"@type": "NATNetworkProfile",

VMware, Inc. 310

Programming Guide

"id": "599541aa-ffb0-4a37-9483-4353f3fc6be3",
"name": "NATTest",
"description": "",
"createdDate": "2014-11-11T02:29:09.000Z",
"lastModifiedDate": "2014-11-11T02:29:09.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "9f7d8025-bd4c-4560-9b41-9ce455ee49ae",
"name": "range",
"description": "",
"beginIPv4Address": "10.118.190.110",
"endIPv4Address": "10.118.190.115",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z",
"definedAddresses": [
{
"id": "6e7dc8c3-dc64-4ebd-a282-05852010310f",
"name": null,
"description": null,
"IPv4Address": "10.118.190.111",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "f6802100-1d7e-4f31-bdeb-1b27f7e77766",
"name": null,
"description": null,
"IPv4Address": "10.118.190.115",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "f6deba8c-fbf4-4ea0-9d9c-325e9db2f13e",
"name": null,
"description": null,
"IPv4Address": "10.118.190.114",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "9d5a9d25-26d7-4ce3-93a2-61242a88c5b2",
"name": null,
"description": null,
"IPv4Address": "10.118.190.110",

VMware, Inc. 311

Programming Guide

"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "2b616f1a-dc35-4caa-8ee7-6494ca50db57",
"name": null,
"description": null,
"IPv4Address": "10.118.190.113",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "9dd5d265-ec23-42be-9bdb-734c11b1e315",
"name": null,
"description": null,
"IPv4Address": "10.118.190.112",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},

]
}
],
"profileType": "NAT",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.118.190.230",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": "",
"dhcpStartIPAddress": null,
"dhcpEndIPAddress": null,
"leaseTimeInSeconds": 0
},
{
"@type": "PrivateNetworkProfile",
"id": "594e4016-b067-4d19-aa81-63502675f925",
"name": "privateTest",
"description": "",
"createdDate": "2014-11-11T02:26:44.000Z",
"lastModifiedDate": "2014-11-11T02:26:44.000Z",
"isHidden": false,
"definedRanges": [
{

VMware, Inc. 312

Programming Guide

"id": "8827193e-f1c3-493e-8bcd-1b153f2a5e74",
"name": "range",
"description": "",
"beginIPv4Address": "10.118.190.110",
"endIPv4Address": "10.118.190.112",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z",
"definedAddresses": [
{
"id": "262a4273-1e75-4c23-8fb8-088473521b19",
"name": null,
"description": null,
"IPv4Address": "10.118.190.111",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
{
"id": "7eebd0ad-0dde-4fa1-aad3-750498214caf",
"name": null,
"description": null,
"IPv4Address": "10.118.190.110",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
{
"id": "37ca8368-5d19-4d23-a6b8-7b233bb2320d",
"name": null,
"description": null,
"IPv4Address": "10.118.190.112",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
]
}
],
"profileType": "PRIVATE",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.118.190.230",
"dhcpStartIPAddress": null,
"dhcpEndIPAddress": null,
"leaseTimeInSeconds": 0
},
{
"@type": "RoutedNetworkProfile",
"id": "a3dbfc76-7eab-4c1f-8f59-8fcc0b50ec6c",

VMware, Inc. 313

Programming Guide

"name": "routedTest",
"description": "",
"createdDate": "2014-11-11T02:31:11.000Z",
"lastModifiedDate": "2014-11-11T02:31:11.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "4d9b291a-841f-4f62-b03e-83781133024c",
"name": "Range 1",
"description": "",
"beginIPv4Address": "10.118.183.1",
"endIPv4Address": "10.118.183.254",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:30:34.000Z",
"lastModifiedDate": "2014-11-11T02:30:34.000Z",
"definedAddresses": [

]
}
],
"profileType": "ROUTED",
"subnetMask": "255.255.254.0",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": "",
"baseIP": "10.118.183.1"
},
{
"@type": "ExternalNetworkProfile",
"id": "68b6a183-fc8a-4592-af23-92f8d410ee32",
"name": "externalTest",
"description": "",
"createdDate": "2014-11-11T02:24:07.000Z",
"lastModifiedDate": "2014-11-11T02:24:07.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "3a85a049-522f-4b64-8f60-6e7b252ad204",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.200",
"endIPv4Address": "10.110.183.201",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z",
"definedAddresses": [
{
"id": "f229ea1a-18de-4dae-ae7b-0cec7feaa99b",
"name": null,
"description": null,
"IPv4Address": "10.110.183.201",
"IPSortValue": 0,

VMware, Inc. 314

Programming Guide

"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
{
"id": "cd39e786-6490-4c95-8cf7-d6e3b6a0ba67",
"name": null,
"description": null,
"IPv4Address": "10.110.183.200",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
]
},
{
"id": "67acdc6f-d0b9-4f47-a74b-ea58ff9ce074",
"name": "range2",
"description": "",
"beginIPv4Address": "10.110.183.180",
"endIPv4Address": "10.110.183.183",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z",
"definedAddresses": [
{
"id": "37b5c7d1-b82f-4961-a7cc-0117d3610ed7",
"name": null,
"description": null,
"IPv4Address": "10.110.183.182",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
"id": "43d8bae4-7b78-40d2-a9ef-350d28901c24",
"name": null,
"description": null,
"IPv4Address": "10.110.183.180",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
{
"id": "c270ce8e-a418-4d02-89db-3b84f6816a75",
"name": null,
"description": null,
"IPv4Address": "10.110.183.181",
"IPSortValue": 0,

VMware, Inc. 315

Programming Guide

"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
{
"id": "684bbe43-29ce-4113-92c7-43921c943099",
"name": null,
"description": null,
"IPv4Address": "10.110.183.183",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},

]
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
],
"metadata": {
"size": 0,
"totalElements": 4,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/iaas-proxy-provider/api/network/profiles

Method Get

VMware, Inc. 316

Programming Guide

Parameter Description

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 317

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or
requested. This parameter does not appear when you
query a single profile.
n First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n Specifies the application or service that determines
the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents one

of the tenant objects returned in a pageable list. Each tenant
object can contain the following information:
n @type:

Specifies one of the following network profile type values:

n ExternalNetworkProfile
n NATNetworkProfile
n PrivateNetworkProfile
n RoutedNetworkProfile
n $id:

Specifies the unique network profile identifier.

n $name:

Specifies the network profile name.

n createdDate:

Specifies the date and time that the network profile was
created.
n lastModifiedDate:

Specifies the date and time that the network profile was
last modified.
n isHidden:

Specifies if the network profile is hidden from the vRealize

Automation user interface.
n definedRanges:

Specifies the IP range array that is defined for the

network profile.
n profileType:

Specifies the network profile type as one of the following

types:
n EXTERNAL
n NAT
n ROUTED
n IPAMEndpointId:

VMware, Inc. 318

Programming Guide

Parameter Description

If you are creating or querying an external network profile

that uses extrernal, IPAM , specifies the endpoint ID for
the external IPAM provider. If you are creating a network
profile and the profile does not use external IPAM, code
null for this value.
n subnetMask:

Specifies the subnet mask.

n gatewayAddress:

Specifies the IP address of the network gateway.

n primaryDnsAddress:

Specifies the IP address of the primary DNS server. This

parameter is only available for external, NAT, and routed
network profiles.
n secondaryDnsAddress:

Specifies the IP address of a secondary DNS server. This

parameter is only available for external, NAT, and routed
network profiles.
n dnsSuffix:

Specifies the DNS suffix. This parameter is only available

for external, NAT, and routed network profiles.
n dnsSearchSuffix:

Specifies the DNS search suffix. This parameter is only

available for external, NAT, and routed network profiles.
n primaryWinsAddress:

Specifies the IP address of the primary Wins server. This

parameter is only available for external, NAT, and routed
network profiles.
n secondaryWinsAddress:

Specifies the IP address of secondary Wins server. This

parameter is only available for external, NAT, and routed
network profiles.
n dhcpStartIPAddress:

Specifies the start IP address of the DHCP server. This

parameter is only supported by NAT and private network
profiles.
n dhcpEndIPAddress:

Specifies the end IP address of the DHCP server. This

parameter is only supported by NAT and private network
profiles.
n leaseTimeInSeconds:

Specifies the lease time for the DHCP server. This

parameter is only supported by NAT and private network
profiles.
n baseIP:

VMware, Inc. 319

Programming Guide

Parameter Description

Specifies the base IP address. This parameter is only

supported by routed network profiles.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single
profile.
n totalPages: Specifies the total number of pages of data
available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single
profile.
n totalPages: Specifies the total number of pages of data
available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

Create an External Network Profile Without IPAM Example

POST /api/network/profiles creates an external, NAT, private, or routed network profile.

curl Command
The following example command creates an external network profile without IPAM.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/$networkProfileID -d “
{
"@type": "ExternalNetworkProfile",
"name": "externalTestCreate",
"description": "",
"isHidden": false,
"definedRanges": [
{
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.221",
"endIPv4Address": "10.110.183.240",
"state": "UNALLOCATED"
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",

VMware, Inc. 320

Programming Guide

"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
“

JSON Output
The JSON output consists of a location URL, which points to the newly created network
profile. The output contains an empty HTTP response body and the following or similar header
statement. Copy the location URL into a text editor for future use.

Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/network/profiles/263b80f5-
d34f-47f2-b0b1-5a3db991c2e9

Copy the location URL into a text editor for future use.

Input
Use the supported input parameters to control the command output.

Input Description

URL https://$vRA/iaas-proxy-provider/api/network/profiles

Method Post

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

HTTP Body The HTTP body describes the network profile to create.
Sample HTTP body field values are presented in the
JSON Output section of the Get a Network Profile List
Example topic. Format your HTTP body using this content
as reference.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 321

Programming Guide

Property Description

status If the command is successful, the HTTP status is 201 Created.

Header.Location The HTTP response should contain a Location attribute that

is formatted as https://$vRA/iaas-proxy-provider/api/network/
profiles/$networkProfileID.

$networkProfileID Specifies the unique identifier of the new network profile.

Create an External Network Profile Using External IPAM

Example
POST /api/network/profiles creates a external network profile using external IPAM.

curl Command
The following example command creates an external IPAM profile.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/$networkProfileID -d “

{
"profileType" : "EXTERNAL",
"id" : null,
"@type" : "ExternalNetworkProfile",
"name" : "External IPAM",
"IPAMEndpointId" : "c20f305c-07a5-4ba7-88ac-35da7b9713e0",
"addressSpaceExternalId" : "address-space-4",
"description" : null,
"definedRanges" : [{
"externalId" : "network-1",
"name" : "192.168.1.0/24",
"description" : "Created by vRO package stub workflow",
"state" : "UNALLOCATED",
"beginIPv4Address" : null,
"endIPv4Address" : null
}
]
}

JSON Output
The output contains an empty HTTP response body and the location and network profile ID in
the header statement.

Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/network/profiles/263b80f5-
d34f-47f2-b0b1-5a3db991c2e9

VMware, Inc. 322

Programming Guide

Copy the location URL into a text editor for future use.

Input
Use the supported input parameters to control the command output.

Input Description

URL https://$vRA/iaas-proxy-provider/api/network/profiles

Method Post

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

HTTP Body The HTTP body specifies the information for creating an
external IPAM profile.
n profileType: Specify EXTERNAL for this parameter.
n id: Specifies null.
n name: Specifies the name of the profile.
n IPAMEndpointId: Specifies the endpoint ID for an
external IPAM provider.
n addressSpaceExternalId: Specify the address space of
the IPAM provider. This is represented in the vRealize
Automation UI as Address Space.
n description: Optionally, can specify a description for
the profile. If you do not provide a description, code
"null" for this parameter.
n definedRanges: Specifies parameters that set up
defined address ranges:
n externalId: Specify the address range of the IPAM
provider.

This is the tie between vRealize Automation

and he external IPAM provider. When you edit
a network profile, vRealize Automation pulls
information about the address ranges based on
the external ID.
n name: Optionally, you can specify a descriptive
name for the range.
n description
n state: Specify "UNALLOCATED" for this value.
n beginIPv4Address: Specify "null" for this
parameter.
n endIPv4Address: Specify "null" for this parameter.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 323

Programming Guide

Property Description

status If the command is successful, the HTTP status is 201 Created.

Header.Location The HTTP response should contain a Location attribute that

is formatted as https://$vRA/iaas-proxy-provider/api/network/
profiles/$networkProfileID.

$networkProfileID Specifies the unique identifier of the new network profile.

Query a Network Profile Example

GET /api/network/profiles/{id} queries and displays an external, NAT, or routed network
profile. For example, you can query an external network profile and use it as the basis for
creating a different type of network profile.

curl Command
The following example command queries the existing network profile ID 68b6a183-fc8a-4592-
af23-92f8d410ee32.

curl --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/network/profiles/68b6a183-fc8a-4592-af23-92f8d410ee32

JSON Output
The following JSON output is returned based on the command input.

{
"@type": "ExternalNetworkProfile",
"id": "68b6a183-fc8a-4592-af23-92f8d410ee32",
"name": "externalTest",
"description": "",
"createdDate": "2014-11-11T02:24:07.000Z",
"lastModifiedDate": "2014-11-11T02:24:07.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "3a85a049-522f-4b64-8f60-6e7b252ad204",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.200",
"endIPv4Address": "10.110.183.201",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z",
"definedAddresses": [
{
"id": "f229ea1a-18de-4dae-ae7b-0cec7feaa99b",
"name": null,

VMware, Inc. 324

Programming Guide

"description": null,
"IPv4Address": "10.110.183.201",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
{
"id": "cd39e786-6490-4c95-8cf7-d6e3b6a0ba67",
"name": null,
"description": null,
"IPv4Address": "10.110.183.200",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/iaas-proxy-provider/api/network/profiles/$id

Method Get

$vRA Specifies the appliance name and fully qualified domain name,
or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

$id: Specifies the unique network profile identifier.

VMware, Inc. 325

Programming Guide

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 326

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or
requested. This 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.

Content Specifies an array of data rows, each of which represents

one of the objects returned in a pageable list. Each object
contains the following information:
n @type:

Specifies one of the following network profile type values:

n ExternalNetworkProfile
n NATNetworkProfile
n RoutedNetworkProfile
n $id:

Specifies the unique network profile identifier.

n $name:

Specifies the network profile name.

n createdDate:

Specifies the date and time that the network profile was
created.
n lastModifiedDate:

Specifies the date and time that the network profile was
last modified.
n isHidden:

Specifies if the network profile is hidden from the vRealize

Automation user interface.
n definedRanges:

Specifies the IP range array that is defined for the

network profile.
n profileType:

Specifies the network profile type as one of the following

types:
n EXTERNAL
n NAT
n ROUTED
n IPAMEndpointId

VMware, Inc. 327

Programming Guide

Parameter Description

If you are querying an external network profile that uses

external IPAM, shows the endpoint ID for the external
IPAM provider.
n subnetMask:

Specifies the subnet mask.

n gatewayAddress:

Specifies the IP address of the network gateway.

n primaryDnsAddress:

Specifies the IP address of the primary DNS server. This

parameter is only available for external, NAT, and routed
network profiles.
n secondaryDnsAddress:

Specifies the IP address of a secondary DNS server. This

parameter is only available for external, NAT, and routed
network profiles.
n dnsSuffix:

Specifies the DNS suffix. This parameter is only available

for external, NAT, and routed network profiles.
n dnsSearchSuffix:

Specifies the DNS search suffix. This parameter is only

available for external, NAT, and routed network profiles.
n primaryWinsAddress:

Specifies the IP address of the primary Wins server. This

parameter is only available for external, NAT, and routed
network profiles.
n secondaryWinsAddress:

Specifies the IP address of secondary Wins server. This

parameter is only available for external, NAT, and routed
network profiles.
n dhcpStartIPAddress:

Specifies the start IP address of the DHCP server. This

parameter is only supported by NAT network profiles.
n dhcpEndIPAddress:

Specifies the end IP address of the DHCP server. This

parameter is only supported by NAT network profiles.
n leaseTimeInSeconds:

Specifies the lease time for the DHCP server. This

parameter is only supported by NAT network profiles.
n baseIP:

Specifies the base IP address. This parameter is only

supported by routed network profiles.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.

VMware, Inc. 328

Programming Guide

Parameter Description

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.

Update a Network Profile Example

PUT /api/network/profiles/{id} updates an existing network profile.

curl Command
The following example command updates the network profile with an ID of 263b80f5-d34f-47f2-
b0b1-5a3db991c2e9.

curl –X PUT --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/network/profiles/263b80f5-d34f-47f2-b0b1-5a3db991c2e9 -d
“
{
"@type": "ExternalNetworkProfile",
"id": "263b80f5-d34f-47f2-b0b1-5a3db991c2e9",
"name": "externalTestEdit",
"description": "",
"createdDate": "2014-11-16T09:11:55.000Z",
"lastModifiedDate": "2014-11-16T09:11:55.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "ce266d4c-5fbb-47a9-a391-c77444c20b09",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.239",
"endIPv4Address": "10.110.183.240",
"state": "UNALLOCATED",
"createdDate": "2014-11-16T09:11:55.000Z",
"lastModifiedDate": "2014-11-16T09:11:55.000Z",
"definedAddresses": [

VMware, Inc. 329

Programming Guide

]
}
],
"profileType": "EXTERNAL",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
“

JSON Output
The output contains an empty HTTP response body and the following status code.

204 No Content

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/iaas-proxy-provider/api/network/profiles/$id

Method Put

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

Output
The command output contains a status statement.

Parameter Description

status If the command is not successful, the HTTP status is 204

No Content.

Delete a Network Profile Example

DELETE /api/network/profiles/{id} deletes an existing network profile corresponding to its
unique ID.

VMware, Inc. 330

Programming Guide

curl Command
The following example command deletes a network profile with an ID of 263b80f5-d34f-47f2-
b0b1-5a3db991c2e9.

curl –X “Delete” --insecure -H "Accept:application/json"

-H "Authorization: Bearer $token"
https://$vRA/iaas-proxy-provider/api/network/profiles/263b80f5-d34f-47f2-b0b1-5a3db991c2e9

JSON Output
The output contains an empty HTTP response body and the following status code.

204 No Content

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/iaas-proxy-provider/api/network/
profiles/$id

Method Delete

$vRA Specifies the appliance name and fully qualified domain

name, or IP address of the vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary

credentials.

$id: Specifies the unique network profile identifier.

Output
The command output contains a status statement.

Parameter Description

status If the command is not successful, the HTTP status is 204

No Content.

VMware, Inc. 331

Getting a List of Available IP
Ranges 12
After creating a network profile, the administrator imports IP address ranges into vRealize
Automation from a registered IP address management (IPAM) service provider.

This chapter includes the following topics:

n Get a List of Available IP Ranges for an IPAM Provider

Get a List of Available IP Ranges for an IPAM Provider

GET /api/providers/{providerEnpointId}/ip-ranges queries a specified IPAM provider
endpoint for a list of the available IP address ranges configured on the IPAM provider device.

Prerequisites

n Log in to vRealize Automation as 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.

n Obtain the endpoint ID for the external IPAM provider device you want to query.

Procedure

1 Use the following command to query an IPAM endpoint for a list of configured IP address
ranges.

curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token" https://

$vRA/ ipam-service/api/providers/<ENDPOINT_ID>/ip-ranges

ENDPOINT_ID is the endpoint ID of the external IPAM service provider.

2 Examine the response for a list of the available IP address ranges configured on the IPAM
provider device.

{
"links": [],
"content": [
{

VMware, Inc. 332

Programming Guide

"@type": "IPRange",
"id": null,
"name": "192.168.0.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 0"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.0.0",
"subnetPrefixLength": 24,
"externalId": "network-0",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.1.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",

VMware, Inc. 333

Programming Guide

"value": "Building 1"

}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.1.0",
"subnetPrefixLength": 24,
"externalId": "network-1",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.2.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 2"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}

VMware, Inc. 334

Programming Guide

]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.2.0",
"subnetPrefixLength": 24,
"externalId": "network-2",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.3.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 3"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.3.0",
"subnetPrefixLength": 24,
"externalId": "network-3",

VMware, Inc. 335

Programming Guide

"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.4.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 4"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.4.0",
"subnetPrefixLength": 24,
"externalId": "network-4",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",

VMware, Inc. 336

Programming Guide

"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.5.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 5"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.5.0",
"subnetPrefixLength": 24,
"externalId": "network-5",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.6.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {

VMware, Inc. 337

Programming Guide

"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 6"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.6.0",
"subnetPrefixLength": 24,
"externalId": "network-6",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.7.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 7"
}
},
{
"key": "City",

VMware, Inc. 338

Programming Guide

"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.7.0",
"subnetPrefixLength": 24,
"externalId": "network-7",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.8.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 8"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,

VMware, Inc. 339

Programming Guide

"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.8.0",
"subnetPrefixLength": 24,
"externalId": "network-8",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.9.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 9"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.9.0",
"subnetPrefixLength": 24,
"externalId": "network-9",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,

VMware, Inc. 340

Programming Guide

"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.10.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 10"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.10.0",
"subnetPrefixLength": 24,
"externalId": "network-10",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{

VMware, Inc. 341

Programming Guide

"@type": "IPRange",
"id": null,
"name": "192.168.11.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 11"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.11.0",
"subnetPrefixLength": 24,
"externalId": "network-11",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.12.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",

VMware, Inc. 342

Programming Guide

"value": "Building 12"

}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.12.0",
"subnetPrefixLength": 24,
"externalId": "network-12",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.13.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 13"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}

VMware, Inc. 343

Programming Guide

]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.13.0",
"subnetPrefixLength": 24,
"externalId": "network-13",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.14.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 14"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.14.0",
"subnetPrefixLength": 24,
"externalId": "network-14",

VMware, Inc. 344

Programming Guide

"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.15.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 15"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.15.0",
"subnetPrefixLength": 24,
"externalId": "network-15",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",

VMware, Inc. 345

Programming Guide

"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.16.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 16"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.16.0",
"subnetPrefixLength": 24,
"externalId": "network-16",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.17.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {

VMware, Inc. 346

Programming Guide

"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 17"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.17.0",
"subnetPrefixLength": 24,
"externalId": "network-17",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.18.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 18"
}
},
{
"key": "City",

VMware, Inc. 347

Programming Guide

"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.18.0",
"subnetPrefixLength": 24,
"externalId": "network-18",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.19.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 19"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,

VMware, Inc. 348

Programming Guide

"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.19.0",
"subnetPrefixLength": 24,
"externalId": "network-19",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
}
],
"metadata": {
"size": 0,
"totalElements": 20,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

VMware, Inc. 349

Importing and Exporting Content
13
You use the content management service to import and export content such as blueprints,
software components, and other artifacts between vRealize Automation systems.

vRealize Automation customers often experiment with system artifacts in their development or
staging deployments. When ready, they can use the content management service to move the
artifacts to production environments or between different tenants.

Import and export has some known constraints.

Table 13-1. Import and Export Considerations

Issue Consideration

Approval policies and entitlements You cannot import or export approval policies or
entitlements.

Required secure property values If you export a blueprint that has the option --secure
true, the values are removed during the export process.
If the secure property is marked required, the import
process will fail unless you update the package with the
secure property values before you import it.

Draft state You cannot import or export any content that is in a draft
state.

For consistency with other service examples, each example lists a curl command. However the
content management service provides a convenient mechanism for moving artifacts between
systems using the CloudClient interface. With CloudClient, there is no need to set heading
values, including the Authorization header. The $vRA//$servicename/api is eliminated from the
URL and the service name becomes a separate parameter. For example, consumer/entitled
CatalogItems/{id}/request/template. See Using vRealize CloudClient.

XaaS services are integrated with the content management service, and all commands that work
with other content types also work with XaaS content to migrate XaaS content into vRealize
Automation.

The same set prerequisites apply to each example.

This chapter includes the following topics:

n Understanding Blueprint Schema

n Prerequisites for Importing and Exporting Content

VMware, Inc. 350

Programming Guide

n List Supported Content Types Example

n List Available Content Example

n Filter Content by Content Type Example

n Create a Package for Export Example

n List Packages in the Content Service Example

n Export a Package Example

n Validate a Content Bundle Before Importing example

n Import a Package Example

n Export XaaS Content Example

n Import XaaS Content Example

Understanding Blueprint Schema

Users who wish to edit blueprints when exporting them to a deployment may need to
understand the blueprint schema.

Simple Blueprint Structure

The following is an example of a simple blueprint. Note that this example includes line number
that are referenced later in this topic.

1 id: Blueprint.CentOSAndApache
2. name: CentOSAndApache
3. status: PUBLISHED
4. components:
5. web:
6. type: Infrastructure.CatalogItem.Machine.Virtual.vSphere
7. data:
8. cpu: 1
9. memory:
10. min: 512
11. max: 8192
12. os_type: Linux
13. os_distribution: rhel
14. action: LinkedClone
15. archive_days: 1
16. provisioning_workflow: {id: CloneWorkflow}
17. lease_days: 3
18. source_machine_name: cbp_centos_63_x86
19. cost_center: sales
20. _cluster: 2
21. apache:
22. type: Software.Apache
23. data:

VMware, Inc. 351

Programming Guide

24. host: '${_resource~web}'

25. http_port: 8080

Each of these lines plays an important role in the blueprint structure.

n Lines 1 - 4 represent possible top level blueprint fields that provide identifying information.
The only other possible field is description. The semantics of these fields is straightforward,
but you can refer to java.classBlueprintDocument for more information.

n Line 4 represents the blueprint components. Each key under components is the ID of the
component that must be unique under the current blueprint.

n Lines 5 - 19 correspond to the Web component. The following appear under any component
data:

n The key type is mandatory and must refer to the component type on which the current
component is based.

n The key dependsOn is optional and contains the list of component IDs current component
depends on. Component dependencies are extracted automatically based on property
binding expressions. In most cases, you do not need to explicitly specify component
dependencies.

n The key data defines the component configuration and appears under all component
data.

n Key is the name of the property or field of that component. This can be a property
defined in the corresponding component type.

Property or field option Example

A property defined in the corresponding cpu

component type

A reserved property _cluster

Custom property cost_center

n The value of the field can be directly defined as in cpu: 2, or you can defines its
constraints, as done for the memory field in the example.

n Line 16 shows how to specify and entity reference field. The available sub-keys are id and
label.

n Line 24 depicts several things.

n ${<field_path>} provides a way to express the value of a field to come from another
field.

n _resource is a reserved field ID that captures the output of entire blueprint. Output from
each component is exposed under the same key as component ID. So in this case, host
value is set to the output of the web component thus saying the apache component needs
to be hosted on machine provisioned from the web component.

VMware, Inc. 352

Programming Guide

n Whenever a property binding refers to output of some other component, it creates an

implicit dependency between components.

Blueprint Constraints
To define constraints in any blueprint field. create a new hierarchy or level in YAML, and use any
of the keys below to define constraints and their values.

ID or Key Corresponding CAFE Constraint Description

default com.vmware.vcac.platform.content.facets.DefaultValueB Specifies the value for a field.

ehavior

fixed com.vmware.vcac.platform.content.facets.FixedValueCo Specifies the value for a field that

nstraint cannot be overridden at request or
reuse time.

mandatory com.vmware.vcac.platform.content.facets.MandatoryCo Indicates that the field is mandatory.

nstraint

min com.vmware.vcac.platform.content.facets.MinValueCons Indicates the minimum value for a

traint numeric field.

max com.vmware.vcac.platform.content.facets.MaxValueCon Indicates the maximum value for a

straint numeric field.

minLength com.vmware.vcac.platform.content.facets.MinLengthCon Indicates the minimum length for a

straint string field.

maxLength com.vmware.vcac.platform.content.facets.MaxLengthCo Indicates the maximum length for a

nstraint string field.

minCardinality com.vmware.vcac.platform.content.facets.MinLengthCon Indicates the minimum cardinality for

straint an array field.

maxCardinality com.vmware.vcac.platform.content.facets.MaxCardinalit Indicates the maximum cardinality for

yConstraint an array field.

increment com.vmware.vcac.platform.content.facets.IncrementBeh Indicates the step or increment for a

avior numeric field.

regex com.vmware.vcac.platform.content.facets.RegexpConstr Indicates the valid regex for a string

aint field.

secured com.vmware.vcac.platform.content.facets.EncryptedBeh Indicates whether the field is to be

avior treated securely.

valid_values com.vmware.vcac.platform.content.fields.PermissibleVal Defines the valid values for a field.

ueList

Blueprint Components
The blueprint schema can include multiple components each with a corresponding API service.

Component Responsible Service

VM node IaaS

Network and Security Network

VMware, Inc. 353

Programming Guide

Component Responsible Service

Software components Software

Nested blueprints Blueprint

XaaS blueprints XaaS

Containers IaaS

Configuration Management Config Management

Other Components Other Component

For detailed information regarding each component and its corresponding service, see the
Swagger specification available as https://$vRA/component-registry/services/docs#!/
apis where $vRA denotes an instance of vRealize Automation.

Prerequisites for Importing and Exporting Content

Satisfy the following conditions before performing any tasks for this use case.

n Log in to vRealize Automation with an appropriate role. For example: Software Architect,
Application Architect, Infrastructure Architecture or some combination of these depending on
the need.

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.

List Supported Content Types Example

GET /api/provider/contenttypes displays a list of supported content types.

Supported Content Types

A content type describes content that you can import or export using the content management
service. Content types contain metadata about the content provider and the content itself, such
as type information or service type ID. Usually the content provider supplies this information.

The REST API supports import and export of the following registered content types:

n composite-blueprint - the content type corresponding to the composite blueprint

n software-component - the content type corresponding to the software component

n property-group - the content type corresponding to the property groups

n property-definition - the content type corresponding to the property definitions

VMware, Inc. 354

Programming Guide

Everything as a Service (XaaS) content types:

n XaaS-blueprint

n XaaS-resource-action

n XaaS-resource-type

n XaaS-resource-mapping

curl Command
The following example command returns a list of supported content types.

$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer $token"

https://$vRA/content-management-service/api/provider/contenttypes

JSON Output
The following JSON output is returned based on the command input.

{
"links": [
],
"content": [
{
"@type": "ContentType",
"id": "property-group",
"name": "Property Group",
"description": "Content type corresponding to the property groups.",
"classId": "PropertyGroup",
"serviceTypeId": "com.vmware.csp.core.properties.service"
},
{
"@type": "ContentType",
"id": "property-definition",
"name": "Property Definition",
"description": "Content type corresponding to the property definitions.",
"classId": "PropertyDefinition",
"serviceTypeId": "com.vmware.csp.core.properties.service"
},
{
"@type": "ContentType",
"id": "composite-blueprint",
"name": "Composite Blueprint Content Type",
"description": "The content type corresponding to the composite blueprint",
"classId": "Composite.Blueprint",
"serviceTypeId": "com.vmware.csp.component.cafe.composition"
},
{
"@type": "ContentType",
"id": "asd-blueprint",
"name": "{com.vmware.csp.core.designer.service@service.blueprint.content.type.name}",
"description":
"{com.vmware.csp.core.designer.service@service.blueprint.content.type.description}",

VMware, Inc. 355

Programming Guide

"classId": "asdServiceBlueprint",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "asd-resource-action",
"name": "{com.vmware.csp.core.designer.service@resource.action.content.type.name}",
"description":
"{com.vmware.csp.core.designer.service@resource.action.content.type.description}",
"classId": "asdResourceAction",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "asd-resource-type",
"name": "{com.vmware.csp.core.designer.service@resource.type.content.type.name}",
"description":
"{com.vmware.csp.core.designer.service@resource.type.content.type.description}",
"classId": "asdResourceType",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "asd-resource-mapping",
"name": "{com.vmware.csp.core.designer.service@resource.mapping.content.type.name}",
"description":
"{com.vmware.csp.core.designer.service@resource.mapping.content.type.description}",
"classId": "asdResourceMapping",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "software-component",
"name": "Software Component Content Type",
"description":
"{com.vmware.csp.component.software.service@software.component.content.type.description}",
"classId": "softwareComponentType",
"serviceTypeId": "com.vmware.csp.component.software.service"
}
],
"metadata": {
"size": 20,
"totalElements": 9,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Input
Use the supported input parameters with your query URL to control command output. .

VMware, Inc. 356

Programming Guide

Name Description Type

page Page Number. Default is 1. Query

limit Number of entries per page. Default is 20. Query

$orderby Multiple comma-separated properties sorted in ascending or descending order. Query

$top The number of returned entries from the top of the response (total number per page in Query
relation to skip).

$skip The number of entries to skip. Query

$filter Boolean expression for whether a particular entry should be included in the response. Query

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 357

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains

the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single profile.
n First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n Specifies the application or service that
determines the other names.
n href: Specifies the URL that produces the result.

Content n id: The unique identifier for the content. This is also
used as a folder name to group similar content
artifacts.
n name: The name of a given content type provided in
localized message key form.
n description: Additional information describing the
content type.
n classId: The class identifier associated with a content
type.
n serviceTypeId: The service ID for the given content
type.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per
page.
n totalElement: Specifies the number of rows returned.
This parameter is not output when you query for a
single profile.
n totalPages: Specifies the total number of pages of
data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per
page.
n totalElement: Specifies the number of rows returned.
This parameter is not output when you query for a
single profile.
n totalPages: Specifies the total number of pages of
data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

List Available Content Example

GET /api/contents lists the content that is available for export on your vRealize Automation
deployment. Content is some artifact, entity or information that provides value to a user in a

VMware, Inc. 358

Programming Guide

specific context. Content can be represented in a file in different formats, such as XML, JSON, or
a package of files.

curl Command
The following command displays a list of all available content in your vRealize Automation
deployment.

$curl --insecure -s -H "Content-Type: application/json"-H "Authorization: Bearer $token"

https://$vRA/content-management-service/api/contents

JSON Output
The output includes published artifacts such as blueprints, software, and properties.

{
"links": [],
"content": [
{
"@type": "Content",
"id": "6ba58cb4-257d-4833-b2dc-f090f92f86be",
"contentId": "3482e3a7-c6c2-4372-b8e1-0db517b93406",
"name": "Echo String",
"description": null,
"contentTypeId": "asd-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T19:14:54.899Z",
"lastUpdated": "2015-08-18T19:14:54.899Z",
"version": 0
},
{
"@type": "Content",
"id": "079cc912-b870-4f56-a1c3-91905526b09d",
"contentId": "NicksBP",
"name": "Nick's BP",
"description": "Nick's BP",
"contentTypeId": "composite-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T20:14:57.299Z",
"lastUpdated": "2015-08-18T20:14:57.299Z",
"version": 0
},
{
"@type": "Content",
"id": "9795e97f-7025-44f9-9a57-f59242a7775d",
"contentId": "de81f329-cb72-4099-b831-309db708833b",
"name": "TestMapping",

VMware, Inc. 359

Programming Guide

"description": null,
"contentTypeId": "asd-resource-mapping",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T20:53:25.062Z",
"lastUpdated": "2015-08-18T20:53:25.062Z",
"version": 0
},
{
"@type": "Content",
"id": "3922fda1-b5fd-4c51-997d-5f803ec6fb6e",
"contentId": "e8ae6093-18a9-4ec9-a415-1ef850f243f9",
"name": "CustomRes",
"description": null,
"contentTypeId": "asd-resource-type",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T20:56:11.052Z",
"lastUpdated": "2015-08-18T20:56:11.052Z",
"version": 0
},
{
"@type": "Content",
"id": "4754ad69-a6a7-447f-96de-2ed6fa260f7c",
"contentId": "Software.Apache_LB",
"name": "Apache_LB",
"description": "Apache 2.2 The Apache HTTP Server is an open-source HTTP server for
modern operating systems including UNIX, Microsoft Windows, Mac OS/X and Netware. The goal
of this project is to provide a secure, efficient and extensible server that provides HTTP
services observing the current HTTP standards. Apache has been the most popular web server on
the Internet since April of 1996.",
"contentTypeId": "software-component",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T21:31:43.094Z",
"lastUpdated": "2015-08-18T21:31:44.133Z",
"version": 1
},
{

Input
Use the supported input parameters with your query URL to control command output.

VMware, Inc. 360

Programming Guide

Name Description Type

page Page Number. Default is 1. Query

limit Number of entries per page. Default is 20. Query

$orderby Multiple comma-separated properties sorted in ascending or descending order. Query

$top The number of returned entries from the top of the response (total number per page in Query
relation to skip).

$skip The number of entries to skip. Query

$filter Boolean expression for whether a particular entry should be included in the response. Query

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 361

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains

the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single profile.
n First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n Specifies the application or service that
determines the other names.
n href: Specifies the URL that produces the result.

Content Specifies an array of data rows, each of which represents

one of the objects returned in a pageable list.
n id: Specifies the unique identifier for the content. This
is also used as a folder name to group similar content
artifacts.
n contentId: The human readable immutable user or
provider supplied content ID.
n name: Specifies the name of a given content type
provided in localized message key form.
n description: Specifies additional information describing
the package.
n contentTypeId: Identifies the nature of the content.
n mimeType: Identifies the mime type.
n tenantId: The ID of the tenant associated with the
package. Used to enforce ownership.
n subtenantId: (Optional) The ID of the sub tenant or
business group associated with the package.
n dependencies: Represents the dependencies of the
content unit in the form of content IDs.
n createdDate: The creation date of the content.
n lastUpdated: The date on which the content was last
updated.
n version: The version identifier of the content.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per
page.
n totalElement: Specifies the number of rows returned.
This parameter is not output when you query for a
single profile.
n totalPages: Specifies the total number of pages of
data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per
page.

VMware, Inc. 362

Programming Guide

Parameter Description

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.

Filter Content by Content Type Example

GET /api/provider/contenttypes with parameters to filter a list of returned content type
items.

curl Command
The following command filters content by the contentTypeId named composite-blueprint.

$curl --insecure -s -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA/content-management-service/api/contents?
%24filter=contentTypeId+eq+%27composite-blueprint%27

JSON Output
In this example, the returned IDs correspond to composite blueprints that meet the filtering
criteria.

{
"links": [],
"content": [
{
"@type": "Content",
"id": "9b348c29-88ff-4fa8-b93e-f80bc7c3e723",
"contentId": "vSphere",
"name": "vSphere",
"description": "vSphere",
"contentTypeId": "composite-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-04T14:46:54.201Z",
"lastUpdated": "2015-08-04T16:59:30.488Z",
"version": 1
},
{
"@type": "Content",
"id": "968ae331-1ef2-44f8-bdc5-dfc2be78ca2f",
"contentId": "Amazon",
"name": "Amazon",

VMware, Inc. 363

Programming Guide

"description": "Amazon",
"contentTypeId": "composite-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [
"9e2005c3-c56e-48d0-801c-be36851f2b08"
],
"createdDate": "2015-08-04T20:47:20.308Z",
"lastUpdated": "2015-08-04T20:47:20.308Z",
"version": 0
}
],
"metadata": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Input

Output
The command output contains property names and values based on the command input
parameters.

Create a Package for Export Example

POST /api/packages creates a package for export use.

Creating a Package with Content

n For import or export purposes you must create a package to contain the desired content.

n The package is a logical unit that enables you to piece together different content elements.

n You can add multiple content IDs to the package.

n Provide the input as an array with comma-separated content IDs.

n To obtain the IDs of content that is available for export, you use GET /api/contents.
See List Available Content Example.

A package represents an entity that you can export or import via the content management
service. A set of references to the content instances can be bundled together as a package.

VMware, Inc. 364

Programming Guide

curl Command
The following command creates a package named Demo Package with a single content ID of
9b348c29-88ff-4fa8-b93e-f80bc7c3e723.

$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer

$token" https://$vRA/content-management-service/api/packages -d'{"name" : "Demo Package",
"description" : "Package for demo purposes", "contents" : ["9b348c29-88ff-4fa8-b93e-
f80bc7c3e723" ]}'

JSON Output
The JSON output is a URL for the created package.

Input
Parameter Description

createdDate The package creation date.

lastUpdated The date when the package was last updated.

version The package version identifier.

tenantId The ID of the tenant associated with the package. Used to

enforce ownership.

subTenantId (Optional) The ID of the sub tenant or business group

associated with the package

id Specifies the unique identifier for the content. This is also

used as a folder name to group similar content artifacts.

name Specifies the name of a given content type provided in

localized message key form.

description Specifies additional information describing the package.

contents Collection of references that form the contents of the

package.

Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

createdDate The package creation date.

lastUpdated The date when the package was last updated.

version The package version identifier.

tenantId The ID of the tenant associated with the package. Used to

enforce ownership.

VMware, Inc. 365

Programming Guide

Parameter Description

subTenantId (Optional) The ID of the sub tenant or business group

associated with the package

id Specifies the unique identifier for the content. This is also

used as a folder name to group similar content artifacts.

name Specifies the name of a given content type provided in

localized message key form.

description Specifies additional information describing the package.

contents Collection of references that form the contents of the

package.

List Packages in the Content Service Example

GET /api/packages lists the packages within the content service. Use this command to confirm
the contents of a created package.

curl Command
The following command lists the packages within the content service.

$curl --insecure -s -H"Content-Type: application/json" -H "Authorization: Bearer

$token"https://$vRA/content-management-service/api/packages

JSON Output
The following output lists all packages within the content service.

{
"links": [
],
"content": [
{
"@type": "Package",
"createdDate": "2015-08-04T22:22:53.490Z",
"lastUpdated": "2015-08-04T22:22:53.490Z",
"version": 0,
"id": "54f627bb-2277-48af-9fa0-7d7366b498f3",
"name": "Demo Package",
"description": "Package for demo purposes",
"contents": [
"9b348c29-88ff-4fa8-b93e-f80bc7c3e723"
],
"tenantId": "qe",
"subTenantId": null
}
],
"metadata": {
"size": 20,

VMware, Inc. 366

Programming Guide

"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Input
You must provide the appropriate request parameters to list packages within the content service.

Name Description Type

page Page Number. Default is 1. Query

limit Number of entries per page. Default is 20. Query

$orderby Multiple comma-separated properties sorted in ascending or descending order. Query

$top The number of returned entries from the top of the response (total number per page in Query
relation to skip).

$skip The number of entries to skip. Query

$filter Boolean expression for whether a particular entry should be included in the response. Query

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 367

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains

the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single profile.
n First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n Specifies the application or service that
determines the other names.
n href: Specifies the URL that produces the result.

Content n createdDate: The creation date of the content.

n lastUpdated: The date on which the content was last
updated.
n version: The version identifier of the content.
n id: Specifies the unique identifier for the content. This
is also used as a folder name to group similar content
artifacts.
n contentId: The human readable immutable user or
provider supplied content ID.
n name: Specifies the name of a given content type
provided in localized message key form.
n description: Specifies additional information describing
the package.
n contentTypeId: The unique identifier of the
contentType.
n mimeType: The mime type file identifier.
n tenantId: The ID of the tenant associated with the
package. Used to enforce ownership.
n subtenantId: (Optional) The ID of the sub tenant or
business group associated with the package.
n dependencies: These represent the content unit
dependencies in the form of content IDs.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per
page.
n totalElement: Specifies the number of rows returned.
This parameter is not output when you query for a
single profile.
n totalPages: Specifies the total number of pages of
data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.
n Size: Specifies the maximum number of rows per
page.
n totalElement: Specifies the number of rows returned.
This parameter is not output when you query for a
single profile.

VMware, Inc. 368

Programming Guide

Parameter Description

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.

Export a Package Example

GET /api/packages/{id} exports a package as a .zip file.

curl Command
The following command exports a package as a .zip file.

$curl --insecure -s -H "Accept: application/zip" -H "Authorization: Bearer $token"

https://$vRA/content-management-service/api/packages/54f627bb-2277-48af-9fa0-7d7366b498f3-o
package.zip

JSON Output
The export command returns a message that indicates whether or not the package was
exported. A successful export produces a package.zip exported to the specified location. The
returned message is '200 - Successes' with the Package or 404 - 'Not Found' if it does not find
a package with provided ID.

Input
The query URL for the export command must specify the ID of the package to export.

Table 13-2. Export Query URL Parameters

Name Description Type

id The identifier of the package Path

secureValueFormat The format in which secure values should be sent. This Query
parameter is optional and defaults to "BLANKOUT".

Output
The output of this command is a .zip file.

Validate a Content Bundle Before Importing example

POST /api/packages/validate validates a content bundle before importing to a critical
system. A best practice is to validate all packages before importing into to any system.

VMware, Inc. 369

Programming Guide

curl Command
The following command validates a content bundle prior to importing it. This example uses
the DukesBankApp.zip file which is provided on the vRealize Automation virtual appliance.
You can copy the file from /usr/lib/vcac/tools/initial-config/sample-oob-content/
DukesBankApp.zip using WinSCP (Windows) or scp (Mac).

$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"

https://$vRA/content-management-service/api/packages/validate -F "[email protected]"

JSON Output
The validation output displays the validation status of each content item within the bundle.

{
"contentImportStatus": "SUCCESS",
"contentImportResults": [
{
"contentId": "Apache_LB",
"contentName": "Apache_LB",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "MySql",
"contentName": "MySql",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "JBossAppServer",
"contentName": "JBossAppServer",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes-Bank-DB-setup",
"contentName": "Dukes-Bank-DB-setup",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes_Bank_App",
"contentName": "Dukes_Bank_App",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{

VMware, Inc. 370

Programming Guide

"contentId": "DukesBankApplication",
"contentName": "DukesBankApplication",
"contentTypeId": "composite-blueprint",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
}
]
}

Input
You can use optional request parameters with your query URL to customize the returned
content.

Table 13-3. Package Validation Parameters

Name Description Type

file The name of the package file to be validated query

resolution mode The resolution mode to be used for performing validation query
when the same entity exists in the system. Valid values are
SKIP, OVERWRITE. SKIP will not update the existing entity
with the new content while OVERWRITE will update the old
entity with the new data. In case the resolution mode is not
explicitly provided the default mode OVERWRITE will be used
for conflict resolution.

Output
The package validation response body contains the following parameters.

VMware, Inc. 371

Programming Guide

Table 13-4. Import and Export Response Body Parameters

Parameter Description

contentImportSta Over all status of the import/validation operation, one failure in import/validation result guarantees
tus failed status. Values are as follows:
n Success - Denotes the successful import or validation status at a particular component or
package level.
n Failed - Denotes an import or validation failure at a particular component package level.
n Warning - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.

contentImportRes Set of collected content import/validation results populated by the provider. The Content import
ults operation result collection is the set of content that passed or failed. If failed the errors are
populated in ContentImportError. Properties are as follows:
n contentId - (string) Unique content ID within the file system.
n contentName - (anyType) Name of the content being imported.
n contentTypeId - (string) The ID for the content type being exported. This matches the folder
structure in the exported zip.
n contentImportStatus - Track the failed or succeeded status of an entity.
n messages - Information returned by the provider.
n contentImportErrors - Set of errors returned by the provider.

Import a Package Example

POST /api/packages imports a package.

curl Command
The following command imports a .zip file. This example uses the DukesBankApp.zip
file which is provided on the vRealize Automation virtual appliance. You can copy the
file from /usr/lib/vcac/tools/initial-config/sample-oob-content/DukesBankApp.zip
using WinSCP (Windows) or scp (Mac).

$curl --insecure -s -H "Content-Type: multipart/form-data" -H "Authorization: Bearer $token"

https://$vRA/content-management-service/api/packages -F "[email protected]"

To verify success of a package import, use vRealize Automation to view the imported items on
the target system.

JSON Output
The following JSON output is returned on the command input.

{
"contentImportStatus": "SUCCESS",
"contentImportResults": [
{
"contentId": "Apache_LB",
"contentName": "Apache_LB",
"contentTypeId": "software-component",

VMware, Inc. 372

Programming Guide

"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "MySql",
"contentName": "MySql",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "JBossAppServer",
"contentName": "JBossAppServer",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes-Bank-DB-setup",
"contentName": "Dukes-Bank-DB-setup",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes_Bank_App",
"contentName": "Dukes_Bank_App",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "DukesBankApplication",
"contentName": "DukesBankApplication",
"contentTypeId": "composite-blueprint",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
}
]
}

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 373

Programming Guide

Table 13-5. Import and Export Response Body Parameters

Parameter Description

contentImportSta Over all status of the import/validation operation, one failure in import/validation result guarantees
tus failed status. Values are as follows:
n Success - Denotes the successful import or validation status at a particular component or
package level.
n Failed - Denotes an import or validation failure at a particular component package level.
n Warning - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.

contentImportRes Set of collected content import/validation results populated by the provider. The Content import
ults operation result collection is the set of content that passed or failed. If failed the errors are
populated in ContentImportError. Properties are as follows:
n contentId - (string) Unique content ID within the file system.
n contentName - (anyType) Name of the content being imported.
n contentTypeId - (string) The ID for the content type being exported. This matches the folder
structure in the exported zip.
n contentImportStatus - Track the failed or succeeded status of an entity.
n messages - Information returned by the provider.
n contentImportErrors - Set of errors returned by the provider.

Export XaaS Content Example

PUT /api/content/bundles/filters exports a package as a .zip file.

curl Command
The following command exports an XaaS package as a .zip file at the specified location.

curl -X PUT -H "Authorization: Bearer $token" -H "Content-Type: application/json"-

d'{"jsonAccepted" : true, "tenantId" : "qe", "data" : [] }' 'https://$vRA/advanced-designer-
service/api/content/bundles/filters'

JSON Output
The output of a successful export command is a .zip file at the specified location.

Input
Table 13-6. XaaS Import Input Parameters

Name Parameter

tenantId Identifies the tenant associated with the export package.

data Information about the export package. Includes the following:

n entityType
n id

jsonAccepted Valid values are true or false.

VMware, Inc. 374

Programming Guide

Output

Import XaaS Content Example

POST /api/content/bundles imports an XaaS content bundle. You can use the command to
import a 6.2.x package into vRealize Automation 7.0.

curl Command
The following command imports a file called XaaSContent.zip.

curl --insecure -X POST -H "Authorization: Bearer $token" -H "Content-Type:multipart/form-

data"-F"[email protected]"-F"prefix=prefix_"-F"prefixOnlyConflicting=true"' https://$vRA/
advanced-designer-service/api/content/bundles'

JSON Output
The output of the command is a message indicating the status and details of the import
operation.

{
"importStatus" : "SUCCESSFUL",
"data" : [ {
"logLevel" : "INFO",
"entityType" : "com.vmware.vcac.designer.service.domain.ServiceBlueprint",
"entityId" : "4740aa54-61e6-47d7-945f-0bb50ff153c8",
"entityName" : "XaaSBlueprint",
"messageKey" : "import.blueprint.success",
"message" : "Success"
} ]
}

Input
Table 13-7. XaaS Import Input Parameters

Name Parameter

file Identifies the .zip file that is the content bundle to import.

prefix The prefix to use with imported objects. Ensures avoidance of a duplicate name failure.

prefixOnlyConflicting Set to true to rename or prefix conflicting objects.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 375

Programming Guide

Table 13-8. Import and Export Response Body Parameters

Parameter Description

importStatus Over all status of the import/validation operation, one failure in import/validation result
guarantees failed status. Values are as follows:
n Successful - Denotes the successful import or validation status at a particular
component or package level.
n Partial - Denotes a scenario that warrants a system level warning. Alerts the user
about a possible error condition that the proposed action may create.
n Failed - Denotes an import or validation failure at a particular component package
level.

data Set of collected content import/validation results populated by the provider. The
Content import operation result collection is the set of content that passed or failed:
n entityType - (string) The ID for the entity being imported.
n entitytId - (string) Unique content ID within the file system.
n messageKey - (string)
n logLevel - The logging level to use for any errors that occur.
n message - Information returned by the provider.
n entityName - (anyType) Name of the entity being imported.

VMware, Inc. 376

Updating Tenancy on a Security
Object 14
You use the network service to perform tasks related to updating tenancy on a security object.

As a vRealize Automation system administrator, you can change the tenancy of a security group,
security tag, or security policy. The tenancy levels are:

n Unscoped — Security object not visible to any tenant.

n Global — Security object visible to all tenants with a reservation on the specific endpoint in
which the security object exists. To indicate that a tenancy is global, the tenantID must be set
to null.

n TenantId — Security object visible only to the tenant specified.

This chapter includes the following topics:

n Update the Tenancy for a Security Group

n Network Service Examples for Updating Tenancy

Update the Tenancy for a Security Group

To set the tenancy level for an NSX security object, you pass the security object to its API with
a tenant ID specified. To do this efficiently, you use the API to retrieve the object, alter its JSON,
then pass the edited JSON back to the API.

This use case example updates the tenant ID for a security group, but the same procedure
applies to security tags and security policies using similar APIs such as:

n /network-service/api/security-tags/{id}

n /network-service/api/security-policies/{id}

Prerequisites

n Log in to vRealize Automation as a system administrator or 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.

VMware, Inc. 377

Programming Guide

Procedure

1 Retrieve the security group with ID=24.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA/network-service/api/security-groups/24

For details regarding input and output for this request, see Syntax for Retrieving Security
Groups.

2 Edit the JSON for the security group.

Name the JSON file updateTenantId.json and set the tenant ID to a single tenant named
rainpole.

{
"@type": "SecurityGroup",
"id": "24",
"name": "security-group-name",
"description": "Managed by VMware vRealize Automation",
"externalId": "securitygroup-19567",
"tenantId": "rainpole",
"extensionData": {
"entries": [...]
},
"securityGroupTypeId": "Infrastructure.Network.SecurityGroup.NSX",
"internal": false,
"machineIdCollection": null,
"ipAddressCollection": null
}

3 Submit a request to update the security group with ID=24 that calls the JSON file.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-type: application/

json" -H "Authorization: Bearer $token” -H "Cache-control: no cache" https://$vRA/network-
service/api/security-groups/24 --data @C:/Temp/updateTenantId.json

For details regarding input and output for this request see Syntax for Updating a Tenant ID .

4 Examine the response to verify that the security group has the tenant you specified.

Results

With the tenancy changed to rainpole, rainpole is the only tenant on this endpoint that can now
see the security group with ID=24 .

Network Service Examples for Updating Tenancy

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

VMware, Inc. 378

Programming Guide

Syntax for Retrieving Security Groups

GET /api/security-groups/{id} retrieves a security group identified by its ID.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/network-service/api/security-groups/{id}, where id is the ID of the

security group.

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

Content Specifies an array of data rows, each of which represents one of the security objects
returned in a pageable list. Each security object can contain the following information:
n id: Specifies the unique security object identifier.
n name: Specifies the name of the security object.
n description: Specifies a description of the security object.
n externalId: Specifies the external ID of the security object.
n tenantId: Specifies the tenant ID value. Default value is null.
n extensionData: Contains an array of Literals name "entries". Each Literanl contains a
key and a value. The value, in turn, contains a type (such as a string or integer) and
the Literal's value.
n securityGroupTypeId: For internal use only. Applies to security groups only.
n internal: For internal use only. Applies to security groups only.
n machineIdCollection: For internal use only. Applies to security groups only.
n ipAddressCollection: For internal use only. Applies to security groups only.

Example: curl Command to Retrieve Security Groups

The following example command retrieves information about security group with ID=24.

curl -X --insecure -H "accept: application/json"

-H "Authorization: Bearer $token” https://$vRA/network-service/api/security-groups/24

The response in JSON lists the information for the security group specified.

{
"links": [],
"content": [
{

VMware, Inc. 379

Programming Guide

"@type": "SecurityGroup",
"id": "24",
"name": "security-group-name",
"description": "Managed by VMware vRealize Automation",
"externalId": "securitygroup-19567",
"tenantId": null,
"extensionData": {
"entries": [...]
},
"securityGroupTypeId": "Infrastructure.Network.SecurityGroup.NSX",
"internal": false,
"machineIdCollection": null,
"ipAddressCollection": null
}
],
}

Syntax for Updating a Tenant ID

PUT /api/security-groups/{id} updates the tenant for the security group with a specified
ID.

Input
Use the supported input parameters to control the command output.

Table 14-1. Input parameters

Parameter Description

URL https://$vRA/network-service/api/security-groups/{id}, where id is the ID of the

security group to update.

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

$securityId Specifies the unique security object identifier.

$securityName Specifies the name of the security object.

$description Specifies a description of the security object.

$externalId Specifies the external ID of the security object.

VMware, Inc. 380

Programming Guide

Table 14-1. Input parameters (continued)

Parameter Description

$tenantId Specifies the tenant ID value. Valid values are: <unscoped>, null, and tenant_name,
where:
n "tenantID": "<unscoped>" — Hides the security object from all tenants.

n "tenantID": null — Specifies global tenancy. The object is visible to all tenants
with a reservation on the specific endpoint in which the security object exists.
n "tenantID": "my_tenant_example" — The security object is only visible to the
tenant named my_tenant_example.

$extensionData Contains an array of Literals name "entries". Each Literanl contains a key and a value.
The value, in turn, contains a type (such as a string or integer) and the Literal's value.

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": "SecurityGroup",
"id": "$securityId",
"name": "$securityName",
"description": "$description",
"externalId": "$externalId",
"tenantId": "$tenantId",
"extensionData": {
"entries": [...]
},
"securityGroupTypeId": "$securityGroupTypeId",
"internal": false,
"machineIdCollection": null,
"ipAddressCollection": null
}

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 381

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This 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.

Content Specifies an array of data rows, each of which represents one of the security objects
returned in a pageable list. Each security object can contain the following information:
n id: Specifies the unique security object identifier.
n name: Specifies the name of the security object.
n description: Specifies a description of the security object.
n externalId: Specifies the external ID of the security object.
n tenantId: Specifies the tenant ID value. Default value is null.
n extensionData: Contains an array of Literals name "entries". Each Literanl contains a
key and a value. The value, in turn, contains a type (such as a string or integer) and
the Literal's value.
n securityGroupTypeId: For internal use only. Applies to security groups only.
n internal: For internal use only. Applies to security groups only.
n machineIdCollection: For internal use only. Applies to security groups only.
n ipAddressCollection: For internal use only. Applies to security groups only.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned.
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 Update the Tenant ID for a Security Group With
JSON File
The following sample updateTenantId.json file contains parameters for the request to update
a security group with ID=24.

{
"@type": "SecurityGroup",
"id": "24",
"name": "security-group-name",
"description": "Managed by VMware vRealize Automation",
"externalId": "securitygroup-19567",
"tenantId": "my_tenant_example",
"extensionData": {
"entries": [...]
},
"securityGroupTypeId": "Infrastructure.Network.SecurityGroup.NSX",

VMware, Inc. 382

Programming Guide

"internal": false,
"machineIdCollection": null,
"ipAddressCollection": null
}

The following example requests a tenant ID update for security group with ID=24 by calling the
updateTenantId.json file.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-type: application/json" -H

"Authorization: Bearer $token” -H "Cache-control: no cache" https://$vRA/network-service/api/
security-groups/24 --data @C:/Temp/updateTenantId.json

Example: curl Command to Update the Tenant ID for a Security Group With
Parameters Inline
The following example requests a tenant ID update for security group with ID=24 with input
parameters specified inline.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-type: application/json" -H

"Authorization: Bearer $token” -H "Cache-control: no cache" https://$vRA/network-service/api/
security-groups/24 --data
{
"@type": "SecurityGroup",
"id": "24",
"name": "security-group-name",
"description": "Managed by VMware vRealize Automation",
"externalId": "securitygroup-19567",
"tenantId": "my_tenant_example",
"extensionData": {
"entries": [...]
},
"securityGroupTypeId": "Infrastructure.Network.SecurityGroup.NSX",
"internal": false,
"machineIdCollection": null,
"ipAddressCollection": null
}

VMware, Inc. 383

Triggering an Active Directory
Synchronization 15
You use the identity service to initiate the synchronization process for an active directory.

On-demand directory synchronization brings users and groups into vRealize Automation without
reading and saving the active directory configuration first. In this way, you can automate the
process.

This chapter includes the following topics:

n Trigger Sync to an Active Directory

n Identity Service Examples for Triggering Active Directory Synchronization

Trigger Sync to an Active Directory

To initiate synchronization to an active directory, you retrieve the domain name of the directory
then use that domain name in the API request to synchronize the groups and users to that
directory.

Prerequisites

n Log in to vRealize Automation as a system administrator or 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.

Procedure

1 Retrieve the directories for the specified tenant.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA/identity/api/$tenantId/directories

For details regarding input and output for this request, see Syntax for Retrieving Directories.

2 Examine the result to find the domain name of the directory for which you want to initiate
synchronization.

{
"@type": "IdentityStore",

VMware, Inc. 384

Programming Guide

"domain": "demo.ad-example.local",
"name": "Demo AD for sync",
"description": "Demo AD for sync",
"alias": "",
"type": "AD",
...
}

In this example, the directory is Demo AD for sync with domain name demo.ad-
example.local.

3 Use the domain name to initiate the synchronization process.

curl -X POST --insecure -H "Accept: application/json" -H "Content-type: application/json"

-H "Authorization: Bearer $token” -H "Cache-control: no cache" https://$vRA/identity/api/
tenants/$tenantId/directories/demo.ad-example.local/sync

For details regarding input and output for this request, see Syntax for Synchronizing the
Active Directory.

4 Check the state of the synchronization process.

curl -X GET --insecure -H "Accept: application/json" -H "Content-type: application/json"

-H "Authorization: Bearer $token” -H "Cache-control: no cache" https://$vRA/identity/api/
tenants/$tenantId/directories/demo.ad-example.local/status

For details regarding input and output for this request, see Syntax for Checking the
Synchronization Process.

5 Examine the result for the value of the syncStatus attribute.

{
"syncStatus": {
"status": "RUNNING",
"message": null
}
}

In this example, the status is RUNNING.

Results

When the synchronization process completes successfully, the status is COMPLETED and the
directory with the name Demo AD for sync appears with synced groups and users under
Administration > Directories in the vRealize Automation interface.

Identity Service Examples for Triggering Active Directory

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

VMware, Inc. 385

Programming Guide

Syntax for Retrieving Directories

GET /api/tenants/{tenantId}/directories retrieves a list of directories for a tenant.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/identity/api/tenants/{tenantId}/directories, where tenantId is the ID of

the tenant.

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

The bearer token is included in the HEADER of the request.

Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

Links Specifies an array of link objects, each of which contains the following parts:
n rel: Specifies the name of the link.
n Self refers to the object that was returned or requested. This 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.

Content Specifies an array of data rows, each of which represents one of the objects returned
in a pageable list. Each object can contain the following information:
n domain: Specifies the domain name for the directory.
n name: Specifies the name of the directory.
n description: Specifies a description of the directory.
n alias: Specifies the alternate name of the directory, if applicable.
n type: Specifies the type of directory, such as active directory or local directory.

Metadata Specifies the following paging-related data:

n Size: Specifies the maximum number of rows per page.
n totalElement: Specifies the number of rows returned. This parameter is not output
when you query for a single profile.
n totalPages: Specifies the total number of pages of data available.
n Number: Specifies the current page number.
n Offset: Specifies the number of rows skipped.

VMware, Inc. 386

Programming Guide

Example: curl Command to Retrieve Directories

The following example command retrieves all directories for the tenant.

curl -X --insecure -H "accept: application/json" -H "Authorization: Bearer $token” https://

$vRA/identity/api/$tenantId/directories

The response in JSON lists the information for the tenant specified.

{
"links": [],
"content": [
{
"@type": "IdentityStore",
"domain": "domain_name1",
"name": "Active Directory Example 1",
"description": "Active Directory Example 1",
"alias": "",
"type": "AD",
...
}
{
"@type": "IdentityStore",
"domain": "domain_name2",
"name": "Active Directory Example 2",
"description": "Active Directory Example 2",
"alias": "",
"type": "AD",
...
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}

Syntax for Synchronizing the Active Directory

POST /api/tenants/{tenantId}/directories/{id}/sync initiates the sync process on the
directory identified by its domain name.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 387

Programming Guide

Parameter Description

URL https://$vRA/identity/api/tenants/{tenantId}/directories/{id}/sync, where:

n tenantId is the ID of the tenant
n id is the domain name of the directory for synchronization

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

The bearer token is included in the HEADER of the request.

Response Status Codes

One of the following codes is displayed as a result of your synchronization request.

Status Code Description

200 OK Your request succeeded and a sync process was initiated.

401 UNAUTHORIZED The request might not authenticate the user or

authentication credentials required.

404 NOT FOUND The domain name is incorrect or there is no such domain
in the tenant. For example:

Cannot find a directory with domain name

'someDomain' in tenant 'someTenant'!

Use the information in the response to troubleshoot the

problem with the request.

Example: curl Command to Synchronize the Active Directory

The following example command initiates the synchronization process for a directory with
domain name demo.ad-example.local.

curl -X --insecure -H "accept: application/json" -H "Authorization: Bearer $token” https://

$vRA/identity/api/tenants/$tenantId/directories/demo.ad-example.local/sync

Syntax for Checking the Synchronization Process

GET /api/tenants/{tenantId}/directories/{id}/status shows the status of the
synchronization.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 388

Programming Guide

Parameter Description

URL https://$vRA/identity/api/tenants/{tenantId}/directories/{id}/sync, where:

n tenantId is the ID of the tenant
n id is the domain name of the directory for synchronization

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

The bearer token is included in the HEADER of the request.

Output
The command output contains property names and values based on the command input
parameters.

Parameter Description

syncStatus Specifies the status of the synchronization:

n status: Specifies the status of the sync process. Positive responses include:
RUNNING and COMPLETED. If a negative status code is returned, the message
included with the error provides troubleshooting suggestions.
n message: Provides additional information regarding the status.

Example: curl Command to Check Status of Synchronization

The following example command checks the synchronization process for a directory with domain
name demo.ad-example.local.

curl -X --insecure -H "accept: application/json" -H "Authorization: Bearer $token” https://

$vRA/identity/api/tenants/$tenantId/directories/demo.ad-example.local/status

The response in JSON provides the status of the synchronization process. The following example
is a positive response that shows the synchronization is running.

{
"syncStatus": {
"status": "RUNNING",
"message": null
},
}

VMware, Inc. 389

Retrieving Health Test Results
16
You use the health broker proxy server to retrieve and examine results of a health test
configuration.

A configuration includes one or more test suites that you create and run on a schedule to check
the health of your vRealize Automation or vRealize Orchestrator installation. vRealize Automation
Health Service is a plug-in to vRealize Automation, and each configuration corresponds to a tile
on the Health page of the user interface.

This chapter includes the following topics:

n Retrieve Health Test Results

n Health Broker Proxy Server Examples to Obtain Test Results

Retrieve Health Test Results

To find the results of a health test, you retrieve a list of all configurations, query for an execution
of a particular configuration, then query for the individual results of that execution.

This example shows how to retrieve results for the latest execution of a health test configuration.
You can also retrieve results for tests executed at a different time.

Prerequisites

n Log in to vRealize Automation as a system administrator and a tenant administrator. In

addition, the tenant administrator must have fabric administrator permissions to use the
health broker proxy server.

n Verify that the appliance name and fully qualified domain name of the vRealize Automation
instance are available.

n Verify that you have a valid HTTP bearer token that matches your login credentials. See
Chapter 2 REST API Authentication.

Procedure

1 Use the health broker proxy server to get an authentication token for the health services API.

curl -X GET --insecure "https://$vRA/healthbroker-proxy-server/api/authn/all HTTP/1.1" -H

"accept: text/html" -H "authorization: Bearer $token"

VMware, Inc. 390

Programming Guide

For details regarding input and output for this request, see Syntax for Requesting a Health
Services Token.

A successful request returns an authentication token that you include in subsequent API
requests.

2 For convenience, store the token in a variable.

export healthtoken="EXAMPLE-HEALTH-TOKEN-TEXT"

3 Retrieve a list of health test configurations.

curl -X GET --insecure "https://$vRA:8090/health/config/configurations HTTP/1.1" -H "x-

xenon-auth-token: $healthtoken"

For details regarding input and output for this request see Syntax to Retrieve a List of
Configurations.

4 Examine the response for configurations listed under documentLinks.

"documentLinks": [
"/health/config/configurations/80dc3a6f1478553368707000",
"/health/config/configurations/8277769f1478213933292000",
"/health/config/configurations/80dc3a6f1478545923685000"
],

Every time the Health Broker runs a test configuration, an execution is created.

5 Submit a request to find the latest execution for one of the health test configurations.

curl -X POST --insecure "https://$vRA:8090/core/health-query-tasks HTTP/1.1" -H "content-

type: application/json" -H "x-xenon-auth-token: $healthtoken"

The query body specifies the configuration /health/config/configurations/

8277769f1478213933292000 as the value to match.

{
"taskInfo": {
"isDirect": true
},
"querySpec": {
"query": {
"occurance": "MUST_OCCUR",
"booleanClauses": [{
"occurance": "MUST_OCCUR",
"term": {
"propertyName": "documentKind",
"matchValue": "com:vmware:healthbroker:states:ExecutionServiceState",
"matchType": "TERM"
}
},
{
"occurance": "MUST_OCCUR",
"term": {

VMware, Inc. 391

Programming Guide

"propertyName": "configurationLink",
"matchValue": "/health/config/configurations/8277769f1478213933292000",
"matchType": "TERM"
}
}]
},
"sortTerm": {
"propertyName": "startedTimestamp",
"propertyType": "LONG"
},
"sortOrder": "DESC",
"resultLimit": 1,
"options": ["TOP_RESULTS",
"EXPAND_CONTENT",
"SORT"]
}
}

For details regarding input and output for this request see Syntax to Filter for Latest
Execution of a Configuration .

6 Examine the execution document contained in the response to find the overallResultLink.

"overallResultsLink": "/health/result/overall-results/Report_vRA_20161103-22.59.03.0373",

This is the latest execution of the configuration.

7 Submit a request to find all the individual results for the latest execution.

curl -X POST --insecure "https://$vRA:8090/core/health-query-tasks HTTP/1.1" -H "content-

type: application/json" -H "x-xenon-auth-token: $healthtoken"

The query body specifies the value for the overallResultsLink as the value to match.

{
"taskInfo": {
"isDirect": true
},
"querySpec": {
"query": {
"occurance": "MUST_OCCUR",
"booleanClauses": [{
"occurance": "MUST_OCCUR",
"term": {
"propertyName": "documentKind",
"matchValue":
"com:vmware:healthbroker:states:IndividualTestResultServiceState",
"matchType": "TERM"
}
},
{
"occurance": "MUST_OCCUR",
"term": {
"propertyName": "overallResultsLink",

VMware, Inc. 392

Programming Guide

"matchValue": "/health/result/overall-results/
Report_vRA_20161103-22.59.03.0373",
"matchType": "TERM"
}
}]
},
"sortTerm": {
"propertyName": "state",
"propertyType": "STRING"
},
"sortOrder": "DESC",
"options": ["EXPAND_CONTENT",
"SORT"]
}
}

For details regarding input and output for this request see Syntax to Find All Individual
Results.

Results

Detailed test results output in a textual representation facilitate programmatic post-processing. In

cases where a check fails, a message describing the failure appears in the output.

{
"testMethod": {
"name": "vRealize Automation Node Common Name Certificate Check",
"description": "This test case verifies that the vRA node certificate Common names match
that of it's server. This test is most useful for distributed/HA environments.",
"descriptionType": "text",
"severity": "CRITICAL",
"methodName": "areVraNodeCertsCommonNameValid",
"accessLevel": "INFRASTRUCTURE",
"enabled": false,
"configurationReferences": []
},
"startTime": "1478213951731",
"endTime": "1478213960684",
"state": "FAILED",
"message": "Not all checks were successful. See the following errors for more
details: \njava.io.IOException: Unable to get the certificate of your server [cava-
pn-210-066.eng.vmware.com:443]. Please confirm configuration information. The returned
exception is: [java.net.UnknownHostException: cava-pn-210-066.eng.vmware.com] \n",
"remediationType": "html",
"remediation": "http://kb.vmware.com/selfservice/microsites/search.do?
language=en_US&cmd=displayKC&externalId=2106583",
"overallResultsLink": "/health/result/overall-results/Report_vRA_20161103-22.59.03.0373",
}

Health Broker Proxy Server Examples to Obtain Test Results

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

VMware, Inc. 393

Programming Guide

Syntax for Requesting a Health Services Token

GET /api/authn/all requests an authentication token for the health services API.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA/healthbroker-proxy-server/api/authn/all

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$token Specifies a valid HTTP bearer token with necessary credentials.

Output
The output is a text file with the token to authenticate to the health services API.

Example: curl Command to Retrieve Directories

The following example command requests the authentication token.

curl -X --insecure -H "accept: text/html" -H "Authorization: Bearer $token" https://$vRA/

healthbroker-proxy-server/api/authn/all

The text response is the authentication token for requests to the health services API.

Syntax to Retrieve a List of Configurations

GET /health/config/configurations retrieves a list of health test configurations.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA:8090/health/config/configurations

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$healthtoken Specifies a valid authentication token for the health services API.

Note The request does not use the API endpoint so healthbroker-proxy-service/api is not
used.

Output
The command output contains property names and values based on the command input
parameters.

VMware, Inc. 394

Programming Guide

Parameter Description

Content Specifies an array of data rows, each of which represents one of the objects returned
in a pageable list. Each object can contain the following information:
n documentLinks: Specifies the configurations.
n documentCount: Specifies the number of configurations
n queryTimeMicros: Specifies
n documentOwner: Specifies

Example: curl Command to Retrieve List of Configurations

The following example command retrieves a list of all configurations.

curl -X --insecure -H "x-xenon-auth-token: $healthtoken" https://$vRA:8090/health/config/

configurations

The response lists all configurations.

{
"documentLinks": [
"/health/config/configurations/12858d4c34f278755680551b52340"
],
"documentCount": 1,
"queryTimeMicros": 3000,
"documentVersion": 0,
"documentUpdateTimeMicros": 0,
"documentExpirationTimeMicros": 0,
"documentOwner": "213feac8-675e-49da-b882-0fca7149962a"
}

Syntax to Filter for Latest Execution of a Configuration

POST /core/health-query-tasks submits a request for the latest execution of a configuration.

Input
Use the supported input parameters to control the command output.

Parameter Description

URL https://$vRA:8090/core/health-query-tasks

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$healthtoken Specifies a valid authentication token for the health services API.

Note The request does not use the API endpoint so healthbroker-proxy-service/api is not
used.

VMware, Inc. 395

Programming Guide

Response Status Codes

One of the following codes is displayed as a result of your synchronization request.

Status Code Description

200 OK Your request succeeded and the object was updated.

400 BAD REQUEST The data you provided in the POST failed validation.
Inspect the response body for details.

401 UNAUTHORIZED The request might not authenticate the user or

authentication credentials required.

Example: curl Command to Filter for Latest Execution of a Configuration

The following example command retrieves the latest execution of the configuration named /
health/config/configurations/12858d4c34f278755680551b52340.

curl -X --insecure -H "content-type: application/json" -H "x-xenon-auth-token: $healthtoken"

https://$vRA:8090/core/health-query-tasks
{
"taskInfo": {
"isDirect": true
},
"querySpec": {
"query": {
"occurance": "MUST_OCCUR",
"booleanClauses": [{
"occurance": "MUST_OCCUR",
"term": {
"propertyName": "documentKind",
"matchValue": "com:vmware:healthbroker:states:ExecutionServiceState",
"matchType": "TERM"
}
},
{
"occurance": "MUST_OCCUR",
"term": {
"propertyName": "configurationLink",
"matchValue": "/health/config/configurations/
12858d4c34f278755680551b52340",
"matchType": "TERM"
}
}]
},
"sortTerm": {
"propertyName": "startedTimestamp",
"propertyType": "LONG"
},
"sortOrder": "DESC",
"resultLimit": 1,
"options": ["TOP_RESULTS",

VMware, Inc. 396

Programming Guide

"EXPAND_CONTENT",
"SORT"]
}
}

Example: JSON Output

The following sample shows the latest execution of the configuration specified by the
overallResultsLink.

{
"taskInfo": {
...
},
"querySpec": {
"query": {
...
}
},
"results": {
"documentLinks": [
"/health/exec/executions/12858d4c34f278755680551d322f0"
],
"documents": {
"/health/exec/executions/12858d4c34f278755680551d322f0": {
"configurationLink": "/health/config/configurations/
12858d4c34f278755680551b52340",
"started": "2018-03-22T19:29:00.471Z",
"overallResultsLink": "/health/result/overall-results/Report_089adaf3-44d3-4cb2-
a1a5-d2de4f376e73-20180322-19.29.00.0471",

...
},
...
},
}

Syntax to Find All Individual Results

POST /core/health-query-tasks submits a request for all individual results for the latest
execution of a configuration.

Input
Use the supported input parameters to control the command output.

VMware, Inc. 397

Programming Guide

Parameter Description

URL https://$vRA:8090/core/health-query-tasks

$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.

$healthtoken Specifies a valid authentication token for the health services API.

Note The request does not use the API endpoint so healthbroker-proxy-service/api is not
used.

Response Status Codes

One of the following codes is displayed as a result of your synchronization request.

Status Code Description

200 OK Your request succeeded and the object was updated.

400 BAD REQUEST The data you provided in the POST failed validation.
Inspect the response body for details.

401 UNAUTHORIZED The request might not authenticate the user or

authentication credentials required.

Example: curl Command to Retrieve all the Individual Results for the Latest
Execution
The following example command retrieves the individual results for the
execution named /health/result/overall-results/Report_089adaf3-44d3-4cb2-a1a5-
d2de4f376e73-20180322-19.29.00.0471.

curl -X --insecure -H "content-type: application/json" -H "x-xenon-auth-token: $healthtoken"

https://$vRA:8090/core/health-query-tasks
{
"taskInfo": {
"isDirect": true
},
"querySpec": {
"query": {
"occurance": "MUST_OCCUR",
"booleanClauses": [{
"occurance": "MUST_OCCUR",
"term": {
"propertyName": "documentKind",
"matchValue":
"com:vmware:healthbroker:states:IndividualTestResultServiceState",
"matchType": "TERM"
}
},
{
"occurance": "MUST_OCCUR",

VMware, Inc. 398

Programming Guide

"term": {
"propertyName": "overallResultsLink",
"matchValue": "/health/result/overall-results/Report_089adaf3-44d3-4cb2-
a1a5-d2de4f376e73-20180322-19.29.00.0471",
"matchType": "TERM"
}
}]
},
"sortTerm": {
"propertyName": "state",
"propertyType": "STRING"
},
"sortOrder": "DESC",
"options": ["EXPAND_CONTENT",
"SORT"]
}
}

Example: JSON Output

The following snippet is from the output that shows all the individual results for the latest
execution of the configuration. This section shows an example of the message that appears if
the test fails. The value of the overallResultsLink is the matched value from the input body.

{
"taskInfo": {
...
},
"querySpec": {
"query": {
...
}
},
"results": {
"documentLinks": [
"/health/exec/executions/12858d4c34f278755680551d322f0"
],
"documents": {
"/health/result/individual-result/Report_089..." : {
"testMethod": {
"name": "Check Storage Reservation Policy to Reservation
Assignments",
"description": "This test collects all storages that are assigned
a storage reservation policy(from all tenants), and checks them against created
reservations(in the specified tenant) to see if that storage is assigned to a
reservation.",
"descriptionType": "text",
"severity": "NORMAL",
"methodName":
"CheckIfAllStorageReservationPoliciesAreAssignedToReservations",
"accessLevel": "NORMAL",
"enabled": false,
"configurationReferences": []
},

VMware, Inc. 399

Programming Guide

"startTime": "1521746961853",
"endTime": "1521746962763",
"state": "FAILED",
"message": "[Storage reservation policy [Rainpole High Speed] is assigned
to storage [Datastore1], but the storage is not in any reservation in tenant [rainpole].]
\n[Storage reservation policy [Rainpole Low Cost] is assigned to storage [VNXe:nsx61-data1],
but the storage is not in any reservation in tenant [rainpole].]\n[Storage reservation policy
[Rainpole High Speed] is assigned to storage [VNXe:nsx61-data2], but the storage is not in
any reservation in tenant [rainpole].] expected [false] but found [true]",
"remediationType": "html",
"remediation":
"http://pubs.vmware.com/vrealize-automation-72/index.jsp#com.vmware.vrealize.automation.doc/
GUID-95AADE6A-4CE2-4AC9-9D1F-1E42DC3E52FF.html",
"overallResultsLink": "/health/result/overall-results/
Report_089adaf3-44d3-4cb2-a1a5-d2de4f376e73-20180322-19.29.00.0471",
...
},
...
},
...
},
...
}

VMware, Inc. 400

Using SNMP to Monitor vRealize
Automation 17
The SNMP service is one of the configuration services included with the management command
APIs.

SNMP uses http://www.net-snmp.org with customization to hide the plain text passwords
from the configuration file. The VMware SNMP daemon or vSNMPD is the vRealize Automation
implementation of SNMP. vSNMPD facilitates the monitoring of vRealize Automation node
resources such as CPU, memory, or disk space.

As a system administrator, you can use vSNMPD as an early warning system to prevent a
vRealize Automation slowdown. For example, if vSNMPD sends a message about high CPU
usage, you can scan your processes to find the one that is the most CPU intensive. You can also
further investigate the correlation between CPU, memory, and disk usage. Using your current
tools, all network and system monitoring is secure because vSNMPD uses SNMPv3.

The Swagger document for configuration services is available at the following URL.

https://$vRA:5480/config/

$vRA denotes an instance of vRealize Automation.

Prerequisites
Satisfy the following conditions before using the SNMP service.

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.

This chapter includes the following topics:

n Configuring Local SNMP

n Configure Global SNMP

VMware, Inc. 401

Programming Guide

Configuring Local SNMP

You use local SNMP in environments with tight security where use of an SNMP port is not
allowed. To secure the connection between the vRealize Automation SNMP agent and the SNMP
server, vRealize Automation uses SNMP authentication and AES-256 encryption.

Local SNMP only runs on the localhost. To access the service using the REST API on VAMI
port 5480, you use the URL https://$vRA:5480/config#/vSNMP-local-daemon. To maintain
network security and accessibility within your environment, leave the local SNMP daemon
running.

Before running any SNMP service requests, verify that you have satisfied the prerequisites in
Chapter 17 Using SNMP to Monitor vRealize Automation.

Obtain information about an Object Identifier

To obtain information about an object identifier (OID) for free memory such as
1.3.6.1.4.1.2021.4.11.0, you use the following GET request.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/

json" -H "Authorization: Bearer $token" https://$vRA:5480/config/snmp/local/get?
obj=1.3.6.1.4.1.2021.4.11.0

The response body provides information about the OID.

{
"SNMPv2-SMI::enterprises.2021.4.11.0": "6813296"
}

In this response, 6813296 is the total free memory on the SNMP device.

Walk the local SNMP tree

To walk the local SNMP tree with Management Information Database (MIB) value 1.3.6.1, you use
the following GET request.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA:5480/config/snmp/local/walk?obj=1.3.6.1

A snippet of the response body shows information about the network objects.

{
"SNMPv2-SMI::mib-2.6.13.1.5.127.0.0.1.37866.127.0.0.1.61613": "61613",
"SNMPv2-SMI::mib-2.6.13.1.4.10.126.188.32.58326.10.126.188.32.9300": "10.126.188.32",
"SNMPv2-SMI::mib-2.25.4.2.1.3.1532": "0.0",
"SNMPv2-SMI::mib-2.6.20.1.4.1.4.0.0.0.0.8080": "30132",
"SNMPv2-SMI::mib-2.6.13.1.1.127.0.0.1.44418.127.0.0.1.5433": "5",
...
"SNMPv2-SMI::mib-2.6.13.1.1.127.0.0.1.443.127.0.0.1.33257": "5",
"SNMPv2-SMI::enterprises.2021.4.11.0": "6727248",
"SNMPv2-SMI::mib-2.25.3.7.1.2.393232.1": "/dev/sda1",
"SNMPv2-SMI::mib-2.25.3.7.1.2.393232.2": "/dev/sda2",

VMware, Inc. 402

Programming Guide

...
"SNMPv2-SMI::mib-2.25.4.2.1.5.382": "",
"SNMPv2-SMI::mib-2.25.4.2.1.4.41367": "postgres: vcac vcac 127.0.0.1(38115) idle",
"SNMPv2-SMI::mib-2.25.4.2.1.4.41366": "postgres: vcac vcac 127.0.0.1(38113) idle",
"SNMPv2-SMI::mib-2.25.4.2.1.4.57817": "",
"SNMPv2-SMI::enterprises.8072.1.2.1.1.5.0.11.1.3.6.1.2.1.55.1.6.1.7.127": "0x80"
}

By using the MIB definition to access all OID data, you can see the names of all SNMP devices.

Configure Global SNMP

You use global SNMP when you want to send trap or informational messages to external SNMP
daemons.

To access global SNMP using the REST API on VAMI port 5480, you use the URL https://
$vRA:5480/config#/vSNMP. The following procedure shows how to configure, enable, and start
the VMware SNMP daemon.

Prerequisites

Verify that you have satisfied the prerequisites in Chapter 17 Using SNMP to Monitor vRealize
Automation.

Procedure

1 Configure the VMware SNMP daemon.

curl -X PUT --insecure \

https://$vRA:5480/config/snmp/agent/configure \
-H "Authorization: Bearer $token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ \
"manager": { \
"host": "Your snmp server here &#33;", \
"auth_user": "The user that is authorized to send snmp inform messages", \
"auth_password": "Authentication password for auth_user", \
"channel_encryption_password": "The password to be used for connection encryption
between this agent and your snmp server.", \
"security_engine": "Authentication engine. Example: 0x8000000001020304", \
"content_engine": "Content engine. Example: 0x8000000001020304" \
} \
}'

2 Retrieve the default configuration for SNMP.

curl --insecure -H "Accept: application/json" -H "Content-Type: application/json" -H

"Authorization: Bearer $token" https://$vRA:5480/config/snmp/monitors/config

VMware, Inc. 403

Programming Guide

The response body shows the default configuration.

{
"load": {
"load": [
[
"10",
"10",
"10"
]
],
"monitor": {
"seconds": "30"
}
},
"disk": {
"disk": [
[
"/",
"15%"
],
[
"/storage/log",
"15%"
],
[
"/storage/artifactory",
"15%"
],
[
"/storage/db",
"15%"
]
],
"monitor": {
"seconds": "10"
}
},
"proc": {
"proc": [
[
"postgres",
"1",
"300"
]
],
"monitor": {
"seconds": "60"
}
},
"file": {
"monitor": {
"seconds": "60"
},
"file": [

VMware, Inc. 404

Programming Guide

[
"\"/storage/db/pgdata/recovery.conf\"",
"0"
]
]
}
}

3 To change the configuration for SNMP, edit parameter values in the response and use the
new configuration as input to the request. In this example, the load monitoring period is
extended to 180 seconds.

curl -X PUT --insecure \

https://$vRA:5480/config/snmp/monitors \
-H "Authorization: Bearer $token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ \
"load": { \
"load": [["10","10","10"]], \
"monitor": {"seconds": "180"} \
}, \
"disk": { \
"disk": [ \
["/","15%"], \
["/storage/log","15%"], \
["/storage/artifactory","15%"], \
["/storage/db","15%"] \
], \
"monitor": {"seconds": "10"} \
}, \
"proc": { \
"proc": [["postgres","1","300"]], \
"monitor": {"seconds": "60"} \
}, \
"file": { \
"monitor": {"seconds": "60"}, \
"file": [["\"/storage/db/pgdata/recovery.conf\"","0"]] \
} \
}'

4 Enable but do not start the VMware SNMP daemon.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-Type: application/json"

-H "Authorization: Bearer $token" https://$vRA:5480/config/snmp/enable

5 Start the VMware SNMP daemon.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-Type: application/json"

-H "Authorization: Bearer $token" https://$vRA:5480/config/snmp/start

VMware, Inc. 405

Programming Guide

If the daemon fails to start, perform the following steps.

a Stop the daemon.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-Type: application/

json" -H "Authorization: Bearer $token" https://$vRA:5480/config/snmp/stop

b Restore the default configuration of SNMP monitoring.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-Type:

application/json" -H "Authorization: Bearer $token" https://$vRA:5480/config/snmp/
restore_default_config?proceed=true

c Disable the daemon to prevent it from running if vRealize Automation is rebooted or if

there is an attempt to restart the daemon using the API.

curl -X PUT --insecure -H "Accept: application/json" -H "Content-Type: application/

json" -H "Authorization: Bearer $token" https://$vRA:5480/config/snmp/disable

Results

After the VMware SNMP daemon is configured and running, you can access the vRealize
Automation node agent on port 161. For authentication, you use the same user name and
password that you used to configure SNMP. To encrypt the channel, you use the same
channel_encryption_password that you used to encrypt the channel between the vSNMPD and
the SNMP server.

VMware, Inc. 406

Related Tools and Documentation
18
In addition to the provided use case code snippets, you can expand your options for working
with the vRealize Automation REST API by using related tools and documentation.

You can use the vRealize CloudClient to simplify your interaction with the vRealize Automation
REST API. You can also use third party tools such as Chrome Developer Tools or Firebug to
further expand your vRealize Automation REST API programming options.

This chapter includes the following topics:

n Using vRealize CloudClient

n Using Third Party Tools

Using vRealize CloudClient

vRealize CloudClient is a separate command-line utility that provides a unified interface for
working with the vRealize Automation APIs.

For information about vRealize CloudClient, see the VMware Developer site at https://
developercenter.vmware.com/tool/cloudclient.

Enabling vRealize CloudClient Multi-Factor Authentication for

vRealize Automation Users
To provide a higher level of security than basic username and password authentication, you can
enable vRealize CloudClient to use multi-factor authentication with vRealize Automation.

Configuring vRealize CloudClient for multi-factor authentication is a two-step process. First,

the vRealize Automation administrator creates or registers a new OAuth2 client in vRealize
Automation. Then vRealize CloudClient uses the new client to obtain an access token from
vRealize Automation.

Creating the New OAuth2 Client

The vRealize Automation administrator runs a command to create a new OAuth2 client. Any
vRealize CloudClient user who wants to authenticate with vRealize Automation needs the new
OAuth2 client ID and secret.

VMware, Inc. 407

Programming Guide

Creating a new OAuth2 client in vRealize Automation is a privileged operation. To create a new
OAuth2 client, the administrator must authenticate with vRealize Automation using an existing
client ID and secret.

Obtaining the Existing OAuth2 Client ID and Secret

During the initial deployment of vRealize Automation, an OAuth2 client is created for internal use.
The vRealize Automation administrator logs in to the vRealize Automation virtual appliance as
root using SSH and runs the following commands to obtain the client ID and secret.

n To obtain the existing client ID.

$(grep -i csp-admin= /etc/vcac/solution-users.properties | sed -e 's/csp-admin=//')

n To obtain the existing client secret.

$ (grep -i csp-admin.secret /etc/vcac/solution-users.properties | sed -e 's/csp-

admin.secret=//'| xargs -n 1 vcac-config prop-util -d --p)

Creating the New OAuth2 Client

To create a new OAuth2 client, the vRealize Automation administrator logs in to vRealize
CloudClient and runs the following command.

CloudClient> vra oauth2client create --server <vra-server-fqdn>

--tenant <tenant-id>
--newoauth2clientid <cc-oauth2-client-id>
--newoauth2clientsecret <cc-oauth2-client-secret>
--existingoauth2clientid <existing-oauth2-client-id>
--existingoauth2clientsecret <existing-oauth2-client-secret>
--port <port-number>
--accesstokenttl <token-lifetime-in-seconds>
--refreshtokenttl <token-lifetime-in-seconds>

Table 18-1. Input parameters for the vra oauth2client create command

Parameter Description

vra-server-fqdn Hostname of the vRealize Automation server

tenant-id Tenant with which the user is authenticating

cc-oauth2-client-id ID of the new OAuth2 client provided by the vRealize

Automation administrator

cc-oauth2-client-secret Secret of the new OAuth2 client provided by the vRealize

Automation administrator

existing-oauth2-client-id ID of existing OAuth2 client registered with vRealize

Automation

existing-oauth2-client-secret Secret of existing OAuth2 client registered with vRealize

Automation

VMware, Inc. 408

Programming Guide

Table 18-1. Input parameters for the vra oauth2client create command (continued)

Parameter Description

port-number Port on the physical machine where vRealize CloudClient

is running. vRealize Automation sends the OAuth2
authorization code to the vRealize CloudClient listener on
this port.

token-lifetime-in-seconds (optional) Number of seconds from generation to

expiration of the access token that is to be generated
when the OAuth2 Client ID and secret are used during
authentication by the end user. If unspecified, the default
value is 3600 or 1 hour.

token-lifetime-in-seconds (optional) Number of seconds from generation to

expiration of the refresh token that is to be generated
when the OAuth2 Client ID and secret are used during
authentication by the end user. If unspecified, the default
value is 2592000 or 30 days.

If the command is successful, the following output appears.

Successfully created OAuth2 Client

In a large organization, a vRealize Automation administrator may want to create an OAuth2 client
per business group rather than per individual user. vRealize CloudClient end users in the same
business group would use the same OAuth2 client. If a user were to leave the organization, the
administrator would delete the existing OAuth2 client and create a new client for the business
group.

Obtaining the Access Token

With the new OAuth2 client information provided by the vRealize Automation administrator, the
vRealize CloudClient end user can use vRealize CloudClient to obtain an access token that is later
used when vRealize CloudClient makes vRealize Automation API calls.

Understanding How Multi-Factor Authentication Works with vRealize Automation

When the end user enters the vRealize CloudClient command to obtain an access token,
this initiates the Authorization Code Grant flow process. A browser opens with the vRealize
Automation login page and the user provides login credentials. Once vRealize Automation
validates the credentials, it generates an authorization code and sends it to the port on
the machine where vRealize CloudClient is running. When vRealize CloudClient receives the
authorization code, it provides the code along with the new OAuth2 client ID and client secret
to vRealize Automation so that vRealize Automation can provide the access token to vRealize
CloudClient.

In addition to the access token used to authenticate the current vRealize CloudClient session,
vRealize Automation provides a refresh token that is a valid for a longer period and can be used
to obtain a new access token after the initial access token expires.

VMware, Inc. 409

Programming Guide

Obtaining the Initial Access Token and Refresh Token

To obtain the initial access token and a refresh token, the vRealize CloudClient end user runs the
following command.

CloudClient> vra login authzcode --server <vra-server-fqdn>

--tenant <tenant-id>
--oauth2clientid <cc-oauth2-client-id>
--oauth2clientsecret <cc-oauth2-client-secret>
--port <port-number>

Table 18-2. Input parameters for the vra login authzcode command

Parameter Description

vra-server-fqdn Hostname of the vRealize Automation server

tenant-id Tenant with which the user is authenticating

cc-oauth2-client-id ID of the new OAuth2 client provided by the vRealize

Automation administrator

cc-oauth2-client-secret Secret of the new OAuth2 client provided by the vRealize

Automation administrator

port-number Port on the physical machine where vRealize CloudClient

is running. vRealize Automation sends the OAuth2
authorization code to this port.

The output includes a refresh token, such as

refreshToken=[2Cov05jaxFWSJaNbxlBDAsCcyH2HkOci].

Obtaining a New Access Token with the Refresh Token

To obtain a new access token using a refresh token, the vRealize CloudClient end user runs the
following command.

CloudClient> vra login refreshtoken --server <vra-server-fqdn>

--tenant <tenant-id>
--oauth2clientid <cc-oauth2-client-id>
--oauth2clientsecret <cc-oauth2-client-secret>
--refreshtoken <refresh-token>

Table 18-3. Input parameters for the vra login refreshtoken command

Parameter Description

vra-server-fqdn Hostname of the vRealize Automation server

tenant-id Tenant with which the user is authenticating

cc-oauth2-client-id ID of the new OAuth2 client provided by the vRealize

Automation administrator

VMware, Inc. 410

Programming Guide

Table 18-3. Input parameters for the vra login refreshtoken command (continued)

Parameter Description

cc-oauth2-client-secret Secret of the new OAuth2 client provided by the vRealize

Automation administrator

refresh-token Refresh token obtained from the vra login authzcode

command.

The output is a new refresh token.

Cron jobs or other scheduled jobs can use vra login refreshtoken and a refresh-token to
authenticate with vRealize Automation. This avoids the browser interaction requiring username
and password credentials that is part of the vra login authzcode authentication process.

Using Third Party Tools

You can use third party tools such as Chrome Developer Tools or Firebug to reveal the data that
you can then use to construct a vRealize Automation REST API service call.

You can adapt these steps to perform a different action, such as adding a tenant.

Prerequisites

This example shows how you might use the Chrome Developer Tools to perform a catalog
service query. This option is not available for all vRealize Automation functions.

n Open a Chrome browser session and log in to the vRealize Automation console as a business
group user with access to catalog items.

n Open a command prompt or a shell and log in to the vRealize Automation command line
interface.

Procedure

1 Click the Catalog tab in the vRealize Automation console.

2 Click the catalog Item you want to request.

3 Enter the request information for the catalog item, but do not submit your changes.

4 Press the Ctrl-Shift-I keys simultaneously to open the Chrome Developer Tools. For example:

a Click the Network tab.

b Click Record Network Log.

c Click Submit in the console.

VMware, Inc. 411

Programming Guide

5 Verify that the network logs in the Chrome Developer Tools contain the relevant data. For
example:

a Locate a makeRequest POST in the network recordings.

b Click makeRequest POST to view its details.

c Scroll to view the Form Data url and postData sections.

The url section shows the vRealize Automation service and URI for you to use. This example
uses the catalog-service, under the uri consumer/requests.

The postData section shows the JSON data passed in the HTTP POST call. You can insert the
JSON data in a JSON file, for example request.json, and submit it with the POST method in
the command line.

Note Click Clear to purge the network logs if they become too large to navigate easily.

6 Enter the following call in the vRealize Automation shell, where the request.json text file
contains the JSON data from the postData section.

rest post --headers --service catalog-service --uri consumer/requests --data request.json

This call makes the same request that was submitted by using the console.

VMware, Inc. 412

Filtering and Formatting REST API
Information 19
You can filter and format your vRealize Automation REST API command line and command line
output.

You can use filters in your command line to limit JSON output to specific conditions. For example,
you can use a filter in a catalog item request to display only catalog items that contain a specific
catalog ID. Or you can use the requestID resource call to format the output of a command that
displays request status. You can also use an Odata equivalent to format that same information
For details, see Syntax for Getting Information for a Catalog Item.

Note You must URL encode all filter parameters when using curl commands.

You can also reduce command line errors by using a JSON formatter to validate the JSON data
and present it in an easy-to-read format.

You can use command line options or JSON formatting tools, such as Open Data Protocol
(OData), to control the JSON results of your vRealize Automation REST API commands.

To simplify your JSON output, consider using command line options or a to filter out unnecessary
data and display only the information that you are interested in, such as the following information
categories:

n Published catalog items

n Request status

n Provisioned machine identifiers

VMware, Inc. 413