vRO: working with workflow

As vRealize Automation and vRealize Orchestrator are used, the scope of their tasks is constantly expanding. The number of processes supporting these tasks is growing even faster. Fortunately, any process is just another object that can also be automated.

1. Searching for a process
2. Basic properties of the workflow object
3. Starting a workflow and passing parameters, token
4. Waiting for execution, receiving results
5. Action for starting a process
6. Starting a process according to a schedule

1. Search for a process

Any company or even individual vendors can provide packages and processes for vRealize Orchestrator, so there is no prohibition on using the same process names in vRO. This means that it is more correct to search for a process by its ID, and not by its name:

var myWorkflow = Server.getWorkflowWithId("11111111-aaaa-bbbb-cccc-11112222333");

or

var workflowId = "11111111-aaaa-bbbb-cccc-11112222333";
var myWorkflow = Server.findForType("Workflow", workflowId);

Both examples will return you the same Workflow object corresponding to the specified ID.
You can get the object of your current process during its execution like this:

var myWorkflow = workflow.currentWorkflow;
var myWorkflow = workflow.rootWorkflow;

Both methods are identical. In this example, workflow is an object of the WorkflowToken class, an object of the current execution of the process (execution), or simply a process token. If you need to get all the processes on the vRO for processing, use the method:

var workflows = Server.findAllForType("Workflow");

VRO has the ability to search for a process by its name:

System.getModule("com.vmware.library.vcac").getWorkflowByName("Test Workflow");

But if you look at the implementation of this function, you will immediately understand why it is better to search for a process by ID. The function gets the complete list of processes using Server.findAllForType (“Workflow”) and then filters the resulting list by process name. If more than one process is found as a result, the error “More than one workflow with name ****” is returned .

2. Basic properties of the workflow object

So you’ve got a Workflow object. This object contains complete information about the process, so it is worth taking a closer look at its main properties:

• attributes – a list of process attributes, their types and values ​​(an array of objects of the Attribute type);
• inParameters – a list of parameters accepted by the process at the input (an array of objects of the Parameter type);
• outParameters – a list of parameters returned by the process (an array of Parameter objects);
• executions – a list of process starts, all their input values ​​and execution results (an array of WorkflowToken objects);
• items – a list of process items, blocks on the process diagram: scripts, processes, branches, etc. (an array of objects of type WorkflowItem);
• logEvents – a list of events: start and end of the process, saving a new version, errors (an array of objects of the LofEvents type).

Try listing the attributes of the current process and their initial value:

var myWorkflow = workflow.currentWorkflow;
for each (item in myWorkflow.attributes) {
	System.log(item.name + ": " + item.value);
}

3. Launching workflow and passing parameters, token

The purpose of any process is to perform certain actions. To start the process, you need to call the execute method of the Workflow object. If the process needs input parameters, then the Properties object is passed to execute :

var myWorkflow = Server.getWorkflowWithId("11111111-aaaa-bbbb-cccc-11112222333");
// preparation of input parameters
var inputProperties = new Properties(); 
inputProperties.put("inputVariable1_str", "test");
inputProperties.put("inputVariable2_int", 42);
inputProperties.put("inputVariable3_bool", true);
var token = myWorkflow.execute(inputProperties);

The execute method returns another object – WorkflowToken, which contains information about the parameters of the process execution (in the example above, this is the token variable). The execute method starts execution of the process once. To start several processes in parallel, you can call  execute in a loop, passing different parameters to the input. An example of such parallel processing can be found in the “Start workflows in parallel” process.
What if you haven’t started the process, but you want to check the status of its execution and get the results? You can get the token of the last execution of any process using the getWorkflowLastToken function:

var token = System.getModule("com.vmware.library.vcac").getWorkflowLastToken(myWorkflow);

Or you can sequentially analyze all starts of this process:

var myWorkflow = Server.getWorkflowWithId("11111111-aaaa-bbbb-cccc-11112222333");
for each (token in myWorkflow.executions) {
	if (token.isStillValid) {
		System.log(token.startDate + ": " + token.state);
	}
}

Here, the start time of the process and its current state are displayed in the log. The isStillValid property allows you to check the token for correctness before using it.

In the following example, the state property is used to determine the execution status of a process (a more detailed description and examples of its use will be below).

