@bpmnkit/camunda-docspack 0.0.0

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

@@ -0,0 +1,62 @@
+# Job workers — Job prioritization
+
+Use job prioritization when you have mixed-urgency workloads and want time-sensitive jobs to be activated ahead of lower-priority ones.
+
+Camunda supports job prioritization for pull-based job activation. Job priority affects the order in which jobs are activated for workers. It does not change retries, failures, or completion semantics.
+
+Priority ordering is automatic. No worker-level flag or configuration is required — once a job has a priority set, Zeebe activates higher-priority jobs first when a job pull method is used.
+
+You can define job priority:
+
+- On the process as a default.
+- On supported job-creating tasks as an override, including service tasks, send tasks, and script or business rule tasks implemented as job workers.
+
+### Process-level priority
+
+To set a default priority for all jobs created by a process, add `zeebe:jobPriorityDefinition` to the process `extensionElements`:
+
+```xml
+<bpmn:process id="my-process" isExecutable="true">
+  <bpmn:extensionElements>
+    <zeebe:jobPriorityDefinition priority="42" />
+  </bpmn:extensionElements>
+  ...
+</bpmn:process>
+```
+
+A task-level priority definition overrides this process-level default.
+
+### Task-level priority
+
+Job priority is enforced per partition, not globally across the cluster. Within a partition, higher-priority jobs are activated before lower-priority ones. Within the same priority level, jobs activate in FIFO order. If you don't set any priorities, standard FIFO behavior applies throughout.
+
+The default priority is 0.
+
+Be aware that low-priority jobs can starve if workers are consistently occupied by higher-priority work. Camunda doesn't provide starvation mitigation, fairness guarantees, or priority aging. If starvation becomes a problem, increase worker capacity or revise your priority assignments.
+
+Priority values can be static integers or FEEL expressions. FEEL expressions are evaluated when the job is created, and the resulting integer is stored on the job.
+
+Priority accepts any signed 32-bit integer. The engine does not enforce a fixed upper or lower bound such as `0-99`.
+
+Jobs created before version 8.10 do not have a stored priority value. For job execution, Camunda treats them as having the default priority of 0.
+
+**Warning**
+If you use job APIs that filter or sort by priority, pre-8.10 jobs are excluded from results because no priority value is stored for them. Review any priority-based queries before upgrading.
+
+### Validation and runtime failure behavior
+
+Invalid FEEL expressions are handled differently depending on when they fail:
+
+- If the expression is invalid at deployment time, BPMN deployment fails and the process is not deployed.
+- If the expression fails at runtime, for example because a referenced variable is missing, Camunda raises an incident and the job is not created.
+
+To recover, provide the missing variable value and resolve the incident manually in Operate.
+
+### Job streaming limitation
+
+Job streaming activates jobs as they are created and ignores priorities.
+
+If you use job pulling and job streaming together for the same job type, this negates the benefits of job prioritization.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-streaming-backpressure.md

@@ -0,0 +1,40 @@
+# Job workers — Job streaming — Backpressure
+
+To avoid workers overloaded with too many jobs, e.g. running out of memory:
+
+- The workers rely on the [built-in gRPC flow control mechanism](https://grpc.io/docs/guides/flow-control/).
+- Or, if lacking for your language of choice, [the built-in HTTP/2 stream flow control](https://httpwg.org/specs/rfc7540.html#FlowControl), e.g. Golang implementation of gRPC.
+
+Essentially, as jobs are pushed downstream from the broker to the client, they're first buffered in the gateway where the direct client connection resides. The gateway only sends as much data as the client can consume over a specific connection. If it notices its send buffers fill up, it marks a client as `not-ready`. This can happen, for example, if the client's receive method is blocked/suspended.
+
+If a client is not ready to receive a job, the gateway instead tries to re-route the job to another logically equivalent worker. If this fails (e.g. all workers connected to a specific gateway are not ready), the job is returned to the broker. There, it may be retried to another gateway, if and only if it has a logically equivalent worker.
+
+#### Implementing backpressure
+
+If you're using the raw `StreamActivatedJobs` RPC, or want to add support for this to your client of choice, the criteria to apply backpressure is to stall the underlying HTTP/2 transport. To do so, you may need to block the thread in which the gRPC stream is running (e.g. Java), or suspend the coroutine (e.g. Kotlin, Go). Once the transport stops receiving, this causes the gateway's send buffers to fill up, and effectively apply backpressure.
+
+If you wish to test this, you can do so by simulating a very slow worker with your new implementation. Then, start generating many jobs on the server side (e.g. create many process instances with lots of jobs). You should then observe backpressure via server side metrics, or many `Job.YIELD` commands written to the log.
+
+Refer to the [client implementations](https://github.com/camunda/camunda/tree/main/clients) for more information.
+
+#### Detecting backpressure
+
+There are different ways to detect backpressure.
+
+On the client side, you can use the job worker metrics to do so. For example, by subtracting the rate of handled jobs (i.e. `camunda.client.worker.job.handled`) from the rate of activated jobs (i.e. `camunda.client.worker.job.activated`), you can estimate the rate of queued jobs. If this is too close to the `maxJobsActive` consistently, this may indicate you need to scale your worker deployment.
+
+**Warning: Deprecated metrics**
+The following metrics are deprecated and will be removed in version 8.10:
+
+- `zeebe.client.worker.job.activated`, replace with `camunda.client.worker.job.activated`
+- `zeebe.client.worker.job.handled`, replace with `camunda.client.worker.job.handled`
+
+Please update your monitoring integrations to use the new metrics before upgrading to version 8.10.
+
+**Note**
+If you're using Prometheus, you can use the following query to estimate the queue size of your workers. We recommend adding a job type label to be able to group per workload, e.g. `sum(zeebe_client_worker_job_activated_total - zeebe_client_worker_job_handled_total) by (jobType)`
+
+On the server side (e.g. if you're running a self-managed cluster), you can measure the rate of jobs which are not pushed due to clients which are not ready via the metric `zeebe_broker_jobs_push_fail_try_count_total{code="BLOCKED"}`. If the rate of this metric is high for a sustained amount of time, it may be a good indicator that you need to scale your workers. Unfortunately, on the server side we don't differentiate between clients, so this metric doesn't tell you which worker deployment needs to be scaled. We thus recommend using client metrics whenever possible.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

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

@@ -0,0 +1,27 @@
+# Job workers — Job streaming — How it works
+
+Job streaming works by having the worker open a long living gRPC unidirectional stream from the client to the gateway. The gateway then aggregates logically equivalent streams and registers each of these aggregated streams to every broker.
+
+**Note**
+Two streams are considered logically equivalent if they would both activate the same job in the exact same way. More concretely, this means if they:
+
+- Target the same job type
+- Have the same worker name
+- Have the same job activation timeout
+- Have the same fetch variables
+
+On the broker side, whenever a job is made activate-able (e.g. a service task is activated, a job failed and is retried, etc.), if there is one or more streams for this job type, a random one is picked, the job is activated and pushed to it. As the job makes its way back to the gateway that owns this stream, a random client associated with it is picked, and the job is forwarded to it.
+
+**Note**
+The RNG used to randomly pick streams and clients provides a good uniform distribution for the same underlying set, which is a cheap way of evenly distributing the load _as long as the stream set remains stable_.
+
+Job leasing also applies to streaming: a leased job only matches streams opened with a lease request, and streams opened without one only match unleased jobs. See [job leasing](#job-leasing) for details.
+
+If a job contains unresolved secret references, the broker requests resolution before pushing the job. Once the references resolve, the broker pushes the job. See [secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation).
+
+To help visualize the process in general, here is a sequence diagram which shows a single worker opening a job stream for jobs of type "foo" against a cluster consisting of a single gateway and a single broker. It receives some jobs, and when it closes, one job that was pushed asynchronously is returned to the broker:
+
+![Sample Sequence Diagram](assets/job-push-sequence.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-streaming-how-job-streaming-and-polling-deliver-jobs.md

@@ -0,0 +1,35 @@
+# Job workers — Job streaming — How job streaming and polling deliver jobs
+
+Job streaming and polling are separate delivery paths, not two ways of draining the same queue.
+
+Zeebe queues any job that has no registered stream for its type in an internal backlog (the `ACTIVATABLE` state), and long polling (via the [`ActivateJobs` RPC](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#activatejobs-rpc)) is the only path that serves this backlog. A pushed job bypasses the backlog only on its first delivery attempt: as soon as the job becomes `ACTIVATABLE`, Zeebe pushes it directly to a registered stream for its type, if one exists. If the push fails or the job times out before completion, the job returns to the `ACTIVATABLE` backlog like any other job.
+
+The following diagram shows both delivery paths, from the broker through the gateway to the worker’s job capacity:
+
+```mermaid
+flowchart TB
+    created["Job becomes activate-able"]
+
+    subgraph broker["Broker"]
+        created
+        backlog[["ACTIVATABLE backlog"]]
+    end
+
+    subgraph gateway["Gateway"]
+        pushFwd["Push forwarding"]
+        pollFwd["Poll forwarding<br/>(ActivateJobs)"]
+    end
+
+    subgraph worker["Worker"]
+        capacity(("Job capacity<br/>(worker-defined limit)"))
+    end
+
+    created -- "no stream registered" --> backlog
+    created -- "stream registered: pushed immediately" --> pushFwd
+    pushFwd --> capacity
+    backlog -- "drained only by polling" --> pollFwd
+    pollFwd --> capacity
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-streaming-proxying.md

@@ -0,0 +1,6 @@
+# Job workers — Job streaming — Proxying
+
+If you're using a reverse proxy or a load balancer between your worker and your gateway, you may need to configure additional parameters to ensure the job stream is not closed unexpectedly with an error. If you observe regular 504 timeouts, read our guide on [job streaming](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/zeebe/zeebe-gateway/job-streaming).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.job-streaming-troubleshooting.md

@@ -0,0 +1,29 @@
+# Job workers — Job streaming — Troubleshooting
+
+Since this feature requires a good amount of coordination between various components over the network, we've built in some tools to help monitor the health of the job streams.
+
+#### Metrics
+
+We expose several metrics which help check whether the feature is working.
+
+- `zeebe_gateway_job_stream_push_total`: Allows you to derive the rate at which a gateway is pushing jobs out to clients. If this is much less than the broker's pushed count, this could indicate an issue between the broker and the gateway: jobs are getting lost, the gateway is overloaded, etc.
+- `zeebe_gateway_job_stream_clients`: The number of open job stream client calls on the gateway. This can help you figure out if your workers are well load balanced across your gateways.
+- `zeebe_gateway_job_stream_streams`: The number of aggregated streams per gateway.
+- `zeebe_gateway_job_stream_servers`: The amount of known brokers (or stream servers) per gateway. This should always be the number of brokers in your cluster. If this is less, this could indicate a clustering issue between your gateways and brokers (e.g. temporary network partition).
+- `zeebe_gateway_job_stream_push_fail_try_total`: The count of failed push attempts. This includes pushes which eventually succeeded (e.g. tried worker `A`, failed, rerouted to worker `B` which succeeded), and as such may be higher than the total number of pushes. This can be useful to narrow down on which gateways errors are coming from, or if a gateway has a higher number of faulty or blocked clients.
+- `zeebe_broker_jobs_pushed_count_total`: Allows you to derive the rate at which a broker is pushing jobs out to all streams. This can help you figure out if the broker is the bottleneck when it comes to throughput.
+- `zeebe_broker_open_job_stream_count`: The count of job streams registered on the broker. This should be the sum of all gateway aggregated streams.
+- `zeebe_broker_jobs_push_fail_try_count_total`: The count of failed job push attempts registered by a given broker. This includes pushes which eventually succeeded (e.g. tried all workers on gateway A, failed, then rerouted to gateway B where it succeeded), and as such may be higher than the total number of pushes. It's useful to detect if a specific gateway is producing errors which may otherwise be hidden by other gateways picking up the slack.
+
+#### Actuator endpoint
+
+Each broker and gateway exposes a new actuator endpoint - `/actuator/jobstreams` - accessible via the monitoring port. For example, if you run Zeebe locally with the default monitoring port, it would be accessible under `localhost:9600/actuator/jobstreams`.
+
+This returns the current view of the registered job streams, where `client` refers to client streams opened on the gateway, and `remote` refers to the aggregated gateway streams as opened on each broker.
+
+For example, if jobs of a given type are not activated, but a worker is opened for this type, you can verify first if it exists in one of the gateways as a client stream. Once you've found it, grab its ID, and verify that you can find it as a consumer of a remote stream on each broker.
+
+If it's not present in the gateway as a client stream, restart your worker. If it's not present as a consumer in one of the brokers, this indicates a bug. As a workaround, restart your gateway, which will cause some interruption in your service, but will force all streams for this gateway to be recreated properly.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

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

@@ -0,0 +1,6 @@
+# Job workers — Job streaming
+
+It's also possible to use job workers in a streaming fashion, such that jobs are automatically activated and pushed downstream to workers without requiring an extra round of polling, which greatly cuts down on overall latency.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

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

@@ -0,0 +1,24 @@
+# Job workers
+
+Learn more about job workers, a service that can perform a particular task in a process. Each time that task needs to be performed, it is represented by a job.
+
+A [job worker](https://docs.camunda.io/docs/next/reference/glossary#job-worker) is a service capable of performing a particular task in a process. Each time that task needs to be performed, it is represented by a [job](https://docs.camunda.io/docs/next/reference/glossary#job).
+For example, [AI agent](https://docs.camunda.io/docs/next/reference/glossary#ai-agent) tool calls use this mechanism. Each activity inside an [ad-hoc sub-process](https://docs.camunda.io/docs/next/reference/glossary#ad-hoc-sub-process) acts as a tool and is executed as a job, like any other task in the process.
+
+A job has the following properties:
+
+- **Type**: Describes the work item and is defined in each task in the process. The type is referenced by workers to request the jobs they are able to perform.
+
+**Important**
+This is a case-sensitive field, if supported by the underlying operating system. For example, `orderProcess` refers to a different worker than `OrderProcess`.
+
+**Note**
+Job worker types are subject to backend-dependent length limits: up to **32,768 characters** with Elasticsearch/OpenSearch-backed secondary storage and up to **256 characters** with RDBMS-backed secondary storage. If you use RDBMS, or might migrate to it later, keep job types within the 256-character limit.
+
+- **Custom headers**: Additional static metadata that is defined in the process. Custom headers are used to configure reusable job workers (e.g. a `notify Slack` worker might read out the Slack channel from its header.)
+- **Key**: Unique key to identify a job. The key is used to hand in the results of a job execution, or to report failures during job execution.
+- **Variables**: The contextual/business data of the process instance required by the worker to do its work.
+- **Tags**: Immutable labels copied from the process instance at job creation. This is great for providing additional metadata (e.g., `reference:1234`, `team:accounting`, `trace-id:3004`). See [tags](#tags) and [process instance creation tags](https://docs.camunda.io/docs/next/components/concepts/process-instance-creation#tags).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.job-workers.requesting-jobs.md

@@ -0,0 +1,49 @@
+# Job workers — Requesting jobs
+
+Job workers request jobs of a certain type on a regular interval (i.e. polling). This interval and the number of jobs requested are configurable in the [Zeebe client](https://docs.camunda.io/docs/next/apis-tools/working-with-apis-tools).
+
+If one or more jobs of the requested type are available, [Zeebe](https://docs.camunda.io/docs/next/components/zeebe/zeebe-overview) (the workflow engine inside Camunda 8) streams activated jobs to the worker. Upon receiving jobs, a worker performs them and sends back a `complete` or `fail` command for each job, depending on if the job could be completed successfully.
+
+For example, the following process might generate three different types of jobs: `process-payment`, `fetch-items`, and `ship-parcel`:
+
+![order-process-model](assets/order-process.png)
+
+Three different job workers, one for each job type, could request jobs from Zeebe:
+
+![zeebe-job-workers-requesting-jobs](assets/zeebe-job-workers-graphic.png)
+
+Many workers can request the same job type to scale up processing. In this scenario, Zeebe ensures each job is sent to only one of the workers.
+
+Such a job is considered activated until the job is completed, failed, or the job activation times out.
+
+If a job's variables contain secret references, the job is handed out only once those references have been resolved. A job that is still waiting is not returned by the request and does not count against **MaxJobsToActivate**, so jobs behind it are still activated, and it becomes available again on its own once resolution completes. See [secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation).
+
+On requesting jobs, the following properties can be set:
+
+- **Worker**: The identifier of the worker used for auditing purposes.
+- **Timeout**: The time a job is assigned to the worker. If a job is not completed within this time, it can be reassigned by Zeebe to another worker.
+- **MaxJobsToActivate**: The maximum number of jobs which should be activated by this request.
+- **FetchVariables**: A list of required variable names. If the list is empty, all variables of the process instance are requested.
+
+### Long polling
+
+Ordinarily, a request for jobs can be completed immediately when no jobs are available.
+
+To find a job to work on, the worker must poll again for available jobs. This leads to workers repeatedly sending requests until a job is available.
+
+This is expensive in terms of resource usage, because both the worker and the server are performing a lot of unproductive work. Zeebe supports **long polling** for available jobs to better utilize resources.
+
+With **long polling**, a request is kept open while no jobs are available. The request is completed when at least one job becomes available.
+
+**Long polling** is set during [job activation with the parameter `request-timeout`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#activatejobs-rpc).
+
+### Job queuing
+
+Zeebe decouples creation of jobs from performing the work on them. It is always possible to create jobs at the highest possible rate, regardless if there is a job worker available to work on them. This is possible because Zeebe queues jobs until workers request them.
+
+This increases the resilience of the overall system. Camunda 8 is highly available so job workers don't have to be highly available. Zeebe queues all jobs during any job worker outages, and progress resumes as soon as workers are available.
+
+This also insulates job workers against sudden bursts in traffic. Because workers request jobs, they have full control over the rate at which they take on new jobs.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

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

@@ -0,0 +1,23 @@
+# Job workers — Tags
+
+Tags provide a powerful way to add lightweight metadata to jobs.
+
+### How tags work with jobs
+
+When a BPMN element is activated and creates a job:
+
+1. **Snapshot creation**: The job receives a copy of all tags from the process instance at that exact moment.
+2. **Immutability**: Once copied to the job, tags cannot be modified, added, or removed.
+3. **Worker access**: Job workers can read these tags to implement custom logic.
+
+### Key characteristics
+
+- **Case-sensitive**: Tags `Priority:High` and `priority:high` are different.
+- **Timing**: Tags are copied exactly once when the job is created from the BPMN element.
+- **Immutable**: The tag set on a job never changes after creation.
+- **Inherited**: Jobs inherit the complete tag set from their process instance.
+
+For detailed information about tag formats, validation rules, limits, and additional use cases, see [process instance creation tags](https://docs.camunda.io/docs/next/components/concepts/process-instance-creation#tags).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

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

@@ -0,0 +1,26 @@
+# Job workers — Timeouts
+
+If the job is not completed or failed within the configured job activation timeout, Zeebe reassigns the job to another job worker. This does not affect the number of `remaining retries`.
+
+A timeout may lead to two different workers working on the same job, possibly at the same time. If this occurs, only one worker successfully completes the job. The other `complete job` command is rejected with a `NOT FOUND` error.
+
+The fact that jobs may be worked on more than once means that Zeebe is an "at least once" system with respect to job delivery and that worker code must be idempotent. In other words, workers **must** deal with jobs in a way that allows the code to be executed more than once for the same job, all while preserving the expected application state.
+
+### Timeout update
+
+When a job worker activates a job it can specify a timeout for how long the job should remain activated. For example, this timeout can be updated in the following scenarios:
+
+- When there are jobs which have an elastic timespan. They can potentially run for five minutes, but can be also 24+ hours. That can cause a problem when the workers picking up the jobs do not know in advance how long the given process takes, thus they can't accurately estimate a timeout.
+
+- In case of a long-running job. The scenario can occur where there is a problem with the job worker, but the task will be unavailable until the timeout is reached.
+
+In the scenarios described above, job timeout can be dynamically extended or shortened using `UpdateJobTimeout` gRPC command. This command takes a duration. This is not the duration with which the timeout will be extended or shortened. Instead, this will be the new duration the timeout is set to from the current time. This allows to not only extend the timeout of a job, but also to shorten the timeout.
+
+That means the worker does not need to estimate job timeout accurately at the very beginning. It can use some “standard” initial value and then extend or shorten the timeout as necessary.
+
+A job worker should not wait until the last second to update a job timeout as some time might be needed to process the update and there is a chance that in between the job could already time out. A buffer should be applied to avoid this issue.
+
+Job timeout can be updated [using the `UpdateJobTimeout` command](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#updatejobtimeout-rpc).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/job-workers

package/.llms/chunks/components.concepts.message-aggregation.behavior.md

@@ -0,0 +1,33 @@
+# Message aggregation — Behavior
+
+The first message with a unique correlation key starts a process instance.
+
+Each subsequent message with that same key is correlated to the same instance and appended to the list.
+
+Once three messages are received (`count(messages) == 3`), the process continues to the **Process Aggregated Messages** task.
+
+
+## Publishing messages
+
+Here’s an example in Java using the Zeebe client:
+
+```java
+final ZeebeClient client = ZeebeClient.newClientBuilder().build();
+
+for (int i = 0; i < 3; i++) {
+  client.newPublishMessageCommand()
+      .messageName("Message_Received")
+      .correlationKey("order-123")
+      .timeToLive(Duration.ofMinutes(5))
+      .variables(Map.of(
+          "message", "iteration #" + i + " order-123 " + Instant.now(),
+          "correlation_key", "order-123"))
+      .send()
+      .join();
+}
+```
+
+The first message starts the workflow; the next two correlate to the existing instance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/message-aggregation

package/.llms/chunks/components.concepts.message-aggregation.best-practices.md

@@ -0,0 +1,15 @@
+# Message aggregation — Best practices
+
+- Always include a unique `correlationKey` in message variables and BPMN definition.
+- Use a **timer boundary event** to avoid waiting indefinitely for missing messages.
+- Add logging or audit tasks for tracking message count and correlation.
+- If using multiple sources, validate messages before appending to the collection.
+- Test with different message arrival orders to ensure correct behavior.
+
+
+## Related resources
+
+- [Messages](https://docs.camunda.io/docs/next/components/concepts/messages)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/message-aggregation

package/.llms/chunks/components.concepts.message-aggregation.example-use-case.md

@@ -0,0 +1,56 @@
+# Message aggregation — Example use case
+
+Imagine a workflow that collects three messages for each order before processing them together.
+
+### BPMN model
+
+Below is the key structure of the BPMN process:
+
+- **Start event:** Message start event that starts a process for the first message of each `correlation_key`.
+- **Intermediate catch event:** Waits for additional messages with the same correlation key.
+- **Gateway:** Checks if the desired number of messages has been received.
+- **Service task:** Processes all aggregated messages when complete.
+
+```xml
+<bpmn:process id="message_aggregator" name="Message Aggregator" isExecutable="true">
+  <bpmn:startEvent id="StartEvent_Message">
+    <bpmn:messageEventDefinition messageRef="Message_Received" />
+    <bpmn:extensionElements>
+      <zeebe:ioMapping>
+        <zeebe:output source="= [message]" target="messages" />
+        <zeebe:output source="= correlation_key" target="correlation_key" />
+      </zeebe:ioMapping>
+    </bpmn:extensionElements>
+  </bpmn:startEvent>
+
+  <bpmn:intermediateCatchEvent id="CatchEvent_Message">
+    <bpmn:messageEventDefinition messageRef="Message_Received" />
+    <bpmn:extensionElements>
+      <zeebe:ioMapping>
+        <zeebe:output source="= append(messages, message)" target="messages" />
+      </zeebe:ioMapping>
+    </bpmn:extensionElements>
+  </bpmn:intermediateCatchEvent>
+
+  <bpmn:exclusiveGateway id="Gateway_CheckCount" default="Flow_Process">
+    <bpmn:sequenceFlow id="Flow_Loop" sourceRef="Gateway_CheckCount" targetRef="CatchEvent_Message">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=count(messages) &lt; 3</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="Flow_Process" sourceRef="Gateway_CheckCount" targetRef="Service_Process" />
+  </bpmn:exclusiveGateway>
+
+  <bpmn:serviceTask id="Service_Process" name="Process Aggregated Messages">
+    <bpmn:extensionElements>
+      <zeebe:taskDefinition type="process-aggregated" />
+      <zeebe:ioMapping>
+        <zeebe:input source="=messages" target="messages" />
+      </zeebe:ioMapping>
+    </bpmn:extensionElements>
+  </bpmn:serviceTask>
+
+  <bpmn:endEvent id="EndEvent_Complete" />
+</bpmn:process>
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/message-aggregation

package/.llms/chunks/components.concepts.message-aggregation.how-it-works.md

@@ -0,0 +1,15 @@
+# Message aggregation — How it works
+
+1. Each message is published with:
+   - A **message name** (for example, `"ItemReceived"`)
+   - A **correlation key** (for example, `"order-123"`)
+   - Optionally, a **time-to-live (TTL)** greater than `0`
+2. The first message starts a new process instance.
+3. All subsequent messages with the same correlation key are correlated to that instance.
+4. The workflow collects the message data (for example, appending to a list).
+5. Once all expected messages are received, the process continues.
+
+If additional messages with the same correlation key arrive after the process instance has completed, a new instance is created automatically.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/message-aggregation

package/.llms/chunks/components.concepts.message-aggregation.md

@@ -0,0 +1,24 @@
+# Message aggregation
+
+Learn how to collect and process multiple related messages in a single workflow instance using message correlation in Camunda 8.
+
+Use message aggregation to collect multiple related messages into a single process instance before proceeding to the next step of your workflow.
+
+
+## What message aggregation is
+
+Message aggregation is a message correlation pattern that allows you to receive, store, and process multiple messages belonging to the same business entity.
+
+It’s commonly used when:
+
+- You receive multiple events about a single entity (for example, shipments for the same order).
+- You need to wait for _N_ messages before proceeding.
+- You want to combine or "map-reduce" data across messages before continuing.
+
+Instead of creating a new process instance for each message, messages with the same **correlation key** are routed to the same instance.
+
+**Note**
+This guide applies to Camunda 8 (Zeebe). The message aggregation pattern requires understanding of [message correlation](https://docs.camunda.io/docs/next/components/concepts/messages#message-correlation-overview) and BPMN message events.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/message-aggregation

package/.llms/chunks/components.concepts.message-aggregation.troubleshooting.md

@@ -0,0 +1,11 @@
+# Message aggregation — Troubleshooting
+
+| Problem                                     | Cause                                                       | Solution                                                            |
+| ------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
+| Every message starts a new process instance | Missing or mismatched `correlationKey` in message variables | Ensure all messages use the same correlation key and name           |
+| Process never completes                     | The `count(messages)` condition is not met                  | Verify your condition and that messages are successfully correlated |
+| Messages not correlated                     | TTL expired or wrong message name                           | Use a TTL > 0 and match the BPMN message name exactly               |
+| Duplicate aggregation                       | The instance ended but more messages arrived                | This is expected — a new instance is started                        |
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/message-aggregation

package/.llms/chunks/components.concepts.messages.business-id-in-message-correlation.md

@@ -0,0 +1,57 @@
+# Messages — Business ID in message correlation
+
+Starting in Camunda 8.10, you can include a business ID in message publication and correlation. Business ID acts as an additional filter constraint on top of the message name and correlation key.
+
+### Supported combinations
+
+Message name is always required. The following additional fields are supported per event type:
+
+| Event type                                                       | Supported correlation fields                 |
+| :--------------------------------------------------------------- | :------------------------------------------- |
+| Start event                                                      | Message name                                 |
+| Start event                                                      | Message name + business ID                   |
+| Start event                                                      | Message name + correlation key               |
+| Start event                                                      | Message name + correlation key + business ID |
+| Non-start event (intermediate catch, boundary, event subprocess) | Message name + correlation key               |
+| Non-start event                                                  | Message name + correlation key + business ID |
+
+For non-start events, a business ID can only be used together with an existing correlation key. Business ID alone is not sufficient to correlate to a non-start subscription.
+
+When both a correlation key and a business ID are provided, the message correlates only if both fields match the corresponding values stored on the subscription.
+
+### Matching semantics
+
+A business ID on a message is an optional narrowing filter, on top of — never a replacement for — the correlation key. Matching is asymmetric between the two sides:
+
+| Message business ID | Subscription business ID | Correlates?                                      |
+| :------------------ | :----------------------- | :----------------------------------------------- |
+| Not set             | Not set                  | Yes — matches on name and correlation key alone. |
+| Not set             | Set                      | Yes — the subscription's business ID is ignored. |
+| Set                 | Not set                  | No.                                              |
+| Set                 | Set, same value          | Yes.                                             |
+| Set                 | Set, different value     | No.                                              |
+
+A message subscription snapshots the process instance's business ID at the time the subscription is opened.
+
+If a [late business ID assignment](https://docs.camunda.io/docs/next/components/concepts/process-instance-creation#late-business-id-assignment) updates a process instance after a subscription is already open, the existing subscription is not updated. Only subscriptions opened after the assignment carry the new business ID.
+
+### Message-start buffering with uniqueness
+
+When business ID uniqueness is enabled, a message-start event that would create a new instance with a business ID already held by an active instance is not dropped immediately. The message stays buffered and is retried until either:
+
+- The active instance releases the business ID (by completing or terminating), or
+- The message's TTL expires.
+
+If the TTL expires before the business ID is released, the message is discarded without starting a new instance.
+
+**Note**
+`TTL = 0` (fire-and-forget) message-start events are not retried. They activate on first arrival only and are discarded immediately if blocked by uniqueness.
+
+### API reference
+
+- [Publish message](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/publish-message.api) — `businessId` request field.
+- [Correlate message](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/correlate-message.api) — `businessId` request field.
+- [Search correlated message subscriptions](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-correlated-message-subscriptions.api) — `businessId` as a filter and sort field.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/messages

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

@@ -0,0 +1,52 @@
+# Messages
+
+Learn how process instances can respond to incoming messages.
+
+[Process instances](https://docs.camunda.io/docs/next/reference/glossary#process-instance) can respond to incoming [messages](https://docs.camunda.io/docs/next/reference/glossary#message). Published messages must be mapped onto a process instance. This step is called [message correlation](https://docs.camunda.io/docs/next/components/modeler/bpmn/message-events/message-events#message-correlation).
+
+
+## Message subscriptions
+
+A message is not sent to a process instance directly. Instead, the message correlation is based on subscriptions that contain the `message name` and the `correlation key` (also known as the correlation value).
+
+![Message Correlation](assets/message-correlation.png)
+
+A subscription is opened when a process instance awaits a message; for example, when entering a message catch event. The message name is defined either statically in the process (e.g. `Money collected`) or dynamically as an expression. The correlation key is defined dynamically as an expression (for example, `= orderId`). The expressions are evaluated on activating the message catch event. The results of the evaluations are used as message name and as correlation key of the subscription (e.g. `"order-123"`).
+
+**Note**
+Message names and correlation keys are subject to backend-dependent length limits. They support up to **32,768 characters** with Elasticsearch/OpenSearch-backed secondary storage and up to **256 characters** with RDBMS-backed secondary storage. Length is enforced using Java string length semantics, so the effective visible-character limit can be lower for characters represented as surrogate pairs in Java.
+
+When a message is published and the message name and correlation key match to a subscription, the message is correlated to the corresponding process instance. If no proper subscription is opened, the message is discarded.
+
+A subscription is closed when the corresponding element (e.g. the message catch event), or its scope is left. After a subscription is opened, it is not updated (for example, when the referenced process variable is changed.)
+
+   Publish message via Orchestration Cluster REST API
+   
+
+```
+curl -L 'http://localhost:8080/v2/messages/publication' \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json' \
+-d '{
+  "name": "Money collected",
+  "correlationKey": "order-123"
+}'
+```
+
+See the [API reference for publish message](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/publish-message.api) for more information, including additional request fields and code samples.
+When you require immediate feedback if the message was correlated to an open subscription, you can use `Correlate message` via Orchestration Cluster REST API. If correlation is successful it will return the first process instance key the message correlated with.
+
+```
+curl -L 'http://localhost:8080/v2/messages/correlation' \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json' \
+-d '{
+"name": "Money collected",
+"correlationKey": "order-123"
+}'
+```
+
+See the [API reference for correlate message](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/correlate-message.api) for more information, including additional request fields and code samples.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/messages