Skip to content

Commit c57e31d

Browse files
fabiopaini-camundafabiopaini-camunda
committed
feat: documentation for Global User Task Listeners
1 parent 3b65b65 commit c57e31d

File tree

4 files changed

+173
-2
lines changed

4 files changed

+173
-2
lines changed

‎docs/components/concepts/global-user-task-listeners.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
id: global-user-task-listeners
3+
title: "Global user task listeners"
4+
sidebar_label: "Global user task listeners"
5+
description: "Configure cluster‑wide listeners that react to user task lifecycle events across all processes."
6+
---
7+
8+
Global user task listeners are [user task listeners](/components/concepts/user-task-listeners.md) defined once for all processes in the cluster rather than individually per [user task](/components/modeler/bpmn/user-tasks.md).
9+
They let you react to user task lifecycle events across all processes without modifying BPMN models.
10+
11+
They are configured at the cluster level and behave like model-level [user task listeners](/components/concepts/user-task-listeners.md): using the exact same lifecycle events, blocking behavior, deny/correction semantics, payload structure, and incident behavior.
12+
13+
:::tip
14+
Read the [user task listeners](/components/concepts/user-task-listeners.md) page before this one to understand the fundamentals of user task listeners.
15+
:::
16+
17+
## About global user task listeners
18+
19+
Global user task listeners are a cluster-level mechanism to consistently react to user task lifecycle events across all processes. They use the same job mechanism as model-level listeners, so your existing job workers can usually handle them with minimal changes.
20+
21+
Global listeners are particularly useful for:
22+
23+
- Replicating user task changes and context to external systems (audit, analytics, custom Tasklist apps).
24+
- Centralizing SLAs and notifications across all processes.
25+
- Enforcing governance rules and validations (for example, pre-completion checks).
26+
- Applying due date and priority policies consistently.
27+
28+
### How they relate to model-level listeners
29+
30+
Global listeners:
31+
32+
- Require no BPMN model changes. They are configured centrally and apply to all user tasks.
33+
- Use the exact same lifecycle events, blocking behavior, deny/correction semantics, payload structure, and incident behavior as model-level user task listeners.
34+
- Can be ordered before or after model-level listeners.
35+
36+
## Configuration
37+
38+
You configure global user task listeners at the cluster level in the [Unified Configuration](/self-managed/components/orchestration-cluster/core-settings/configuration/properties.md#camundaclusterglobal-listeners).
39+
40+
Configuration path: `camunda.cluster.global-listeners.user-task`
41+
42+
Each listener entry supports the following properties:
43+
44+
| Property | Description |
45+
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
46+
| `event-types` | (Required) 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. |
47+
| `type` | (Required) 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`. |
48+
| `retries` | (Optional) Number of retries for the user task listener job (defaults to 3 if omitted). |
49+
| `after-non-global` | (Optional) Boolean indicating whether the listener should run after model-level listeners. Defaults to `false` (runs before model-level listeners). |
50+
51+
### Validation behavior
52+
53+
On startup, the configuration is validated against the following rules, trying to correct issues where possible instead of failing startup:
54+
55+
- Invalid event types are removed and ignored.
56+
- Listeners with missing information about event types or job type are removed and ignored.
57+
- This also includes listeners for which only invalid event types have been defined.
58+
- If a listener defines both the special `all` value and a normal event type for `event-types`, the configuration is corrected to only include `all`.
59+
- Listeners with invalid information about retries (non-numeric or negative values) are removed and ignored.
60+
61+
In all the above cases, a suitable warning is reported in the orchestration cluster startup log, identifying the problem and its location in the configuration.
62+
63+
### Example configuration (YAML)
64+
65+
```yaml
66+
camunda:
67+
cluster:
68+
global-listeners:
69+
user-task:
70+
- type: "validate-task"
71+
event-types:
72+
- creating
73+
- type: "audit-generic"
74+
event-types: all
75+
retries: 5
76+
- type: "notify-assignee"
77+
event-types:
78+
- assigning
79+
- updating
80+
- canceling
81+
after-non-global: true
82+
```
83+
84+
### Example configuration (environment variables)
85+
86+
```
87+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_TYPE=validate-task
88+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_EVENT_TYPES_0=creating
89+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_TYPE=audit-generic
90+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_EVENT_TYPES_0=all
91+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_1_RETRIES=5
92+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_TYPE=notify-assignee
93+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_EVENT_TYPES_0=assigning
94+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_EVENT_TYPES_1=updating
95+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_EVENT_TYPES_2=canceling
96+
CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_2_AFTER_NON_GLOBAL=true
97+
```
98+
99+
### Applying changes
100+
101+
Configuration changes take effect after a cluster restart. Use rolling restarts to avoid downtime.
102+
103+
After the restart, the new configuration applies to new lifecycle events for both running and new instances, without the need for a redeployment of models.
104+
105+
## Execution and ordering
106+
107+
For a given event on a task instance:
108+
109+
- Global listeners run in configuration order.
110+
- Model-level listeners run next in the order defined in the BPMN model.
111+
- Global listeners marked with `after-non-global: true` run after model-level listeners.
112+
113+
All listeners are blocking and execute sequentially.
114+
115+
## Features
116+
117+
Global listeners support the same features as model-level user task listeners:
118+
119+
- [Blocking behavior](/components/concepts/user-task-listeners.md#blocking-behavior)
120+
- [Triggering on a specific lifecycle event](/components/concepts/user-task-listeners/#trigger-a-user-task-listener)
121+
- [Accessing user task data in job workers](/components/concepts/user-task-listeners/#accessing-user-task-data), in particular:
122+
- task-specific data (assignee, due date, priority, etc.)
123+
- attributes were changed by the event (either through an `updating` event or because of corrections done by previous listeners)
124+
- headers defined in the user task model
125+
- [Correcting user task data](/components/concepts/user-task-listeners/#correcting-user-task-data)
126+
- [Denying lifecycle transitions](/components/concepts/user-task-listeners/#denying-the-lifecycle-transition)
127+
- [Incident recovery](/components/concepts/user-task-listeners/#incident-recovery)
128+
129+
Additionally, you can configure a single global listener to be triggered by more than one lifecycle event (possibly all of them).
130+
131+
## Limitations
132+
133+
The [same limitations as model-level user task listeners](/components/concepts/user-task-listeners.md#limitations) apply.
134+
135+
In addition to those:
136+
137+
- **No tenant-specific configuration**: Configuration is cluster-wide (not per tenant). Payloads include `tenantId` for downstream handling.
138+
- **Restart required**: Configuration changes require a cluster restart to take effect.
139+
140+
## Related resources
141+
142+
- [User task listeners (fundamentals and APIs)](/components/concepts/user-task-listeners.md)
143+
- [Global listener configuration properties](/self-managed/components/orchestration-cluster/core-settings/configuration/properties.md#camundaclusterglobal-listeners)
144+
- [Configure properties through Helm charts](/self-managed/deployment/helm/configure/application-configs.md)

‎docs/components/concepts/user-task-listeners.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,10 @@ Once triggered, the workflow engine creates a job that you can process using a j
8585

8686
## Define a user task listener
8787

88-
You can configure user task listeners per BPMN user task element.
88+
You can configure user task listeners either:
89+
90+
- per BPMN user task element
91+
- for all user tasks in the cluster (see [global user task listeners](/components/concepts/global-user-task-listeners.md))
8992

9093
### User task listener properties
9194

@@ -273,3 +276,4 @@ While you can use [Tasklist v1](components/tasklist/api-versions.md) or the depr
273276
- [Expressions](/components/concepts/expressions.md)
274277
- [Execution listeners](/components/concepts/execution-listeners.md)
275278
- [User tasks](/components/modeler/bpmn/user-tasks/user-tasks.md)
279+
- [Global user task listeners](/components/concepts/global-user-task-listeners.md)

‎docs/self-managed/components/orchestration-cluster/core-settings/configuration/properties.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,16 @@ The following configurations apply to all components within the Orchestration Cl
188188
| `camunda.cluster.replication-factor` | <p>The number of replicas for each partition in the cluster. The replication factor cannot be greater than the number of nodes in the cluster.</p> | `1` |
189189
| `camunda.cluster.size` | <p>The number of nodes in the cluster.</p> | `1` |
190190

191+
### `camunda.cluster.global-listeners`
192+
193+
| Property | Description | Default value |
194+
| :-------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
195+
| `camunda.cluster.global-listeners.user-task[]` | <p>List of configuration entries for global user task listeners (see also [Global user task listeners](/components/concepts/global-user-task-listeners.md).)</p> | No entries |
196+
| `camunda.cluster.global-listeners.user-task[].event-types[]` | <p>List of user task event types that trigger the listener. Supported values are `creating`, `assigning`, `updating`, `completing`, and `canceling`. The shorthand `all` value is also available if the listener should react to all lifecycle events. </p> | - |
197+
| `camunda.cluster.global-listeners.user-task[].type` | <p>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`. </p> | - |
198+
| `camunda.cluster.global-listeners.user-task[].retries` | <p>The number of retries for the user task listener job. </p> | `"3"` |
199+
| `camunda.cluster.global-listeners.user-task[].after-non-global` | <p>Boolean flag indicating whether the listener should run after model-level listeners. </p> | `false` |
200+
191201
### `camunda.cluster.metadata`
192202

193203
| Property | Description | Default value |
@@ -220,6 +230,16 @@ The following configurations apply to all components within the Orchestration Cl
220230
| `CAMUNDA_CLUSTER_REPLICATIONFACTOR` | <p>The number of replicas for each partition in the cluster. The replication factor cannot be greater than the number of nodes in the cluster.</p> | `1` |
221231
| `CAMUNDA_CLUSTER_SIZE` | <p>The number of nodes in the cluster.</p> | `1` |
222232

233+
### `CAMUNDA_CLUSTER_GLOBAL_LISTENERS`
234+
235+
| Property | Description | Default value |
236+
| :-------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
237+
| `CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK` | <p>List of configuration entries for global user task listeners (see also [Global user task listeners](/components/concepts/global-user-task-listeners.md).)</p> | No entries |
238+
| `CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_EVENT_TYPES` | <p>List of user task event types that trigger the listener. Supported values are `creating`, `assigning`, `updating`, `completing`, and `canceling`. The shorthand `all` value is also available if the listener should react to all lifecycle events. </p> | - |
239+
| `CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_TYPE` | <p>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`. </p> | - |
240+
| `CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_RETRIES` | <p>The number of retries for the user task listener job. </p> | `"3"` |
241+
| `CAMUNDA_CLUSTER_GLOBAL_LISTENERS_USER_TASK_0_AFTER_NON_GLOBAL` | <p>Boolean flag indicating whether the listener should run after model-level listeners. </p> | `false` |
242+
223243
### `CAMUNDA_CLUSTER_METADATA`
224244

225245
| Property | Description | Default value |

‎sidebars.js‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,10 @@ module.exports = {
111111
type: "doc",
112112
id: "components/concepts/user-task-listeners",
113113
},
114-
items: ["components/concepts/listen-to-user-tasks"],
114+
items: [
115+
"components/concepts/global-user-task-listeners",
116+
"components/concepts/listen-to-user-tasks",
117+
],
115118
},
116119
],
117120
},

0 commit comments

Comments
 (0)