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:

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:

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:

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:

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

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:

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: