vRealize Automation Properties Service API

Property Service API Specification

What Is the Property Service?

The property service provides APIs to manage property definitions and property groups.

Typical Use Cases

You can use the property service REST API to:

  • Create, update, and delete property definitions.
  • Retrieve permissible values for property definitions.
  • Create, update, and delete property groups.

Key Concepts

Custom Property

A custom property is a string key-value pair that can be associated with some object types in vRealize Automation. Custom properties provide a mechanism to annotate objects with custom attributes and can be used to invoke custom behavior during provisioning.

Custom properties have the following attributes:

  • Name - the identifier for this custom property. It is a user-provided string value and must be unique within the object on which the property is defined.
  • Value - the value to assign to this property. The value is optional.
  • Show in Request - a flag indicating whether this property should be shown on a request form. If true, the request form will present this property as an input for the requesting user.
  • Encrypted - a flag indicating whether the value of the property should be encrypted.

Property Definition

A property definition provides request-time enhancement for custom properties. Without a corresponding property definition, a custom property that is displayed on a request form appears as a simple text input field.

Property definitions allow you to customize the way a property appears to show a type-specific control. For example, by defining a property definition, you can configure a custom property that represents a true or false value to appear as a checkbox.

Property Groups

A property group is a named collection of custom properties. Some vRealize Automation objects (for example, blueprints) allow linking property groups as well as individual custom properties. This allows properties to be grouped into logically dependent sets. For example, a property group might define a set of custom properties that configure a virtual machine to be deployed into a particular environment.

Custom properties in property groups behave the same way as custom properties defined directly on any other type of vRealize Automation object.

Tenancy

Property groups and property definitions may be either tenanted or global:

  • Tenanted property groups and definitions are accessible only in the tenant they are defined in. Tenanted property groups and definitions may be created by tenant administrators.
  • Global property groups and definitions are accessible to any tenant. Global property groups and definitions may be created by fabric group administrators and system administrators.

A user who is both a tenant administrator and a fabric group administrator or system administrator can create either global or tenanted property groups and definitions.

Unique Identifiers

Property groups and property definitions have user-specified unique identifiers. This supports referencing both types of object in blueprints as code. However, to maximize portability of both types of object across tenants and vRealize Automation systems, the tenant ID is not part of the reference. This requires that unique identifiers satisfy the following uniqueness constraint:

  • A tenanted property group cannot have the same ID as another global property group. It may, however, have the same ID as a property group in another tenant.
  • A global property group cannot have the same ID as another tenanted property group in any tenant.

In effect, a property group's identifier can be used by either:

  • Any number of tenanted property groups but no global ones.
  • A single global property group but no tenanted ones.

The same rules apply for property definitions.

Permissible Values

A property definition may define a field as a dropdown. In this case, the definition must also define the values of that dropdown. It may do this in one of two ways:

  • A static list of values.
  • A list of values retrieved by executing a vRealize Orchestrator (vRO) script action.

The property service provides an API to retrieve the permissible values of a property definition. In the case of a static list, this is redundant, because the list is also provided as part of the property definition object itself. However, in the case where the list if populated by a vRO script action, the action is invoked every time the list must be rendered and so the values API must be called to retrieve these values.

How the Property Service Works

The property service works as follows:

  1. Tenant administrators and fabric administrators define property groups and property definitions as required.
  2. Blueprint authors link property groups to their blueprints and define other custom properties as required.
  3. At request time, references to property groups are resolved and properties from any linked property groups are unwrapped and set directly on the component to which the property group was attached.
  4. At request time, the request form queries the property dictionary for any property definitions matching custom properties that are to be displayed on the request form.
  5. The request form renders the custom properties according to their corresponding property definitions

API Usage Examples

Retrieve Dropdown Values for a Property Definition

First, create a property definition. In this example, the property definition is for a property called "costcenter" that retrieves a set of cost centers from an external system via a vRO script action.

PUT /api/propertydefinitions/costcenter

{
 "id" : "costcenter",
 "label" : "Cost Center",
 "description" : null,
 "dataType" : {
   "type" : "primitive",
   "typeId" : "STRING"
 },
 "isMultiValued" : false,
 "displayAdvice" : "DROPDOWN",
 "tenantId" : "tenant1",
 "orderIndex" : null,
 "permissibleValues" : {
   "type" : "dynamic",
   "customAllowed" : false,
   "dependencies" : [ ],
   "context" : {
     "providerEntityId" : "org.example.accounts/getCostCenters"
   }
 }
}

Now, the values associated with this property definition can be retrieved by calling the API below:

POST /api/propertydefinitions/costcenter/values

{
  "tenantId" : "pepsi",
  "dependencyValues" : {
    "entries" : [ ]
  },
  "associateValue" : null
}

The response from this call is the list of values:

{
 "values": [
   {
     "underlyingValue": {
       "type": "string",
       "value": "1003"
     },
     "label": "Research & Development"
   },
   {
     "underlyingValue": {
       "type": "string",
       "value": "4896"
     },
     "label": "Human Resources"
   },
   {
     "underlyingValue": {
       "type": "string",
       "value": "6783"
     },
     "label": "Manufacturing"
   }
 ]
}

Additional Information

For more detailed information on using the property service API, refer to:

  • The Custom Properties Reference topic in the VMWare vRealize Automation Information Center documentation.

  • The vRA Programming Guide.

  • The vRO User Guide.

 

Related Documentation

Related SDKs

