Monday, February 27, 2017

vRealize Event Broker and Extensibility 101

vRealize Event Broker and Extensibility 101

It's now a while that the event broker for vRealize Automation got announced and now I would like to share some of my findings and what I would recommend to do when using the event broker. Also I would like to share what I would recommend for vRealize Extensibility.

Add, Update or Delete custom properties from workflows

Of course in most Orchestrator workflows we run during provisioning, we want to get back with some information to vRealize Automation by adding or updating some custom properties. But also we have use-cases where we want to delete custom properties or force a specific event or state after our workflow.
  • add or update custom properties
To add, update or delete properties, in the "bad" old days, there was the need to get the virtual machine entity from the old vRealize Automation Orchestrator plugin and on this object do the right commands to add, update or delete properties. With the event broker we can simply output the custom properties we want to add or update using virtualMachineAddOrUpdateProperties and the event broker will take care to add or update the custom properties.
  • delete custom properties
It is nearly the same when we need to delete properties. To delete properties we must set the property name into virtualMachineDeleteProperties and the event broker will delete the custom property.

The pre-requisites to use this functionality are:

  • Your subscription must be set to blocking. This ensures the event broker waits until your workflow finishes. Otherwise it's a fire-and-forget workflow execution.
  • Your subscriptions needs to run in a PRE state phase. Only in PRE state phases custom properties will get handled by the event broker.
The following graphic illustrates how the execution of an event or state works for a single workflow and when the modified properties will get handled by vRealize Automation.

Forcing a state or event

If you want to force the event broker to set the provisioning workflow into a specific lifecycle state or event from your workflow you can also use workflow output's to do so.
  • force an event
If you want to force an event from your workflow, you can set the event name in the workflow output virtualMachineEvent. The event broker then will set the current provisioning to the event you provided. You can find all events in the official documentation: vRealize Automation 7.2 Informationcenter but it's important to use the [Triggering String] cause the real event name will not trigger anything.
  • force a lifecycle state
To force a lifecycle state you set the state name in the workflow output workflowNextState and the event broker will force the provisioning process into the state provided. You find the workflow states on the same page of the documentation than the events and you can use the real state names here.
The pre-requisites to use this functionality are:
  • Your subscription must be set to blocking.
  • Your subscription must run in a PRE state phase.

Multiple workflows in the same event or state

If you are running multiple workflows in the same state or the same event, there are some things you have to keep in mind.
First of all, how the event broker works if you run multiple workflows in the same state or event is, that vRealize Automation will only once trigger the event/state. The subscriptions then will get executed on the order set using the 'Priority' on the subscription starting at the lowest number provided. For example if you have two workflows, lets say workflowA with a priority of 20 and workflowB with a priority of 10, workflowB will get executed first.
The second thing to mention here is a special behaviour about the before mentioned functionality to add, update or delete properties and to force an event or state:
  • The workflow outputs of virtualMachineAddOrUpdateProperties and virtualMachineDeleteProperties will not handled after each workflow but on the end of the event/state meaning when all workflows are finished.
  • The same for the functionality of forcing a specific event or state.
  • Every output of a workflow will get passed to the next workflow in the same event/state as a workflow input. So if your first worklfow has an output of lets say GeneratedHostname, all other workflows in the same event or state will have an input called GeneratedHostname. This also means if your first workflow has an output called virtualMachineAddOrUpdateProperties, this will also be passed to the next workflow, even if you have there the same attribute set as a workflow output. You are going to overwrite the value of it and only the output of your last workflow of the event or state will get back to vRealize Automation. If you want to use virtualMachineAddOrUpdateProperties at multiple workflows in an event or state, you need to workaround this behaviour. I would recommend whenever you work with virtualMachineAddOrUpdateProperties to do it like this:

  • If you create virtualMachineAddOrUpdateProperties like this, you check if there is already something set to virtualMachineAddOrUpdateProperties and if it is so, it uses the already modified object. If not, it creates virtualMachineAddOrUpdateProperties as a new and empty Properties object.
  • The same of course is valid for reading custom properties. If your first workflow adds some custom properties which you want to use in your next workflow in the same event or state, you need to check the already modified virtualMachineAddOrUpdateProperties object before checking the object:
  • If you search your custom property like this, you also be sure to always go for the latest version of your custom property even if you modify the value of it in multiple workflows.

The following graphic should illustrate how the execution of multiple workflows in a single event or state works:

Passing custom properties to workflows

