Skip to main content
Version: 8.9 (unreleased)

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.

Configure global user task listeners​

Set global user task listeners at the cluster level using the zeebe.broker.experimental.listeners.task path in the broker configuration.

Each listener entry can be configured with the following properties:

PropertyRequiredDescription
event-typesYes

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.

typeYes

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.

retriesNoNumber of retries for the user task listener job. Defaults to 3 if not set.
after-localNoBoolean indicating whether the listener should run after model-level listeners. Defaults to false (runs before model-level listeners).

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 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:

zeebe:
  broker:
    experimental:
      engine:
        listeners:
          task:
            - type: "validate-task"
              event-types:
                - creating
            - type: "audit-generic"
              event-types: all
              retries: 5
            - type: "notify-assignee"
              event-types:
                - assigning
                - updating
                - canceling
              after-local: true
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_0_TYPE=validate-task
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_0_EVENT_TYPES_0=creating
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_1_TYPE=audit-generic
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_1_EVENT_TYPES_0=all
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_1_RETRIES=5
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_2_TYPE=notify-assignee
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_2_EVENT_TYPES_0=assigning
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_2_EVENT_TYPES_1=updating
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_2_EVENT_TYPES_2=canceling
ZEEBE_BROKER_EXPERIMENTAL_ENGINE_LISTENERS_TASK_2_AFTER_LOCAL=true

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.

Execution order​

For a given event on a task instance:

  • Global listeners run in the order defined in the configuration.
  • Model-level listeners run next, in the order defined in the BPMN model.
  • Global listeners marked with after-local: true run after model-level listeners.

Supported features​

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

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: Configuration changes take effect only after a cluster restart.

See also​