Skip to main content
Version: 8.9 (unreleased)

Configure global user task listeners

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

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.

You can use both methods at the same time. After a cluster restart:

  • Listeners defined through Unified Configuration are recreated, even if they were deleted through the API before restart.
  • API-defined listeners remain active in addition to configuration-defined listeners.
  • If an id conflict occurs, the listener from Unified Configuration takes precedence and replaces the API-defined listener.

Configure through Unified Configuration​

Configure global user task listeners through Unified Configuration under camunda.cluster.global-listeners.user-task.

Each listener entry supports the properties in global listener definition, except source, which is automatically set to CONFIGURATION. Any provided source value is ignored.

How the configuration is validated​

If configuration entries are invalid, the system rectifies them instead of failing startup.

The following validation rules are applied automatically on startup:

  • If a listener is missing the required id, type, or event-types properties, it is removed.
  • If a listener defines invalid event types, those event types are removed. If all event types are invalid, the listener is removed.
    • Valid event types are: creating, assigning, updating, completing, canceling, or the special value all. Event type matching is case-insensitive, so Creating and creating are both valid, but create is not.
  • If a listener defines duplicate event types, the duplicates are removed and only one instance of each event type is kept.
  • 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. This ensures the listener catches all events as intended.
  • If a listener defines invalid retry values (non-numeric, negative, or zero), it is removed. Valid retry values are positive integers.
  • If a listener defines an invalid priority, it is removed. Valid priorities are integers from 0 to 100.

In all these cases, the Orchestration Cluster writes a startup warning that identifies the problem location. Invalid listeners are removed while valid listeners remain active.

note

Listeners defined through the API are not subject to this validation.

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​

note

You need specific authorizations to manage global listeners through the API.

Read more about authorizations and how to create them in the Admin UI.

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, provide the properties described in global listener definition. The source property is set automatically to API.

Changes take effect immediately after the API call for new lifecycle events on running and new instances, without requiring model redeployments or a cluster restart.

Configure via Admin UI​

tip

To learn more about the Admin UI for global user task listeners, see the dedicated page.

You can configure global listeners in the Admin UI through the Global Task Listeners tab.

You can update and delete listeners in the Admin UI without interacting with the API directly or restarting the cluster.

The Admin UI uses the Orchestration Cluster API to manage global user task listeners, so the same considerations apply.

See also​