Task Assignment — stateway:assignmentDefinition

BPMN 2.0 does not define a standard syntax for assigning tasks to users or groups — that space is intentionally left for each engine to define. Stateway uses the stateway:assignmentDefinition extension inside <bpmn:extensionElements> of any userTask.

The Three Mechanisms

<bpmn:userTask id="reviewTask" name="Review Request">
  <bpmn:extensionElements>
    <stateway:assignmentDefinition
      assignee="{{variables.managerId}}"
      candidateUsers="alice,bob,carol"
      candidateGroups="approvers,supervisors" />
  </bpmn:extensionElements>
</bpmn:userTask>

assignee — Direct assignment to a specific user. Only that user_id receives the task. Accepts expressions: {{variables.responsibleAnalyst}}.

candidateUsers — A list of individual users who can claim the task. Any user on the list can take ownership and complete it. Useful when the process knows the candidates individually (e.g., an external system designated two analysts to review a case). Accepts expressions: {{variables.eligibleReviewers}} (must resolve to a CSV string).

candidateGroups — A list of groups that can claim the task. Any user whose session declares one of those groups in roles can take ownership. Useful for role-based work pools (e.g., any member of the approvers group). Accepts expressions: {{variables.departmentGroup}}.

The three attributes can coexist. Eligibility is calculated by union: a user is eligible if they satisfy at least one criterion.

Pool Tasks vs. Direct Assignment

Tasks with assignee defined arrive directly to the user — no claim required. The user can complete immediately.

Tasks with candidateUsers or candidateGroups (without assignee) are pool tasks: any eligible user sees them in their inbox, but must claim the task before completing it. The SDK exposes task.isClaimed and task.claimedBy so the frontend can render the correct state.

How to Configure

In Camunda Modeler, use the custom extension panel. In bpmn.io, edit the XML directly (Edit → Edit as XML).

The stateway:assignmentDefinition element belongs to the stateway: namespace. Your BPMN file should declare it:

<bpmn:definitions
  xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
  xmlns:stateway="http://stateway.io/schema/1.0"
  ...>

Expression Support

All three attributes accept expressions resolved against process variables at the moment the token reaches the element:

<stateway:assignmentDefinition
  assignee="{{variables.requestApprover}}"
  candidateGroups="{{variables.departmentGroup}}" />

Task Visibility in the Frontend Gateway

For a user to receive a task via the Frontend Gateway, the session scope must be configured correctly:

Task mechanism	Required scope configuration
assignee = user_id	No special configuration — the session's user_id is always checked
candidateUsers contains user_id	candidate_as_user: true in the definition scope
candidateGroups contains a group	The group must be listed in roles in the definition scope

Validation Rules

The engine rejects BPMN where a userTask has a stateway:assignmentDefinition with none of the three attributes filled. A task without assignment is only valid when there is no stateway:assignmentDefinition at all — in that case, your backend can assign it manually via the REST API after creation.