​Activities

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

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

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

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

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

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

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.

HTML Body 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

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

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.

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:

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:

iCM API Server Task

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

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

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.

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.