@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.concepts.process-instance-modification.limitations.md

@@ -0,0 +1,37 @@
+# Process instance modification — Limitations
+
+Currently, we can't modify the process instance in all possible ways. In the following cases, the process instance can't
+apply the modification instructions and rejects the modification command.
+
+- If the activating element is a BPMN element of the type:
+  - A start event of a process or a subprocess
+  - A boundary event
+  - An event that belongs to an event-based gateway
+  - A sequence flow
+- If the modification terminates all active instances of a child process instance.
+
+
+## Use at your own risk
+
+Process instance modification is a powerful tool to repair a process instance. However, use it with care. You
+can modify the process instance to create situations that are not reachable by the regular execution. Consider the
+following example:
+
+![The process instance waits on a task after a parallel joining gateway.](assets/process-instance-modification/process-instance-modification-use-at-your-own-risk.png)
+
+The process instance completed the first tasks `A` and `B` and waits on task `C`.
+
+We could apply the following modifications, but the process instance may end up in an unintended situation:
+
+- If we activate task `A` again, the process instance is stuck on the parallel gateway.
+- If we activate task `D` and don't set all variables that would be provided by the message, the task `D` could be
+  processed with the wrong input.
+- If we activate task `E` inside the interrupting event subprocess, the process instance doesn't interrupt task `C`
+  and the processing of the tasks could override variables.
+
+The process instance doesn't detect these situations. It is up to you to apply suitable modifications.
+
+When in doubt, we recommend testing your modification on a non-production cluster or using [Camunda Process Test](https://docs.camunda.io/docs/next/apis-tools/testing/getting-started).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-modification

package/.llms/chunks/components.concepts.process-instance-modification.md

@@ -0,0 +1,43 @@
+# Process instance modification
+
+Use process instance modification to repair a running process instance.
+
+Process instance modification is a powerful feature for repairing a running process instance. For example, a process instance may be stuck at an element, waiting for an event, or following an unintended path because an external system is unavailable or doesn't respond as expected.
+
+Use the [modification command](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#modifyprocessinstance-rpc) to skip or repeat a step in the
+process. Consider the following example:
+
+![The process instance is stuck in the message catch event.](assets/process-instance-modification/process-instance-modification-example-1.png)
+
+The process contains two service tasks and a message catch event in between. The process instance completed the first
+task `A` and waits on the message catch event `B`. An external system will publish the message, but the external
+system is not available and can't continue the process. The process instance is stuck.
+
+![We use the modification to skip the event and continue on the next task.](assets/process-instance-modification/process-instance-modification-example-2.png)
+
+We use the modification to repair the process instance. We "move the token" from the catch event `B` to the next
+task `C`. This operation is presented by two instructions in the modification command:
+
+- Terminate the instance of the catch event `B`.
+- Activate the element `C`.
+
+![After the modification is applied, the message catch event is terminated and the next task is active.](assets/process-instance-modification/process-instance-modification-example-3.png)
+
+As a result of the command, the process instances terminated the instance of catch event `B` and activated the task `C`.
+Now, the process instance is not stuck anymore and can continue in the process.
+
+Generally, the process instance modification command can contain multiple instructions:
+
+- To activate an element of the process.
+- To terminate an active instance of an element.
+
+Read more about the behavior of the instructions in the following sections.
+
+**Note**
+Use the process instance modification only in exceptional cases to repair the process instance. It is not
+recommended using it as a part of the regular flow of the process; find additional details [here](#use-at-your-own-risk).
+Instead, model all possible cases
+explicitly in your process.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-modification

package/.llms/chunks/components.concepts.process-instance-modification.move-an-element-instance.md

@@ -0,0 +1,32 @@
+# Process instance modification — Move an element instance
+
+Use the modification command to move an element instance. The move operation combines termination and activation in a single instruction. It terminates the source element instance and activates a target element in one atomic operation.
+
+**Note**
+This is the recommended way to relocate execution within a process instance, as it ensures the operation is performed atomically and correctly handles complex scenarios such as multi-instance subprocesses.
+
+### Use the move instruction API
+
+When using the [modification API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/modify-process-instance.api), you can provide a move instruction with the following parameters:
+
+- **Source element**: Specify the element instance to move from, either by element ID or by element instance key.
+- **Target element**: Specify the element ID of the element to activate.
+- **Ancestor scope instruction** (for nested elements): Controls how the target element is activated within subprocess hierarchies. See [Move elements inside multi-instance subprocesses](#moving-elements-inside-multi-instance-subprocesses) for details on using this with multi-instance activities.
+
+### Move elements inside multi-instance subprocesses
+
+Move modifications are supported for elements inside multi-instance subprocesses. When you move an element instance within a multi-instance subprocess, the process instance terminates only that specific element instance and activates exactly one target element in the same instance of the multi-instance subprocess.
+
+With move modifications in multi-instance subprocesses, you can relocate execution within a specific iteration of a multi-instance activity without affecting other instances or creating new instances of the multi-instance subprocess.
+
+The **ancestor scope instruction** provides three strategies for controlling how the target element is activated:
+
+- `direct`: Specify the key of the ancestor scope in which the element instance should be created.
+- `inferred`: Let the engine automatically find the appropriate ancestor element scope.
+- `sourceParent`: Use the source element's parent scope (recommended for moving between sibling elements inside multi-instance subprocesses, as it offers better performance than `inferred`).
+
+**Note**
+While move modifications are supported for elements inside multi-instance subprocesses, add (activate) modifications are not. You cannot directly add or activate new tokens for elements inside multi-instance subprocesses. Use move modifications to relocate execution in multi-instance contexts.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-modification

package/.llms/chunks/components.concepts.process-instance-modification.set-variables.md

@@ -0,0 +1,24 @@
+# Process instance modification — Set variables
+
+We can use the modification command to set one or more variables together by activating an element of the process.
+Consider the following example:
+
+![The process instance waits on task. We use the modification command to activate a task inside a non-interrupting message event subprocess.](assets/process-instance-modification/process-instance-modification-set-variables.png)
+
+The process instance completed the first task `A` and waited on task `B`. Task `C` is embedded in a non-interrupting
+message event subprocess. An external system will publish the message, but it is not available.
+
+To correct the state of the process instance, we modify it and activate the task `C` inside the non-interrupting message
+event subprocess. Additionally, we add variable instructions to the modification to set variables that should be
+provided by the message.
+
+The process instance sets the variables before activating the given element. As a result, the variables are available
+when applying the input variable mappings and creating the event subscriptions of the element.
+
+A variable instruction can define the [scope](https://docs.camunda.io/docs/next/components/concepts/variables#variable-scopes) of the variables. If a scope is defined, the process instance sets the variables as **local** variables in the given scope. For example, set the message variables
+as local variables of the event subprocess. The scope must be a flow scope of the activating element.
+
+If no scope is defined, the process instance sets the variables **globally** in the root scope of the process instance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-modification

package/.llms/chunks/components.concepts.process-instance-modification.terminate-an-element-instance.md

@@ -0,0 +1,40 @@
+# Process instance modification — Terminate an element instance
+
+We can use the modification command to terminate an active element instance of the process instance. Consider the
+following example:
+
+![The process instance waits on a task inside a nested interrupting event subprocess. We use the modification command to terminate the event subprocess.](assets/process-instance-modification/process-instance-modification-terminate-element-instance.png)
+
+The process instance completed the first task `A` in the embedded subprocess. It triggered the interrupting timer event
+subprocess and terminated task `B` inside the embedded subprocess. An external system published a message and triggered
+the non-interrupting message boundary event on the subprocess. The process instance waits on task `C` inside the event
+subprocess and on task `D` connected to the boundary event.
+
+The job worker for task `C` failed to complete the job successfully. To skip the task and continue the process instance,
+we modify it and terminate the element instance of the event subprocess.
+
+As a result, the process instance terminates the event subprocess and the element instance of the task `C` that is
+inside the event subprocess. Additionally, the process instance terminates the embedded subprocess because it doesn't
+contain active element instances anymore.
+
+Generally, the modification applies the following rules:
+
+- If the terminating element instance is a subprocess, it terminates all active instances in the subprocess.
+- If the terminating element instance is a call activity, it terminates the child process instance.
+- If the terminating element instance was the last active instance inside a subprocess, it terminates the subprocess.
+- If the terminating element instance was the last active instance of the process instance, it terminates the
+  process instance.
+
+If a terminating element instance is not active, the process instance doesn't apply the termination instruction
+and rejects the command.
+
+**Note**
+The process instance can't terminate the last active element instance of a child process instance. As a result, the
+process instance doesn't apply the termination instruction and rejects the command.
+
+Instead, we can terminate the call activity that created the child process instance.
+
+Terminating a user task via modification does not trigger its [`canceling` user task listener](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners#trigger-a-user-task-listener).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-modification

package/.llms/chunks/components.concepts.processes.bpmn.md

@@ -0,0 +1,24 @@
+# Processes — BPMN
+
+Camunda uses **[Business Process Model and Notation (BPMN) 2.0](https://docs.camunda.io/docs/next/components/modeler/bpmn/bpmn)** to represent processes. The visual nature of BPMN enables greater collaboration between different teams, and is employed by numerous organizations globally.
+
+![process example](./assets/order-process.png)
+
+**Note**
+New to BPMN? Visit our step-by-step introductory guide on [automating a process using BPMN](https://docs.camunda.io/docs/next/components/modeler/bpmn/automating-a-process-using-bpmn)
+
+
+## Modeling BPMN
+
+Camunda provides [Modeler](https://docs.camunda.io/docs/next/components/modeler/about-modeler), a free and open source BPMN modeling tool to create BPMN diagrams and configure their technical properties.
+
+Camunda offers two Modeler tools to design and implement your diagrams:
+
+- [Camunda Hub](https://docs.camunda.io/docs/next/components/hub/workspace/modeler/index): Integrate seamlessly with Camunda 8 SaaS and Self-Managed installations.
+- [Desktop Modeler](https://docs.camunda.io/docs/next/components/modeler/desktop-modeler/index): Design, view, and edit models using this desktop application. Install and use Desktop Modeler locally, all while integrating your local development environment.
+
+**Note**
+New to modeling a process? Visit our [getting started guide](https://docs.camunda.io/docs/next/components/hub/workspace/modeler/collaboration/design-your-process).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/processes

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

@@ -0,0 +1,22 @@
+# Processes
+
+Processes are flowchart-like blueprints that define the orchestration of tasks.
+
+A [process](https://docs.camunda.io/docs/next/reference/glossary#process) is a defined sequence of distinct steps or tasks representing your business logic. For example, an e-commerce shopping experience or onboarding a new employee.
+
+Process orchestration is the technology that coordinates the various moving parts, or endpoints, of a business process, and sometimes ties multiple processes together. It helps you work with the people, systems, and devices you already have, while achieving goals around end-to-end process automation.
+
+With Camunda, you can orchestrate [human tasks](https://docs.camunda.io/docs/next/guides/getting-started-orchestrate-human-tasks), [microservices](https://docs.camunda.io/docs/next/guides/getting-started-example), [APIs](https://docs.camunda.io/docs/next/guides/getting-started-orchestrate-apis), and [AI agents](https://docs.camunda.io/docs/next/guides/getting-started-agentic-orchestration) as endpoints in the same process. For example, an order fulfillment process could run a fixed sequence of steps, then hand off a step to an [AI agent](https://docs.camunda.io/docs/next/reference/glossary#ai-agent) that decides which tools to call, before returning control to the next fixed step.
+
+A **[job worker](https://docs.camunda.io/docs/next/components/concepts/job-workers)** implements the business logic required to complete a task. You can choose to write a worker as a microservice, or also as part of a classical 3-tier application, as a \(lambda\) function, via command line tools, etc.
+
+Running a process broadly requires three steps:
+
+1. Deploy a process to Camunda 8.
+2. Implement and register job workers for tasks in the workflows.
+3. Create new instances of the process.
+
+However, if you haven't yet, design the process:
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/processes

package/.llms/chunks/components.concepts.processes.process-execution.md

@@ -0,0 +1,40 @@
+# Processes — Process execution
+
+The simplest kind of process is an ordered sequence of tasks. Whenever process execution reaches a task, [Zeebe](https://docs.camunda.io/docs/next/components/zeebe/zeebe-overview) (the workflow engine inside Camunda 8) creates a job that can be requested and completed by a job worker.
+
+![process-sequence](assets/order-process.png)
+
+Process orchestration typically follows the steps below:
+
+1. A process instance reaches a task, and Zeebe creates a job that can be requested by a worker.
+2. Zeebe waits for the worker to request a job and complete the work.
+3. Once the work is complete, the flow continues to the next step.
+4. If the worker fails to complete the work, the process remains at the current step, and the job could be retried until it's successfully completed.
+
+As Zeebe progresses from one task to the next in a process, it can move custom data in the form of [variables](https://docs.camunda.io/docs/next/components/concepts/variables). Variables are key-value pairs and part of the process instance.
+
+![data-flow](assets/process-data-flow.png)
+
+Any job worker can read the variables and modify them when completing a job so data can be shared between different tasks in a process.
+
+### Agent-driven steps
+
+Not every step has to follow a deterministic path you model in advance. Where a decision can't be fixed up front, you can hand part of the process to an [AI agent](https://docs.camunda.io/docs/next/reference/glossary#ai-agent).
+
+In the following order process, **Fetch items** is an AI agent rather than a fixed task.
+
+![order process with an ai agent](assets/order-process-agent.png)
+
+Execution works as described above, with one difference: the AI agent chooses which activity runs next.
+
+1. The process instance reaches the AI agent, which sends the prompt and the available tool definitions to a large language model (LLM).
+2. If the LLM selects a tool, Camunda activates the matching activity inside the sub-process. **Check inventory**, **Reserve stock**, **Order from supplier**, and **Ask warehouse team** are service and user tasks, completed by the same job workers and users as any other task.
+3. The tool result is passed back to the LLM, which decides whether more tool calls are needed.
+4. Once the LLM returns a final response, the flow continues to **Ship parcel**.
+
+The LLM decides which tools to call and in what order. Camunda runs them, moves the same [variables](https://docs.camunda.io/docs/next/components/concepts/variables), and applies the same retries, incident handling, and audit trail as the fixed steps around them.
+
+To learn more, see [agentic orchestration](https://docs.camunda.io/docs/next/components/agentic-orchestration/agentic-orchestration-overview).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/processes

package/.llms/chunks/components.concepts.resource-deletion.deleting-a-decision-requirements-graph.md

@@ -0,0 +1,29 @@
+# Resource deletion — Deleting a decision requirements graph
+
+Delete a decision requirements graph (DRG) by sending a [delete resource command](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#deleteresource-rpc) and providing the `decision requirements key` as the `resource key`.
+
+Deleting a DRG also deletes the decisions it contains. Attempts to evaluate a deleted decision result in a `NOT_FOUND` exception. Deleting a DRG also deletes historical data.
+
+### Business rule tasks
+
+A [business rule task](https://docs.camunda.io/docs/next/components/modeler/bpmn/business-rule-tasks/business-rule-tasks) references a decision by ID. If all versions of that decision are deleted, Zeebe creates an incident on the business rule task indicating that no decision with the given ID can be found.
+
+### Historic data
+
+Optionally enable historic data deletion to permanently remove all data related to the decision definition from secondary storage.
+
+**Warning**
+Deletion is irreversible. Restore deleted data only by restoring a backup of your cluster.
+
+Delete historic data for a decision definition using the [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/delete-resource.api) and set the `deleteHistory` flag to `true`.
+
+You can also delete historic data for a decision definition in Operate. See the [Operate user guide](https://docs.camunda.io/docs/next/components/operate/userguide/delete-resources#delete-decision-definition).
+
+If you only want to delete decision instance data, see [decision instance deletion](https://docs.camunda.io/docs/next/components/concepts/decision-instance-deletion).
+
+#### Eventual consistency
+
+Historic data deletion runs asynchronously. Depending on the amount of data, it may take time for the data to be removed and for it to disappear from Operate and Tasklist.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/resource-deletion

package/.llms/chunks/components.concepts.resource-deletion.deleting-a-process-definition.md

@@ -0,0 +1,48 @@
+# Resource deletion — Deleting a process definition
+
+Delete a process definition by sending a [delete resource command](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#deleteresource-rpc) and providing the `process definition key` as the `resource key`.
+
+You can delete any version of a process definition. After deletion, the definition no longer exists in Zeebe's state and new process instances cannot be created for it. Attempts to create a new instance result in a `NOT_FOUND` exception.
+
+Zeebe **never** reuses a process version. Even after deletion, Zeebe continues tracking version numbers. Deploying a new process with the same ID increments the version as usual.
+
+### Deleting the latest version
+
+When deleting the `latest` version of a process definition, the previous version becomes the new `latest`.
+
+For example, if three versions exist and `Version 3` is the latest, deleting it results in the following:
+
+- No new instances can be created for `Version 3`.
+- Creating a new process instance using `latest` creates an instance of `Version 2`.
+- If `Version 2` contains timer start events, they are reactivated and triggered according to their schedule.
+- If `Version 2` contains message or signal start events, they are reactivated. Publishing a message or broadcasting a signal creates a new process instance of `Version 2`.
+
+Deleting `Version 2` before `Version 3` produces the same behavior, except `Version 1` becomes the new `latest`.
+
+### Call activities
+
+A [call activity](https://docs.camunda.io/docs/next/components/modeler/bpmn/call-activities/call-activities) references a process by ID. If all process definitions for that process ID are deleted, Zeebe creates an [incident](https://docs.camunda.io/docs/next/components/concepts/incidents) on the call activity indicating that the referenced process cannot be found.
+
+### Limitations
+
+You cannot delete a process definition that has one or more running process instances. Terminate or complete all running instances before deleting the definition.
+
+### Historic data
+
+Optionally enable historic data deletion to permanently remove all data related to the process definition from secondary storage.
+
+**Warning**
+Deletion is irreversible. Restore deleted data only by restoring a backup of your cluster.
+
+Delete historic data for a process definition using the [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/delete-resource.api) and set the `deleteHistory` flag to `true`.
+
+You can also delete a process definition with historic data using Operate. See the [Operate user guide](https://docs.camunda.io/docs/next/components/operate/userguide/delete-resources#delete-process-definition).
+
+If you only want to delete process instance data, see [process instance deletion](https://docs.camunda.io/docs/next/components/concepts/process-instance-deletion).
+
+#### Eventual consistency
+
+Historic data deletion runs asynchronously. Depending on the amount of data, it may take time for the data to be removed and for it to disappear from Operate and Tasklist.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/resource-deletion

package/.llms/chunks/components.concepts.resource-deletion.md

@@ -0,0 +1,20 @@
+# Resource deletion
+
+Delete process definitions and decision requirements graphs from Camunda.
+
+Use resource deletion to remove resources from a cluster when they are no longer needed or should no longer be used.
+
+Deleting resources:
+
+1. **Frees storage space**, as Zeebe no longer needs to keep the definition in its state.
+2. **Prevents new instances from being created**, which can help avoid usage of faulty process definitions.
+
+The following resource types can be deleted:
+
+1. [Process definitions](https://docs.camunda.io/docs/next/components/concepts/processes)
+2. [Decision Requirements Graphs (DRG)](https://docs.camunda.io/docs/next/components/modeler/dmn/decision-requirements-graph)
+
+Delete a resource using [Operate](https://docs.camunda.io/docs/next/components/operate/userguide/delete-resources) or by sending the [delete resource command](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#deleteresource-rpc) to the Zeebe API.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/resource-deletion

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.activate-a-job-that-references-secrets-job-push.md

@@ -0,0 +1,10 @@
+# Secret resolution and job activation — Activate a job that references secrets — Job push
+
+On the push path, the broker performs the same check before pushing a job to a matching job stream. If a reference is not yet cached, the broker requests resolution and parks the job as it does on the polling path.
+
+When the reference resolves, the broker pushes the parked job to a matching stream. Because a worker using job push never polls, the broker must push the reactivated job.
+
+The resolved values are injected into the pushed job only. On this path the activation event carries no variables at all, so neither a value nor a placeholder reaches the log.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.activate-a-job-that-references-secrets-long-polling.md

@@ -0,0 +1,17 @@
+# Secret resolution and job activation — Activate a job that references secrets — Long polling
+
+During batch collection, a job with a reference that is not yet cached is skipped without consuming a slot in the batch, so jobs behind it can still be activated in the same response.
+
+The broker then requests resolution of that job's missing references and parks the job until they resolve. A parked job is not activatable, so a later poll does not collect it again and no worker receives it. Once the reference resolves, the job is made activatable again automatically. Neither redeployment nor client action is required.
+
+Two limits affect how many jobs one activation can return:
+
+- If a single activation skips 100 jobs for uncached references, it stops there and marks the batch truncated. The gateway polls the same partition again within the same request, so the jobs behind the cap are not held back until the long poll times out.
+- If injecting a job's resolved values would exceed the configured message size, the broker removes that job and every subsequent job from the activation and marks the batch as truncated. These jobs remain activatable for the next activation.
+
+The truncated flag is internal to the broker and the gateway. It is not part of the activate jobs response, so a worker never sees it and does not act on it.
+
+The broker injects the resolved values into a copy of the batch used only for the response. The event the broker appends to its log still carries the placeholders.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.activate-a-job-that-references-secrets-understand-what-a-job-worker-receives.md

@@ -0,0 +1,15 @@
+# Secret resolution and job activation — Activate a job that references secrets — Understand what a job worker receives
+
+A job worker does not need to handle secret resolution. While a job waits for a reference to resolve, the broker does not include it in an activation response or push it to a worker.
+
+A worker receives the job with the placeholders replaced by the resolved values. If your worker logs its input variables, the resolved secret values appear in plaintext.
+
+**Warning**
+The guarantees below describe what Camunda stores, not what a worker does with the value it received. A worker can still write the resolved value back into process variables, for example through a completed job's variables, an output mapping, a connector result, or an error message. Doing so writes it to process variables and exposes it in runtime state and every exported record as plaintext, the same as any other variable value. Write resolved secret values into a worker's own request to the credential's consumer, not back into process variables.
+
+You don't need to make client-side changes. Existing workers, clients, and job worker libraries continue to work with a cluster that resolves secrets.
+
+One exception: a worker's `CompleteJob`, `FailJob`, or `ThrowError` command is rejected with `INVALID_STATE` if the job is parked for secret resolution when the command arrives; the rejection names the state. This can surface as a race: if a worker's activation times out and it completes, fails, or throws an error late, and by then the job's cached secret value has expired and the broker parked it again, that late command is rejected instead of accepted. The work of that activation is lost, and the job is resolved and handed out again once its references are cached, the same outcome as any other lost race between a timed-out worker and a new activation.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.activate-a-job-that-references-secrets.md

@@ -0,0 +1,12 @@
+# Secret resolution and job activation — Activate a job that references secrets
+
+At activation time, the broker looks up each job reference in the secret store's local cache. The broker does not read the store during activation, so store latency cannot block activation.
+
+The broker hands a job to a worker only when every reference has a cached value. If a reference is not yet cached, the broker requests resolution instead of handing out the job. The broker does not fail the waiting job or raise an incident. Once the reference resolves, the job becomes available automatically.
+
+While it waits, the job is parked internally and is not activatable, so no worker receives it on either delivery path. This parked state isn't exposed through the API, Operate, or exported records. Observe it instead through its effects: the job is missing from an activation response, no `ACTIVATED` event exists for its batch, a `RESOLUTION_REQUESTED` record exists for the pending reference, and the `zeebe_job_events_total` metric counts it under `action="skipped uncached secret"`.
+
+The following sections describe this behavior for each delivery path. The broker injects the same resolved values on both paths.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.availability.md

@@ -0,0 +1,13 @@
+# Secret resolution and job activation — Availability
+
+Secret resolution is available in both SaaS and Self-Managed.
+
+| Offering     | Secret store            | What you configure                                                                                                                                                                                                                                                                            |
+| :----------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SaaS         | Provisioned and managed | No secret store configuration. Manage secret values on the cluster's **Cluster secrets** tab and reference them as `camunda.secrets.<key>`. See [Manage connector secrets](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/manage-secrets#reference-connector-secrets-as-camundasecretsname). |
+| Self-Managed | File, AWS, or GCP       | The store type, path, and credentials. See [secrets configuration](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#secrets).                                                                                                                         |
+
+You can configure AWS Secrets Manager and GCP Secret Manager stores only in Self-Managed.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.md

@@ -0,0 +1,16 @@
+# Secret resolution and job activation
+
+Learn how the broker resolves secret references before job activation and injects resolved values when it hands a job to a worker.
+
+Secret resolution lets job workers use secret values at runtime without storing those values in job variables or configuration.
+
+A job whose variables contain an [Orchestration Cluster secret reference](https://docs.camunda.io/docs/next/reference/glossary#secret-reference-orchestration-cluster) is handed to a worker only after every reference has been resolved. The resolved values reach the worker without being written to any record, runtime state, or log.
+
+The broker resolves secret references in the background rather than while processing a command. It injects the resolved values into the job only when handing the job to a worker. As a result, secret resolution can affect when a job becomes available for activation.
+
+A cluster whose process models contain no `camunda.secrets.<name>` reference is unaffected by any of this. A model that does use a reference behaves differently depending on whether a secret store is configured: on a cluster with no store configured, every reference fails permanently as not found, and the job gets a [secret resolution error incident](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents#resolve-secret-lookup-failures) rather than a delay.
+
+This page describes an alpha feature and may change in future releases. See [alpha features](https://docs.camunda.io/docs/next/components/early-access/alpha/alpha-features).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.related-resources.md

@@ -0,0 +1,8 @@
+# Secret resolution and job activation — Related resources
+
+- [Job workers](https://docs.camunda.io/docs/next/components/concepts/job-workers) describes long polling, job push, and job queuing in general.
+- [Troubleshoot secret resolution failures](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents) covers the incidents described here: their messages, how to diagnose them, and what happens after you resolve them.
+- [Incidents](https://docs.camunda.io/docs/next/components/concepts/incidents) explains what an incident is and how it is resolved, which applies to the incidents described here.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.resolve-references-before-activation.md

@@ -0,0 +1,33 @@
+# Secret resolution and job activation — Resolve references before activation
+
+The broker resolves secret references on a background scheduler, not on the processing path, so a slow or unavailable secret store cannot stall processing.
+
+Each physical tenant supports exactly one secret store, and that store's id must be `default`. A `camunda.secrets.<name>` reference always addresses it. `camunda.physical-tenants.<tenant-key>.secrets.*` can override which store backs a given tenant, but never adds a second store alongside it.
+
+When the broker creates a job, it records each secret reference together with its position in the job variables. The variable value itself keeps the placeholder text `camunda.secrets.<name>`. Nothing is read from a secret store at this point.
+
+The scheduler then works through the references that are still pending:
+
+1. Each cycle collects up to `camunda.processing.engine.secrets.batch-resolution-limit` pending references and groups them by store.
+2. The scheduler requests each store's group of references in one call. The store's local cache holds successfully resolved values for the next activation.
+3. References beyond the limit stay pending and are collected by a later cycle. When a cycle reaches the limit and makes progress, the next cycle starts immediately instead of waiting for `camunda.processing.engine.secrets.interval`.
+
+Resolution records carry no secret values. Only the store's cache holds a value, and only for as long as its cache entry lives.
+
+A cached value expires a fixed time after it is written, regardless of when it was last read. The store can also evict the value earlier if its cache is full. If the value is no longer cached when the broker tries to activate a job, the broker parks the job and resolves the reference again.
+
+Resolving the reference again also makes rotated secrets available to workers without a restart. Configure the store's cache lifetime and size under [`camunda.secrets.cache`](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#camundasecretscache).
+
+Two kinds of failure are treated differently:
+
+| Failure                                                      | Behavior                                                                                                                                                                                     |
+| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The store reports a secret as missing, forbidden, or invalid | Treated as permanent. The reference fails immediately, with no retry and no cache write.                                                                                                     |
+| The store itself is unavailable                              | Treated as transient. The broker retries the store with exponential backoff. After `retry-max-attempts` consecutive failures, the broker fails every reference still pending for that store. |
+
+The broker tracks retry state for its store rather than per secret and holds it in memory only. The retry state resets when the broker restarts or the partition changes leader. During backoff, the scheduler skips the store, so its references do not consume batch capacity that a healthy store can use.
+
+A reference that fails permanently, or whose store never recovers, raises an incident for the jobs waiting on it. See [resolve secret lookup failures](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents#resolve-secret-lookup-failures) for the incident message, how to tell the causes apart, and what resolving it does.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.secret-resolution-across-physical-tenants.md

@@ -0,0 +1,13 @@
+# Secret resolution and job activation — Secret resolution across physical tenants
+
+The secret store, its cache, and the resolution scheduler's retry state are all scoped per [physical tenant](https://docs.camunda.io/docs/next/self-managed/concepts/physical-tenants/configuration-reference). A multi-tenant cluster resolves each tenant's `camunda.secrets.<name>` references against that tenant's own store: two tenants never share a cache entry, and one tenant's store outage does not affect another tenant's resolution.
+
+`camunda.secrets.*` configures the store and cache defaults every physical tenant inherits. Override them for one tenant under `camunda.physical-tenants.<tenant-key>.secrets.*`. The tenant still supports only one store, under the same `default` id.
+
+
+## Monitor secret resolution
+
+A store that is slow or unavailable shows up as jobs that do not activate, and the job worker does not indicate the cause. The cluster emits meters for secret resolution and secret caches. Use these meters to distinguish a cold cache from a store that is not responding. To scrape and interpret cluster meters, see the [metrics reference](https://docs.camunda.io/docs/next/self-managed/operational-guides/monitoring/metrics#secret-resolution-and-cache-metrics).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.secret-values-location.md

@@ -0,0 +1,16 @@
+# Secret resolution and job activation — Secret values location
+
+Resolved secret values exist only in the activation response and in the pushed job, unless a worker writes the value into a process variable itself (see the warning above). Short of that, everywhere else the placeholder text is what is stored.
+
+| Location                                   | What it contains                                              |
+| :----------------------------------------- | :------------------------------------------------------------ |
+| The activation response or the pushed job  | The resolved values                                           |
+| The job batch `ACTIVATED` event in the log | The placeholder text, or no variables at all on the push path |
+| Runtime state and exported records         | The placeholder text                                          |
+| Broker logs, including failure logs        | The placeholder text, never a value                           |
+| Incident messages                          | The reference and the variable path, never a value            |
+
+As a result, Operate shows `camunda.secrets.<name>` for the process instance even though the worker received the resolved value.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.tune-the-resolution-scheduler.md

@@ -0,0 +1,22 @@
+# Secret resolution and job activation — Tune the resolution scheduler
+
+Configure the scheduler under `camunda.processing.engine.secrets`. The defaults are intended for stores that respond in less than a second. The separate `camunda.secrets.cache.ttl` setting controls how long a resolved value remains cached before the reference must be resolved again.
+
+Under a steady stream of pending references, cycles run close to `wake-delay` apart, not `interval`: `interval` only bounds how long a scheduler with nothing to resolve waits before checking again, growing there from `wake-delay` in geometric steps rather than jumping straight to it.
+
+| Property                 | Default | Change it when                                                                                                                                                                                        |
+| :----------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wake-delay`             | `50ms`  | Jobs that reference secrets take too long to activate under a steady stream of requests. A shorter delay reduces that latency at the cost of polling the stores more often.                           |
+| `interval`               | `5s`    | A scheduler that is genuinely idle takes too long to notice a newly pending reference, or you want its idle ceiling to be different. Under load this value is rarely reached; see `wake-delay` above. |
+| `batch-resolution-limit` | `20`    | A backlog of pending references builds up faster than it clears. A higher limit clears it faster at the cost of more concurrent load on the stores.                                                   |
+| `retry-max-attempts`     | `3`     | You want to tolerate brief store outages before raising incidents.                                                                                                                                    |
+| `retry-initial-delay`    | `1s`    | You need a longer or shorter delay before the first retry.                                                                                                                                            |
+| `retry-backoff-factor`   | `2`     | You want retry delays to increase more slowly. A value of `1` keeps the delay constant.                                                                                                               |
+| `retry-max-delay`        | `30s`   | You want to retry an unavailable store sooner or less often.                                                                                                                                          |
+
+The retry settings apply to an unavailable store as a whole. A secret the store reports as missing or forbidden is never retried, because that failure is permanent.
+
+See the [property reference](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties) for the full description of each property and its environment variable form.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation

package/.llms/chunks/components.concepts.secret-resolution-and-job-activation.understand-why-a-job-is-not-activated.md

@@ -0,0 +1,16 @@
+# Secret resolution and job activation — Understand why a job is not activated
+
+Two conditions stop a job from being activated even though all of its references have resolved.
+
+### Resolved values exceed the message size
+
+The activation response has to stay within `camunda.cluster.network.max-message-size`, which defaults to `4MB`. A resolved value is usually longer than the placeholder it replaces, so a job that fit with placeholders can fail to fit once the values are injected. A value shorter than its placeholder reduces the response size and does not cause this condition. If the resolved values exceed the available message size, the broker removes that job and every subsequent job from the activation. The jobs remain activatable for a later batch. If a job cannot fit even in an otherwise empty batch, the broker raises a message size incident.
+
+### Secret injection fails
+
+The broker replaces the placeholder at its recorded position in the job variables. If a later variable merge overwrites the expected placeholder, or if the broker cannot read the variables, the broker does not activate the job and raises an incident. The incident also takes the job out of activation until the incident is resolved, so the same failing injection is not retried on every activation.
+
+For how to inspect and resolve either incident, see [troubleshoot secret resolution failures](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation