10.2. Adding Human Tasks to Processes

10.2.1. User Task Node

This image shows a user task node process.
A user task node represents an atomic task that needs to be executed by a human actor.

Note

Human task nodes are considered the same as any other external service and must be invoked as a domain-specific service, for further details see Section 9.1, “Domain-Specific Service Nodes”
A user task node contains the following properties:
  • ID: The ID of the node (which is unique within one node container).
  • Name: The display name of the node.
  • TaskName: The name of the human task.
  • Priority: An integer indicating the priority of the human task.
  • Comment: A comment associated with the human task.
  • ActorId: The actor ID that is responsible for executing the human task. A list of actor ID's can be specified using a comma (',') as separator.
  • GroupId: The group ID that is responsible for executing the human task. A list of group ID's can be specified using a comma (',') as separator.
  • Skippable: Specifies whether the human task can be skipped, i.e., whether the actor may decide not to execute the task.
  • Content: The data associated with this task.
  • Swimlane: The swimlane this human task node is part of. Swimlanes make it easy to assign multiple human tasks to the same actor.
  • On entry and on exit actions: Action scripts that are executed upon entry and exit of this node.
  • Parameter mapping: Allows copying the value of process variables to parameters of the human task. Upon creation of the human tasks, the values will be copied.
  • Result mapping: Allows copying the value of result parameters of the human task to a process variable. Upon completion of the human task, the values will be copied. A human task has a result variable "Result" that contains the data returned by the human actor. The variable "ActorId" contains the ID of the actor that actually executed the task.
User task nodes can be edited in the properties view when editing in JBoss Developer Studio or in the Properties window when editing in the process designer embedded in the BRMS user interface.

10.2.2. Dynamic Human Task Properties

Properties such as name, actorID, and priority can be added to the user task node when the process is created; however, some properties in human tasks can be dependent on data that comes from another part of the process instance that the node belongs to, making it necessary to add human task properties dynamically. There are two ways to make human task properties dynamic.
#{expression}
Task parameters of type String can use #{expression} to embed the value of the given expression in the String. For example, the comment related to a task might be "Please review this request from user #{user}", where user is a variable in the process. At runtime, #{user} will be replaced by the actual user name for that specific process instance. The value of #{expression} will be resolved when creating human task and the #{...} will be replaced by the toString() value of the value it resolves to. The expression could simply be the name of a variable (in which case it will be resolved to the value of the variable), but more advanced MVEL expressions are possible as well; for example, #{person.name.firstname} could be used as the expression. Note that this approach can only be used for String parameters. Other parameters should use parameter mapping to map a value to that parameter.
Parameter mapping
The value of a process variable (or a value derived from a variable) can be mapped to a task parameter. For example, if a task needs to be assigned to a user whose ID is a variable in the process, the task could be completed by mapping the ID variable to the parameter ActorId.

10.2.3. User and Group Assignment

Tasks can be assigned to one specific user, and the task will show up on the task list of the specified user only. If a task is assigned to more than one user, any of those users can claim and execute the task.
Tasks can also be assigned to one or more groups, the task will show up on the task list for the specified group, and any member of that group can claim and execute the task.

10.2.4. Standard Human Roles

Tasks and notifications within Business Process Management can be assigned to generic human roles. The following list contains some of these generic roles:
  • Task Initiator - creates the task instance.
  • Task Stakeholders - are responsible for the outcome of the task instance.
  • Potential Owners - receive the task so they can complete it.
  • Actual Owner - actually performs the task.
  • Excluded Owners - may not reserve or start the task.
  • Business Administrators - perform the Task Stakeholders role but at a task type level.
  • Notification recipients - receive the notifications pertaining to the task.

Note

Task Stakeholder has no special authority within BRMS BPM 5.3.1; however, Business Administrator has the authority to claim, stop, release, suspend, resume, skip, delegate, forward, activate, and exit tasks even if they are not the task owner.

10.2.5. Task Escalation and Notification

In certain situations, the escalation of a task is necessary. For example, a user assigned to a task may be unable to complete that task within a certain period of time. In such cases, tasks should be automatically reassigned to another actor or group. Escalations can be defined for tasks that are in the following statuses:
  • not started (READY or RESERVED)
  • not completed (IN_PROGRESS)
Whenever an escalation occurs, users and groups defined in it will be assigned to the task as potential owners, replacing those who were previously assigned. If an actual owner is assigned to the task, the escalation will reset and the task will be put in READY state.
A simple Reassignment table illustrating the escalation ids.
The following is a list of attributes that can be specified during the escalation process:
  • Users. This attribute is a comma separated list of user ids that should be assigned to the task on escalation. String values and expressions #{user-id} are acceptable for this attribute.
  • Groups. This comma separated list of group ids should be assigned to the task on escalation. String values and expressions #{group-id} are acceptable for this attribute.
  • Expires At. This attribute defines the time an escalation should take place. It should be defined as time definition (2m, 4h, 6d, etc.) in same way as for timers. String values and expressions #{expiresAt} are acceptable for this attribute.
  • Type. This attribute identifies the type of task state the escalation should take place in (not-started | not-completed).
Email notifications can be sent out through the 'Notifications' tab. It is very similar to escalation in terms of definition. Email notifications can be sent for tasks that are in following statuses:
  • not started (READY or RESERVED)
  • not completed (IN_PROGRESS)
A Notification's tab that illustrates the use of email messages.
Email notifications have the following properties:
  • Type. This attribute identifies the type of task state on which escalation should take place (not-started | not-completed).
  • Expires At. This time definition property determines when escalation should take place. It should be defined as time definition (2m, 4h, 6d, etc.) in the same way as for timers. String values and expressions #{expiresAt} are acceptable properties.
  • From. An optional user or group id that will be used in the 'From' field for email messages; it accepts Strings and expressions.
  • To Users. A comma separated list of user ids that will become recipients of the notification.
  • To Groups. A comma separated list of group ids that will become recipients of the notification.
  • Reply To. An optional user or group id that should receive replies to the notification.
  • Subject. The subject of the notification; it accepts Strings and expressions.
  • Body. The body of the notification; it accepts Strings and expressions.
Notifications can reference process variables by #{processVariable} and task variables by ${taskVariable}. Accordingly, process variables resolve at task creation time, and task variables resolve at notification time. The following list contains several task variables that can be used while working with notifications:
  • taskId: An internal id of a task instance.
  • processInstanceId: An internal id of a process instance that the task belongs to.
  • workItemId: An internal id of a work item that created this task.
  • processSessionId: A session internal id of a runtime engine.
  • owners: A list of users/groups that are potential owners of the task.
  • doc: A map that contains regular task variables.
Below is an example notification message that illustrates how different variables can be accessed. 
<html>
	<body>
		<b>${owners[0].id} you have been assigned to a task (task-id ${taskId})</b><br>
		You can access it in your task 
		<a href="http://localhost:8080/jbpm-console/app.html#errai_ToolSet_Tasks;Group_Tasks.3">inbox</a><br/>
		Important technical information that can be of use when working on it<br/>
		- process instance id - ${processInstanceId}<br/>
		- work item id - ${workItemId}<br/>
		
		<hr/>
		
		Here are some task variables available:
		<ul>
			<li>ActorId = ${doc['ActorId']}</li>
			<li>GroupId = ${doc['GroupId']}</li>
			<li>Comment = ${doc['Comment']}</li>
		</ul>
		<hr/>
		Here are all potential owners for this task:
		<ul>
		$foreach{orgEntity : owners}
			<li>Potential owner = ${orgEntity.id}</li>
		$end{}
		</ul>
		
		<i>Regards</i>
	</body>
</html>

10.2.6. Data Mapping

10.2.6.1. Data Mapping

Human tasks typically present some data related to the task that needs to be performed to the actor that is executing the task. Human tasks usually also request the actor to provide some result data related to the execution of the task. Task forms are typically used to present this data to the actor and request results.

10.2.6.2. Task Parameters

Data that needs to be displayed in a task form should be passed to the task using parameter mapping. Parameter mapping allows you to copy the value of a process variable to a task parameter (as described in Section 10.2.2, “Dynamic Human Task Properties”). This could be the customer name that needs to be displayed in the task form, the actual request, etc. To copy data to the task, map the variable to a task parameter. This parameter will then be accessible in the task form.

10.2.6.3. Task Results

Data that needs to be returned to the process should be mapped from the task back into process variables, using result mapping. Result mapping allows you to copy the value of a task result to a process variable. This could be some data that the actor filled in. To copy a task result to a process variable, map the task result parameter to the variable in the result mapping. The value of the task result will then be copied after completion of the task so it can be used in the remainder of the process.

10.2.7. Swimlanes

User tasks can be used in combination with swimlanes to assign multiple human tasks to the same actor. Whenever the first task in a swimlane is created, and that task has an actorId specified, that actorId will be assigned to all the tasks in that swimlane. Note that this would override the actorId of subsequent tasks in that swimlane (if specified), so only the actorId of the first human task in a swimlane will be taken into account, all others will then take the actorId as assigned in the first one.
To add a human task to a swimlane, first ensure the swimlane has been defined in the process. If it has not been defined, define the swimlane by editing the swimlane property. Next, specify the name of the swimlane as the value of the Swimlane parameter of the user task node.

10.2.8. Removing Tasks from the Database

Human tasks information can be removed from the database with the org.jbpm.task.admin.TaskCleanUpProcessEventListener, which is a DefaultProcessEventListener that archives and removes completed tasks with the associated process ID.
The TaskCleanUpProcessEventListener uses an instance of org.jbpm.task.admin.TasksAdmin, which can be obtained from org.jbpm.task.service.TaskService#createTaskAdmin().

Example 10.1. Attaching the Event Listener

TasksAdmin admin = new TaskService(...).createTaskAdmin();
StatefulKnowledgeSession ksession = ...
ksession.addEventListener(new TaskCleanUpProcessEventListener(admin));