How to use Human Tasks in jBPM

A Human task, according to the (WS-HumanTask) Specification lets you model an activity that requires a human actor. When the process execution reaches at the user task node, a new task instance is created in the worklist of the actor(s) or group(s) defined for this task.

Human tasks can transition to several different states and involve stakeholders depending on the action taken on the task itself and the defined Roles.

jBPM Human Task roles

Human Task roles define what a person or a group of actors can do with tasks. Following here is the list of roles for the human task activities:

  • Task initiator: The person who creates the task instance.
  • Actual owner: The person who owns the task and is performing it. A task always has one actual owner.
  • Potential owners: users able to claim and complete a Task A potential owner can become the actual owner of a task by claiming it.
  • Excluded owners: Actors may not transition to be an actual or potential owner, and they may not reserve or start a task.
  • Business administrators: Business administrators are able to perform the same operations as task users since they are always potential owners of every task. jBPM provides a default business administrator user (Administrator) and group (Administrators).

Creating a Task from the jBPM Designer

Creating a jBPM Task from your designer is pretty simple as it’s available in the default palette. As you can see from the following picture, when you add a Task and enter in the Properties window you will be able to set key Task attributes such as: Task Name, Subject, Actors, Groups, Assignments / Reassignments/ Notifications, Priority, On Entry/On Exit actions:

jbpm human task

In the above example, the Task has been assigned to the user “john”.

Task reassignment

Task reassignment is a mechanism that lets you change its ownership by setting specific rules, which are based on the task state transition and a deadline time expression.

For example: “if John does not start the task in 60 seconds then reassign the task instance to Krisv”. The resulting reassignment rule syntax is :


Task notification

A notification can be emitted to alert an actor or group when a task has not been Started or has not been Completed by its deadline. The default jBPM notification is via e-mail and the default e-mail configuration is read from the and files.

jbpm human task

In the above example, If the human task is not started with in 1 min of process start then a notification email would be triggered.

Human Task State transitions

The task remains in the Created state until it is activated. When the task has a single potential owner, it transitions into the Reserved state (it is assigned to a single actual actor); otherwise, it transitions into the Ready state; this state indicates that the task can be claimed by one of its potential owners. After being claimed, the task transitions into the Reserved state, elevating the potential owner to the actual
owner actor.

At this point, the actor can start the task that is in either the Ready or the Reserved state and make it transition to the InProgress state. The InProgress state means that the task is being worked on. If the actor completes the work, the task transitions into the Completed state. If the completion of the work goes wrong (exception), the task is put into the Failed state.

Alternatively, the user can release the task, bringing it back to the Ready state. No transition is allowed from the Complete state and the Failed state.

UserTaskService API

the API covers complete life cycle of individual task so it can be managed from start to end. The following example shows how to interact with the UserTaskService to get the list of Tasks assigned to the user “john”, that will be claimed, started and finally completed passing as input a list of parameters:

public class Application  {

    private ProcessService processService;
    private RuntimeDataService runtimeDataService;
    private UserTaskService userTaskService;
    public static void main(String[] args) {, args);

    public ResponseEntity<String> sayHello(@RequestParam Integer age) throws Exception {

        // Provided as an example. Not actually needed by our process.
        Map<String, Object> vars = new HashMap<>();
        vars.put("processVar1", "Hello");

        Long processInstanceId = processService.startProcess("business-application-kjar-1_0-SNAPSHOT", "com.mastertheboss.LicenseDemo", vars);

        Map<String, Object> params = new HashMap<String, Object>();
        params.put("age", age);

        List<TaskSummary> taskSummaries = runtimeDataService.getTasksAssignedAsPotentialOwner("john", new QueryFilter());

            Status status = taskSummaries.get(0).getStatus();
            if ( status == Status.Ready )
                userTaskService.claim(s.getId(), "john");
            userTaskService.start(s.getId(), "john");
            userTaskService.complete(s.getId(), "john", params);

        return ResponseEntity.status(HttpStatus.CREATED).body("Task completed!");

This example is taken from Developing a jBPM 7 Web application example

Found the article helpful? if so please follow us on Socials