VMware vRealize Automation - 7.0 Programming Guide
Programming Guide
vRealize Automation 7.0
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
Copyright © 2008–2018 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc. 2
Contents
vRealize Automation Programming Guide 6
Updated Information 7
1
Overview of the vRealize Automation REST API 8
2
REST API Authentication 10
3
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
4
Create a Tenant 16
Syntax for Displaying Your Current Tenants 19
Syntax for Requesting a New Tenant 21
Syntax for Listing All Tenant Identity Stores 24
Syntax for Linking an Identity Store to the Tenant 27
Syntax for Searching LDAP or Active Directory for a User 31
Syntax for Assigning a User to a Role 33
Syntax for Displaying all Roles Assigned to a User 33
Request a Machine 36
Syntax for Listing Shared and Private Catalog Items 38
Syntax for Getting Information for a Catalog Item 41
Syntax for Getting a Template Request for a Catalog Item 44
Syntax for Requesting a Machine 48
Syntax for Viewing Details of a Machine Request 51
Approve a Machine Request 55
Syntax for Listing Work Items 56
Syntax for Getting Work Item Details 62
Syntax for Constructing a JSON File to Approve a Machine Request 67
Syntax for Approving a Submitted Machine Request 70
List Provisioned Resources 72
Syntax for Displaying Your Provisioned Resources 73
Syntax for Displaying Provisioned Resources by Resource Type 75
Syntax for Displaying All Available Resource Types 78
Syntax for Displaying Provisioned Resources by Business Groups You Manage 80
VMware, Inc.
3
Programming Guide
Manage Provisioned Deployments 91
Working with Reservations 106
Working with Reservation Policies 278
Working with Key Pairs 289
Working with Network Profiles 303
Import and Export Content 371
Syntax for Viewing Machine Details 87
Syntax for Getting Deployment Details 93
Syntax for Navigating to the Children of a Deployed Resource 97
Perform a Day 2 Action: Power Off 103
Perform a Day 2 Action: Change Lease 104
Create a Reservation 106
Display a List of Reservations 256
Update a Reservation 267
Delete a Reservation 276
List Reservation Policies 278
Create a Reservation Policy 281
Display a Reservation Policy by ID 283
Update a Reservation Policy 285
Delete a Reservation Policy 287
Get a Key Pair List 289
Create a Key Pair 294
Query a Key Pair 297
Update a Key Pair 298
Delete a Key Pair 301
Get a Network Profile List 303
Create a Network Profile 342
Query a Network Profile 345
Update a Network Profile 367
Delete a Network Profile 370
Syntax for Listing Supported Content Types 373
Syntax for Listing Available Content 377
Syntax for Filtering Content by Content Type 380
Syntax for Creating a Package for Export 382
Syntax for Listing Packages in the Content Service 383
Syntax for Exporting a Package 385
Syntax for Validating a Content Bundle Before Importing 386
Syntax for Importing a Package 388
Understanding Blueprint Schema 390
Manage XaaS Content with Import and Export 392
Filtering and Formatting REST API Information 396
5
VMware, Inc. 4
Programming Guide
Related Tools and Documentation 397
6
Using the vRealize Automation REST API Reference 397
Using vRealize CloudClient 398
Using Third Party Tools 398
VMware, Inc. 5
vRealize Automation Programming Guide
The Programming Guide provides information about the vRealize Automation REST APIs, including how
to use the REST API services and resources, create HTTP bearer tokens for authentication and
authorization, and construct REST API service calls.
Intended Audience
This information is intended for administrators and programmers who want to configure and manage
vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on
common use cases. For related information about all available REST API services, see in REST 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.
6
Updated Information 1
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
EN-001841-01
EN-001841-00 Initial 6.2 release.
n
Removed the section titled Logging in Programmatically.
n
Removed the section titled Using the API Explorer.
VMware, Inc. 7
Overview of the
vRealize Automation REST API 2
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 2‑1. vRealize Automation REST API Services
Service Description
Advanced Designer Service Manage XaaS elements such as forms, endpoints, XaaS blueprints,
tenants, vRealize Orchestrator imports, workflows, and work items
through the Advanced Designer Service.
The Advanced Designer Service service relates to XaaS in the
vRealize Automation console user interface.
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 Access and manage all services and serves as the central view for all
service lookups.
Composition Service Access and manage blueprints.
Content Management Access and manage the content controller and package controller for
export and import processes. This includes export and import for
blueprints and software.
Event Broker Service Provide a central location and a consistent way of recording events and
querying for events.
Fabric Service Access and manage key pairs and network profiles.
Identity Service Manage tenants, business groups, SSO and custom groups, users, and
identity stores.
Licensing Service Retrieve permissions and post serial keys.
VMware, Inc. 8
Programming Guide
Table 2‑1. vRealize Automation REST API Services (Continued)
Service Description
Management 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.
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.
Reservation Service Retrieve, create, update, and delete a reservation or reservation policy.
Software Services Manage software component types, software resource requests, and
nodes (machines).
vCO Service Manage vRealize Orchestrator actions, tasks, packages, and workflows.
Browse system and plug-in inventories.
WorkItem Service Retrieve, create, update, complete, cancel, and delete a work item. Also
retrieve form data, metadata, detail forms, and submission forms from
service providers.
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 REST API Reference and the REST API Reference in the vRealize Automation
Documentation Center at https://www.vmware.com/support/pubs/vcac-pubs.html.
VMware, Inc. 9
REST API Authentication 3
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.
For information about requesting a bearer token, see the Identity option on the REST API Reference
landing page.
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.
The root URL for HTTP bearer calls is https://$vra_server/identity/api/tokens.
Configure the Duration of an HTTP Bearer Token
You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties file on the
vRealize Automation appliance.
VMware, Inc.
10
Programming Guide
The effective duration or lifetime of an HTTP bearer token depends on the duration of its corresponding
SAML token, which the SSO server creates at request time. An HTTP bearer token expires when it
reaches the end of its configured duration, or at the end of the configured duration of the SAML token,
whichever comes first. For example, if the configured duration is three days for the HTTP bearer token
and two days for the SAML token, the HTTP bearer token expires in two days. A configuration setting on
the SSO server determines the duration of SAML tokens.
Prerequisites
n
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specified
when you deployed the appliance.
n
The /etc/vcac/security.properties file on the appliance must be editable.
Procedure
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
n
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a
role, log in as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc. 11
Programming Guide
Procedure
u
Enter a curl command in the following format, replacing the variables with the correct values.
The variable $vRA used in this example represents the host name.domain name of the
vRealize Automation server, for example, mycompany.mktg.mydomain.com.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}'
https://$vRA/identities/api/tokens
For example, enter the following command line:
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"TenantAdminUser @example.com","password":"password","tenant":"MYCOMPANY"}'
https://vra.mycompany.com/identities/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
n
Request an HTTP Bearer Token.
Procedure
u
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
n
Request an HTTP Bearer Token.
Procedure
u
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 4
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 REST 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.
This chapter includes the following topics:
n
Create a Tenant
n
Request a Machine
n
Approve a Machine Request
n
List Provisioned Resources
n
Manage Provisioned Deployments
n
Working with Reservations
n
Working with Reservation Policies
n
Working with Key Pairs
n
Working with Network Profiles
n
Import and Export Content
Create a Tenant
You can use the REST API identity service to create a vRealize Automation tenant and perform related
functions. Perform the tasks required to create a tenant with the REST API in sequence. For information
about creating and working with tenants and roles by using thevRealize Automation application user
interface, see the Tenant Administration and IaaS Configuration documentation.
Prerequisites
n
Log in to vRealize Automation as a system administrator and a tenant administrator.
VMware, Inc.
16
Programming Guide
n
Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity
server.
n
Verify that the identity server details required for the JSON template are available.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
If you are not using the API Explorer, verify that you have a valid HTTP bearer token that matches
your login credentials. See Chapter 3 REST API Authentication.
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",
"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.
Example 2
Specify the parameters for the tenant
request by using inline text.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data
@C:\Temp\newTenant.json
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}'
VMware, Inc. 17
Programming Guide
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",
"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 "{}"
VMware, Inc. 18
Programming Guide
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.
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. 19
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.
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.
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. 20
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. 21
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.
$enantName 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. 22
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.
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.
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
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.
VMware, Inc. 23
Programming Guide
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.
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:
n
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.
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.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
VMware, Inc. 25
Programming Guide
Example: curl Command
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. 26
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:
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",
VMware, Inc. 27
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. 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.
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.
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. 29
Programming Guide
Example JSON Input File
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",
"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"
}
Example: curl Command
The following example command calls the example JSON text file and links an identity store to a tenant.
The command also tests that vRealize Automation can connect to the identity store successfully. If the
command finishes successfully,vRealize Automation succeeded in connecting to the identity store.
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
Example: JSON Output
This output 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,
VMware, Inc. 30
Loading...