@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.concepts.user-task-listeners-guide.step-8-verify-the-result-in-operate-and-tasklist.md

@@ -0,0 +1,33 @@
+# Example user task listener — Step 8: Verify the result in Operate and Tasklist
+
+Now that the task listener is running, the listener job will have been handled and completed. Let's see what effects this has had.
+
+1. Navigate to Operate and see that the listener that was **Active** previously, has now been **Completed**.
+
+   ![Listener has been completed in Operate](./assets/user-task-listeners-guide/8.1-verify-listener-completed.png)
+
+2. Navigate to Tasklist and see that the task is available and assigned to the assignee or manager that you provided.
+
+   ![Task is assigned in Tasklist](./assets/user-task-listeners-guide/8.2-verify-task-assigned.png)
+
+
+## Suggestions for further exploration
+
+To build your understanding of task listeners, you can also:
+
+- Stop the listener application.
+- Start a new instance of the process, and notice that the task does not appear in Tasklist.
+- Check Operate, and notice that a creating listener is active.
+- Restart the listener application and notice that the listener failed, and an incident is raised.
+- Set a variable `assignee` or `manager` in the process instance, and resolve the incident.
+- Check Tasklist, and notice that the task is assigned to the assignee or manager that you provided.
+
+Further, you can try the following:
+
+- Add a separate listener for another event type, and [trigger that event](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#trigger-a-user-task-listener).
+- [Access the user task's data](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#accessing-user-task-data) from the **activated job**.
+- [Correct the assignee](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#correcting-user-task-data) in the listener by adding a **job result** to the complete job command.
+- [Deny the assignment](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#denying-the-lifecycle-transition) from the listener to avoid the task's assignment altogether.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners.define-a-user-task-listener.md

@@ -0,0 +1,22 @@
+# User task listeners — Define a user task listener
+
+You can configure user task listeners either:
+
+- Per BPMN user task element.
+- For all user tasks in the cluster. See [Global user task listeners](https://docs.camunda.io/docs/next/components/concepts/global-user-task-listeners).
+
+### User task listener properties
+
+Each user task listener has the following properties:
+
+| Property    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `eventType` | (Required) Specifies the user task event type that triggers the listener. Supported values are `creating`, `assigning`, `updating`, `completing`, and `canceling`.                                                                                                                                                                                                                                                                                                                                            |
+| `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`. The `type` can be specified as any static value (`myType`), or as a FEEL expression prefixed with `=`, that evaluates to a FEEL string; for example, `= "order-" + priorityGroup`. This is a case-sensitive field, if supported by the underlying operating system. For example, `orderProcess` refers to a different worker than `OrderProcess`. |
+| `retries`   | (Optional) The number of retries for the user task listener job (defaults to 3 if omitted).                                                                                                                                                                                                                                                                                                                                                                                                                   |
+
+**Note**
+If multiple user task listeners of the same `eventType` (such as multiple `assigning` listeners) are defined on the same user task, they are executed sequentially, one after the other, in the order they are defined in the BPMN model.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.user-task-listeners.expression-evaluation-and-incident-behavior.md

@@ -0,0 +1,17 @@
+# User task listeners — Expression evaluation and incident behavior
+
+### Expression evaluation
+
+User task listener properties, such as job `type` or `retries`, are evaluated right before the job creation for the listener.
+
+### Incident recovery
+
+If a user task listener job fails or its expression evaluation raises an [incident](https://docs.camunda.io/docs/next/components/concepts/incidents), the lifecycle transition is paused until the incident is resolved.
+
+There are two types of incidents for task listeners:
+
+- **Expression evaluation failure**: Raised when a listener property expression fails to evaluate. After the incident is resolved, the entire lifecycle transition is retried, re-executing all listeners configured for the transition, including those that previously completed successfully.
+- **Job failure**: If a listener job fails, it is retried according to the `retries` property. If all retries are exhausted and the job still fails, an incident is raised. Once resolved, only the failed listener job is retried, allowing the lifecycle transition to resume without re-executing successfully completed listeners.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.user-task-listeners.implement-a-user-task-listener-accessing-user-task-data.md

@@ -0,0 +1,54 @@
+# User task listeners — Implement a user task listener — Accessing user task data
+
+User task-specific data, such as `assignee` and `priority`, are accessible through the `userTask` property of the user task listener job.  
+The following user task attributes can be accessed from the activated job's `userTask` property:
+
+| Attribute           | Description                                                                                                                                                                                   |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`            | A custom action value provided along with the request that triggered this event. If none was provided, it defaults to one of `assign`, `claim`, `update`, or `complete`.                      |
+| `assignee`          | The user assigned to the task. If not specified, the task is unassigned. Refer to [assignments](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#assignments) for more details.              |
+| `candidateGroups`   | Specifies the groups of users that the task can be assigned to. Refer to [assignments](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#assignments) for more details.                       |
+| `candidateUsers`    | Specifies the users that the task can be assigned to. Refer to [assignments](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#assignments) for more details.                                 |
+| `changedAttributes` | Lists the user task attributes that have changed with the event. Refer to the [changed attributes](#changed-attributes) section below for more details.                                       |
+| `dueDate`           | Specifies the due date of the task. Refer to [scheduling](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#scheduling) for more details.                                                     |
+| `followUpDate`      | Specifies the follow-up date of the task. Refer to [scheduling](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#scheduling) for more details.                                               |
+| `formKey`           | The form linked to the user task, referenced by its uniquely identifying key. Refer to [user task forms](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#user-task-forms) for more details. |
+| `priority`          | The task’s priority level. Refer to [priority](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#define-user-task-priority) for more details.                                                 |
+| `userTaskKey`       | The unique key identifying the user task.                                                                                                                                                     |
+
+Below is an example of accessing the `assignee` value from the activated job in Java:
+
+```java
+final JobHandler userTaskListenerHandler =
+    (jobClient, job) -> {
+        // Access the 'assignee' from the job's user task property
+        // highlight-start
+        final String assignee = job.getUserTask().getAssignee();
+        // highlight-end
+
+        System.out.println("The assignee for this user task is: " + assignee);
+
+        // remaining job handler logic
+    };
+```
+
+This user task data can be leveraged to customize the behavior of the user task listener job worker.
+
+#### Changed attributes
+
+The `changedAttributes` attribute lists which user task attributes have changed with the event.
+
+**Note**
+User task data corrections are taken into account.
+For example, consider a user task with three `assigning` listeners defined.
+When assigning the user task, the first listener sees the `assignee` attribute in the `changedAttributes`.
+If it corrects the priority, a subsequent assigning listener sees both the `assignee` and the `priority` attributes as changed attributes.
+Now, this second listener corrects the priority back to the value it had before assigning.
+The third listener sees only the `assignee` attribute as changed attribute, because the priority is no longer changed with the event.
+
+#### Task headers
+
+Configured [task headers](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#task-headers) on the user task are available in the job's custom headers.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.user-task-listeners.implement-a-user-task-listener-correcting-user-task-data.md

@@ -0,0 +1,42 @@
+# User task listeners — Implement a user task listener — Correcting user task data
+
+User task listeners can correct user task data before the lifecycle transition is finalized. Corrections allow user task listeners to update specific attributes of the user task, such as the assignee, due date, follow-up date, candidate users, candidate groups, and priority. These corrections are immediately available to any subsequent task listeners and are applied to the user task when the lifecycle transition is finalized, without triggering the `UPDATING` lifecycle event.
+
+If a lifecycle transition is denied by a listener, no corrections are applied to the user task.
+
+Below is an example of how to correct the user task data from a job worker while completing the user task listener job in Java:
+
+```java
+final JobHandler completeTaskListenerJobWithCorrectionsHandler =
+    (jobClient, job) ->
+        jobClient
+            .newCompleteCommand(job)
+            // highlight-start
+            .withResult(
+                r -> r.forUserTask()
+                    .correctAssignee("john_doe")                    // assigns the user task to 'john_doe'
+                    .correctDueDate(null)                           // preserves the current 'dueDate'
+                    .correctFollowUpDate("")                        // clears the 'followUpDate'
+                    .correctCandidateUsers(List.of("alice", "bob")) // sets candidate users
+                    .correctCandidateGroups(List.of())              // clears the candidate groups
+                    .correctPriority(80))                           // sets the priority to 80
+            // highlight-end
+            .send();
+
+client.newWorker()
+    .jobType("user-task-listener-completion") // type of the user task listener job
+    .handler(completeTaskListenerJobWithCorrectionsHandler)
+    .open();
+```
+
+#### On correcting the assignee
+
+The assignee can be corrected in the `creating` listener only if the process hasn't specified an assignee for this user task already. For example, if the user task's `assignee` expression evaluates to `null`.
+
+**Tip**
+To set an assignee when creating the user task, review [specifying the assignee in the process](https://docs.camunda.io/docs/next/components/concepts/components/modeler/bpmn/user-tasks/user-tasks#assignments), or verify the assignee is not yet defined by the process by [accessing the `assignee` attribute in the job headers](#accessing-user-task-data).
+
+To change the assignee specified by the process, correct it with the `assigning` event.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.user-task-listeners.implement-a-user-task-listener-denying-the-lifecycle-transition.md

@@ -0,0 +1,33 @@
+# User task listeners — Implement a user task listener — Denying the lifecycle transition
+
+User task listeners can deny the user task lifecycle transition belonging to the lifecycle event. For example, it can deny the completion of a task in reaction to the completing event, effectively preventing a user request to complete the task.
+
+When a lifecycle transition is denied:
+
+- **Corrections discarded**: Any corrections made by preceding listeners within the same lifecycle transition are discarded.
+- **Task state preserved**: The user task retains its state and data as if the lifecycle event never occurred.
+
+This capability is particularly useful for implementing validation logic or enforcing business rules before allowing a user task lifecycle transition to proceed.
+
+Below is an example of how to deny a user task lifecycle transition from a job worker while completing the user task listener job in Java:
+
+```java
+final JobHandler denyUserTaskLifecycleTransitionHandler =
+    (jobClient, job) ->
+        jobClient
+            .newCompleteCommand(job)
+            // highlight-start
+            .withResult(r -> r.forUserTask().deny(true))
+            // highlight-end
+            .send();
+```
+
+Not all events can be denied. For example, it's not possible to deny the creation or cancelation of a user task.
+Currently, user task listeners can deny the lifecycle transition for the following events:
+
+- `assigning`
+- `updating`
+- `completing`
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.user-task-listeners.implement-a-user-task-listener.md

@@ -0,0 +1,8 @@
+# User task listeners — Implement a user task listener
+
+User task listeners are implemented using [job workers](https://docs.camunda.io/docs/next/components/concepts/job-workers), similar to execution listeners and service task jobs. The job worker processes the task listener job, can apply corrections, and may optionally deny the lifecycle transition.
+
+See the [job worker documentation](https://docs.camunda.io/docs/next/apis-tools/java-client/job-worker) for examples of how to create a job worker and handler that can also process user task listener jobs.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

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

@@ -0,0 +1,20 @@
+# User task listeners — Limitations
+
+User task listeners have the following limitations:
+
+- **No variable handling**: User task listener jobs cannot be completed if variables are provided.
+- **No BPMN error throwing**: Throwing BPMN errors from user task listener jobs is not supported.
+
+### Legacy behavior before 8.10
+
+User task listeners are designed for use with the [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview).
+
+Before Camunda 8.10, Tasklist V1 and the deprecated Tasklist API had the following limitations when used with user task listeners:
+
+- **Tasklist v1 does not list tasks with pending task listeners**: If a task's lifecycle transition is blocked by a pending task listener, Tasklist v1 does not display the task in the task queue. However, Tasklist v1 can still show the details of such a task.
+- **Tasklist v1 incorrectly lists creating tasks when filtering for the "all" status (open and completed)**: If a task's creation is blocked by a pending task listener, Tasklist v1 includes it in the task queue when filtering for the "all" status, even though the task has not yet been created.
+- **Tasklist v1 API cannot filter for tasks with pending task listeners**: The deprecated Tasklist API cannot filter for the following task states when searching tasks: `CREATING`, `ASSIGNING`, `UPDATING`, `COMPLETING`, `CANCELING`. Tasks in these states are included in responses when not filtering by state.
+- **Tasklist v1 API responses may not reflect corrections applied by task listeners**: Requests made to the deprecated Tasklist API can trigger a listener. Responses to such requests will appear as if the listener did not make any [corrections](#correcting-user-task-data) to the user task data, even when the listener did make corrections.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

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

@@ -0,0 +1,70 @@
+# User task listeners
+
+User task listeners allow users to react to specific user task lifecycle events.
+
+A [user task listener](https://docs.camunda.io/docs/next/reference/glossary#user-task-listener) allows users to react to specific user task lifecycle events.
+
+**Tip**
+Try out our [getting started with user task listeners guide](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide).
+
+
+## About user task listeners
+
+User task listeners provide flexibility and control over [user task](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks) behavior:
+
+- They can react to user task lifecycle events, such as assigning and completing.
+- They can access user task data, such as the assignee, to execute task-specific business logic.
+- They can dynamically correct user task data during execution, allowing adjustments to key attributes such as the assignee, due date, and priority.
+- They can deny state transitions, rolling back the task to its previous state, which enables validation of task lifecycle changes.
+
+### Use cases
+
+User task listeners are useful in the following scenarios:
+
+- Implementing complex user task assignment or reassignment logic.
+- Validating user task lifecycle changes, e.g. completing with valid variables.
+- Notifying users of new task assignments with contextual information.
+- Reacting to task completions with custom logic.
+
+### User task lifecycle
+
+A user task has the following lifecycle.
+A user task listener can react to the events highlighted in orange.
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    [*] --> creating
+    creating --> created
+
+    created --> assigning
+    assigning --> created
+
+    created --> updating
+    updating --> created
+
+    created --> completing
+    completing --> created
+    completing --> completed
+
+    creating --> canceling
+    created --> canceling
+    assigning --> canceling
+    updating --> canceling
+    completing --> canceling
+    canceling --> canceled
+
+    classDef listenerEvent fill:#fc5d0d,color:white,font-weight:bold
+    class creating listenerEvent
+    class assigning listenerEvent
+    class updating listenerEvent
+    class completing listenerEvent
+    class canceling listenerEvent
+```
+
+### Blocking behavior
+
+User task listeners operate in a blocking manner, meaning the user task lifecycle transition is paused until the task listener completes. This ensures that any corrections or validations defined by the task listener are fully applied before the task transition continues.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

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

@@ -0,0 +1,11 @@
+# User task listeners — Related resources
+
+- [Job workers (basics)](https://docs.camunda.io/docs/next/components/concepts/job-workers)
+- [Job workers (Java client)](https://docs.camunda.io/docs/next/apis-tools/java-client/job-worker)
+- [Incidents](https://docs.camunda.io/docs/next/components/concepts/incidents)
+- [Expressions](https://docs.camunda.io/docs/next/components/concepts/expressions)
+- [Execution listeners](https://docs.camunda.io/docs/next/components/concepts/execution-listeners)
+- [User tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.user-task-listeners.trigger-a-user-task-listener.md

@@ -0,0 +1,19 @@
+# User task listeners — Trigger a user task listener
+
+The supported user task listener events can be triggered in the following ways.
+
+| Event        | Triggered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `creating`   | When a process instance reaches a user task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `assigning`  | When the [assign user task API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/assign-user-task.api) is called.When activating a user task that [specifies an `assignee`](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks#assignments) in the process.When a user task is assigned using the [Tasklist interface](https://docs.camunda.io/docs/next/components/tasklist/userguide/managing-tasks#assign-tasks).                                                                                                                                                                                                        |
+| `updating`   | When the [update user task API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/update-user-task.api) is called. When the [update element instance variables API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-element-instance-variables.api) is called on a user task instance.When the [set variables RPC](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#setvariables-rpc) is called on a user task instance.When variables are set at a user task scope using the [Operate interface](https://docs.camunda.io/docs/next/components/operate/userguide/resolve-incidents-update-variables). |
+| `completing` | When a user task is completed using the [Tasklist interface](https://docs.camunda.io/docs/next/components/tasklist/userguide/managing-tasks#complete-a-task).When the [complete user task API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/complete-user-task.api) is called.                                                                                                                                                                                                                                                                                                                                                  |
+| `canceling`  | When a canceling process instance terminates a user task.When a [catch event](https://docs.camunda.io/docs/next/components/modeler/bpmn/events) interrupts a user task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+**Note**
+[Process instance modification](https://docs.camunda.io/docs/next/components/concepts/process-instance-modification) does not trigger the `canceling` event. User task listeners are intentionally skipped when a user task is terminated via modification to prevent a failing listener job from blocking the operation.
+
+Once triggered, the workflow engine creates a job that you can process using a job worker.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings-context-variable.md

@@ -0,0 +1,20 @@
+# Variables — Input/output variable mappings — Context variable
+
+A context variable is a reserved variable that describes the context of a task. It can group variables together to provide a detailed description of the task or offer more descriptive data about it.
+The reserved variable name for a context variable is `taskContextDisplayName`. This name is reserved exclusively for this purpose and should not be used for other variables.
+
+**Warning**
+Context variables were a Tasklist V1 feature and are not supported in current Tasklist releases. See [Tasklist API changes](https://docs.camunda.io/docs/next/components/tasklist/api-versions).
+
+Example:
+
+| Input variable           | Example                              |
+| ------------------------ | ------------------------------------ |
+| `taskContextDisplayName` | `This is a context variable example` |
+
+The data from the variable will be shown on the task tile, as shown in the example below:
+
+![context-variables](assets/context-variables.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings-input-mappings.md

@@ -0,0 +1,24 @@
+# Variables — Input/output variable mappings — Input mappings
+
+Input mappings can be used to create new variables. They can be defined on [service tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/service-tasks/service-tasks), [script tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/script-tasks/script-tasks), [business rule tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/business-rule-tasks/business-rule-tasks), [call activities](https://docs.camunda.io/docs/next/components/modeler/bpmn/call-activities/call-activities), [user tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks), [send tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/send-tasks/send-tasks), [subprocesses](https://docs.camunda.io/docs/next/components/modeler/bpmn/subprocesses), [event subprocesses](https://docs.camunda.io/docs/next/components/modeler/bpmn/event-subprocesses/event-subprocesses), and [ad-hoc subprocesses](https://docs.camunda.io/docs/next/components/modeler/bpmn/ad-hoc-subprocesses/ad-hoc-subprocesses). Support depends on the element type. See the element's own page for details.
+
+When an input mapping is applied, it creates a new [**local variable**](#local-variables) in the scope where the mapping is defined.
+
+In Modeler, define these mappings in the element properties.
+
+You can use [expressions](https://docs.camunda.io/docs/next/components/concepts/expressions) or static values for input mappings. You can leave the `source` empty to map the `target` variable to `null`.
+
+For string literals containing escaped characters (e.g., a newline character `\n`), the string is returned in its original form as expected (no double escaping is applied).
+
+Examples:
+
+| Process variables                      | Input mappings                                                                                               | New variables                               |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| `orderId: "order-123"`                 | **source:** `=orderId` **target:** `reference`                                                          | `reference: "order-123"`                    |
+| `customer:{"name": "John"}`            | **source:** `=customer.name`**target:** `sender`                                                        | `sender: "John"`                            |
+| `customer: "John"``iban: "DE456"` | **source:** `=customer` **target:** `sender.name`**source:** `=iban`**target:** `sender.iban` | `sender: {"name": "John", "iban": "DE456"}` |
+| -                                      | **source:** `"Peter"`**target:** `sender`                                                               | `sender: "Peter"`                           |
+| `customer:{"name": "John"}`            | **source:** (not provided)**target:** `customer`                                                        | `customer: null`                            |
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings-nested-variables-in-mappings.md

@@ -0,0 +1,11 @@
+# Variables — Input/output variable mappings — Nested variables in mappings
+
+Input and output mappings build nested `target` paths in opposite ways:
+
+- **Input mappings** treat the `target` as a full path and write the entire nested object at that path, replacing any value already there.
+- **Output mappings** write only the final property (the leaf) of the `target` path and merge it into the existing structure, preserving sibling properties that are already present.
+
+For example, an input mapping with target `order` replaces the whole `order` variable, while an output mapping with target `order.status` sets only `status` inside an existing `order` variable and leaves its other properties unchanged.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings-output-mappings.md

@@ -0,0 +1,29 @@
+# Variables — Input/output variable mappings — Output mappings
+
+Output mappings can be used for several purposes:
+
+- To customize how variables are merged into the process instance.
+- They can be defined on most tasks (service, send, user, receive, script, and business rule tasks), [embedded](https://docs.camunda.io/docs/next/components/modeler/bpmn/embedded-subprocesses/embedded-subprocesses) and [event subprocesses](https://docs.camunda.io/docs/next/components/modeler/bpmn/event-subprocesses/event-subprocesses), [call activities](https://docs.camunda.io/docs/next/components/modeler/bpmn/call-activities/call-activities), and [ad-hoc subprocesses](https://docs.camunda.io/docs/next/components/modeler/bpmn/ad-hoc-subprocesses/ad-hoc-subprocesses).
+- They can also be defined on many events, including message, signal, timer, and conditional catch events, boundary events, and start events.
+
+If **one or more** output mappings are defined, the results variables are set as **local variables** in the scope where the mapping is defined. Then, the output mappings are applied to the variables and create new variables in this scope. The new variables are merged into the parent scope. If there is no mapping for a job/message variable, the variable is not merged.
+
+**Note**
+This can lead to a case where some variables with an output mapping are merged into the parent scope, and others without an output mapping are not merged.
+
+If **no** output mappings are defined, the behavior depends on the element. Tasks and events that produce a result (a job result, or a correlated message or signal payload) merge that whole result into the parent scope. Subprocesses and events that produce no result, such as none, link, escalation, and compensation events, propagate nothing; their local variables are discarded when the scope is left. For an overview across all element types, see [variable propagation by BPMN element](#variable-propagation-by-bpmn-element).
+
+In the case of a subprocess, the behavior is different. There are no results variables to be merged. However, output mappings can be used to propagate **local variables** of the subprocess to higher scopes. By default, all **local variables** are removed when the scope is left.
+
+Examples:
+
+| Results variables                                    | Output mappings                                                                                                                      | Process variables                                  |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| `status: "Ok"`                                       | **source:** `=status`**target:** `paymentStatus`                                                                                | `paymentStatus: "OK"`                              |
+| `result: {"status": "Ok", "transactionId": "t-789"}` | **source:** `=result.status`**target:** `paymentStatus`**source:** `=result.transactionId`**target:** `transactionId` | `paymentStatus: "Ok"``transactionId: "t-789"` |
+
+**Note**
+An output mapping `target` that contains a period (for example, `order.status`) updates only the final property and merges it into the existing variable at that path, leaving sibling properties untouched. This is supported, but use it deliberately, as it modifies a property of an existing variable rather than replacing the whole variable. For details, see [nested variables in mappings](#nested-variables-in-mappings).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings-secret-references-in-input-mappings-2.md

@@ -0,0 +1,23 @@
+# Variables — Input/output variable mappings — Secret references in input mappings (2)
+
+**Note**
+A secret reference can also come from a [cluster variable](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/data-types) of kind `SECRET_REFERENCE`. An input mapping that selects such a variable, for example `=camunda.vars.env.MY_CONFIG`, resolves the `camunda.secrets.<name>` references embedded in its value the same way. See [resolve secret references in a cluster variable](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/usage-guide#resolve-secret-references-in-a-cluster-variable).
+
+**Note**
+Avoid using `camunda` as a process variable name. A process variable literally named `camunda` takes precedence over the secret namespace, so `camunda.secrets.<name>` resolves against that variable and no secret is injected.
+
+#### Escape secret names with special characters
+
+A secret name containing a character FEEL doesn't allow in a bare identifier (most commonly a dash) must be backtick-escaped, the same way any other FEEL name with special characters is:
+
+```feel
+=camunda.secrets.`db-password`
+```
+
+Without the backticks, `camunda.secrets.db-password` parses as a subtraction (`db` minus `password`). FEEL reads the left operand as a reference named `db`, which is not a valid secret reference, so the deployment fails at evaluation.
+
+**Note**
+When a reference is written directly in an input mapping source, backtick escaping accepts any name, including a name your secret store accepts but the [`/v2/secrets`](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/list-secrets.api) endpoints do not. Those endpoints list and resolve only names matching `[\p{Alnum}_-]+`. A name outside that set, such as `tls.crt`, can be backtick-escaped and resolved from a process model (``=camunda.secrets.`tls.crt` ``) if your secret store holds it under that name, but the same secret cannot be listed or resolved through `/v2/secrets`. This applies to references written directly in an input mapping source, not to references embedded in a [`SECRET_REFERENCE`-kind cluster variable value](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/data-types#where-references-can-appear-in-a-value), whose names follow the restricted cluster-variable character set.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings-secret-references-in-input-mappings.md

@@ -0,0 +1,47 @@
+# Variables — Input/output variable mappings — Secret references in input mappings
+
+An input mapping's `source` can reference a secret directly, without first storing it in a process variable. Write the reference as `camunda.secrets.<name>` in a FEEL expression.
+
+This is part of an [alpha feature](https://docs.camunda.io/docs/next/components/early-access/alpha/alpha-features) and may be subject to change in future releases.
+
+Using secret references requires a secret store that holds the secret. In SaaS, the store is provisioned for you. You can reference values from the cluster's **Cluster secrets** tab as `camunda.secrets.<name>` without additional setup. See [manage connector secrets](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/manage-secrets#reference-connector-secrets-as-camundasecretsname). In Self-Managed, an operator must [configure a secret store](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#secrets). Without an available store, Camunda cannot resolve the reference.
+
+| Process variables | Input mappings                                                                       | New variables                                                    |
+| ----------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| -                 | **source:** `=camunda.secrets.API_TOKEN`**target:** `token`                     | `token` holds the secret's value when the job reaches the worker |
+| -                 | **source:** `="Bearer " + camunda.secrets.API_TOKEN`**target:** `authorization` | `authorization` holds `"Bearer "` followed by the secret's value |
+
+Secret references are only resolved in input mappings defined on elements that create a job for a job worker (for example, service tasks, business rule tasks, and ad hoc sub-processes). See [secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation) for how a reference is resolved and what the worker receives once the job is handed out. The stored process variable always holds the placeholder text `camunda.secrets.<name>`; resolution replaces it only in the payload handed to the worker, not in the variable kept in the process instance's state. Any other consumer of that variable sees the placeholder.
+
+A reference must be an expression, and the reference itself must be exactly the three-segment path `camunda.secrets.<name>`. It can still take part in a supported expression, such as the concatenation shown above, but the following rejections apply:
+
+- Writing the reference as a plain string, or quoting it inside an expression, is rejected at deployment rather than passed through as literal text:
+
+  ```feel
+  ="camunda.secrets.API_TOKEN"
+  ```
+
+  ```text
+  Secret reference(s) 'camunda.secrets.API_TOKEN' must be used as an expression (e.g. '=camunda.secrets.<name>'), not as a string literal, in input mapping source '="camunda.secrets.API_TOKEN"'.
+  ```
+
+- A trailing path after the name, such as `camunda.secrets.API_TOKEN.length`, is not treated as a reference. It's evaluated as an ordinary FEEL path access instead.
+
+- A reference placed inside a list, or inside a context built by an `if` branch, is rejected at deployment, because the reference is no longer a value the mapping assigns directly:
+
+  ```feel
+  =[camunda.secrets.API_TOKEN]
+  ```
+
+  ```text
+  Input mapping source '=[camunda.secrets.API_TOKEN]' puts a secret reference inside a list, or inside a context built by an 'if' branch. Camunda can only replace a secret where the mapping assigns it directly to a value, so this secret would never be filled in. Assign each secret reference to its own input mapping instead.
+  ```
+
+Give each secret its own input mapping. A later mapping that reads the _variable_ created by an earlier one, rather than writing `camunda.secrets.<name>` itself, does not get the secret resolved:
+
+| Input mappings                                                                                        | New variables                                                                                                     |
+| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **source:** `=camunda.secrets.API_TOKEN`**target:** `x`**source:** `=x`**target:** `y` | `x` exposes the resolved secret value to the worker; `y` holds the literal placeholder text, not the secret value |
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.input-output-variable-mappings.md

@@ -0,0 +1,31 @@
+# Variables — Input/output variable mappings
+
+Input/output variable mappings can be used to create new variables or customize how variables are merged into the process instance.
+
+Variable mappings are defined in the process as extension elements under `ioMapping`. Every variable mapping has a `source` and a `target` expression.
+
+The `source` expression defines the **value** of the mapping. It usually [accesses a variable](https://docs.camunda.io/docs/next/components/modeler/feel/language-guide/feel-variables#access-variable) of the process instance that holds the value. If the variable or nested property doesn't exist, the value resolves to `null`. The same applies if you do not provide a `source`.
+
+The `target` expression defines **where** the value of the `source` expression is stored. It can reference a variable by its name or a nested property of a variable. If the variable or the nested property doesn't exist, it's created.
+
+Variable mappings are evaluated in the defined order. Therefore, a `source` expression can access the target variable of a previous mapping.
+
+![variable-mappings](assets/variable-mappings.png)
+
+**Input mappings**
+
+| Source          | Target      |
+| --------------- | ----------- |
+| `customer.name` | `sender`    |
+| `customer.iban` | `iban`      |
+| `totalPrice`    | `price`     |
+| `orderId`       | `reference` |
+
+**Output mapping**
+
+| Source   | Target          |
+| -------- | --------------- |
+| `status` | `paymentStatus` |
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

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

@@ -0,0 +1,12 @@
+# Variables
+
+Variables are part of process instances and represent their data. Leverage the scope of variables and customize how they are merged into process instances.
+
+[Variables](https://docs.camunda.io/docs/next/reference/glossary#variable) are part of a [process instance](https://docs.camunda.io/docs/next/reference/glossary#process-instance) and represent the data of the instance.
+
+A variable has a name and a JSON value. The visibility of a variable is defined by its variable scope.
+
+When [automating a process using BPMN](https://docs.camunda.io/docs/next/components/modeler/bpmn/automating-a-process-using-bpmn), [orchestrating human tasks](https://docs.camunda.io/docs/next/guides/getting-started-orchestrate-human-tasks), or implementing [agentic orchestration](https://docs.camunda.io/docs/next/components/agentic-orchestration/agentic-orchestration-overview), you can leverage the scope of these variables and customize how variables are merged into the process instance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.next-steps.md

@@ -0,0 +1,7 @@
+# Variables — Next steps
+
+- Understand how to [access variables](https://docs.camunda.io/docs/next/components/modeler/feel/language-guide/feel-variables).
+- Explore how to centrally manage cluster configuration with [cluster variables](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/overview).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.variable-names.md

@@ -0,0 +1,19 @@
+# Variables — Variable names
+
+The name of a variable can be any alphanumeric string including the `_` symbol. For a combination of words, it's recommended to use the `camelCase` or the `snake_case` format. The `kebab-case` format is not allowed because it contains the operator `-`.
+
+When accessing a variable in an expression, keep in mind the variable name is case-sensitive.
+
+Restrictions of a variable name:
+
+- It may not start with a **number** (e.g. `1stChoice` is not allowed; you can use `firstChoice` instead).
+- It may not contain **whitespaces** (e.g. `order number` is not allowed; you can use `orderNumber` instead).
+- It may not contain an **operator** (e.g. `+`, `-`, `*`, `/`, `=`, `>`, `?`, `.`).
+- It may not be a **literal** (e.g. `null`, `true`, `false`) or a **keyword** (e.g. `function`, `if`, `then`, `else`, `for`, `between`, `instance`, `of`, `not`).
+- It must stay within the length limits of the target backend: up to **32,768 characters** with Elasticsearch/OpenSearch-backed secondary storage and up to **256 characters** with RDBMS-backed secondary storage.
+
+**Note**
+Length is enforced using Java string length semantics rather than raw UTF-8 byte counts. Most common characters count as one character, while characters represented as surrogate pairs in Java count as two. Because of that, the effective visible-character limit can be lower for some inputs.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables

package/.llms/chunks/components.concepts.variables.variable-scopes-define-local-variables.md

@@ -0,0 +1,8 @@
+# Variables — Variable scopes — Define local variables
+
+To define a local variable in Modeler, add an input mapping on the activity, subprocess, or call activity where you want the variable to exist. For details on input mapping concepts (`source` and `target`) see [input/output variable mappings](#inputoutput-variable-mappings).
+
+The `target` of the input mapping becomes a local variable in that element's scope. For example, an input mapping with `source: =customer.name` and `target: reviewerName` creates the local variable `reviewerName` in that scope.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/variables