task assignment camunda

A User Task is used to model work that needs to be done by a human actor. When the process execution arrives at such a User Task, a new task is created in the task list of the user(s) or group(s) assigned to that task.

A User Task is defined in XML as follows. The id attribute is required, while the name attribute is optional.

Description

A User Task can also have a description. In fact, any BPMN 2.0 element can have a description. A description is defined by adding the documentation element.

The description text can be retrieved from the task in the standard Java way:

Each task has a field indicating the due date of that task. The Query API can be used to query for tasks that are due on, before or after a certain date.

There is an activity extension which allows you to specify an expression in your task-definition to set the initial due date of a task when it is created. The expression should always resolve to a java.util.Date, java.util.String ( ISO8601 formatted) or null. When using ISO8601 formatted Strings, you may either specify an exact point in time or a time period relative to the time the task is created. For example, you could use a date that was entered in a previous form in the process or calculated in a previous Service Task.

The due date of a task can also be altered using the TaskService or in TaskListeners using the passed DelegateTask.

Follow Up Date

Each task has a field indicating the follow up date of that task. The Query API can be used to query for tasks that need to be followed up on, before or after a certain date.

There is an activity extension which allows you to specify an expression in your task-definition to set the initial follow up date of a task when it is created. The expression should always resolve to a java.util.Date, java.util.String ( ISO8601 formatted) or null. When using ISO8601 formatted Strings, you may either specify an exact point in time or a time period relative to the time the task is created. For example, you could use a date that was entered in a previous form in the process or calculated in a previous Service Task.

User Assignment

A User Task can be directly assigned to a single user, a list of users or a list of groups.

Assignment using BPMN Resource Assignments

BPMN defines some native assignment concepts which can be used in camunda. As a more powerful alternative, Camunda also defines a set of custom extension elements (see below).

Human Performer

This is done by defining a humanPerformer sub element. Such a humanPerformer definition needs a resourceAssignmentExpression that actually defines the user. Currently, only formalExpressions are supported.

Only one user can be assigned to the task as a human performer. In the engine terminology, this user is called the assignee. Tasks that have an assignee are not visible in the task lists of other users and can be found in the so-called personal task list of the assignee instead.

Tasks directly assigned to users can be retrieved through the TaskService as follows:

Potential Owner

Tasks can also be put in the so-called candidate task list of people. In that case, the potentialOwner construct must be used. The usage is similar to the humanPerformer construct. Please note that for each element in the formal expression it is required to specifically define if it is a user or a group (the engine cannot guess this).

Tasks defined with the potential owner construct can be retrieved as follows (or a similar TaskQuery, such as for tasks which have an assignee, can be used):

This will retrieve all tasks where kermit is a candidate user, i.e., the formal expression contains the user kermit . This will also retrieve all tasks that are assigned to a group of which kermit is a member (e.g., group(management) , if kermit is a member of that group and the identity component is used). The groups of a user are resolved at runtime and these can be managed through the IdentityService.

If no specifics are given whether the given text string is a user or a group, the engine defaults to group. So the following two alternatives lead to the same result:

User Assignment using Camunda Extensions

It is clear that user and group assignments are quite cumbersome for use cases where the assignment is more complicated. To avoid these complexities, custom extensions on the User Task are possible.

The assignee attribute: this custom extension allows direct assignment of a User Task to a given user.

This is exactly the same as using a humanPerformer construct as defined above.

Candidate Users

The candidateUsers attribute: this custom extension allows you to make a user a candidate for a task.

This is exactly the same as using a potentialOwner construct as defined above. Note that it is not required to use the user(kermit) declaration as is the case with the potential owner construct, since this attribute can only be used for users.

Candidate Groups

The candidateGroups attribute: this custom extension allows you to make a group a candidate for a task.

This is exactly the same as using a potentialOwner construct as defined above. Note that it is not required to use the group(management) declaration as is the case with the potential owner construct, since this attribute can only be used for groups.

Combining Candidate Users and Groups

candidateUsers and candidateGroups can both be defined for the same User Task.

Assignment based on Data and Service Logic

In the above examples, constant values such as kermit or management are used. But what if the exact name of an assignee or a candidate group is not known at design time? And what if the assignee is not a constant value but depends on data such as “The person who started the process” ? Maybe the assigment logic is also more complex and needs to access an external data source such as LDAP to implement a lookup such as “The manager of the employee who started the process” .

Such things can be implemented using assignment expressions or task listeners.

Assignment Expressions

Assignment expressions allow accessing process variables or calling out to beans and services.

Using Process Variables

Process variables are useful for assignments based on data which has been collected or calculated up front.

The following example shows how to assign a User Task to the person who started the process:

First, the camunda:initiator extension is used to bind the user id of the person who started ( “initiated” ) the process to the variable starter . Then the expression ${ starter } retrieves that value and uses it as assignee for the task.

It is possible to use all process variables visible from the User Task in the expression.

Invoking a Service / Bean

When using Spring or CDI, it is possible to delegate to a bean or service implementation. This way it is possible to call out to complex assignment logic without modeling it as an explicit service task in the process which would then produce a variable used in the assignment.

In the following example, the assignee will be set by calling the findManagerOfEmployee() on the ldapService Spring/CDI bean. The emp parameter that is passed is a process variable.

This also works in a similar way for candidate users and groups:

Note that this will only work if the return type of the invoked methods is String or Collection<String> (for candidate users and groups):

Assignments in Listeners

It is also possible to use task listeners for handling assignments. The following example demonstrates a task listener on the create event:

The DelegateTask that is passed to the TaskListener implementation allows you to set the assignee and candidate-users/groups:

Assigning a task, or setting any other property through a TaskListener, will not result in an assignment or update event unless a TaskService method is used to perform these actions. This is intentional, in order to avoid creating event loops.

Assignments and Identity Service

Although the Camunda engine provides an identity management component, which is exposed through the IdentityService, it does not check whether a provided user is known by the identity component. This allows integration of the engine with existing identity management solutions when it is embedded into an application.

However, note that you can use the identity service in a service / bean or listener to query your user repository if this is useful to you.

You can query for users with the help of the identity service. See the following example:

Reporting Bpmn Error

See the documentation for Error Boundary Events .

To report a business error during user task operation, use TaskService#handleBpmnError . It can be invoked only when the task is active. The #handleBpmnError method requires a mandatory argument: errorCode . The error code identifies a predefined error. If the given errorCode does not exist or there is no boundary event defined, the current activity instance simply ends and the error is not handled.

See the following example:

A BPMN error with the error code bpmn-error-543 is propagated. If a boundary event with this error code exists, the BPMN error will be caught and handled. The error message and variables are optional. They can provide additional information for the error. The variables will be passed to the execution if the BPMN error is caught.

Reporting Bpmn Escalation

See the documentation for Catching Escalation Events .

Reporting an escalation during user task execution can be achieved via TaskService#handleEscalation . The user task should be active to do so. The escalationCode is compulsory to invoke the escalation, this code identifies a predefined escalation. If the given escalationCode does not exist an Process Engine Exception will be thrown. See the following example:

Here an escalation is propagated with escalation code escalation-432 . If a boundary event with this escalation code exists, the escalation will be caught and handled. The variables are optional. They will be passed to the execution if the escalation is caught.

Complete is part of the task lifecycle operation along with create, set candidate, assign, etc. (allow available via Java API). Complete a task by passing variables, optionally the process variables can be retrieved::

It is possible to provide information to render a User Task form by using the camunda:formKey attribute:

The form key is a symbolic value which can be set in the BPMN XML file by using the extension attribute formKey and retrieved at runtime using the process engine API.

If the User Task form is displayed inside the Camunda Tasklist, the format of the formKey must follow special rules. See the corresponding section in the user guide for details .

In custom applications, the value of the form key attribute can be interpreted freely. Based on the specific UI technology used, it can reference the name of an HTML file, a JSF / Facelets template, a Vaadin / GWT view, …

Retrieving the Form Key using the Form Service.

Retrieving the form using the task service.

When performing a task query, it is possible to retrieve the form key as well. This is most useful if the form keys need to be retrieved for a complete list of tasks:

Note that it is required to call the .initializeFormKeys() method on the TaskQuery object to make sure the form keys are initialized.

Form submission

When a form is submitted, it is possible to fetch the process variables in return:

Camunda Extensions

On this page:.

We are looking for talented people. Check out our open positions .

Understanding human task management

Using task assignment features ​.

The lifecycle of human tasks (like assigning, delegating, and completing tasks) is mostly a generic issue. There is no need to model common aspects into all your processes, if often makes models unreadable. Use Camunda task management features or implement your requirements in a generic way.

So every task can be assigned to either a group of people, or a specific individual. An individual can 'claim' a task, indicating that they are picking the task from the pool (to avoid multiple people working on the same task).

As a general rule, you should assign human tasks in your business process to groups of people instead of specific individuals.

Then, require individual members of that group to explicitly claim tasks before working on them. This way, you avoid different people working on the same task at the same time. See claimTask .

You can also directly claim tasks in Camunda Tasklist with the click of a button.

While assigning users to groups is advised, it's not the only option. You could always assign a task to a single person who is supposed to complete the task (e.g. the individual 'customer' of your process or a coworker having specific knowledge for the case). You will need to have access to the specific person relevant for your process instance, e.g. via a process variable:

Deciding about your task list frontend ​

If you have human tasks in your process, you must make up your mind on how exactly you want to let your users work on their tasks and interact with the workflow engine. You have basically three options:

Camunda Tasklist : The Tasklist application shipped with Camunda. This works out-of-the-box and has a low development effort. However, it is limited in terms of customizability and how much you can influence the user experience.

Custom task list application: You can develop a custom task list and adapt this to your needs without compromises. Human tasks are shown inside your custom application, following your style guide and usability concept. You will use the Camunda Tasklist API in the background. This is very flexible, but requires additional development work.

Third party tasklist: If our organization already has a task list application rolled out to the field, you might want to use this for tasks created by Camunda. You will need to develop some synchronization mechanism. The upside of this approach is that your end users might not even notice that you introduce a new workflow engine.

