Creating and Updating Process Variables

Form Field Values

Forms that start processes and complete tasks pass their field values to their process instance as process variables. The resulting variables are named after the fields, in the format form_FIELDNAME. The values of these variables are always strings.

Process Variable Functions in Form Actions

The three form action fields that interact with processes (Workflow - Start Action, Workflow - Complete Task Action, and Workflow - Message Action) include a "Process Variable Function". This function can be used to create additional process variables, or manipulate those created by fields on the form.

For example, the following is taken from the Contribute product, which adds a number of variables to the instance:

function(helper, processVars) {
    processVars.CONFIGNAME = "contributeevent";
    // Additional tasks
    processVars.ADDITIONALTASKS = [{
        "form": "CONTRIBUTE",
        "name": "Contribute Event"
    }, {
        "form": "PRICES",
        "name": "Default Prices"
    }];
    return processVars;
}

This example removes a field from the variables passed to the workflow:

function(helper, processVars) {
    delete processVars['form_NAME'];
    return processVars;
}

Passing JavaScript Objects to a Process Instance

If you need to pass JavaScript objects to a process instance, either from a form or using the Workflow worker's API, prefix the variable name with js_. This will preserve the type so they behave as objects in your process instance and workflow script activities. See below for an example.

Variables from Repeating Pages

If a workflow task form or message is used to update data for a repeating page, the existing "formPage_" process variable is completely replaced. The new page data is not merged with the existing data.

If you do need to display the partial data for a repeating page (eg just a single instance of it) this could be worked around in your workflow model. A script task before the user task could create a new variable with just the data to pass to the form, and a script task following the user task could merge the data back into the original variable.

Script Tasks and the Execution Object

Getting and Setting Variables

You can create process variables in script tasks using execution.setVariable("variableName", variableValue). 

The script below demonstrates the following:

var variable1 = _businessKey;
execution.setVariable("variable2", _businessKey);
execution.setVariable("variable3", variable1);
execution.setVariable("variable4", initiator);
execution.setVariable("variable5", form_NAME);

Other methods include:

• execution.getVariable("varName") - where varName is the name of the variable to retrieve the value of
• execution.removeVariable("varName") - useful when the named variable contains a large API call response, removing the variable improves performance and saves database space
• execution.getVariableNames() - retrieves a list of all defined process variables. This can then be iterated over:

for (var iterator = allVarNames.iterator(); iterator.hasNext();){
    var varName = iterator.next();
     // do something
}

Data Types

When working with process variables in a script activity, use the variable name directly instead of execution.getVariable(). This will give you native JavaScript Strings, Numbers etc. If you are retrieving data using functions accessible through the execution object, use the appropriate JavaScript global function (String, Number, Boolean etc) to convert the object to a native JavaScript type.

For example, this workflow includes an API Server task that returns a number, 123, in the variable APICALLRESULT. A script task uses that result to set some new variables:

var test = execution.getVariable("APICALLRESULT");
execution.setVariable("case1", test + 1);
execution.setVariable("case2", APICALLRESULT + 1);
execution.setVariable("case3", Number(execution.getVariable("APICALLRESULT")) + 1);

And the resulting variables and their values are:

APICALLRESULT: 123
case1: "1231"
case2: 124
case3: 124

Objects

If you want to pass in objects from external calls to a process instance (including from the process variable functions in workflow action form fields) you have two options.

Prior to iCM 10.1.0.28 objects needed to be passed in as JSON strings and converted to JavaScript objects in your workflow script actions, otherwise they'll behave like Java maps.

For example, consider this process variable function on the Start Workflow Action field:

function(helper, processVars) {
    processVars.myObject = {
        "key1": "value1"
    };
    processVars.mySecondObject = JSON.stringify({
        "key2": "value2"
    });
    return processVars;
}

These two process variables are then used in a workflow script action with the following results:

var x = myObject.key1;
execution.setVariable("test1", x);

test1 = undefined

var y = JSON.parse(mySecondObject);
execution.setVariable("test2", y.key2);

test2 = "value2"

From iCM 10.1.0.28, JavaScript objects can be created as process variables if they are prefixed js_.

Repeating the example above, the form field's process variable function could be:

function(helper, processVars) {
    processVars.js_myObject = {
        "key1": "value1"
    };
    return processVars;
}

Which can then be used as you'd expect in a workflow script action:

var x = js_myObject.key1;
execution.setVariable("test1", x);

test1 = "value1"

Engine Services

Many of the workflow engine's objects are available to use in scripts. They can be used to coordinate different process instances when the standard workflow elements don't provide enough flexibility.

These can be accessed by calling execution.getEngineServices. See http://www.flowable.org/docs/javadocs/index.html (opens new window).

For example, we can send a message to another process from within a workflow script:

// Get the runtime service
var runtime = execution.getEngineServices().getRuntimeService();

// Find the execution within the target process that is listening for the message
var listeningExecutionQry = runtime.createExecutionQuery();
listeningExecutionQry.processInstanceId(otherProcessInstanceId).messageEventSubscriptionName("MyMessage");
var listeningExecution = listeningExecutionQry.singleResult();

// Send the message
runtime.messageEventReceived("JobCompleted", listeningExecution.getId());