Toggle menu

​Activities

The activities in the workflow modeller define the tasks that will be carried out as your model is executed. 

User Task

User task
 

A user task is used to model work that needs human input, interacting with the process using an iCM form. When the process execution arrives at a user task the execution pauses and waits for user input.

Products like Self Service and User Requests are used to display lists of tasks to the appropriate users. These groups and users are always defined as website users in iCM. Should an iCM user need to perform a task, they will need to have an associated site user created for them and linked via their "alias".

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for the task - this will appear in site templates like Self Service and User Requests but will be overridden by the description
DescriptionAn optional description for this element. The description can include process variables, see Process Variable Tokens and Expressions in the knowledge base for more information
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task
CandidatesThe users or groups eligible to claim this task (or have it directly assigned to them, see below). This lists excludes any users that have random GUID-type usernames generated by the site authentication service when users log into your site using an external provider - as there's no way of knowing who these users are from this menu there is little point in showing them. In general candidates should be assigned by group
iCM FormA pop-up that allows you to select the iCM form that will be used to interact with this process
Due dateEither an ISO-8601 formatted date and time or an expression such as ${dateVariable}. Due dates are used when querying the workflow worker using the API and are displayed in versions 12 onwards of the Self Service templates
PriorityUsed to order tasks when querying the workflow worker using the API

Candidate Assignment

Candidate Assignment
 

There are three options when defining candidates for tasks: assignee, candidate users and candidate groups.

Assignee

A single user can be selected as the assignee. If an assignee is present the task will be assigned directly to them, ignoring any values entered in either of the two candidate tabs. This option bypasses the "claimable tasks" stage of the various GOSS Self Service products.

Candidate Users and Groups

If there are no direct assignees selected, the user task will show up as a claimable task for all selected site users, or all site users who are members of the selected groups. Even if only a single eligible site user is selected as a candidate, unlike the assignee option, they will still need to claim the task before being able to take the required action. Once the task has been claimed it will be removed from the claimable task lists of other users.

Assignment Expressions

Assignment Expression
 

As well as selecting site groups and users from the available lists, it is also possible to define a candidate using an expression. A commonly used expression assigns a task back to the person who started the process instance, for example:

${initiator}

Where "initiator" is the standard process variable storing the name of the user that started the process instance. The name of this variable can be set in the start event of your model, but we don't recommend changing it.

Preventing Tasks from being Unclaimed

When a user claims a task, they become responsible for it - the task is assigned to them. The Self Service template allows users to manage the tasks currently assigned to them, claiming tasks from a list of tasks they are eligible to complete and unclaiming tasks previously claimed.

You might want to prevent a user from unclaiming a task once it has been claimed. This is especially true if a task only has one candidate.

To prevent a task from being unclaimed:

  1. Open the "Advanced" tab of the user task activity
  2. Click on "Task listeners"
  3. From the default behaviour drop-down select "Prevent Un-Claim"
  4. Press the plus icon, then save

If a task doesn't have any candidates - ie it only has an assignee - it will automatically prevent the assignee from unclaiming it. This is to prevent processes from being orphaned, where an assignee unclaims a task and there aren't any defined candidates to pick it up again.

Task Chaining

If a workflow model includes sequential user tasks which are carried out by the same user, it is possible to chain the tasks together, immediately displaying the form of the second task after the first has been submitted.

The same effect can be achieved by using a multi-page form, which is easier to implement and delivers much of the same functionality. Task chaining should generally only be used when workflows are more complex.

To enable chaining, open the "Advanced" tab of the user task activity you would like to chain to. Click on "Task listeners". From the default behaviour drop-down select "Allow Chaining" and press the plus icon, then save.

The task candidate must be an assignee rather than a candidate user or group. The Task Chaining reference article includes a working example that also shows how to assign a task to the user who completed the previous task. 

Workflow chaining will not work if any activity between the two user tasks is marked as asynchronous. The user must only have one task assigned at a time, otherwise the engine won't know which one to chain to. Chaining cannot work if the second task needs to be claimed.

Auto-Claiming Tasks

In normal use tasks are either directly assigned to a user as the "assignee" or made available to a user or group of users by selecting them as potential "candidates". Candidates have to claim a task (either working in iCM or using one of the Self Service products), and then act upon it.

It is possible to set a task to be "auto-claimed". This still makes the task available to candidates, but removes the claiming step.

