VMware vRealize Automation - 7.1 Programming Guide

Programming Guide

vRealize Automation 7.1

Programming Guide

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

https://docs.vmware.com/

If you have comments about this documentation, submit your feedback to

docfeedback@vmware.com

VMware, Inc.

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

VMware, Inc. 2

vRealize Automation Programming Guide 6

Overview of the vRealize Automation REST API 7

REST API Authentication 10

Using HTTP Bearer Tokens 10

Configure the Duration of an HTTP Bearer Token 10

Request an HTTP Bearer Token 11

Validate an HTTP Bearer Token 14

Delete an HTTP Bearer Token 14

REST API Use Cases 16

Create a Tenant 17

Syntax for Displaying Your Current Tenants 20

Syntax for Requesting a New Tenant 23

Syntax for Listing All Tenant Identity Stores 26

Syntax for Linking an Identity Store to the Tenant 29

Syntax for Searching LDAP or Active Directory for a User 33

Syntax for Assigning a User to a Role 35

Syntax for Displaying all Roles Assigned to a User 36

Request a Machine 38

Syntax for Listing Shared and Private Catalog Items 40

Syntax for Getting Information for a Catalog Item 43

Syntax for Getting a Template Request for a Catalog Item 47

Syntax for Requesting a Machine 51

Syntax for Viewing Details of a Machine Request 54

Approve a Machine Request 57

Syntax for Listing Work Items 58

Syntax for Getting Work Item Details 65

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

Syntax for Approving a Submitted Machine Request 73

Syntax for Updating Cost Information 75

List Provisioned Resources 78

Syntax for Displaying Your Provisioned Resources 79

Syntax for Displaying Provisioned Resources by Resource Type 81

Syntax for Displaying All Available Resource Types 84

Syntax for Displaying Provisioned Resources by Business Groups You Manage 86

Syntax for Viewing Machine Details 93

VMware, Inc.

Programming Guide

Manage Provisioned Deployments 97

Working with Reservations 112

Working with Reservation Policies 285

Working with Key Pairs 296

Working with Network Profiles 310

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

Import and Export Content 359

Syntax for Getting Deployment Details 99

Syntax for Navigating to the Children of a Deployed Resource 103

Perform a Day 2 Action: Power Off 109

Perform a Day 2 Action: Change Lease 111

Create a Reservation 113

Display a List of Reservations 263

Update a Reservation 274

Delete a Reservation 283

List Reservation Policies 285

Create a Reservation Policy 288

Display a Reservation Policy by ID 290

Update a Reservation Policy 292

Delete a Reservation Policy 294

Get a Key Pair List 296

Create a Key Pair 301

Query a Key Pair 304

Update a Key Pair 305

Delete a Key Pair 308

Get a Network Profile List 311

Create a Network Profile 327

Query a Network Profile 332

Update a Network Profile 338

Delete a Network Profile 341

Syntax for Listing Supported Content Types 362

Syntax for Listing Available Content 365

Syntax for Filtering Content by Content Type 369

Syntax for Creating a Package for Export 371

Syntax for Listing Packages in the Content Service 372

Syntax for Exporting a Package 374

Syntax for Validating a Content Bundle Before Importing 375

Syntax for Importing a Package 377

Understanding Blueprint Schema 379

Manage XaaS Content with Import and Export 381

VMware, Inc. 4

Programming Guide

vRealize Automation Programming Guide

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

Intended Audience

This information is intended for administrators and programmers who want to configure and manage vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on common use cases. For related information about all available REST API services, see in vRealize Automation API Reference at https://www.vmware.com/support/pubs/vcac-pubs.html.

VMware Technical Publications Glossary

VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation, go to

https://www.vmware.com/support/pubs/vcac-pubs.html.

VMware, Inc.

Overview of the

vRealize Automation REST API 1

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

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

Table 1‑1. vRealize Automation REST API Services

Service Description

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

instances, and policy requests.

Branding Service Change the background and text colors, company logo, company name,

product name, tenant name, and other resources in the console.

Catalog Service Retrieve global and entitled catalog items, and entitlements for a catalog

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

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

service lookups.

Composition Service Allows vRealize Automation services to register application components,

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

Content Management Service Access and manage the content controller and package controller for

export and import processes. This includes export and import for blueprints and software.

Endpoint 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.

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.

VMware, Inc. 7

Programming Guide

Table 1‑1. vRealize Automation REST API Services (Continued)

Service Description

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.

Management Service (Reclamation Service) Retrieve work item forms, callbacks, and tasks. Manage endpoint details

including tenant, password, user name, and endpoint URL. Retrieve performance metrics. Retrieve and cancel reclamation requests.

Network 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 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.

Extensibility (Plug-in) Service Retrieve, create, update, and delete a resource. Retrieve an extension.

Retrieve license notifications.

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.

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

Software Services Triggers the execution life cycle of software components using the

software agent, registers software agents, and manages the creation, modification and deletion of software componentsoftware component types, software resource requests, and nodes (machines).

vRA Orchestrator 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.

XaaS Service Manages XaaS elements such as forms, endpoints, XaaS blueprints,

tenants, vRealize Orchestrator imports, workflows, and work items.

The advanced designer service selection on the vRealize Automation API Reference landing page selects the documentation for the XaaS service.

VMware, Inc. 8

Programming Guide

When a service request contains a resource URL, the first part of the URL identifies the service and the last part identifies the resource. For example, the following resource URL identifies the catalog service and the providers resource:

https://$host/component-registry/api/services

For more information about all the vRealize Automation REST API service calls, see Using the vRealize

Automation API Reference and the vRealize Automation API Reference in your vRealize Automation

installation.

VMware, Inc. 9

REST API 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.

Using HTTP Bearer Tokens

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

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

Method URL Description

POST /tokens Authenticate the user with the identity service /tokens and

generate a new token.

HEAD /tokens/tokenID Validate the token tokenID.

DELETE /tokens/tokenID Delete the token tokenID.

Use the following root URL for HTTP bearer calls:

https://$vra_server/identity/api/tokens

Conﬁgure the Duration of an HTTP Bearer Token

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

VMware, Inc.

Programming Guide

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

Prerequisites

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

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.

The new value applies the next time someone requests an HTTP bearer token.

Request an HTTP Bearer Token

You use an HTTP bearer token to authenticate a vRealize Automation REST API consumer request .

A consumer request must specify the correct component registry service and resource. For example, the URL to obtain an HTTP bearer token must specify the identity service and token resource.

The HTTP bearer token expires in 24 hours by default. See Configure the Duration of an HTTP Bearer

Token for information on how to set the duration.

For related information, see Syntax for Requesting an HTTP Bearer Token.

Prerequisites

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

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

VMware, Inc. 11

Programming Guide

Procedure

Enter a curl command in the following format, replacing the variables with the correct values.

The variable $vRA used in this example represents the host name.domain name of the vRealize Automation server, for example, mycompany.mktg.mydomain.com.

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

--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}'

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

For example, enter the following command line:

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

'{"username":"tanteater @example.com","password":"password","tenant":"MYCOMPANY"}'

https://tanteater.eng.mycompany.com:4870/identity/api/tokens

The command returns a response header with a status code and, if your request is successful, an HTTP bearer token.

For example, the following sample output displays based on the command input:

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Cache-Control: no-cache, no-store

Pragma: no-cache

Expires: Thur, 16 Jul 2015 23:59:59 GMT

Content-Type: application/json;charset=UTF-8

Content-Length: 324

Date: Wed, 15 Jul 2015 13:04:50 GMT

{

"expires":"2015-16-01T13:09:45.619Z",

"id":"MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLmNvb

TplMDViNGU0NGM2ZWU0MWQ1OWEwMTNmZGExNTQwZjNlNGM3YTBlM2I5MDhlYWZjYjY1ZjhiODI2OTg4ODU3M2UwOTUwOWRk

MjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==",

"tenant":"MYCOMPANY"

}

What to do next

Include the HTTP bearer token in your REST API service calls. You can store the token in a variable such as $AUTH and then use the variable in your requests.

Syntax for Requesting an HTTP Bearer Token

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

Input

Use the supported input parameters to control the command output.

VMware, Inc. 12

Programming Guide

A consumer request must specify the correct component registry service and resource. For example, the URL to obtain an HTTP bearer token must contain the identity service and token resource values.

Input Description

host host name.domain name of the vRealize Automation server, for example,

mycompany.mktg.mydomain.com.

usrname Specifies the tenant administrator user name.

passwd Specifies the tenant administrator password.

tenantURLtoken Specifies the tenant URL token determined by the system administrator when creating the

tenant, for example, support.

Output

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

Output Description

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

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

tenant Displays the tenant ID associated with the token.

Response Status Codes

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

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

You can enter the following command line format to request an HTTP bearer token.

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

'{"username":"usrname",

"password":"passwd","tenant":"tenantURLtoken"}' https://$host/identity/api/tokens

When your request succeeds, the system returns the 200 OK status code, the expiration date and time of the token, and the HTTP bearer token. After receiving the bearer token, you can include it in your request headers.

VMware, Inc. 13

Programming Guide

Validate an HTTP Bearer Token

You can validate an existing HTTP bearer token.

Prerequisites

Request an HTTP Bearer Token.

Procedure

Create the request to validate the HTTP bearer token, as in the following example.

HEAD

/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O

DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==

Accept: application/json

The system returns one of the following status codes.

Status Code Description

204 NO CONTENT The request succeeded.

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

authenticated.

403 FORBIDDEN Your authentication credentials do not provide 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

Request an HTTP Bearer Token.

Procedure

Create the request to delete the HTTP bearer token, as in the following example.

DELETE

/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O

DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==

Accept: application/json

The system returns one of the following status codes.

VMware, Inc. 14

Programming Guide

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. 15

REST API Use Cases 3

Available use cases provide the prerequisite, command line options and format, and sample results to help you perform a variety of vRealize Automation functions, such as requesting a machine or creating a reservation.

You can find information about all of the available vRealize Automation REST API calls in the vRealize Automation API Reference zip file located in the vRealize Automation Documentation Center. The use cases provide samples of calls that you might commonly use and descriptions of example inputs and outputs relative to those calls.

Create a Tenant

You can use the REST API identity service to create a vRealize Automation tenant and perform related functions. Perform the tasks required to create a tenant with the REST API in sequence. For information about creating and working with tenants and roles by using thevRealize Automation application user interface, see the Tenant Administration and IaaS Configuration documentation.

Request a Machine

You can use REST API catalog service commands to complete a variety of tasks related to requesting a machine. This procedure provides sample command line syntax for machine request tasks. Supporting information regarding available input and output parameters, command-line entry samples, and sample JSON output samples is available in the subsequent topics that explain syntax for the various tasks.

Approve a Machine Request

You can use a sequence of REST API workitem service commands to approve a machine request.

List Provisioned Resources

You can use the REST API catalog service to log in to vRealize Automation and display a full or filtered list of your provisioned resources .

Manage Provisioned Deployments

You can use the REST API catalog service to log in to vRealize Automation and view information about provisioned resources .

Working with Reservations

You can work with the REST API reservation service to perform a variety of functions, such as creating and updating reservations.

VMware, Inc.

Programming Guide

Working with Reservation Policies

You can use the vRealize Automation REST API to work with the reservation service to perform a variety of functions, such as creating and updating reservation policies.

Working with Key Pairs

You can work with the keyValuePair data element of the REST API workitem service to list, create, and update key pairs.

Working with Network Profiles

You can use the vRealize Automation IaaS proxy provider service and IPAM service REST API to create, list, and update network profiles.

Get a List of Available IP Ranges for an IPAM Provider

You can query a specified IPAM provider endpoint for a list of the available IP address ranges configured on the IPAM provider device.

Import and Export Content

You can use the REST API content management service to import and export content, such as blueprints, between vRealize Automation systems.

Create a Tenant

Prerequisites

Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity server.

Verify that the identity server details required for the JSON template are available.

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

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

REST API Authentication.

Syntax for Displaying Your Current Tenants

You can use the REST API identity service to list of all the vRealize Automation tenants in your system.

Syntax for Requesting a New Tenant

You can use the REST API identity service to submit a request for a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON file from the command line.

VMware, Inc. 17

Programming Guide

Syntax for Listing All Tenant Identity Stores

You can use the REST API identity service to list all available identity stores for a named vRealize Automation tenant, such as the default tenant vsphere.local.

Syntax for Linking an Identity Store to the Tenant

You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory identity store to the vRealize Automation tenant.

Syntax for Searching LDAP or Active Directory for a User

You can use the vRealize Automation REST API identity service to search the configured LDAP directory, Active Directory, or Native Active Directory for a user.

Syntax for Assigning a User to a Role

You can use the REST API identity service to assign a user to a role.

Syntax for Displaying all Roles Assigned to a User

You can use the REST API identity service to display all of the roles assigned to a user.

Procedure

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

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants

2 Submit a request for a new tenant and either call a JSON file that contains tenant request parameters

or specify those parameters using inline text. The first example uses a JSON file as input. The second example uses inline text as input.

The first example calls the following sample newTenant.json file.

{

"@type" : "Tenant",

"id" : "development",

"urlName" : "development",

"name" : "DevelopmentTenant",

VMware, Inc. 18

Programming Guide

"description" : "Tenant for all developers",

"contactEmail" : "admin@mycompany.com",

"defaultTenant" : false

}

Examples Command

Example 1

Call the above newTenant.json file,

which contains parameters for the

tenant request.

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

-H "Authorization: Bearer $token" https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json

Example 2

Specify the parameters for the tenant

request by using inline text.

curl --insecure -H "Accept: application/json" -H "ContentType: application/json"

-H "Authorization: Bearer $token"

--data '{"@type":"Tenant","id":"development","urlName":"development"," name": "DevelopmentTenant","description":"Tenant for all developers","contactEmail": "admin@mycompany.com","defaultTenant":false}'

3 List all available identity stores for a named tenant, such as the default tenant vsphere.local by using

variables, instead of the full token and host name.domain name.

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

-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories

4 Link an LDAP, Active Directory, or Native Active Directory identity store to the tenant by using the

identity service.

Call the following sample ldap.json.txt input file from the command line to specify necessary parameters.

{

"alias": "example.com",

"domain": "example.mycompany.com",

"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

"name": "openLDAPDemo",

"password": "password",

"type": "LDAP",

VMware, Inc. 19

Programming Guide

"url": "ldap://10.000.00.000:389",

"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",

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

}

Use the following command to call the example JSON text file and link an identity store to a tenant. The command also tests that vRealize Automation can connect to the identity store successfully. If the command finishes successfully, vRealize Automation succeeded in connecting to the identity store.

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

-H "Authorization: Bearer $token”

https://$host/identity/api/tenants/development/directories/example.mycompany.com

--data @C:\Temp\ldap.json.txt

5 Query the configured LDAP directory, Active Directory, or Native Active Directory for a specific user.

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants/$tenantId/principals/$userId

6 Assign a user to a role with the REST API identity service.

Use the following command string to submit a request to assign the user tony in the domain example.mycompany.com to the tenant administrator role. It provides empty braces for the required

JSON payload.

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

-H "Authorization: Bearer $token"

"https://$host/identity/api/authorization/tenants/development/principals/

susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"

7 Display all of the roles assigned to a user with the identity service.

Use the following command to list all the roles that are assigned to tony@example.mycompany.com.

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

-H "Authorization: Bearer $token"

https://$host/identity/api/authorization/tenants/development/principals/

tony@example.mycompany.com/roles

What to do next

Syntax for Displaying Your Current Tenants

You can use the REST API identity service to list of all the vRealize Automation tenants in your system.

Input

Use the supported input parameters to control the command output.

VMware, Inc. 20

Programming Guide

Parameter Description

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

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity 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. 21

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:

rel

Specifies the name of the link.

Self refers to the object that was returned or requested. This parameter does not appear when you query a single profile.

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

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. Each tenant object can contain the following information:

Id:

Specifies the unique tenant identifier.

urlName:

Specifies the name of the tenant as it appears in URLs.

Name:

Specifies the name of the tenant for display purposes.

description:

Specifies the long description of the tenant.

contactEmail:

Specifies the primary contact email address.

Password:

Unused

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

Size: Specifies the maximum number of rows per page.

totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.

totalPages: Specifies the total number of pages of data available.

Number: Specifies the current page number.

Offset: Specifies the number of rows skipped.

VMware, Inc. 22

Programming Guide

Example: curl Command

The following example command displays all available tenants.

curl --insecure -H "Accept:text/xml"

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants

Format the XML output to improve its readability. For information about formatting output, see Chapter 5

Filtering and Formatting REST API Information.

Example: JSON Output

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

{

"links" : [ ],

"content" : [ {

"@type" : "Tenant",

"id" : "vsphere.local",

"urlName" : "vsphere.local",

"name" : "vsphere.local",

"description" : null,

"contactEmail" : null,

"password" : null,

"defaultTenant" : true

}, {

"@type" : "Tenant",

"id" : "MYCOMPANY",

"urlName" : "MYCOMPANY",

"name" : "QETenant",

"description" : "Test tenant",

"contactEmail" : null,

"password" : "defaultPwd#1",

"defaultTenant" : false

} ],

"metadata" : {

"size" : 19,

"totalElements" : 2,

"totalPages" : 1,

"number" : 1,

"offset" : 0

}

Syntax for Requesting a New Tenant

You can use the REST API identity service to submit a request for a tenant. You can specify request parameters using JSON command line input or by calling an existing JSON file from the command line.

VMware, Inc. 23

Programming Guide

Input

Use the supported input parameters to control the command output.

Parameter Description

URL https://$host/identity/api/tenants/$tenantId --data @

$inputFileName.json

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

$host Specifies the host name and fully qualified domain name or IP address

of the vRealize Automation identity server.

$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.

JSON Input File Template

To simplify command line input, create a JSON file and call that file from the command line. To create a JSON file, copy the following template to a new text file. To maintain formatting, use an XML editor. Replace the italicized variables in the template with your specific values.

{

"@type" : "Tenant",

"id" : "$tenantId",

"urlName" : "$tenantURL",

"name" : "$tenantName",

"description" : "$description",

"contactEmail" : "$emailAddress",

"defaultTenant" : false

}

Output

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

VMware, Inc. 24

Programming Guide

Parameter Description

Links Specifies an array of link objects, each of which contains the

following parts:

rel

Specifies the name of the link.

Self refers to the object that was returned or requested. This parameter does not appear when you query a single profile.

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

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. Each tenant object can contain the following information:

Id:

Specifies the unique tenant identifier.

urlName:

Specifies the name of the tenant as it appears in URLs.

Name:

Specifies the name of the tenant for display purposes.

description:

Specifies the long description of the tenant.

contactEmail:

Specifies the primary contact email address.

Password:

Unused

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

Size: Specifies the maximum number of rows per page.

totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.

totalPages: Specifies the total number of pages of data available.

Number: Specifies the current page number.

Offset: Specifies the number of rows skipped.

VMware, Inc. 25

Programming Guide

Example: curl Command

Submit a request for a new tenant and either call a JSON file that contains tenant request parameters or specify those parameters using inline text. The first example uses a JSON file as input. The second example uses inline text as input.

The first example calls the following sample newTenant.json file.

{

"@type" : "Tenant",

"id" : "development",

"urlName" : "development",

"name" : "DevelopmentTenant",

"description" : "Tenant for all developers",

"contactEmail" : "admin@mycompany.com",

"defaultTenant" : false

}

Example 1: Use the following example to call the above newTenant.json file, which contains parameters for the tenant request.

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

-H "Authorization: Bearer $token"

https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json

Example 2: Use the following example to specify parameters for the tenant request by using inline text.

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

-H "Authorization: Bearer $token"

--data '{"@type":"Tenant","id":"development","urlName":"development","name":

"DevelopmentTenant","description":"Tenant for all developers","contactEmail":

"admin@mycompany.com","defaultTenant":false}'

Syntax for Listing All Tenant Identity Stores

You can use the REST API identity service to list all available identity stores for a named vRealize Automation tenant, such as the default tenant vsphere.local.

Input

Use the supported input parameters to control the command output.

Parameter Description

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

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity server.

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

$tenantId Specifies the ID of the tenant.

VMware, Inc. 26

Programming Guide

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:

rel

Specifies the name of the link.

Self refers to the object that was returned or requested. This parameter does not appear when you query a single profile.

First, Previous, Next, and Last refer to corresponding pages of pageable lists.

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. Each tenant object can contain the following information:

Id:

Specifies the unique tenant identifier.

urlName:

Specifies the name of the tenant as it appears in URLs.

Name:

Specifies the name of the tenant for display purposes.

description:

Specifies the long description of the tenant.

contactEmail:

Specifies the primary contact email address.

Password:

Unused

defaultTenant:

Is set to True if the corresponding tenant is the default tenant (vsphere.local).

Metadata Specifies the following paging-related data:

Size: Specifies the maximum number of rows per page.

totalElement: Specifies the number of rows returned. This parameter is not output when you query for a single profile.

totalPages: Specifies the total number of pages of data available.

Number: Specifies the current page number.

Offset: Specifies the number of rows skipped.

VMware, Inc. 27

Programming Guide

Example: curl Command

The following example command lists the identity stores by using variables, instead of the full token and host name.domain name.

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

-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories

Example: JSON Output

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

HTTP/1.1 200 OK

Server: Apache-Beach/1.1

Cache-Control: no-cache, no-store

Pragma: no-cache

Expires: Wed, 31 Dec 1969 23:59:59 GMT

Content-Type: application/json;charset=UTF-8

Content-Length: 830

Date: Sat, 01 Feb 2014 13:07:54 GMT

{"links":[],

"content":[

{"@type":"IdentityStore",

"domain":"vcac.mycompany.com",

"name":"openLDAPPromocom",

"description":null,

"alias":"promocom.com",

"type":"LDAP",

"userNameDn":"cn=promocomadmin,ou=promocom,dc=vcac,dc=mycompany,dc=com",

"password":null,

"url":"ldap://10.000.00.000:389",

"groupBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com",

"userBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com"

{"@type":"IdentityStore",

"domain":"example.mycompany.com",

"name":"openLDAPDemo",

"description":null,

"alias":"example.com",

"type":"LDAP",

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

"password":null,

"url":"ldap://10.000.00.000:389",

"groupBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com",

"userBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com"

}],

"metadata":{

"size":20,

"totalElements":2,

"totalPages":1,

VMware, Inc. 28

Programming Guide

"number":1,

"offset":0

}

Syntax for Linking an Identity Store to the Tenant

You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory identity store to the vRealize Automation tenant.

Input

Use the supported input parameters to control the command output.

Parameter Description

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

$inputFileName.json

$host Specifies the host name and fully qualified domain name or IP address of the

vRealize Automation identity 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.

$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:

LDAP

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",

VMware, Inc. 29

Programming Guide

"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. 30

+ 359 hidden pages

VMware vRealize Automation - 7.1 Programming Guide

Contents

vRealize Automation Programming Guide

REST API Authentication 2

Using HTTP Bearer Tokens

Request an HTTP Bearer Token

Syntax for Requesting an HTTP Bearer Token

Validate an HTTP Bearer Token

Delete an HTTP Bearer Token

REST API Use Cases 3

Create a Tenant

Syntax for Displaying Your Current Tenants

Syntax for Requesting a New Tenant

Syntax for Listing All Tenant Identity Stores

Syntax for Linking an Identity Store to the Tenant