Dispatch tasks to users: how to do it with Bonita

antoine.mottier's picture
Blog Categories: 


Once you designed a process with user tasks, data and forms you probably want to configure who will be able to perform the various user tasks. This blog post will try to clarify how you do that in Bonita.

Candidates and assignee

First thing to know is that, in Bonita, a user task instance can be performed by a set of users (i.e. the candidates).

When a user is connected on Bonita Portal he/she can see the list of user task instances he/she can perform. But before actually performing the task (usually by submitting the task form), he/she needs to claim the task. By doing so he/she becomes the task assignee. This action prevents concurrent actions from several candidates on a single user task instance. Not that if the task assignee realize that he/she cannot actually perform a user task instance he/she can release it. Releasing a user task instance will make it available again to all the initial candidates.

In order to define the candidates of a user task instances Bonita offers two alternatives: actor and actor filters. Let see how to use them and what are the difference between: Actor and Actor filter


  • In the process definition an actor is just a name declared at the pool level. To add/edit/delete actors select the process definition pool (the outer rectangle shape in the diagram) and go to "General" → "Actors". By default one actor named "Employee actor" is created.
  • Next step is to associate the actor with a lane or directly with a user task definition. To associate an actor with a lane, select the lane by clicking on the lane name (e.g. "Employee lane"), go to "General" → "Actors" and in the drop-down list select the actor. By default, all user task definitions inherent from the lane configuration. You can override this by selecting a user task definition and go to "General" → "Actors". Note that a Bonita process definition includes one lane by default named "Employee lane" associated with the "Employee actor" actor.
  • In process configuration you will then associate this actor with group(s), role(s), membership(s), user(s) or any combinations of all the previous in order to define who can do the task. To configure this mapping between actors declared in the process definition and the organization, select the process definition pool, go to "Server" → "Configure" menu, select "Actor mapping", select the actor name in the list on use the "Groups...", "Roles...", "Memberships...", "Users..." button to configure it.
  • Configuration of the actor is only based on organization (users, roles, groups) information. It cannot use process information such as a process business data or information about the user who start the process.

Actor filter

  • First of all this is really a bad name as it actually does not filter anything.
  • Actor filter is another solution to define the candidates of a user task instances. This list of user will be compute by executing an actor filter when process instance execution flow reach a user task for which an actor filter is configured. An actor filter can have inputs, its own business logic and is executed when the process instance is running. So an actor filter can use information such as process business variables, process instance initiator (the user who start the process instance), external database or service information...
  • Actor filter is for example useful if you want to assign a task to the manager of the user who start a process instance.
  • You have a catalog of actor filters available out of the box and you can also create your own one.
  • Just as for actor, actor filter can be configured by selecting the lane or the user task definition and going in "General" → "Actors" tab. A configuration at the task level will override the configuration done at the lane level.
  • Note that an actor filter receive as input information the name of the actor associated with the task but this information is not usually used.

Who can start a process?

In order to define who can start a process you need to:

  • Have at least one actor declared in your process definition (see above how to delcare actor).
  • Configure the actor mapping to associate the actor with all the users that can start the process (see above for actor configuration).
  • Set the flag "initiator" on the actor: select the process definition pool, go to "General" → "Actors", select an actor, click on "Set as initiator" button.


  • Process definition: the static definition of the process as created in Bonita Studio.
  • User task definition: the static definition of a task. Include the name of the task, connector configuration...
  • Process instance: a running process created based on the process definition. It will store information such as who start the process.
  • User task instance: a live task based on the user task definition. It will include information such as the assignee id if a user claim the task and the performer id if the task has been done.
  • Actor: an identifier declare in process definition and associated with lanes and tasks.
  • Actor mapping: association between an actor and an organization. Association is based on groups, roles...
  • Actor filter: a piece of code that generate a list of candidates associated with a user task instance.
  • Candidates: the set of users who can perform a task. It can be either defined by the actor mapping or override by an actor filter.
  • Assignee: the user who claim a task. This prevent concurrent access from user task instance candidates.
  • Performer: the user who actually do a task usually by submitting the task form.
  • Initiator: the user who start a process usually by submitting the process definition instantiation form. Initiator can also refer to the flag added to an actor in order to define who can start a process.