Typically auto-claim tasks are used in combination with a mail task. Potential candidates are emailed a link to complete the task (ie emailed a link to the appropriate task form), and whoever clicks on the link first will automatically have the task assigned to them. They are then able to complete the task form.

To enable auto-claiming, open the "Advanced" tab of the user task activity you would like to be auto-claimed. Click on "Task listeners". From the default behaviour drop-down select "Allow Auto-Claim" and press the plus icon, then save.

Candidate users should be emailed a link to an article using the Forms Service template. The link needs to include the business key of the workflow instance as a parameter, for example, http://www.mywebsite.com/myform?bk=${_businessKey}. When the form is displayed to the user they will only be able to carry out the task, and see any relevant information from the process, if they are an eligible candidate.

When a task can be auto-claimed you will often need to build in the ability for users to unclaim the task, or for it to return to a claimable state after a certain amount of time has elapsed.

The Linking Directly to Workflow Tasks reference article looks at auto-claiming in more detail.

Script Task

Script task
 

A script task is an automatic activity. When a process execution arrives at the script task, the corresponding script is executed.

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for this element
DescriptionAn optional description for this element
ScriptThe script
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task

Variables in Scripts

All process variables that are accessible through the execution that arrives at the script task can be used within the script by directly using their name, for example:

var variable1 = _businessKey;

By default, no variables are stored automatically. It is possible to store any variable defined in the script by using an execution.setVariable() call.

execution.setVariable("variableName", variableValue)

See Process Variables for more information about variables and script tasks.

Mail Task

Mail task
 

The mail task is used to send email. When a process execution arrives at the mail task, the task is automatically executed. This task uses the API Server's Email Worker, which means you can generate PDFs, handle attachments and use Handlebars templating. Note that this task is not an official task of the BPMN 2.0 specification.

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for this element
DescriptionAn optional description for this element
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task
ToA comma separated list of recipients. Can include values from stored process variables using ${form_EMAIL} (where EMAIL is the name of a field on the form that interacted with this process instance containing the user's email address)

You must be confident that the variables you reference exist. If they don't, the mail task will error and no emails will be sent. This could be checked with a preceding script task, for example:

if (execution.hasVariable("form_EMAIL") == false){
    execution.setVariable("form_EMAIL", "");
}
FromThe from address. Leave this blank to use the from address set in the email worker
SubjectThe subject line of the email
Use Handlebars for Subject?Check this box to enable Handlebars templating in the subject line
CcA comma separated list of recipients, works in the same way as the "To" field
BccA comma separated list of recipients, works in the same way as the "To" field
TextA text only fall-back version of the email for email clients that don't support rich content
HTMLThe HTML content of the email, see below
Use HandlebarsTrue if checked. Handlebars templating can be used to process the body of the email
PDF TemplateA Handlebars template used to generate a PDF attachment, see below
PDF FilenameThe name given to the generated PDF
AttachmentsA array of process variable names that represent attachments. See below
Return VariableThe process variable that any return from the activity will be stored in
Error VariableThe process variable that any error will be stored in
Error HandlingShould an error occur will it be ignored, follow the transition specified on the advanced tab (ie the ID of a sequence flow from the current activity), or throw a BPMN error which could be caught by a boundary error event

HTML Body Content

Mail Task HTML Content
 

The email generated by the mail task can include HTML content, Handlebars templating and simple value substitution.

A header and footer can be added to the email if the email header and footer process variables have been set via the Workflow Worker's configuration. See Process Variables for further information.

PDF Template

The PDF template can be used to generate a PDF version of the email (or any other content) which is automatically attached to the email generated by the mail task (in addition to any other attachments). The name of the PDF attachment is set in the PDF Filename property.

See the Email Worker documentation for further information, including how to configure PDF headers, footers and styling.

Attachments

The attachments property allows you to attach files to the generated email. It is an array of strings, with each string identifying a file. Files can be referenced in two ways: the file UUID, or the value of an upload form field.

A single explicit file identifier would be added to the attachments property as: ["0a148876-c9c3-4e8f-9d3d-cfb476446540"]

The values of upload form fields are added as: ["${form_UPLOADFIELD1}","${form_UPLOADFIELD2}"]

You can create the array in a preceding script task, setting it as the value of a variable using execution.setVariable(). This variable could then be used in the attachment property as: ${myVariable}

See the Handling File Uploads knowledge base article for more information about how the platform handles file uploads and File Uploads and Email Attachments in Workflow for a more detailed look at attachments.

Limits

All mail servers put limits on the total size of the emails they will accept. In AWS (our main hosting provider) the size limit is 40MB after encoding for the complete email, including embedded images and attachments.

There is also a limit of 50 recipients for a single message (combined "to", "cc" and "bcc"). When sending emails you should be emailing each recipient individually. The use cases for recipients having a message with the same message-id are limited to situations in which the recipients are expected to interact with the message as a group, for example, recipients using reply-all to the email and having a resulting email conversation.

End Point Task

iCM End Point Task
 

Calls an End Point with the specified parameters. By default the End point is assumed to be published to the serverlibrary.

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for this element
DescriptionAn optional description for this element
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task
End Point NameA pop-up explorer that lets you select the End Point to call. You can also enter a ${...} expression that resolves to the name of an End Point
End Point ParametersThe parameters that will be passed to the End Point. See below for further information
Return VariableThe process variable that the result of the call will be stored in
Error VariableThe process variable that any error will be stored in
Error HandlingThere are three possible error handling mechanisms:
  • None - whichever strategy is used, a process variable is set with a user-specified name "Error Variable" on the main properties tab. If an error transition or BPMN error is not specified, it is the responsibility of the workflow to determine that an error has occurred by checking this variable.
  • Follow error transition - an outgoing flow from the API Server Task is given a specific label which is also given as the Error Transition property on the advanced properties tab. If an error is returned from the API call this flow will be followed instead of the default flow (note that the "happy path" must be set to be the default flow for this to work).
  • Throw BPMN error - the BPMN error specified on the advanced tab is thrown when the API call returns an error. This can then be caught by an Boundary error event, or other error catching event

End Point Parameters

As in the forms and End Point designers, the End Point Task provides a request builder to assist with building the parameters that will be passed to your End Point.

End Point Task Parameters
 

When first launched, the Parameters tab will include an object with all of the parameters marked as required in the End Point's schema. The other tabs let you view any help that has been written for the End Point, it's schemas, and examples taken from the schema or any saved tests.

The values of process variables can be used as the End Point parameters.

Imagine an End Point that calls the Email Worker. It expects to receive params.to, params.subject and params.body.

A script task in the workflow model sets the following:

var params = {
 "subject": "email subject",
 "to": "support@gossinteractive.com",
 "body": "email body content"
};
execution.setVariable("parameters", params);

The End Point parameters could be set as:

End Point Parameters
 

Parameters can also be taken from individual variables. Process variables that have string values can be accessed using "#myVariable#". Process variables with number values don't need quotes, so #myNumberVariable#.

For example, a script task in the model could set:

execution.setVariable("subject", "test");
execution.setVariable("to", "support@gossinteractive.com");
execution.setVariable("body", "body content set separately");

Each of these values could be added to the parameters as:

End Point Parameters - Variable values
 

iCM API Server Task

API Server task
 

Calls an iCM API Server worker using the specified function name and parameters.

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for this element
DescriptionAn optional description for this element
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task
Worker NameThe name of the worker. For example serverlibrary or ajaxlibrary. Worker names can be found in the API Server section of iCM Management
Function NameThe function to call on that worker. This could, for example, be the name of an End Point
Parameter VariableThe name of the variable that contains the parameters that should be passed to the worker and function. This will be a JSON object, usually set in a preceding script task
Return VariableThe process variable that any return from the activity will be stored in
Error VariableThe process variable that any error will be stored in
Error HandlingThere are three possible error handling mechanisms:
  • None - whichever strategy is used, a process variable is set with a user-specified name "Error Variable" on the main properties tab. If an error transition or BPMN error is not specified, it is the responsibility of the workflow to determine that an error has occurred by checking this variable.
  • Follow error transition - an outgoing flow from the API Server Task is given a specific label which is also given as the Error Transition property on the advanced properties tab. If an error is returned from the API call this flow will be followed instead of the default flow (note that the "happy path" must be set to be the default flow for this to work).
  • Throw BPMN error - the BPMN error specified on the advanced tab is thrown when the API call returns an error. This can then be caught by an Boundary error event, or other error catching event

iCM API Server Data Task

API Server data task
 

Calls an iCM API Server data integration worker using the specified context name and parameters. Note that this task is not an official task of the BPMN 2.0 specification.

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for this element
DescriptionAn optional description for this element
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task
Talend Worker NameThe name of the Talend worker to call
Context NameThe Talend context
Context VariablesA JSON object containing the context variables for the Talend Job
Return VariableThe process variable that any return from the activity will be stored in
Error VariableThe process variable that any error will be stored in
Error HandlingShould an error occur will it be ignored, follow the transition specified on the advanced tab (ie the ID of a sequence flow from the current activity), or throw a BPMN error which could be caught by a boundary error event

History Task

API Server history task
 

Calls the iCM API Server History Worker using the specified parameters. Note that this task is not an official task of the BPMN 2.0 specification.

As well as the standard ID, Name, Description and Variable properties, the history task includes the various properties needed by the History Worker. See the History Service documentation for further information.

When a process instance is started by a form submission, the Workflow - Start Action controls whether or not a history is written. If a history record is written, leaving the label a-e values blank in the history task will write history events to the history of the current instance. Providing new label a-e values will create a new history.

PropertyDescription
IDAn optional unique ID for this element. The modeller will assign a random ID if left blank
NameA name for this element
DescriptionAn optional description for this element
AsynchronousWhen execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task
EventA packet of event data in a JSON object. You can use ${...} expressions to access the values of process variables
SubjectA packet of subject data in a JSON object. You can use ${...} expressions to access the values of process variables. If writing to a history that already exists, this property is ignored
Label AThe labela value. Leave blank to write to the history created when this instance started. You can use ${...} expressions to access the values of process variables
Label BAs above
Label CAs above
Label DAs above
Label EAs above
DatasourceLeave blank to write to the iCM database
Return VariableThe process variable that any return from the activity will be stored in
Error VariableThe process variable that any error will be stored in
Error HandlingShould an error occur will it be ignored, follow the transition specified on the advanced tab (ie the ID of a sequence flow from the current activity), or throw a BPMN error which could be caught by a boundary error event

Multi-instance Activities

A multi-instance activity is a way of defining repetition for a certain step in a business process. In programming concepts, a multi-instance matches the for each construct: it allows the execution of a certain step or even a complete subprocess for each item in a given collection, sequentially or in parallel.

A multi-instance is a regular activity that has extra properties defined (so-called "multi-instance characteristics'') which will cause the activity to be executed multiple times at runtime. Following activities can become a multi-instance activity:

  • User Task
  • Script Task
  • Manual Task
  • Mail Task
  • Receive Task
  • (Embedded) Sub Process
  • Call Activity

A Gateway or Event cannot become multi-instance.

As required by the specification, each parent execution of the created executions for each instance will have following variables:

  • nrOfInstances: the total number of instances
  • nrOfActiveInstances: the number of currently active, i.e. not yet finished, instances. For a sequential multi-instance, this will always be 1.
  • nrOfCompletedInstances: the number of already completed instances.

These values can be retrieved by calling the execution.getVariable(x) method.

Additionally, each of the created executions will have an execution-local variable (i.e. not visible for the other executions, and not stored on process instance level) :

  • loopCounter: indicates the index in the for-each loop of that particular instance. The loopCounter variable can be renamed by the workflow engine's elementIndexVariable attribute.

Graphical Notation

If an activity is multi-instance, this is indicated by three short lines at the bottom of that activity. Three vertical lines indicates that the instances will be executed in parallel, while three horizontal lines indicate sequential execution.

Boundary Events and Multi-instance

Since a multi-instance is a regular activity, it is possible to define a boundary event on its boundary. In case of an interrupting boundary event, when the event is caught, all instances that are still active will be destroyed. So all instances of any subprocesses will be destroyed when the timer fires, regardless of how many instances there are or which inner activities are currently not yet completed.

Multi-instance and Execution Listeners

There is a caveat when using execution listeners in combination with multi-instance. For a normal BPMN activity, there would be an invocation of listeners when the activity is started and ended. However, when the activity is multi instance, the behaviour is different:

  • When the multi-instance activity is entered, before any of the inner activities is executed, a start event is thrown. The loopCounter variable is not yet set (is null).
  • For each of the actual activities visited, a start event is thrown. The loopCounter variable is set.

The same reasoning applies for the end event:

  • When the actual activity is left, an end even is thrown. The loopCounter variable is set.
  • When the multi instance activity has finished as a whole, an end event is thrown. The loopCounter variable is not set.

There's an example of multi-instance tasks in the Multi-Instance Tasks knowledge base article.

Last modified on May 09, 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon