Global user task listeners

Global user task listeners are user task listeners defined once for all processes in a cluster, instead of individually per user task.

About global user task listeners

Use global listeners to react to user task lifecycle events across all processes without modifying BPMN models.

Global listeners are configured at the cluster level and behave like model-level user task listeners, using the same lifecycle events, blocking behavior, deny/correction semantics, payload structure, and incident handling.

They are particularly useful for:

• Replicating user task changes and context to external systems, such as audit, analytics, or custom Tasklist apps.
• Centralizing Service Level Agreements and notifications across all processes.
• Enforcing governance rules and validations. For example, pre-completion checks.
• Consistently applying due date and priority policies.

Global listener definition

Each listener is defined by the following properties:

Property	Required	Description
id	Yes	User-provided unique identifier for the listener. This identifier is used to interact with the global listener through API
eventTypes	Yes	List of user task event types that trigger the listener. Supported values: creating, assigning, updating, completing, canceling. The shorthand all value is also available if the listener should react to all lifecycle events.
type	Yes	The name of the job type. Used as a reference to specify which job workers request the respective task listener job. For example, order-items.
retries	No	Number of retries for the user task listener job. Defaults to 3 if not set.
afterNonGlobal	No	Boolean indicating whether the listener should run after model-level listeners. Defaults to false (runs before model-level listeners).
priority	No	The priority of the listener. Higher priority listeners are executed before lower priority ones. It must be an integer between 0 and 100. Defaults to 50 if not set.
source	No (automatically set)	Indicates how the listener was defined, either through configuration or API. Supported values: CONFIGURATION and API. This property is automatically set by the system and cannot be modified by users.

You have to use a different id for each configured listener, since this property is used to uniquely identify the listener and interact with it through the Orchestration Cluster API, for example, to update or delete the listener.

You can use the same type value for multiple listeners if they should be handled by the same job workers.

The source property only distinguishes how the listener was defined, but it has no practical effect in how the global listeners are executed.

You can configure global user task listeners in multiple ways, as described in configure global user task listeners:

• Through the Unified Configuration.
• Via the Orchestration Cluster API.
• Via the Admin UI.

Execution order

For a given event on a task instance:

• Global listeners run in the order defined by the priority property of each listener.
  • Listeners with a higher priority are executed first.
  • Listeners with the same priority are sorted by their id in lexicographical order to ensure a deterministic execution order.
• Model-level listeners run next, in the order defined in the BPMN model.
• Global listeners marked with after-non-global: true (Unified Configuration) or afterNonGlobal: true (API) run after model-level listeners.

Supported features

Global listeners support the same features as model-level user task listeners:

• Blocking behavior.
• Triggering on a specific lifecycle event.
• Accessing user task data in job workers, in particular:
  • Task-specific data, such as, assignee, due date, or priority.
  • Attributes changed by the event, either through an updating event or because of corrections done by previous listeners.
  • Headers defined in the user task model.
• Correcting user task data.
• Denying lifecycle transitions.
• Incident recovery.

Additionally, you can configure a single global listener to be triggered by multiple lifecycle events, possibly all of them.

Limitations

The same limitations as model-level user task listeners apply.

In addition to the above:

• No tenant-specific configuration: Configuration is cluster-wide, not per tenant. Payloads include tenantId for downstream handling.
• Restart required: Changes made through Unified Configuration take effect only after a cluster restart. This limitation does not apply when you manage listeners through the Orchestration Cluster API.