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.

Special Character Replacement

The characters {, }, and # are replaced with asterisks when the values of form fields are passed into your process.

These characters are used within a process instance to expand tokens and insert the values of process variables, so should not themselves be the values of form fields/variables.

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;
}

Values as Strings
When a page is submitted, forms convert all of their field values to strings.
If you need to pass JavaScript objects to a process instance, either from a form, or using the Workflow worker 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.

Getting and Setting Variables in Script Activities

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.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
}

Transient Variables

The following activities allow you to mark their return variables as transient:

• Mail task
• iCM End Point Task
• iCM API Server Task
• iCM API Server Data Integration Task
• iCM API Server History Task

Transient variables are available to the workflow until the execution reaches its next wait state - see Workflow Transactions - Foreground and Background Jobs for an explanation of states. The variables are not saved to the database, nor are they written to history, significantly reducing the amount of data that gets written.

Three new functions can be used in your script tasks to work with these variables: getTransientVariable(), setTransientVariable() and removeTransientVariable().

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

Creating Objects

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

JSON Strings

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"

js_ Prefixed Process Variables

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"