Updating and retrieving custom properties in vRA7

Custom properties are the corner stone of vRA to enable customization of the deployment of a blueprint. They influence the deployment process within vRA and can be transferred to vRO to customize the blueprint deployment. In this blog post I describe the limitations, in regards of passing information between workflows, of the standard payload mechanism and how you can circumvent them.

Standard payload mechanism

Each vRA request passes trough a number of predefined Extensibility (EBS) states during deployment. These EBS states are typically used to integrate with external systems during the deployment to ensure the deployed item adheres to the requirements. The vRA custom properties are passed to vRealize Orchestrator via the payload (type: properties) input parameter in the workflows. The vRO workflow can then use the payload properties to customize the deployment.

Updating the custom properties from a vRO workflow can be achieved via the builtin process by using the virtualMachineAddOrUpdateProperties (type: properties) output parameter on the workflow. The properties added to virtualMachineAddOrUpdateProperties output parameter are updated on the payload during an EBS state change. The downsides of this mechanism are

• Any workflow executed within the same EBS phase needs to access the updated properties via payload.virtualMachineAddOrUpdateProperties, as the properties in the payload itself are only updated on a EBS state change.
• More importantly virtualMachineAddOrUpdateProperties can only be used during the successful execution path of a workflow. The virtualMachineAddOrUpdateProperties output parameter’s content is not added to the payload whenever a workflow fails. Meaning yThe downside however is that the virtualMachineAddOrUpdateProperties output parameter can only be used in the successful execution path of a workflow. Thus this mechanism cannot be used when you need to update the custom properties during error handling.

Updating payload via actions

The vRO library contains an action called addUpdatePropertyFromVirtualMachineEntity, located in com.vmware.library.vcac, which updates the properties on the virtual machine entity when its executed. No need to wait for the EBS phase change before the custom properties are actually updated.

Using this action is however only part of the solution when you need to use the updated custom properties in one of the other workflows executed during the same EBS phase. The payload is only generated once at the start of the EBS phase and each workflow receives the same payload regardless if the custom properties have been updated or not.

Retrieving custom properties

In case you need to both update the properties in a workflow and retrieve the updated properties in the other workflows, executed in the same EBS phase, then you cannot rely on the payload mechanism. Instead we need to handle retrieving the properties from the deployed VM as well as updating them during the workflow execution in the code.

At the start of the workflow we retrieve the up-to-date properties directly from the VM entity. This is achieved by executing below action. This action ensures we have the latest properties including any updates done previously during the EBS phase.

 1/**
 2 * Returns the properties currently applicable to the Virtual Machine Entity. The properties returned properties are up-to-date even if they were added or updated withing the same vRA EBS state.
 3 * @author Stijn Vermoesen
 4 * @version 1.0.0
 5 * @function getUpToDateVirtualMachineProperties
 6 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 7 * @param {string} machineId - The virtual machine ID
 8 * @returns {Properties} Returns an properties element.
 9 */
10
11System.log("Getting updated properties from vRA.");
12var vcacLibrary = System.getModule("com.vmware.library.vcac");
13
14try {
15    var vmEntity = vcacLibrary.getVirtualMachineEntityFromId(host, machineId)
16    var vcacVM = vmEntity.getInventoryObject();
17    virtualMachineProperties = new Properties();
18
19    var vmEntitiesProperties = vmEntity.getLink(vcacHost, "VirtualMachineProperties");
20    System.log("------------- Up-to-date properties (start) -------------");
21    // Reading up-to-date custom properties from vRA to retrieve properties changed within the same EBS state. Payload does not contain updated info executed within the smae EBS state.
22    for each (var vmEntityProperties in vmEntitiesProperties){
23            var propertyName = vmEntityProperties.getProperty("PropertyName");
24            var propertyValue = vmEntityProperties.getProperty("PropertyValue");
25            virtualMachineProperties.put(propertyName, propertyValue);
26    }
27    System.debug(JSON.stringify(virtualMachineProperties, null, 2));
28    System.log("------------- Up-to-date properties (end) -------------");
29}
30catch (e)
31{
32    System.error("Action failed to retrieve virtual machine's properties. " + e);
33}
34return vmEntitiesProperties;

Now that we have retrieved the properties from the vRA entity we can execute the rest of the workflow. These properties are up-to-date and contain the latest information.

Storing property updates

Using properties should be standard knowledge when working with vRO but I am adding a small example for completeness.

1// storing properties example
2vmAddOrUpdateProperties.put("be.stijnvermoesen.state","success");

Updating custom properties

Add the end of the workflow we trigger the execution of the addUpdatePropertyFromVirtualMachineEntity action. This action updates the custom properties on the virtual machine entity with the values updated during the workflow execution. This action can also be triggered during the error handling of your workflow to update the properties as its nor relying on output parameters.

 1/**
 2 * Adds or updates the virtual machine properties.
 3 * @author Stijn Vermoesen
 4 * @version 1.0.0
 5 * @function updateVirtualMachineProperties
 6 * @param {vCAC:VCACHost} vcacHost - The vCAC Host.
 7 * @param {string} machineId - The virtual machine ID
 8 * @param {Properties} vmAddOrUpdateProperties - The properties that need to be added or updated.
 9  */
10
11var vcacLibrary = System.getModule("com.vmware.library.vcac");
12
13try{
14    var vmEntity = vcacLibrary.getVirtualMachineEntityFromId(vcacHost, machineId)
15
16    System.log("Updating properties:");
17    for (var property in vmAddOrUpdateProperties){
18            // Retrieving propety name and value
19            var propertyName = property;
20            var propertyValue = vmAddOrUpdateProperties[property];
21
22            System.log("    Property: " + propertyName + " : " + propertyValue);
23            // Triggering update action for the property
24            vcacLibrary.addUpdatePropertyFromVirtualMachineEntity(vcacHost,vmEntity,propertyName,propertyValue,propertyIsHidden,propertyIsRuntime,propertyIsEncrypted,doNotUpdate) ;
25    }
26    System.log("Finished updating properties");
27}
28catch (e){
29    System.error("Action failed to update the virtual machine's properties. " + e);
30}

By handling the retrieving and updating of the custom properties in your workflow itself, and not relying on the builtin mechanism, you enable passing information between workflows, executed in the same EBS phase, and updating custom properties during workflow error handling.