var myWorkflow = Server.getWorkflowWithId("11111111-aaaa-bbbb-cccc-11112222333");
for each (token in myWorkflow.executions) {
	if (token.state == "running" || token.state == "waiting-signal") {
		token.cancel();
		System.log("Execution " + token.startDate + " (" + token.id + "): is canceled");
	}
}

This script cancels all pending process starts.

4. Waiting for execution, getting results

Having received a process token (WorkflowToken), you can:

• View the parameters passed to the process (the getInputParameters method):

// display the input parameters of the process and their values
var inParams = workflow.getInputParameters();
if (inParams != null){
	// display all parameters and their values
	for each (key in inParams.keys){
		System.log(key + ": " + inParams.get(key));
	}
}

• If you design this example as an action, you will get an excellent debugging tool, add it to any process and this will lead to the entry of input parameters and their values ​​into the log.

// selective display of parameters and their values
var inParams = workflow.getInputParameters();
if (inParams != null){
	// display the values ​​of individual parameters by their name
	System.log("inputVariable1: " + inParams.inputVariable1);
	System.log("inputVariable2: " + inParams["inputVariable2"]);
}

• Get the results of the process (method getOutputParameters):

// displaying the results of the work process
var outParams = workflow.getOutputParameters();
if (outParams != null){
	// get all parameters and their values
	for each (key in outParams.keys){
		System.log(key + ": " + outParams.get(key));
	}
	// display the values ​​of individual parameters by their name
	System.log("outputVariable1: " + outParams.outputVariable1);
	System.log("outputVariable2: " + outParams["outputVariable2"]);
}

• Monitor the current execution status of the process (state property). The state property can return the following values:
  • running;
  • completed;
  • waiting-signal;
  • canceled;
  • failed;The meanings of all states are clear, except for waiting-signal . This state means that the process is running and is currently waiting for either user actions (Waiting for User Interaction) or a timer event (Waiting for Event or Timer).

// waiting for the process to complete by its token
while (token.state == "running" || token.state == "waiting-signal") {
	System.sleep(100);
}

• The value of the delay in the cycle is selected according to the situation: if the process is not very long and the execution time is critical, then set it less, if the process is running for 10 – 30 minutes, then there is no point in checking its status 10 times per second. You can view a sequential start of a workflow (waiting for completion) in the “Start workflows in a series” process.

5. Action start process

Now you are ready to combine the previous pieces of code together: searching for a process, preparing input parameters, starting and waiting for execution, getting the result. The resulting action can be used on a vRA blueprint or XaaS process to validate / prepare input values ​​by calling an additional process:

// search process by ID
var workflowToLaunch = Server.getWorkflowWithId("11111111-aaaa-bbbb-cccc-11112222333");
if (workflowToLaunch) {
	// preparing input parameters
	var inputProperties = new Properties(); 
	inputProperties.put("inputVariable1", "test value");
	inputProperties.put("inputVariable2", 42);
	// start process
	token = workflowToLaunch.execute(inputProperties);
	// waiting for the process to finish
	while (token.state == "running" || token.state == "waiting-signal") {
		System.sleep(100);
	}
	// getting and analyzing the results
	var prop = token.getOutputParameters();
	if (prop.outputVariable1) {
		return prop["outputVariable1"];
	} else {
		return "Error getting parameter";
	}
} else {
	return "Workflow not found!";
}

6. Start of the process according to the schedule

Another important quality of vRO processes is the ability to create tasks or run on a schedule. The schedule and scheduleRecurrently methods are called to create tasks . The schedule method performs a delayed start and therefore, in addition to the input parameters for the process, it requires a Date object containing the start date and time:

var myWorkflow = Server.getWorkflowWithId("11111111-aaaa-bbbb-cccc-11112222333");
// prepare the date and time for the task
var scheduleDate = new Date();
scheduleDate.setDate(scheduleDate.getDay() + 7);
// preparing input parameters
var inputProperties = new Properties();
inputProperties.put("inputVariable1_str", "test");
inputProperties.put("inputVariable2_int", 42);
inputProperties.put("inputVariable3_bool", true);
// create a task
var task = myWorkflow.schedule(inputProperties, scheduleDate);

Running a repeating task will require a little more preparation, see the ready-made example of starting a task with a description of the parameters.

That’s all about working with processes. Do you have interesting examples of your own? Share and do not forget to write comments and questions, if of course they have arisen!

Translated by Google Translate