vcoportal – Orchestrate. Your Cloud.

Don’t fear anything, it’s not necessary to live in a barrel to understand this topic! You just have to go a bit beyond the obvious…

“In computer science, reflection is the process by which a computer program can observe (do type introspection) and modify its own structure and behavior at runtime.” says Wikipedia.

The Orchestrator also provides a kind of reflection for workflows: Using the keyword “workflow” in a JavaScript Element a workflow can access its current runtime state. This article explains the basic understanding about Workflows and WorkflowToken, script examples and common use-cases for that.

The Basics

An important conecpt of vCO is to create a so called Workflow Token for every single time a workflow gets executed. Only so it’s possible to keep track of multiple in-parallel runs of the same workflow, what’s absolutely possible. (Currently supported in vCO 4.2: 150 concurrent running workflows).

In the vCO Smart Client you can see all the workflow token (=past executions) in the Workflow library, as leafs under the workflow itself:

If you are familiar with object-oriented programming, consider the Workflow as a class (description), the WorkflowToken is an actual instance of this class.

When you select a workflow token in the tree, you can see its details in the main window, most important:

• the state (e.g. running, failed, completed, waiting)
• the current vlaues of the workflow attributes
• the log output (done via System.log() or System.debug())
• (if there is one:) the error message at the bottom of the Variables-Tab

<Additional Technical Background>: All information about the state of a workflow token is stored in vCO’s database (the state, the attributes, the current element,…). So it’s possible for vCO to continue the workflow even after a crash of the server (Checkpointing).
For a quick & (really!) dirty ( & completly unsupported!) monitoring you could do SQL-cram against the vCO database like that:

ALTER trigger [dbo].[monitor] on [dbo].[VMO_WorkflowToken]
AFTER UPDATE
AS
SET NOCOUNT ON
IF EXISTS ( SELECT * FROM Inserted I WHERE I.globalState = 'failed')
BEGIN
/* ***DEMO ONLY:** */ Insert into dbo.fails VALUES ('adsf'); # send a mail, wake somebody up...
END

</Additional Technical Background>

How to…

Back to topic: You can also access the runtime information about the current workflow execution “from inside”, by using the keyword “workflow” (small-caps, remember: JavaScript is case-sensitive!) in a scriptable element.
This keyword returns an object of type WorkflowToken.  This object now represents the current instance of the workflow. This object provides some attributes, see the script below for examples…

Important: If you want to access the Workflow-object (the (class/description/definition), you have to use the rootWorkflow-Attribute of the WorkflowToken (eg. “var theWorkflow = workflow.rootWorkflow”; theWorkflow will be of type Workflow). (Yeah, that’s what I meant with “beyond the obvious”)

The following script examples shows all that stuff: First we get some information about the current instance (you got it, the WorkflowToken). Starting in line 10 we access the Workflow, the last part from line 23 uses the WorkflowToken again.

//get the current workflow token /"instance"
 var token = workflow;
 System.debug(token);

//get some details about the current workflow token/execution/instance
 System.debug("startDate: " + token.startDate);
 System.debug("businessState: " + token.businessState);

//get the Workflow-"Class" of the current token
 var rootWorkflow = workflow.rootWorkflow;
 System.debug(rootWorkflow);

// get "declaraction": Array of Input Parameters of the workflow in general
 var inParams = rootWorkflow.inParameters;
 System.debug("inParams: " + inParams);
 //loop through array and print out details for each parameter
 for (var i in inParams) {
 loopParam = inParams[i];
 //print out in type:::name:::description
 System.debug(loopParam.type + ":::"+ loopParam.name + ":::" + loopParam.description);
 }

// get the current token's inParameters (they include the values, and are returned as Properties
 //(key : values tuples)
 var curInParams = token.getInputParameters();
 System.debug("curInParams: " + curInParams);
 //crawl through the Properties
 var keys = curInParams.keys;
 for (var i in keys) {
 var curKey = keys[i];
 //print out properties in format key :::: value
 var curValue = curInParams.get(curKey)
 System.debug(curKey + " :::: " + curValue );
 }

All that happens just in the script, there are no workflow attributes bound to this scriptable element. The Workflow you can download below has one INPUT Parameter, just to see something in the logs :-). It’s not used anywhere.

The script produces output like this:

Use-Cases

Now, what to use all that stuff for?

• Obviously, if you need some of the information, like the startDate, later in the workflow
• If your workflow has an User Interaction element, you can send an URL to answer it via email (there is a complete example in Library / Mail)
• It’s possible to change the User context the workflow runs, using the changeCredential()-Method
• If you are working with the Business State field of workflow elements, you eventually want to read this in script.

Not really related to the “Reflection”, but useful anyway:
The same objects are used when you access past workflow tokens not of the current workflow, but of other workflows. This can be used for instance to create Healthcheck Workflows which monitor the vCO Server for failed or canceled workflow runs (a much cleaner & more reliable ( & supported) way to replace the SQL-cram mentioned above!).
Insider Tip: See the Actions provided by the module “com.vmware.web.webview” for a lot of useful scripts! They have many more use-cases than only within webviews…

Now, finally:

Download the example!

It should just run out of the box…

Workflow Reflection example
WorkflowReflection.workflow

This workflow just prints out some information about itself...

Author:	Joerg
Category:	Workflows, Actions and Packages
Date:	March 8, 2012

1.8 KiB
Details...