By default the virtual machine custom properties are not included in the payload unless they are specified as an extensibility custom property for the event or state. To pass the custom properties to a workflow you need to specify special custom properties which tells the event broker to pass the properties to your workflows. The properties are called:
So as an example if you want to pass custom properties in the BuildingMachine state to workflows you need to add a custom property called Extensibility.Lifecycle.Properties.VMPSMasterWorkflow32.BuildingMachine. The value of the property defines which custom properties get passed to the workflow. A '*' wildcard value is allowed and a single '*' will pass all custom properties to the workflow. You can comma separate multiple custom properties or combine the wildcard value with some prefixes. As an example to pass all customer related and all hidden properties to your workflow you would set the value to: '__*,Customer*' this will pass everything starting with '__' and 'Customer' to your workflow but not the custom property VirtualMachine.Network0.Address.
If you want to pass custom properties to an workflow which is subscribing an event instead of a state, you need to set the value to the custom property Extensibility.Lifecycle.Properties.VMPSMasterWorkflow32.VMPSMasterWorkflow32.
The following graphic shows a property group I'm using to pass the properties I need to the workflows I'm executing:

Custom Properties in Subscriptions

You can use custom properties in subscriptions as part of your condition. You may ask why you should do so? Here are two reasons:

  • Create a custom property for each extensibility/integration you have. This allows during development to disable or enable specific integrations for testing.
  • You can enable or disable integrations on blueprint level instead for each workflow. If you have different operating systems or blueprints including a special integration (i.e.: DMZ or something) you don't need to switch in your workflow for blueprint names (which also could change often)
To use custom properties in a subscription, you need to manually specify the property in your subscriptions condition. This follows this format: 'data~machine~properties~SomeCustomProperty'.
The following graphic shows where to enter the custom property when creating a subscription:

And here the following graphic shows how it looks after adding the custom property (in my case 'Customer.Extensibility.Infoblox'):

Error Handling

If you have any workflow which should only get executed in case an error occured, I would recommend using the function to force the next event by setting virtualMachineEvent to 'BuildFailure' and having an event subscription for all the workflows you want to execute in case of an error.

In every workflow I'm using the 'Default error handler' to set the errorCode to a custom property and then forcing the mentioned event. Also I'm having a workflow which creates an incident including the errorCode which subscribes to the event VMPSMasterWorkflow32.VMPSMasterWorkflow32.EVENT.onBuildFailure. This ensures if an error occurs in my workflows or during the provisioning by vRealize Automation, my workflow to create an incident will get executed.

Subscription Naming

Per default if you create a subscription, the name of the workflow within the subscription will be used as the name of the subscription. This makes it not easy to see to which state or event the subscription is related to. Thats why I would recommend the following naming scheme:
<subscription state or event> - <lifecycle phase> - <workflow name>
This allows to order the subscriptions by name and to see all subscriptions in the same state. Seeing the priority in the subscriptions overview helps to see the order in which the workflows of the subscriptions get executed:

Dev-Ops for vRealize Automation

As of today there is no perfect way to do Dev-Ops for vRealize Automation. If multiple persons work with extensibility in vRealize Automation by creating new properties, property groups and workflows, they have an impact on each other. It is not easy to be aware of all properties which others are using in their workflows and what could have an impact on others.
To minimize the risk on others I would recommend to go for a somehow branch aspect with blueprints. Every new integration is a new branch of a 'stable' version of a blueprint. Custom properties and property groups are only modified in the own version of a blueprint minimizing the impact on others:


For each new feature, each developer creates a copy of the 'stable' blueprint before modifying or adding new custom properties or new property groups. This ensures, the development will not have an influence on the blueprints 'stable' version or other developer in the same environment.


Changes on the development blueprint can be done without impact on other blueprints. New property groups special for the new feature can be attached to the blueprints and existing ones can be overwritten by locally creating the custom properties on blueprint level.


Once the development of the new feature is done, a merge will be done manually. Before a merge happens, every other developer must be informed about the changes on the 'stable' blueprint, custom properties, and property groups to ensure others can add those changes to their own development blueprints or to verify the changes will not conflict with own development.


Every 'stable' version of a blueprint will get saved using Houdini or using the CloudClient and can be synced to the productive vRealize Automation environment. For a 'sync' it’s important that a test of the new blueprint version will be made in production environment.

You've done it until here? I'm happy you achieved this and I hope I shared some helpful information with you. Enjoy using vRealize Automation and Orchestrator! Cheers ;-)