Related Sample Code

  • vRealize Automation - Properties Service

    Contributor VMware

    vRealize Automation - Properties Service The property service provides APIs to manage property definitions and property groups. Available Use Cases Manage property definitions Manage property groups ...
    api_vra_properties vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation property definition and property group tool kit

    Contributor qc4vmware

    I figured I'd share what I just put together since the vRO plugin for vRA only has create and delete workflows and associated actions.  This package adds the ability to copy between vRA instances, ove ...
    vRealize Automation vRealize Orchestrator Plug-in SDK vRO Package
    Download

    1 Favorite

    0 Comments

    Updated 2 years ago

  • vRealize Automation API Samples for Postman

    Contributor nsb24

    vRealize Automation API Samples for Postman Overview The vRealize Automation REST API provides consumers and administrators access to all services in its service catalog that support the vRealize Auto ...
    vRealize Automation POSTMAN Collection
    Download

    1 Favorite

    0 Comments

    Updated 1 month ago

  • vRealize Automation - Catalog Service

    Contributor VMware

    vRealize Automation - Catalog Service The catalog service REST API is designed to be used by the consumers of the service catalog; for example, an end user who wants to request a catalog item would be ...
    api_vra_catalog vRealize Automation api_vra_composition POSTMAN Collection
    Download

    1 Favorite

    0 Comments

    Updated 4 months ago

  • vRealize Automation - NSX Integration

    Contributor VMware

    vRealize Automation - NSX Integration NSX integration in vRealize Automation can help creating and configuring existing networks, on-demand NAT networks and on-demand routed networks, creating load ba ...
    vRealize Automation api_vra_network POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - Composition Service

    Contributor VMware

    vRealize Automation - Composition Service The composition service allows vRA services to register application components, which the composition service manages so that they can be used in composite bl ...
    vRealize Automation api_vra_composition POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - Identity Service

    Contributor VMware

    vRealize Automation - Identity Service Identity service manages tenants, business groups (formerly named subtenants), groups (both Single-Sign-On and Custom groups), users and identity stores. It also ...
    vRealize Automation api_vra_identity POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • VMware vRealize Automation Plugin

    Contributor kr1s

    Jenkins vRealize Automation Plugin The vRealize Automation Jenkins plugin enables Jenkins to provision vRealize Automation 7 Blueprints. Requirements Jenkins 1.58+ Java 8 to compile plugin or Java 7 ...
    vRealize Automation Java
    Download

    3 Favorites

    1 Comment

    Updated 8 months ago

  • vRealize Automation - Component Registry

    Contributor VMware

    vRealize Automation - Component Registry Component Registry manages all services (including out-of-the-box services and services from third party solution providers) and serves as the central view for ...
    api_vra_component_registry vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - Management Service API

    Contributor VMware

    vRealize Automation - Management Service API You can use the reclamation service to query the VMs in an installation for non-usage and, if they are not in use, mark them as eligible for reclamation. ...
    vRealize Automation api_vra_management POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - Content Management Service

    Contributor VMware

    vRealize Automation - Content Management Service You can use the content management service REST API to import and export content, such as blueprints, software components, and other artifacts, from vR ...
    vRealize Automation api_vra_content_management api_vra_composition POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - Event Broker

    Contributor VMware

    vRealize Automation - Event Broker The event broker provides features for managing subscriptions, event topics, events, and messages. Available Use Case Get event topics Registers or updates an Even ...
    vRealize Automation api_vra_event_broker POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • Extend Disk vRealize Automation Workflow

    Contributor robertshaw

    This VMware Orchestrator workflow package will extend the C drive of a virtual disk in vRealize Automation from a vCenter (vSphere) machine template blueprint. The workflow receives a payload of prope ...
    vRealize Orchestrator Plug-in SDK vRealize Automation vRO Package
    Download

    1 Favorite

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Branding

    Contributor VMware

    vRealize Automation - Branding The Branding service enables the user to customize the VRA UI header and footer. The configurable properties include logo image, company name, product name, background c ...
    api_vra_branding vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - Approval Service

    Contributor VMware

    vRealize Automation - Approval Service The approval service provides features for managing and tracking the human approval tasks associated with a service process/artifact in a provider realm. It also ...
    api_vra_approval vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • vRealize Automation - WorkItem Service

    Contributor VMware

    vRealize Automation - WorkItem Service The work item service provides a standard way for services to present work items to users. It manages the life-cycle of a work item and passes events back to the ...
    api_vra_approval api_vra_workitem vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 4 months ago

  • Project Bosphorus

    Contributor prydin

    Project Bosphorus Background This project is aimed at providing a custom portal framework for vRealize Automation (vRA) along with a reference implementation. It is intended for advanced users/develop ...
    vRealize Automation Java
    Download

    1 Comment

    Updated 1 year ago

  • vRealize Automation Reference Application

    Contributor hmichaud

    vRealize Automation Reference Application Overview This is a sample project that demonstrates how to create a simple self-service portal for vRealize Automation using only RESTful APIs. You are encour ...
    vRealize Automation JavaScript
    Download

    2 Favorites

    4 Comments

    Updated 1 year ago

  • vRA and Ansible Example Integration

    Contributor vm2cloud

    vRealize Automation vRO Package
    Download

    0 Comments

    Updated 3 years ago

  • vRA 7 and above prepare_vra_template.ps1

    Contributor virtualgcoburn

    Powershell script designed to deploy the needed agents on your windows template. This mimics the prepare_vra_template.sh file for linux and will deploy java, bootstrap and gugent agents from the vRA a ...
    vRealize Automation PowerShell
    Download

    1 Comment

    Updated 1 year ago

;