The task instance life-cycle is straightforward: after creation, one can start the instances. They can then be ended, which means that they will be marked as completed.

A task instance maintains its state by means of three date-properties:

Access these properties via their respective "getters", which can be found on the TaskInstance.

Completed task instances are marked with an end date so that they are not fetched when subsequent queries search for tasks lists. The completed tasks do, however, remain in the JBPM_TASKINSTANCE table.

Task instances are the items in an actor's task list. A signalling task instance is a task instance that, when completed, sends a signal to its token to continue the process execution. Blocking task instances are those that the related token (the path of execution) is not allowed to leave the task-node before the task instance is completed. By default, task instances are configured to be signalling and non-blocking.

If more than one task instance is associated with a task-node, the process developer can specify the way in which completion of the task instances affects continuation of the process. Give any of these values to the task-node's signal-property:

Task instance creation can be based upon a run-time calculation. In these cases, add an ActionHandler to the task-node's node-enter event and set create-tasks="false". Here is an example:

public class CreateTasks implements ActionHandler {

  public void execute(ExecutionContext executionContext) throws Exception {

    Token token = executionContext.getToken();

    TaskMgmtInstance tmi = executionContext.getTaskMgmtInstance();

      

    TaskNode taskNode = (TaskNode) executionContext.getNode();

    Task changeNappy = taskNode.getTask("change nappy");


    // now, 2 task instances are created for the same task.

    tmi.createTaskInstance(changeNappy, token);

    tmi.createTaskInstance(changeNappy, token);

  }

}

Here, the tasks to be created are specified in the task-node. They could also be specified in the process-definition and fetched from the TaskMgmtDefinition. (TaskMgmtDefinition extends the process definition by adding task management information.)

The TaskInstance.end() method is used to mark task instances as completed. One can optionally specify a transition in the end method. In case the completion of this task instance triggers continuation of the execution, the task-node is left over the specified transition.

Assign task instances via the AssignmentHandler interface:

public interface AssignmentHandler extends Serializable {

  void assign( Assignable assignable, ExecutionContext executionContext );

}

An assignment handler implementation is called when a task instance is created. At that time, the task instance is assigned to one or more actors. The AssignmentHandler implementation calls the assignable methods (setActorId or setPooledActors) to assign a task. The assignable item is either a TaskInstance or a SwimlaneInstance (that is, a process role).

public interface Assignable {

  public void setActorId(String actorId);

  public void setPooledActors(String[] pooledActors);

}

Both TaskInstances and SwimlaneInstances can be assigned to a specific user or to a pool of actors. To assign a TaskInstance to a user, call Assignable.setActorId(String actorId). To assign a TaskInstance to a pool of candidate actors, call Assignable.setPooledActors(String[] actorIds).

One can associate each task in the process definition with an handler implementation to perform the assignment at run-time.

The data model for managing assignments of task instances and swimlane instances to actors is the following. Each TaskInstance has an actorId and a set of pooled actors.

The actorId is the responsible for the task, while the set of pooled actors represents a collection of candidates one of whom will become responsible if they take the task. Both actorId and pooledActors are optional and can also be combined.

The personal task list denotes all the task instances that are assigned to a specific individual. This is indicated by the presence of the actorId property on a TaskInstance. Put a TaskInstance in someone's task list in one of these ways:

To fetch the personal task list for a given user, use TaskMgmtSession.findTaskInstances(String actorId).

The pooled actors are the group of candidates to whom the task is offered. One candidate has to accept it. Users can not start working on tasks immediately as that would, potentially, result in a conflict if many people commenced work on the same task. To prevent this, users can only take task instances from the group task list and move these into their personal task lists. It is only when a task is placed on the user's personal task list that her or she can commence working on it.

To put a taskInstance in someone's group task list, add the user's actorId or one of the user's groupIds to the pooledActorIds. To specify the pooled actors, use one of the following methods:

To fetch the group task list for a given user, make a collection that includes the user's actorId and those of all the groups to which the user belongs. Use TaskMgmtSession.findPooledTaskInstances(String actorId) or TaskMgmtSession.findPooledTaskInstances(List actorIds) to search for task instances that are not in a personal task list (actorId==null) and for which there is a match amongst the pooled actorId.

The actorId always overrides pooled actors. Hence, a taskInstance that has an actorId and a list of pooledActorIds will only show up in the actor's personal task list. Retain the pooledActorIds in order to put a task instance back into the group by simply setting the taskInstance's actorId property to null.

The classes in yellow are those which pertain to the expression assignment handler discussed next.

A User represents a user or a service. A Group is any kind of group of users. Groups can be nested to model the relation between a team, a business unit and the whole company. Groups have a type to differentiate between the hierarchical groups and e.g. hair color groups. Memberships represent the many-to-many relation between users and groups. A membership can be used to represent a position in a company. The name of the membership can be used to indicate the role that the user fulfills in the group.

The identity component comes with one implementation that evaluates an expression for the calculation of actors during assignment of tasks. Here's an example of using the assignment expression in a process definition:

<process-definition>

  <task-node name='a'>

    <task name='laundry'>

      <assignment expression='previous --> group(hierarchy) --> member(boss)' />

    </task>

    <transition to='b' />

  </task-node>

      

      <para>Syntax of the assignment expression is like this:</para>

      first-term --> next-term --> next-term --> ... --> next-term



where



first-term ::= previous |

               swimlane(swimlane-name) |

               variable(variable-name) |

               user(user-name) |

               group(group-name)



and 



next-term ::= group(group-type) |

              member(role-name)

</programlisting>

When you want to use your own datasource for organizational information such as your company's user database or LDAP system, you can remove the jBPM identity component. The only thing you need to do is make sure that you delete the following line from the hibernate.cfg.xml.

<mapping resource="org/jbpm/identity/User.hbm.xml"/>

<mapping resource="org/jbpm/identity/Group.hbm.xml"/>

<mapping resource="org/jbpm/identity/Membership.hbm.xml"/>

The ExpressionAssignmentHandler is dependent on the identity component so you will not be able to use it as is. In case you want to reuse the ExpressionAssignmentHandler and bind it to your user data store, you can extend from the ExpressionAssignmentHandler and override the method getExpressionSession.

protected ExpressionSession getExpressionSession(AssignmentContext assignmentContext);