Considerations for developing custom task lists ​

When building a custom tasklist/application, you must plan for the following aspects. You will need to

• Query for user tasks and generate lists of those tasks.
• Filter the list along specific attributes like current assignee, candidate groups, etc.
• Select and display the right forms for starting processes and completing tasks.
• Use custom/business value data in order to filter with those values and display them correlated with the task list and within forms.
• Authorize users to access those lists, filters, and forms.

Considerations for using third party task lists ​

When integrating a third party tasklist, you must plan for the following aspects. You will need to take care of:

• Creating tasks in the third party tasklist based on the user tasks created by Camunda.
• Completing tasks in Camunda and move on process execution based on user action in the third party tasklist.
• Cancelling tasks, triggered by Camunda or triggered by the user in the third-party tasklist.
• Transferring business data to be edited in the third-party tasklist back and forth.

Your third party tasklist application also needs to allow for some programmatic control of the lifecycle of its tasks. The third-party application must have the ability:

• To programmatically create a new task.
• To hook in code which programmatically informs other systems that the user is about to change a task's state.
• To manage custom attributes connected to a task and programmatically access them.

Additionally, it should have the ability

• To programmatically delete a task which was cancelled in Camunda. Without this possibility such tasks remain in the users tasklist and would need to be removed manually. Depending on the way you integrate the task completion mechanism, when the user tries to complete such tasks, they would immediately see an error or the action would just not matter anymore and serve as a removal from the list.

Transfer just the minimal amount of business data in between Camunda and your third-party tasklist application.

For creating tasks, transfer just the taskId and important business data references/ids to your domain objects. As much as possible should be retrieved later, and just when needed (e.g. when displaying task forms to the user) by requesting data from the process engine or by requesting data directly from other systems.

For completing tasks, transfer just the business data which originated from Camunda and was changed by the user. This means, in case you just maintain references, nothing needs to be transferred back. All other business data changed by the user should be directly transferred to the affected systems.

Task lists may not look like task lists ​

There are situations where you might want to show a user interface that does not look like a task list, even if it is fed by tasks. The following example shows such a situation in the document input management process of a company. Every document is handled by a separate process instance, but users typically look at complete mailings consisting of several such documents. In a customer scenario, there were people in charge of assessing the scanned mailing and distributing the individual documents to the responsible departments. It was important to do that in one step, as sometimes documents referred to each other.

So you have several user tasks which are heavily interdependent from a business point of view and should therefore be completed in one step by the same person.

The solution to this was a custom user interface that basically queries for human tasks, but show them grouped by mailings:

The custom tasklist shows each mailing as one "distribution task", even though they consist of several human tasks fetched from the workflow instance.

The custom user interface allows you to work on all four human tasks at once. By dragging and dropping a document within the tree, the user can choose to which department the document is delivered to.

In case the user detects a scanning problem, they can request a new scan of the mailing. But as soon as all documents are quality assured, the button Distribute Mailing gets enabled. By clicking on it, the system completes all four human tasks - one for each document - which moves forward the four process instances associated with the documents.

• Using task assignment features
• Considerations for developing custom task lists
• Considerations for using third party task lists
• Task lists may not look like task lists

• Engineering
• How to send an email when a usertask is assigned
• October 31, 2013

30 Day Free Trial

Bring together legacy systems, RPA bots, microservices and more with Camunda

Sign Up for Camunda Content

Get the latest on Camunda features, events, top trends, and more.

TRENDING CONTENT

Pro-code, Low-code, and the Role of Camunda

Process Automation CoE Playbook

“I don’t want to watch my camunda Tasklist all day. When there is something to do, I want to get an email containing a link that takes me directly to the respective task!”

This is a typical statement by process participants (aka business users). There are numerous possible ways to implement such a requirement in your process application, e.g. using a service task:

But this is not really appropriate, since it makes the process model rather verbose and therefore less valuable for business-IT-alignment.

The more elegant way is to use a task listener: This very powerful concept is  described in detail in the userguide , and the behavior we want is a perfect use case, so let’s see how it works!

Let’s say we created a simple process application (like in the Get Started Tutorial ), but this process contains only one usertask. The next step is to created a Task Listener Class like the one below. The important parts are:

• It implements the Task Listener Interface.
• It retrieves the assignee from the Task Object and loads the according User Profile including the assignee’s email address.
• It creates a simple mail containing a deep link to the task instance.

The last step is to assign the class as a task listener to the usertask in the process model. As you can see below, the task listener will be executed when the usertask has been assigned:

And that’s about it! If you want to see an example ready to run, just check out the Task Assignment Email Quickstart .

From a user perspective, it will look like this:

Have fun with camunda 🙂

Getting Started

Getting started on Camunda is easy thanks to our robust documentation and tutorials

Try All Features of Camunda

Related content, a developer’s guide to migrating an existing workflow to camunda, adapt faster with camunda: embrace ever-changing business requirements with ai-infused end-to-end orchestration, camundacon berlin 2024 day 2 live blog.