@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.concepts.global-user-task-listeners.access-control.md

@@ -0,0 +1,23 @@
+# Access control for global user task listeners
+
+Permissions required to manage global user task listeners.
+
+Global user task listeners are managed through the Orchestration Cluster authorization model. This page lists the permissions required to manage listeners through the Orchestration Cluster REST API and Admin UI.
+
+
+## When you need to configure permissions
+
+Configure permissions for global user task listeners if all of the following apply:
+
+- [Authorizations are enabled for the cluster](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations#configuration).
+- You manage global user task listeners through one of the following:
+  - The [Orchestration Cluster API](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration#configure-via-orchestration-cluster-api), or
+  - The [Admin UI](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration#configure-via-admin-ui).
+
+You do not need additional Orchestration Cluster authorizations when:
+
+- Defining listeners via [Unified Configuration](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration#configure-through-unified-configuration).
+- You only execute processes that are already affected by global listeners. Execution-time behavior is not guarded by separate permissions.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/access-control

package/.llms/chunks/components.concepts.global-user-task-listeners.access-control.required-permissions.md

@@ -0,0 +1,16 @@
+# Access control for global user task listeners — Required permissions
+
+Global user task listeners use the `GLOBAL_LISTENER` resource type in the Orchestration Cluster authorization model. Only the wildcard resource ID `*` is supported. Authorizations for specific listener IDs are not evaluated.
+
+To allow a user, group, role, or client to manage listeners through the Orchestration Cluster API or the Admin UI, grant authorizations on `GLOBAL_LISTENER` with resource ID `*` and the following permissions:
+
+| Operation                                    | Required permission    | Related API endpoint                                                                                                                |
+| :------------------------------------------- | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
+| List or search global user task listeners    | `READ_TASK_LISTENER`   | [Search global user task listeners](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-global-task-listeners.api) |
+| View a single global user task listener      | `READ_TASK_LISTENER`   | [Get global user task listener](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/get-global-task-listener.api)         |
+| Create a new global user task listener       | `CREATE_TASK_LISTENER` | [Create global user task listener](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-global-task-listener.api)   |
+| Update an existing global user task listener | `UPDATE_TASK_LISTENER` | [Update global user task listener](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/update-global-task-listener.api)   |
+| Delete an existing global user task listener | `DELETE_TASK_LISTENER` | [Delete global user task listener](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/delete-global-task-listener.api)   |
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/access-control

package/.llms/chunks/components.concepts.global-user-task-listeners.configuration.configure-through-unified-configuration.md

@@ -0,0 +1,81 @@
+# Configure global user task listeners — Configure through Unified Configuration
+
+Configure global user task listeners through [Unified Configuration](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#camundaclusterglobal-listeners) under `camunda.cluster.global-listeners.user-task`.
+
+Each listener entry supports the properties in [global listener definition](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners#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:
+
+```yaml
+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
+```
+
+```bash
+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.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration

package/.llms/chunks/components.concepts.global-user-task-listeners.configuration.configure-via-admin-ui.md

@@ -0,0 +1,21 @@
+# Configure global user task listeners — Configure via Admin UI
+
+**Tip**
+To learn more about the Admin UI for global user task listeners, see the [dedicated page](https://docs.camunda.io/docs/next/components/admin/global-user-task-listeners).
+
+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
+
+- [Global listener configuration properties](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#camundaclusterglobal-listeners).
+- [Configure properties through Helm charts](https://docs.camunda.io/docs/next/self-managed/deployment/helm/configure/application-configs).
+- [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview).
+- [Access control for global user task listeners](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/access-control).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration

package/.llms/chunks/components.concepts.global-user-task-listeners.configuration.configure-via-orchestration-cluster-api.md

@@ -0,0 +1,15 @@
+# Configure global user task listeners — Configure via Orchestration Cluster API
+
+**Note**
+You need [specific authorizations](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/access-control) to manage global listeners through the API.
+
+Read more about [authorizations](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations) and [how to create them in the Admin UI](https://docs.camunda.io/docs/next/components/admin/authorization).
+
+The [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview) 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](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners#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.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration

package/.llms/chunks/components.concepts.global-user-task-listeners.configuration.md

@@ -0,0 +1,28 @@
+# Configure global user task listeners
+
+Configuration methods for global user task listeners.
+
+You can configure global user task listeners at the cluster level:
+
+- [Through the Unified Configuration](#configure-through-unified-configuration).
+- [Via the Orchestration Cluster API](#configure-via-orchestration-cluster-api).
+- [Via the Admin UI](#configure-via-admin-ui), which uses the Orchestration Cluster API.
+
+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.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration

package/.llms/chunks/components.concepts.global-user-task-listeners.execution-order.md

@@ -0,0 +1,29 @@
+# Global user task listeners — 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](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#blocking-behavior).
+- [Triggering on a specific lifecycle event](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#trigger-a-user-task-listener).
+- [Accessing user task data in job workers](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#accessing-user-task-data), 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](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#correcting-user-task-data).
+- [Denying lifecycle transitions](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#denying-the-lifecycle-transition).
+- [Incident recovery](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#incident-recovery).
+
+Additionally, you can configure a single global listener to be triggered by multiple lifecycle events, possibly all of them.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners

package/.llms/chunks/components.concepts.global-user-task-listeners.global-listener-definition.md

@@ -0,0 +1,28 @@
+# Global user task listeners — 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](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners/configuration):
+
+- Through the Unified Configuration.
+- Via the Orchestration Cluster API.
+- Via the Admin UI.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners

package/.llms/chunks/components.concepts.global-user-task-listeners.limitations.md

@@ -0,0 +1,11 @@
+# Global user task listeners — Limitations
+
+The [same limitations as model-level user task listeners](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#limitations) 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.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners

package/.llms/chunks/components.concepts.global-user-task-listeners.md

@@ -0,0 +1,22 @@
+# Global user task listeners
+
+Configure cluster‑wide listeners that react to user task lifecycle events across all processes.
+
+Global user task listeners are [user task listeners](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners) defined once for all processes in a cluster, instead of individually per [user task](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks).
+
+
+## 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.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners

package/.llms/chunks/components.concepts.incidents.md

@@ -0,0 +1,20 @@
+# Incidents
+
+A process instance is stuck at a particular point, and requires user interaction to resolve the problem.
+
+In Camunda 8, an [incident](https://docs.camunda.io/docs/next/reference/glossary#incident) represents a problem in process execution. This means a [process instance](https://docs.camunda.io/docs/next/reference/glossary#process-instance) is stuck at a particular point and requires user interaction to resolve the problem.
+
+Incidents are created in different situations, including the following:
+
+- A job is failed and it has no retries left.
+- A condition doesn't return `true` or `false`.
+- A timer expression doesn't return the expected type.
+- A decision can't be evaluated.
+- A BPMN error is thrown and not caught by an error boundary event or error event subprocess.
+- A job's secret references cannot be resolved, or their resolved values cannot be injected into the job.
+
+**Note**
+Not all errors necessarily lead to incidents. For example, unexpected errors in Zeebe do not always result in incidents.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/incidents

package/.llms/chunks/components.concepts.incidents.resolving.md

@@ -0,0 +1,76 @@
+# Incidents — Resolving
+
+To resolve an incident, complete the following steps:
+
+1. Identify and resolve the problem.
+2. Mark the incident as resolved, triggering retry process execution.
+3. If the problem still exists, a new incident is created.
+
+### Resolving a job-related incident
+
+If a job fails and has no retries remaining, an incident is created. There are many different reasons why the job may have failed. For example, the variables may not be in the expected format, or a service is not available (e.g. a database).
+
+If the variables are causing the incident, complete the following steps:
+
+1. Update the variables of the process instance.
+2. Increase the remaining retries of the job.
+3. Mark the incident as resolved.
+
+**Note**
+It's recommended you complete these operations in [Operate](https://docs.camunda.io/docs/next/components/operate/operate-introduction).
+
+It is also possible to complete these steps via the [client API](https://docs.camunda.io/docs/next/apis-tools/working-with-apis-tools). Using the Java client, this could look like the following:
+
+```java
+client.newSetVariablesCommand(incident.getElementInstanceKey())
+    .variables(NEW_PAYLOAD)
+    .send()
+    .join();
+
+client.newUpdateRetriesCommand(incident.getJobKey())
+    .retries(3)
+    .send()
+    .join();
+
+client.newResolveIncidentCommand(incident.getKey())
+    .send()
+    .join();
+```
+
+When the incident is resolved, the job can be activated by a worker again.
+
+### Resolving secret resolution incidents
+
+A job that references secrets can raise one of the following incidents:
+
+- `SECRET_RESOLUTION_ERROR` when the secret store cannot return a value or Camunda cannot inject the resolved value into the job.
+- `MESSAGE_SIZE_EXCEEDED` when the resolved values make the job too large to activate.
+
+For diagnosis steps and details about how each incident affects the job, see [Troubleshoot secret resolution failures](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents).
+
+### Resolving a process instance-related incident
+
+If an incident is created during process execution and it's not related to a job, the incident is usually related to the variables of the process instance. For example, a condition expression doesn't return a boolean value.
+
+To resolve the incident, update the variables and mark the incident as resolved.
+
+**Note**
+It's recommended you complete these operations in [Operate](https://docs.camunda.io/docs/next/components/operate/operate-introduction).
+
+Using the Java client, this could look like the following:
+
+```java
+client.newSetVariablesCommand(incident.getElementInstanceKey())
+    .variables(NEW_VARIABLES)
+    .send()
+    .join();
+
+client.newResolveIncidentCommand(incident.getKey())
+    .send()
+    .join();
+```
+
+When the incident is resolved, the process instance continues.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/incidents

package/.llms/chunks/components.concepts.job-workers.completing-or-failing-jobs-using-job-result.md

@@ -0,0 +1,37 @@
+# Job workers — Completing or failing jobs — Using job result
+
+Job workers can provide a **job result** for [user task listeners](https://docs.camunda.io/docs/next/components/concepts/components/concepts/user-task-listeners).
+
+Job results are used to define:
+
+1. **Corrections**: Updates to specific user task attributes, such as assignee, due date, follow-up date, candidate users, candidate groups, and priority, before the task transition is finalized. For more details, see [correcting user task data](https://docs.camunda.io/docs/next/components/concepts/components/concepts/user-task-listeners#correcting-user-task-data).
+2. **Denial**: Indicates that the lifecycle transition should be explicitly denied. Denying the task lifecycle transition rolls back the user task to the previous state, and discards any corrections made by previous listeners. For more details, see [denying the operation](https://docs.camunda.io/docs/next/components/concepts/components/concepts/user-task-listeners#denying-the-operation).
+
+Below is an example of using job result:
+
+```java
+final JobHandler userTaskListenerHandler =
+    (jobClient, job) -> {
+        boolean shouldDeny = someValidationLogic(job);
+
+        jobClient
+            .newCompleteCommand(job)
+            // highlight-start
+            .withResult(
+                r -> r.forUserTask()
+                    .correctAssignee("john_doe")
+                    .correctPriority(42)
+                    .deny(shouldDeny)) // deny based on validation logic
+            // highlight-end
+            .send();
+    };
+```
+
+If both corrections and denial are provided in the same job result (for example, `.correctAssignee(...)` and `.deny(true)`), the job completion command will be rejected. To avoid this, ensure the job is either completed with corrections (without denial set to `true`) or denied (without corrections).
+
+**Info**
+
+The `corrections` and `deny` features are currently available only for user task listener jobs.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.completing-or-failing-jobs.md

@@ -0,0 +1,28 @@
+# Job workers — Completing or failing jobs
+
+After working on an activated job, a job worker informs Camunda 8 that the job has either `completed` or `failed`.
+
+- When the job worker completes its work, it sends a `complete job` command along with any variables, which in turn is merged into the process instance. This is how the job worker exposes the results of its work.
+- If the job worker can not successfully complete its work, it sends a `fail job` command. Fail job commands include the number of remaining retries, which is set by the job worker.
+  - If `remaining retries` is greater than zero, the job is retried and reassigned.
+  - If `remaining retries` is zero or negative, an [incident](https://docs.camunda.io/docs/next/components/concepts/incidents) is raised and the job is not retried until the incident is resolved.
+
+When failing a job it is possible to specify a `retry back off`. This back off allows waiting for a specified amount of time before retrying the job.
+This could be useful when a job worker communicates with an external system. If the external system is down, immediately retrying the job will not work.
+This will result in an incident when the retries run out. Using the `retry back off` delays the retry. This allows the external system some time to recover.
+If no `retry back off` the job is immediately retried.
+
+When completing or failing jobs with [variables](https://docs.camunda.io/docs/next/components/concepts/components/concepts/variables), the variables are merged into the process at the job's associated task:
+
+- When `Completing a job` the variables are propagated from the scope of the task to its higher scopes.
+- When `Failing a job` the variables are only created in the local scope of the task.
+
+**Tip: Failing a job with variables**
+
+There are several advantages when failing a job with variables. Consider the following use cases:
+
+- You can fail a job and raise an incident by setting the job `retries` to zero. In this case, it would be useful to provide some additional details through a variable when the incident is analyzed.
+- If your job worker can split the job into smaller pieces and finish some but not all of these, it can fail the job with variables indicating which parts of the job were successfully finished which weren't. Such a job should be failed with a positive number of retries so another job worker can pick it up again and continue where the other job worker left off. The job can be completed when all parts are finished by a job worker successfully.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-leasing-enforcement-and-rejections.md

@@ -0,0 +1,10 @@
+# Job workers — Job leasing — Enforcement and rejections
+
+Complete, fail, and throw-error commands on a leased job require the matching lease token. If the token is missing or doesn't match, Zeebe rejects the command with `INVALID_STATE`.
+
+Updating a job's timeout, retries, or priority never requires a lease token, but Zeebe validates one if you supply it. This keeps operator and bulk updates of leased jobs possible without requiring a lease.
+
+A lease-mismatch rejection means another activation of the same job has already superseded yours, for example after the job timed out and was reassigned. Treat this as expected, not as an error: don't retry the command, and log it at debug level rather than as an error.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-leasing-example.md

@@ -0,0 +1,47 @@
+# Job workers — Job leasing — Example
+
+The following example activates jobs with a lease and completes the job using the matching lease token.
+
+```java
+client
+    .newWorker()
+    .jobType("process-payment")
+    .handler(
+        (jobClient, job) -> {
+            // process the job ...
+
+            jobClient
+                // highlight-start
+                .newCompleteCommand(job.getKey())
+                .withLeaseToken(job.getLeaseToken())
+                // highlight-end
+                .send();
+        })
+    // highlight-start
+    .withLease(true)
+    // highlight-end
+    .open();
+```
+
+When you build a command from the activated job itself, the client carries the job's lease token for you automatically:
+
+```java
+client
+    .newWorker()
+    .jobType("process-payment")
+    .handler(
+        (jobClient, job) -> {
+            // process the job ...
+
+            // highlight-start
+            jobClient.newCompleteCommand(job).send();
+            // highlight-end
+        })
+    // highlight-start
+    .withLease(true)
+    // highlight-end
+    .open();
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-leasing-how-job-leasing-works.md

@@ -0,0 +1,8 @@
+# Job workers — Job leasing — How job leasing works
+
+To use leasing, request a lease by setting `withLease` to `true` when you activate jobs. Zeebe then returns a `leaseToken` on each activated job. This token identifies that specific activation, not the job itself.
+
+Pass the matching lease token back when you complete, fail, or throw an error on the job. You can also include it when you update the job timeout, retries, or priority, to verify the activation is still current before the update applies.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-leasing-leasing-is-permanent-for-a-job.md

@@ -0,0 +1,19 @@
+# Job workers — Job leasing — Leasing is permanent for a job
+
+Once a job has been leased by any worker, Zeebe never again serves that job to a non-leasing worker of the same type. A non-leasing poll or stream silently skips the job.
+
+The affected process instances may appear stuck with no incident indicating the problem if all leasing workers are stopped. Zeebe exposes a `skipped` action on the `zeebe.job.events.total` metric as the operator signal that a non-leasing worker attempted to activate the leased job.
+
+**Note**
+There is currently no operation to remove a lease from a job. To recover, you have two options:
+
+- Redeploy any worker for the job type with `withLease` set to `true`, to drain the leased jobs.
+- Use process instance modification to terminate and reactivate the element, which produces a fresh, unleased job.
+
+This also affects rollbacks. If you roll back a leasing worker deployment to a non-leasing version, any jobs leased in the interim stay permanently unavailable to the rolled-back version. Before rolling back, drain in-flight leased jobs of that type first, so the rolled-back version doesn't start out starved of jobs it can never activate.
+
+**Tip**
+Run a homogeneous fleet per job type: either all workers for a type request a lease, or none do. Mixed fleets work, but treat them as a transitional state, such as during a rollout. Keep an eye on the `skipped` jobs metric mentioned above to ensure the fleet is homogeneous.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-leasing.md

@@ -0,0 +1,72 @@
+# Job workers — Job leasing
+
+A job lease is an opt-in, opaque token that fences a specific activation of a job. It lets a worker prove its activation is still current when it interacts with Camunda.
+
+For example, consider a job worker that performs a credit check on a loan application and completes the job with its decision: approve or reject. Worker A activates the job and is on its way to approving, but a new negative evaluation appears on the applicant before it completes, and the job's deadline passes. Zeebe reassigns the job to worker B, which sees the new evaluation and decides to reject instead. Without a lease, Zeebe only checks that the job is still activated, not which activation the completion came from, so if worker A's stale approval reaches Zeebe first, it wins: funds get disbursed on outdated information, and worker B's correct rejection is discarded.
+
+```mermaid
+sequenceDiagram
+    participant A as Worker A
+    participant Z as Zeebe
+    participant B as Worker B
+
+    A->>Z: Activate job
+    Z-->>A: job
+    Note over A: Deciding: approve
+    Z->>Z: Job times out, reassigned
+    B->>Z: Activate job
+    Z-->>B: job
+    Note over B: Sees new record, decides: reject
+    A->>Z: Complete job (approve)
+    Z-->>A: Accepted
+    B->>Z: Complete job (reject)
+    Z-->>B: Rejected: job already completed
+```
+
+With leasing, worker A's completion carries its own activation's token, which becomes stale the moment worker B's activation supersedes it, so Zeebe rejects it regardless of arrival order. The outcome flips: instead of whichever completion arrives first, the most up-to-date activation's completion wins.
+
+```mermaid
+sequenceDiagram
+    participant A as Worker A
+    participant Z as Zeebe
+    participant B as Worker B
+
+    A->>Z: Activate job (withLease)
+    Z-->>A: Job with leaseToken A
+    Note over A: Deciding: approve
+    Z->>Z: Job times out, reassigned
+    B->>Z: Activate job (withLease)
+    Z-->>B: Job with leaseToken B
+    Note over B: Sees new record, decides: reject
+    A->>Z: Complete job (leaseToken A)
+    Z-->>A: Rejected: INVALID_STATE, stale lease
+    B->>Z: Complete job (leaseToken B)
+    Z-->>B: Accepted
+```
+
+Camunda's own [agentic orchestration](https://docs.camunda.io/docs/next/components/agentic-orchestration/agentic-orchestration-overview) builds on this same guarantee for visibility into [agent instance](https://docs.camunda.io/docs/next/components/agentic-orchestration/agent-definitions-and-instances#agent-instances)'s conversation. Before completing, an agent worker separately reports its reasoning as an [agent instance update](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/update-agent-instance.api), tied to its lease token. If a later activation supersedes it and completes instead, Zeebe discards the superseded activation's pending update and commits the winning one's, so a retry's contradicting reasoning never gets mixed with the activation that actually gets acted on.
+
+```mermaid
+sequenceDiagram
+    participant A1 as Activation 1
+    participant Z as Zeebe
+    participant A2 as Activation 2
+
+    A1->>Z: Activate job (withLease)
+    Z-->>A1: Job with leaseToken 1
+    A1->>Z: Update agent instance (leaseToken 1)
+    Z-->>A1: Update pending
+    Z->>Z: Job times out, reassigned
+    A2->>Z: Activate job (withLease)
+    Z-->>A2: Job with leaseToken 2
+    A2->>Z: Update agent instance (leaseToken 2)
+    Z-->>A2: Update pending
+    A2->>Z: Complete job (leaseToken 2)
+    Z-->>A2: Accepted
+    Note over Z: Commits activation 2's update,<br/>discards activation 1's pending update
+```
+
+See [connect an external agent](https://docs.camunda.io/docs/next/components/agentic-orchestration/connect-external-agent#step-2-activate-the-job-with-a-lease) for a concrete walkthrough of activating a job with a lease and reporting history against it.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers