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. 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, as explained in the Configure global user task listeners section below, but it has no practical effect in how the global listeners are executed.

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.

Configure global user task listeners

You can configure global user task listeners at the cluster level:

• Configure through Unified Configuration.
• Configure via the Orchestration Cluster API.
• Configure via the Admin UI.

Use the Unified Configuration if:

• You want to define a static set of global listeners that are always active in the cluster.
• You want to use versioning tools to keep track of configuration changes.

Use the Orchestration Cluster API if:

• You want to dynamically manage listeners without restarting the cluster.
• You want to manage permissions for who can create, update, or delete global listeners through API access control.

The two ways of configuring global listeners can be used at the same time, however it is important to be aware of the behaviour after a cluster restart:

• All listeners defined through the Unified Configuration are recreated after a restart, even if they were deleted through the API before the restart.
• Listeners defined through the API are not affected by restarts, so they remain active in addition to the listeners defined through the Unified Configuration.
• If an id conflict occurs between a listener defined through the Unified Configuration and another defined through the API, the listener defined through the Unified Configuration takes precedence and completely replaces the API-defined one.

Configure through Unified Configuration

You can configure the global user task listeners through the Unified Configuration by setting the appropriate properties under the configuration path camunda.cluster.global-listeners.user-task.

Each listener entry can be configured with the properties described in the Global listener definition section above, except for the source property which is automatically set to CONFIGURATION by the system.

How the configuration is validated

On startup, the configuration is validated according to the following rules. The system attempts to correct issues where possible instead of failing the startup:

• Invalid event types are removed and ignored.
• Listeners missing information about identifier, event types or job type are removed and ignored.
  • This also includes listeners for which only invalid event types are defined.
• If a listener defines both the special all value and a normal event type for event-types, the configuration is corrected to include only all.
• Listeners with invalid retry values, i.e., non-numeric or negative, are removed and ignored.

In all cases, a suitable warning is reported in the orchestration cluster startup log, identifying the problem and its location in the configuration.

Example configuration

The following is an example YAML configuration and environment variables:

camunda:
  cluster:
    global-listeners:
      user-task:
        - id: "validation-listener"
          type: "validate-task"
          event-types:
            - creating
          priority: 70
        - id: "audit-listener"
          type: "audit-generic"
          event-types: all
          retries: 5
          priority: 50
        - id: "notification-listener"
          type: "notify-assignee"
          event-types:
            - assigning
            - updating
            - canceling
          after-non-global: true
          priority: 30

CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_ID=validation-listener
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_TYPE=validate-task
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_EVENT_TYPES_0=creating
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_PRIORITY=70
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_ID=audit-listener
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_TYPE=audit-generic
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_EVENT_TYPES_0=all
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_RETRIES=5
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_PRIORITY=50
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_ID=notification-listener
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_TYPE=notify-assignee
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_EVENT_TYPES_0=assigning
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_EVENT_TYPES_1=updating
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_EVENT_TYPES_2=canceling
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_AFTER_NON_GLOBAL=true
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_PRIORITY=30

Apply changes

Configuration changes take effect after you restart the cluster. Use rolling restarts to avoid downtime.

After the restart, the new configuration applies to new lifecycle events for both running and new instances, without requiring you to redeploy models.

Configure via Orchestration Cluster API

The Orchestration Cluster API provides CRUD operations to manage global user task listeners at runtime. This allows you to create, update, and delete listeners without restarting the cluster.

When you create or update a listener through the API, you need to provide the same properties described in the Global listener definition section above, except for the source property which is automatically set to API by the system.

The changes to the global listeners take effect immediately after the API call, applying to new lifecycle events for both running and new instances, without requiring you to redeploy models or restart the cluster.

Configure via Admin UI

You can visually configure global listeners through the Admin UI, which provides a user-friendly interface to manage the listeners in the Global Task Listeners tab.

You can update and delete global listeners through the Admin UI without needing to interact directly with the API or restart the cluster.

The Admin UI uses the Orchestration Cluster API to interact with the global user task listeners configuration, so the exact same considerations apply.

Known limitations

The Admin UI retrieves the listener list from secondary storage. Because secondary storage is eventually consistent, changes might not appear immediately.

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.

See also

• Global listener configuration properties.
• Configure properties through Helm charts.
• Orchestration Cluster API.