Toggle menu

Standard Process Variables

This article looks at the variables present as standard in process instances. Some are added by the workflow worker, and some by the form fields that interact with process instances.

Process variables have a name and value. Some are created automatically when a process instance starts. Some hold values from iCM form submissions (that either started the process, or completed tasks during the process). Other variables are created as various tasks and activities are completed.

Inspecting Instances and Variables

In the process modeller you can inspect a process instance and see all of the process variables associated with it.

Inspecting a Process Instance
 

Instance Properties

In the top section of the instance details view you can see basic information about the instance, including the name of the definition, the user who started it and when, and the instance business key. These values can be used as filters when you're searching in the modeller, trying to find a particular instance.

Standard Process Variables

The following process variables are available as standard in a process instance.

VariableDescription
_businessKeyA unique identifier for this instance, generated automatically in the workflow worker's startProcess function
_fileReferencesIf the "Workflow - Start Action" field type is set to "Keep file references" this variable contains the IDs and file names of uploaded files. For example:

{
  "form_FILEUPLOAD": [
    {
      "id": "8E8F9EE4-DAB8-4A34-BA7D-0D9648291CA0",
      "filename": "handlebars.PNG"
    }
  ],
  "form_FILEUPLOAD2": [
    {
      "id": "4A243AED-FE57-4CDF-9982-6786D1F3E8E8",
      "filename": "hot-air.jpg"
    }
  ]
}
_historyLabelsThe default settings of the "Workflow - Start Action" form field will write information to the API Server's History worker. labela is set as the name of the process, labelb as the unique business key that identifies this instance.

Values can be accessed using ${_historyLabels.labelb} etc.
_initiatorProxyThe initiator of the process instance if it was started by a proxy user, for example using the Assisted Service product
_logFinalSummaryIf false a final summary event will not be logged to the history that accompanies this instance (this variable is set by the "summaries" property in the workflow form action fields)
_processDefinitionIDThe full ID of a deployed process (not the instance!). This is unique within the database and is made up of the _processDefinitionKey plus a unique suffix
_processDefinitionKeyThe process identifier, set in the workflow model (generally the name of the model). It is not unique
_startDateThe date/time the instance started
_startDateStringThe _startDate formatted as a date string
_startFormThe name of the form that was used to start this instance
_startFormDescriptionThe description of the form that was used to start this instance
_startPageURLThe URL of the form that was used to start this instance
_summaryFormWhen you interact with a process instance using the GOSS Self Service template, it's possible to view summaries of that instance. The form used to view that summary is, by default, the same form that started the process. You can select a different form in the "Workflow - Start Action" field type
_taskFormThe name of the form used to complete the last task
_taskFormDescriptionThe description of the form used to complete the last task
_traceEnabledIf the form that started the process instance has tracing enabled, this variable will be present with the value true. This enables tracing in the workflow engine. See Debug and Tracing for more information
form_FIELDNAMEValues from form submissions that interact with a instance (ie start an instance or complete a task) are stored as process variables, prefixed with form_ and followed by the name of the field. These variables can be manipulated or excluded via options in the Workflow - Start/Complete/Message field types.

The values of these variables will always be strings.

Including fields in user task forms with the same names as these variables will return the values of the variables to the forms (and display them in the fields as appropriate)
formPage_PAGENAMEThe values of fields from repeating pages are stored as an array of objects, with one object per page instance, and the key-value pairs in each object the field names and submitted values. See Repeating Page Data for more information
initiatorThe initiator of the process. The name of this variable can be set in the Start Event of your model
js_VARIABLENAMEIf you need to pass JavaScript objects to a process instance (either from a form, or using the Workflow worker's API) prefix them with js_. This will preserve their type

Process Variables Generated by Activities

Process variables are automatically added to an instance as tasks are claimed, released or completed, and when the process receives a message or signal.

_claimed, _released, _completed

When a task is claimed a process variable is created called _TASKID_claimed. Note that this task ID is the value you can enter when designing your process. If left blank iCM will assign a random value to it. When these variables are created, messages with the same name (message reference) are also sent to the instance.

Setting the Task ID
   

These variables are JavaScript objects with the following form:

"_TheTaskID_claimed": {
    "user": "<user who claimed task>",
    "proxyUser": "<user who claimed on behalf of new assignee>",
    "taskId": "<task id in process instance>",
    "time": "<time task was claimed in ISO format>"
}

For example, if a process contains a user task with the ID "usertask1", when that task is claimed a process variable called _usertask1_claimed will be created. You can then access properties within that object, for example _usertask1_claimed.user.

Similar process variables are created when tasks are released or completed.

History
Private history events called CLAIMTASK and RELEASETASK are logged in the workflow's corresponding history. History events for completing tasks are recorded by the complete task form action field.

_received

When a message or signal is received, process variables called _MESSAGE_received or _SIGNAL_received are created.

These variables are JavaScript objects with the following form:

{
    "user": "<user who sent message/signal>",
    "proxyUser": "<user who sent message/signal on behalf of user>",
    "time": "<time message/signal was sent in ISO format>"
}

The prefix is set by the message reference/message name.

_finalHistoryDescription

When a process instance starts it also generates a history using the platform's History service. As tasks and activities are performed they are recorded as events in the history. When the process instance ends a final event is added to the history, marking it as complete (sealing the history).

This final event is a standard event generated by the workflow engine. Its default description is "Process Ended". The description of this final event can be set by creating a process variable named _finalHistoryDescription. The value of this variable must be a string. If it is not supplied, is null, or is another type, the description will fall back to "Process Ended".

If you set _finalHistoryDescription using one of the form action fields, variable expansion can also be used. For example:

function(helper, processVars) {
    processVars._finalHistoryDescription = "I was started with #_startForm#";
    return processVars;
}

Setting Additional Universal Process Variables

Additional variables can be added to every process instance by defining them in the configuration sent to the Workflow worker. This is done using the processConfig property.

For example, including:

{
    "name": "workflow",
    "instances": 1,
    "threadsPerInstance": 5,
    "processConfig" : {
                "SITEURL" : "http://demodev1.gossinteractive.com/toptasks/",
                "SELFSERVEURL" : "http://demodev1.gossinteractive.com/toptasks/selfserve"
        }
}

Would result in the following being available in every process instance:

Process Modeller - Process Variables
 

Last modified on January 02, 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon