@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.embracing-business-transactions-and-eventual-consistency-business-strategies-to-handle-inconsistency.md

@@ -0,0 +1,12 @@
+# Dealing with problems and exceptions — Embracing business transactions and eventual consistency — Business strategies to handle inconsistency
+
+There are three basic strategies if a consistency problem occurs:
+
+- Ignore it. While it sounds strange to consider ignoring a consistency issue, it actually can be a valid strategy. It’s a question of how much business impact the inconsistency may have.
+- Apologize. This is an extension of the strategy to ignore. You don’t try to prevent inconsistencies, but you do make sure that you apologize when their effects come to light.
+- Resolve it. Tackle the problem head-on and actively resolve the inconsistency. This could be done by different means, such as the reconciliation jobs mentioned earlier, but this practice focuses on how BPMN can help by looking into the Saga pattern.
+
+Selecting the right strategy is a clear business decision, as none of them are right or wrong, but simply more or less well suited to the situation at hand. You should always think about the cost/value ratio.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.embracing-business-transactions-and-eventual-consistency-eventual-consistency.md

@@ -0,0 +1,8 @@
+# Dealing with problems and exceptions — Embracing business transactions and eventual consistency — Eventual consistency
+
+It is important to be aware that these temporary inconsistencies are possible. You also have to understand the failure scenarios they can cause. In the above example, you could have created a marketing campaign at a moment when a customer was already in the CRM system, but not yet in billing, so they got included in that list. Then, even if their order gets rejected and they never end up as an active customer, they might still receive an upgrade advertisement.
+
+You need to understand the effects of this happening. Furthermore, you have to think about a strategy to resolve inconsistencies. The term **eventual consistency** suggests that you need to take measures to get back to a consistent state eventually. In the onboarding example, this could mean you need to deactivate the customer in the CRM system if adding them to the billing system fails. This leads to the consistent state that the customer is not visible in any system anymore.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.embracing-business-transactions-and-eventual-consistency-technical-vs-business-transactions.md

@@ -0,0 +1,16 @@
+# Dealing with problems and exceptions — Embracing business transactions and eventual consistency — Technical vs business transactions
+
+Applications using databases can often leverage ACID (atomic, consistent, isolated, durable) capabilities of that database. This means that some business logic is either successfully committed as a whole, or rolled back completely in case of any error. It is normally referred to as "transactions".
+
+Those ACID transactions cannot be applied to distributed systems (the talk [lost in transaction](https://www.youtube.com/watch?v=WRR26jJNh68) elaborates on this), so if you call out to multiple services from a process, you end up with separate ACID transactions at play. The following illustrations are taken from the O'Reilly book [Practical Process Automation](https://processautomationbook.com/):
+
+![Multiple ACID transactions](dealing-with-problems-and-exceptions-assets/multiple-acid-transactions.png)
+
+In the above example, the CRM system and the billing system have their local ACID transactions. The workflow engine itself also runs transactional. However, there cannot be a joined technical transaction. This requires a new way of dealing with consistency on the business level, which is referred to as **business transaction**:
+
+![Businss vs technical transaction](dealing-with-problems-and-exceptions-assets/business-vs-technical-transaction.png)
+
+A **business transaction** marks a section in a process for which 'all or nothing' semantics (similar to a technical transaction) should apply, but from a business perspective. You might encounter inconsistent states in between (for example a new customer being present in the CRM system, but not yet in the billing system).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.embracing-business-transactions-and-eventual-consistency-the-saga-pattern-and-bpmn-compensation.md

@@ -0,0 +1,33 @@
+# Dealing with problems and exceptions — Embracing business transactions and eventual consistency — The Saga pattern and BPMN compensation
+
+The Saga pattern describes long-running transactions in distributed systems. The main idea is simple: when you can’t roll back tasks, you undo them. (The name Saga refers back to a paper written in the 1980s about long-lived transactions in databases.)
+
+Camunda supports this through BPMN compensation events, which can link tasks with their undo tasks.
+
+Diagram (BPMN):
+  start "Customer order received" → parallel gateway
+    — service task "Add customer to CRM system" → parallel gateway → service task "Provision SIM card" → service task "Register SIM in network" → end "Customer order processed"
+    — service task "Add customer to billing system" → (back to parallel gateway)
+
+**(1)**
+
+Assume the customer was already added to the CRM system...
+
+**(2)**
+
+...when an error occurred...
+
+**(3)**
+
+...the process triggers the compensation to happen. This will roll back the business transaction.
+
+**(4)**
+
+All compensating activities of successfully completed tasks will be executed, in this case also this one.
+
+**(5)**
+
+As a result, the customer will be deactivated, as the API of the CRM system might not allow to simply delete it.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-errors-on-the-process-level-business-vs.-technical-errors.md

@@ -0,0 +1,17 @@
+# Dealing with problems and exceptions — Handling errors on the process level — Business vs. technical errors
+
+Note that you have two different ways of dealing with problems at your disposal now:
+
+- **Retrying**. You don't want to model the retrying, as you would have to add it to each and every service task. This will bloat the visual model and confuse business personnel. Instead, either retry or fall back to incidents as described above. This is hidden in the visual.
+- Branch out **separate paths**, as described with the error event.
+
+In this context, we found the terms **business error** and **technical error** can be confusing, as they emphasize the source of the error too much. This can lead to long discussions about whether a certain problem is technical or not, and if you are allowed to observe technical errors in a business process model.
+
+It's much more important to look at how you react to certain errors. Even a technical problem can qualify for a business reaction. In the above example, upon technical problems with the invoice service you can decide to manually send the invoice (business reaction) or to retry until the invoice service becomes available again (technical reaction).
+
+Or, for example, you could decide to continue a process in the event that a scoring service is not available, and simply give every customer a good rating instead of blocking progress. The error is clearly technical, but the reaction is a business decision.
+
+In general, we recommend talking about business reactions, which are modeled in your process, and technical reactions, which are handled generically using retries or incidents.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-errors-on-the-process-level-distinguishing-between-exceptions-and-results.md

@@ -0,0 +1,27 @@
+# Dealing with problems and exceptions — Handling errors on the process level — Distinguishing between exceptions and results
+
+As an alternative to throwing a Java exception, you can also write a problematic result into a process variable and model an XOR-Gateway later in the process flow to take a different path if that problem occurs.
+
+From a business perspective, the underlying problem then looks less like an error and more like a result of an activity, so as a rule of thumb we deal with _expected results_ of activities by means of gateways, but model exceptional errors, which _hinder us in reaching the expected result_ as boundary error events.
+
+Diagram (BPMN):
+  start "Order received" → "Check order completeness" → exclusive gateway "Order complete?"
+    — [Yes: =complete] "Check customer's credit-worthiness" → exclusive gateway "Customer credit-worthy?"
+      — [Yes: =creditWorthy] "Determine delivery date" → exclusive gateway → "Fax order confirmation" → end "Order confirmed"
+      — [No: =not(creditWorthy)] exclusive gateway → end "Order declined"
+    — [No: =not(complete)] (back to exclusive gateway)
+
+**(1)**
+
+The task is to "check the customer's credit-worthiness", so we can reason that we _expect as a result_ to know whether the customer is credit-worthy or not.
+
+**(2)**
+
+We can therefore model an _exclusive gateway_ working on that result and decide via the subsequent process flow what to do with a customer who is not credit-worthy. Here, we just consider the order to be declined.
+
+**(3)**
+
+However, it could be that we _cannot reach a result_, because while we are trying to obtain knowledge about the customer's creditworthiness, we discover that the ID we have is not associated with any known real person. We can't obtain the expected result and therefore model a _boundary error event_. In the example, the consequence is just the same and we consider the order to be declined.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-errors-on-the-process-level-thinking-about-unhandled-bpmn-exceptions.md

@@ -0,0 +1,15 @@
+# Dealing with problems and exceptions — Handling errors on the process level — Thinking about unhandled BPMN exceptions
+
+It is crucial to understand that if a BPMN error is not handled anywhere in the process, Camunda 8 raises an [incident](https://docs.camunda.io/docs/next/components/concepts/incidents) (for example, `Unhandled error event`) instead of silently terminating the process instance. Therefore, you can and normally should always handle the BPMN error. You can, of course, also handle it in a parent process scope like in the example below:
+
+Diagram (BPMN):
+  start "Order received" → "Get good from stock" → exclusive gateway "Good in stock?"
+    — [No: =not(inStock)] call activity "Purchase" → exclusive gateway → "Deliver good" → end "Order delivered"
+    — [Yes: =inStock] (back to exclusive gateway)
+
+**(1)**
+
+The boundary error event deals with the case that the item is unavailable.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-errors-on-the-process-level-throwing-and-handling-bpmn-errors.md

@@ -0,0 +1,28 @@
+# Dealing with problems and exceptions — Handling errors on the process level — Throwing and handling BPMN errors
+
+In BPMN process definitions, we can explicitly model an end event as an error.
+
+Diagram (BPMN):
+  start "Good to be purchased" → "Order good" → exclusive gateway "Good available?"
+    — [Yes: =available] intermediate catch event "Good received" → end "Good purchased"
+    — [No: =not(available)] end "Good unavailable"
+
+**(1)**
+
+In case the item is not available, we finish the process with an **error end event**.
+
+**Note**
+You can mimic a BPMN error in your glue code by using the [`ThrowError`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#throwerror-rpc) API. The consequences for the process are the same as if it were an explicit error end event. So, in case your 'purchase' activity is not a subprocess, but a service task, it could throw a BPMN Error informing the process that the good is unavailable.
+
+Example in Java:
+
+```java
+jobClient.newThrowErrorCommand(job)
+   .errorCode("GOOD_UNAVAILABLE")
+   .errorMessage()
+   .send()
+   .exceptionally(t -> {throw new RuntimeException("Could not throw BPMN error: " + t.getMessage(), t);});
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-errors-on-the-process-level-using-bpmn-error-events.md

@@ -0,0 +1,19 @@
+# Dealing with problems and exceptions — Handling errors on the process level — Using BPMN error events
+
+A common way to resolve these deviations is using a BPMN error event, which allows a process model to react to errors within a task. For example:
+
+Diagram (BPMN):
+  start "..." → user task "Provide shipping address" → service task "Generate invoice" → service task "Send invoice to customer" → exclusive gateway → intermediate catch event "Wait until next business day" → "..." → end "..."
+
+**(1)**
+
+We decide that we want to deal with an exception in the process: in case the invoice cannot be sent automatically...
+
+**(2)**
+
+...we assign a task to a human user, who is now in charge of taking care of delivering the invoice.
+
+Learn more about the usage of [error events](https://docs.camunda.io/docs/next/components/modeler/bpmn/error-events/error-events) in the user guide.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-errors-on-the-process-level.md

@@ -0,0 +1,6 @@
+# Dealing with problems and exceptions — Handling errors on the process level
+
+You often encounter deviations from the "happy path" (the default scenario with a positive outcome) which shall be modeled in the process model.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-exceptions-on-a-technical-level-leveraging-retries.md

@@ -0,0 +1,51 @@
+# Dealing with problems and exceptions — Handling exceptions on a technical level — Leveraging retries
+
+Using the [`FailJob `](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#failjob-rpc) API is pretty handy to leverage the built-in retry mechanism of Zeebe. The initial number of retries is set in the BPMN process model:
+
+```xml
+    <bpmn:serviceTask id="TaskRetrieveMoney">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition retries="5" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+```
+
+This number is typically decremented with every attempt to execute the service task. Note that you need to do that in your worker code. Example in Java:
+
+```java
+  @JobWorker(type = "retrieveMoney", autoComplete = false)
+  public void retrieveMoney(final JobClient client, final ActivatedJob job) {
+    try {
+        // your code
+    } catch (Exception ex) {
+        jobClient.newFailCommand(job)
+          .retries(job.getRetries()-1) // <1>: Decrement retries
+          .errorMessage("Could not retrieve money due to: " + ex.getMessage()) // <2>
+          .send()
+          .exceptionally(t -> {throw new RuntimeException("Could not fail job: " + t.getMessage(), t);});
+    }
+  }
+```
+
+**(1)**
+
+Decrement the retries by one.
+
+**(2)**
+
+Provide a meaningful error message, as this will be displayed to a human operator once an incident is created in Operate.
+
+Example in Node.js:
+
+```js
+zbc.createWorker("retrieveMoney", (job) => {
+  try {
+    // ...
+  } catch (e) {
+    job.fail("Could not retrieve money due to: " + e.message, job.retries - 1);
+  }
+});
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-exceptions-on-a-technical-level-using-incidents.md

@@ -0,0 +1,8 @@
+# Dealing with problems and exceptions — Handling exceptions on a technical level — Using incidents
+
+Whenever a job fails with a retry count of `0`, an incident is raised. An incident requires human intervention, typically using Operate. Refer to [incidents in the Operate docs](https://docs.camunda.io/docs/next/components/operate/userguide/resolve-incidents-update-variables).
+
+For example, this behavior also applies to tools called by an AI agent. Each tool the agent selects runs as an ordinary BPMN activity, so retries and incidents work as described above. See [how the feedback loop works](https://docs.camunda.io/docs/next/components/agentic-orchestration/ai-agents#how-the-feedback-loop-works).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.handling-exceptions-on-a-technical-level-writing-idempotent-workers.md

@@ -0,0 +1,22 @@
+# Dealing with problems and exceptions — Handling exceptions on a technical level — Writing idempotent workers
+
+Zeebe uses the **at-least-once strategy** for job handlers, which is a typical choice in distributed systems. This means that the process instance only advances in the happy case (the job was completed, the workflow engine received the complete job request and committed it). A typical failure case occurs when the worker who polled the job crashes and cannot complete the job anymore. [In this case, the workflow engine gives the job to another worker after a configured timeout](https://docs.camunda.io/docs/next/components/concepts/job-workers#timeouts). This ensures that the job handler is executed at least once.
+
+But this can mean that the handler is executed more than once! You need to consider this in your handler code, as the handler might be called more than one time. The [technical term describing this is idempotency](https://en.wikipedia.org/wiki/Idempotence).
+
+For example, typical strategies are described in [3 common pitfalls in microservice integration — and how to avoid them](https://blog.bernd-ruecker.com/3-common-pitfalls-in-microservice-integration-and-how-to-avoid-them-3f27a442cd07). One possibility is to ask the service provider if it has already seen the same request. A more common approach is to implement the service provider in a way that allows for duplicate calls. There are two ways of mastering this:
+
+- **Natural idempotency**. Some methods can be executed as often as you want because they just flip some state. Example: `confirmCustomer()`.
+- **Business idempotency**. Sometimes you have business identifiers that allow you to detect duplicate calls (e.g. by keeping a database of records that you can check). Example: `createCustomer(email)`.
+
+If these approaches do not work, you will need to add a **custom idempotency handling** by using unique IDs or hashes. For example, you can generate a unique identifier and add it to the call. This way, a duplicate call can be easily spotted if you store that ID on the service provider side. If you leverage a workflow engine you probably can let it do the heavy lifting. Example: `charge(transactionId, amount)`.
+
+See this snippet of a process about how to support custom idempotency handling in a process model:
+
+Diagram (BPMN):
+  service task "Create transaction id" → service task "Charge credit card"
+
+Whatever strategy you use, make sure that you’ve considered idempotency consciously.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.dealing-with-problems-and-exceptions.md

@@ -0,0 +1,38 @@
+# Dealing with problems and exceptions
+
+Take a closer look at understanding workers, handling exceptions on a technical level, leveraging retries, using incidents, and more.
+
+
+## Understanding workers
+
+**Caution: Camunda 8 only**
+The description of workers targets Camunda 8, even if [external tasks in Camunda 7](https://docs.camunda.org/manual/latest/user-guide/process-engine/external-tasks/) are conceptually similar.
+
+First, let's briefly examine how a worker operates.
+
+Whenever a process instance arrives at a service task, a new job is created and pushed to an internal persistent queue within Camunda 8. A client application can subscribe to these jobs with the workflow engine by the task type name (which is comparable to a queue name).
+
+If there is no worker subscribed when a job is created, the job is simply put in a queue. If multiple workers are subscribed, they are competing consumers, and jobs are distributed among them.
+
+![Worker concept](dealing-with-problems-and-exceptions-assets/worker-concept.png)
+
+Whenever the worker has finished whatever it needs to do (like invoking the REST endpoint), it sends another call to the workflow engine, which [can be one of these three](https://docs.camunda.io/docs/next/components/concepts/job-workers#completing-or-failing-jobs):
+
+- [`CompleteJob`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#completejob-rpc): The service task went well, the process instance can move on.
+- [`FailJob `](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#failjob-rpc): The service task failed, and the workflow engine should handle this failure. There are two possibilities:
+  - `remaining retries > 0`: The job is retried.
+  - `remaining retries <= 0`: An [incident](https://docs.camunda.io/docs/next/components/concepts/incidents) is raised and the job is not retried until the incident is resolved.
+- [`ThrowError`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#throwerror-rpc): A BPMN error is reported, which typically is handled on the BPMN level.
+
+As the glue code in the worker is external to the workflow engine, there is **no technical transaction spanning both components**. Technical transactions refer to ACID (atomic, consistent, isolated, durable) properties, mostly known from relational databases.
+
+If, for example, your application leverages those capabilities, your business logic is either successfully committed as a whole, or rolled back completely in case of any error. However, those ACID transactions cannot be applied to distributed systems (the talk [lost in transaction](https://www.youtube.com/watch?v=WRR26jJNh68) elaborates on this). In other words, things can get out of sync if either the job handler or the workflow engine fails.
+
+A typical example scenario is the following, where a worker calls a REST endpoint to invoke business logic:
+
+![Typical call chain](dealing-with-problems-and-exceptions-assets/typical-call-chain.png)
+
+Technical ACID transaction will only be applied in the business application. The job worker mostly needs to handle exceptions on a technical level, e.g. to control retry behavior, or pass it on to the process level, where you might need to implement business transactions.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions

package/.llms/chunks/components.best-practices.development.handling-data-in-processes.complex-data-as-entities.md

@@ -0,0 +1,18 @@
+# Handling data in processes — Complex data as entities
+
+There are some use cases when it is clever to _introduce entities alongside the process_ to store complex data in a relational database. You can observe this logically as _typed process context_ where you create custom tables for your custom process deployment. Then, you can even use **Data** **Accessor** classes to access these entities in a convenient way.
+
+You will only store a reference to the entity's primary key (typically an artificial UUID) as real process variable within Camunda.
+
+Some people refer to this as **externalized process context**.
+
+There are a couple of advantages of this approach:
+
+- You can do very _rich queries_ on structured process variables via typical SQL.
+- You can apply custom _data migration strategies_ when deploying new versions of your process or services, which require data changes.
+- Data can be designed and modeled properly, even graphically by, for example, leveraging UML.
+
+It requires additional complexity by adding the need for a relational database and code to handle this.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/handling-data-in-processes

package/.llms/chunks/components.best-practices.development.handling-data-in-processes.md

@@ -0,0 +1,10 @@
+# Handling data in processes
+
+When using Camunda, you have access to a dynamic map of process variables, which lets you associate data to every single process instance.
+
+When using Camunda, you have access to a dynamic map of process variables, which lets you associate data to every single process instance (and local scopes in case of user tasks or parallel flows). Ensure you use these mechanisms in a lightweight and meaningful manner, storing just the relevant data in the process instance.
+
+Depending on your programming language, consider accessing your process variables in a type safe way, centralizing (simple and complex) type conversion and using constants for process variable names.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/handling-data-in-processes

package/.llms/chunks/components.best-practices.development.handling-data-in-processes.storing-just-the-relevant-data.md

@@ -0,0 +1,45 @@
+# Handling data in processes — Storing just the relevant data
+
+Do not excessively use process variables. Process variables are subject to [size limitations](https://docs.camunda.io/docs/next/components/concepts/variables#variable-size-limitation), so as a rule of thumb, store _as few variables as possible_ within Camunda.
+
+Keep this limitation in mind when designing your BPMN processes. For example, an AI agent’s context is stored in a process variable by default and counts toward this size limit. Alternatively, you can store the conversation in document storage. See [choose a memory storage backend](https://docs.camunda.io/docs/next/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess#choose-a-memory-storage-backend).
+
+### Storing references only
+
+If you have leading systems already storing the business relevant data...
+
+![Hold references only](handling-data-in-processes-assets/hold-references-only.svg)
+
+...then we suggest you store references only (e.g. ID's) to the objects stored there. So instead of holding the `tweet` and the `approved` variable, the process variables would now, for example, look more like the following:
+
+| Variable name | Variable type | Value |
+| ------------- | ------------- | ----- |
+| `tweetId`     | Long          | 8213  |
+
+### Use cases for storing payload
+
+Store _payload_ (actual business data) as process variables, if you....
+
+- ...have data only of interest within the process itself (e.g. for gateway decisions).
+
+In case of the tweet approval process, even if you are using a tweet domain object, it might still be meaningful to hold the approved value explicitly as a process variable, because it serves the purpose to guide the gateway decision in the process. It might not be true if you want to keep track in the tweet domain objects regarding the approval.
+
+| Variable name | Variable type | Value |
+| ------------- | ------------- | ----- |
+| `tweetId`     | Long          | 8213  |
+| `approved`    | Boolean       | true  |
+
+- ...communicate in a _message oriented_ style. For example, retrieving data from one system and handing it over to another system via a process.
+
+When receiving external messages, consider storing just those parts of the payload relevant for you, and not the whole response. This not only serves the goal of having a lean process variables map, it also makes you more independent of changes in the service's message interface.
+
+- ...want to use the process engine as kind of _cache_. For example, you cannot query relevant customer data in every step for performance reasons.
+
+- ...need to _postpone data changes_ in the leading system to a later step in the process. For example, you only want to insert the Tweet in the Tweet Management Application if it is approved.
+
+- ...want to track the _historical development_ of the data going through your process.
+
+- ...don't have a leading system for this data.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/handling-data-in-processes

package/.llms/chunks/components.best-practices.development.handling-data-in-processes.understanding-data-handling-in-camunda.md

@@ -0,0 +1,62 @@
+# Handling data in processes — Understanding data handling in Camunda
+
+When reading and interpreting a business process diagram, you quickly realize there is always data necessary for tasks, but also to drive the process through gateways to the correct next steps.
+
+Examine the following tweet approval process example:
+
+Diagram (BPMN): TwitterDemoProcess
+  start "New Tweet written" → user task "Review tweet" → exclusive gateway "Tweet approved?"
+    — [Yes: =approved] service task "Publish on Twitter" → end "Tweet published"
+    — [No: =not(approved)] service task "Send rejection notification" → end "Tweet rejected"
+
+**(1)**
+
+The process instance starts with a freshly written `tweet` we need to remember.
+
+**(2)**
+
+We need to present this `tweet` so that the user can decide whether to `approve` it.
+
+**(3)**
+
+The gateway needs to have access to this information: was the tweet `approved`?
+
+**(4)**
+
+To publish the tweet, the service task again needs the `tweet` itself!
+
+Therefore, the tweet approval process needs two variables:
+
+| Variable name | Variable type | Sample value     |
+| ------------- | ------------- | ---------------- |
+| `tweet`       | String        | "@Camunda rocks" |
+| `approved`    | Boolean       | true             |
+
+In Camunda 8, [values are stored as JSON](https://docs.camunda.io/docs/next/components/concepts/variables#variable-values).
+
+**Caution: Camunda 7 handles variables slightly differently**
+This best practice describes variable handling within Camunda 8. Process variables are handled slightly differently with Camunda 7. Consult the [Camunda 7 documentation](https://docs.camunda.org/manual/latest/user-guide/process-engine/variables/) for details. In essence, variable values are not handled as JSON and thus there are [different values](https://docs.camunda.org/manual/latest/user-guide/process-engine/variables/#supported-variable-values) supported.
+
+You can dynamically create such variables by assigning an object of choice to a (string typed) variable name; for example, by passing a `Map<String, Object>` when [completing](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/complete-user-task.api) the "Review tweet" task via the API:
+
+```
+// TODO: Double check!
+completeTask(
+    taskId: "547811"
+    variables: [
+        {
+            name: "approved"
+            value: true
+        }
+    ]
+)
+```
+
+In Camunda, you do _not_ declare process variables in the process model. This allows for a lot of flexibility. Refer to recommendations below on how to overcome possible disadvantages of this approach.
+
+Consult the [docs about variables](https://docs.camunda.io/docs/next/components/concepts/variables#variable-values) to learn more.
+
+Camunda does not treat BPMN **data objects** () as process variables. We recommend using them occasionally _for documentation_, but you need to [avoid excessive usage of data objects](https://docs.camunda.io/docs/next/components/best-practices/modeling/creating-readable-process-models#avoiding-excessive-usage-of-data-objects).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/handling-data-in-processes

package/.llms/chunks/components.best-practices.development.handling-data-in-processes.using-constants-and-data-accessors.md

@@ -0,0 +1,62 @@
+# Handling data in processes — Using constants and data accessors
+
+Avoid the copy/paste of string representations of your process variable names across your code base. Collect the variable names for a process definition in _constants_. For example, in Java:
+
+```java
+public interface TwitterDemoProcessConstants {
+  String VAR_NAME_TWEET = "tweet";
+  String VAR_NAME_APPROVED = "approved";
+}
+```
+
+This way, you have much more security against typos and can easily make use of refactoring mechanisms offered by your IDE.
+
+However, if you also want to solve necessary type conversions (casting) or probably even complex serialization logic, we recommend that you use a **Data Accessor** class. It comes in two flavors:
+
+- A **Process Data Accessor**: Knows the names and types of all process variables of a certain process definition. It serves as the central point to declare variables for that process.
+- A **Process Variable Accessor**: Encapsulates the access to exactly one variable. This is useful if you reuse certain variables in different processes.
+
+Consider, for example, the BPMN "Publish on Twitter" task in the Tweet Approval Process:
+
+Diagram (BPMN): TwitterDemoProcess
+  start "New Tweet written" → user task "Review tweet" → exclusive gateway "Tweet approved?"
+    — [Yes: =approved] service task "Publish on Twitter" → end "Tweet published"
+    — [No: =not(approved)] service task "Send rejection notification" → end "Tweet rejected"
+
+**(1)**
+
+We use a **TweetPublicationDelegate** to implement the "Publish on Twitter" task:
+
+```java
+public class PublishTweetJobHandler implements JobHandler  {
+    public void handle(JobClient client, ActivatedJob job) throws Exception {
+        String tweet = job.getVariablesAsType(TwitterDemoProcessVariables.class).getTweet();
+        // ...
+```
+
+The `tweet` variable is accessed in a type safe way.
+
+This reusable **Process Data Accessor** class could, for example, be a simple object. The Java client API can automatically deserialize the process variables as JSON into this object, while all process variables that are not found in that class are ignored.
+
+```java
+public class TwitterDemoProcessVariables {
+
+    private String tweet;
+    private boolean approved;
+
+    public String getTweet() {
+        return tweet;
+    }
+
+    public void setTweet(String tweet) {
+        this.tweet = tweet;
+    }
+}
+```
+
+The getters and setters could further take care of additional serialization and deserialization logic for complex objects.
+
+Your specific implementation approach might differ depending on the programming language and framework you are using.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/handling-data-in-processes

package/.llms/chunks/components.best-practices.development.local-development-with-element-templates.configure-element-templates-in-desktop-modeler.md

@@ -0,0 +1,13 @@
+# Local development with element templates and Camunda 8 Run — Configure element templates in Desktop Modeler
+
+To make your element templates available in Desktop Modeler, see the [configuration guide](https://docs.camunda.io/docs/next/components/modeler/desktop-modeler/element-templates/configuring-templates).
+
+
+## Additional resources and next steps
+
+- [Using element templates in Desktop Modeler](https://docs.camunda.io/docs/next/components/modeler/desktop-modeler/element-templates/using-templates)
+- [Run your first local Camunda 8 project](https://docs.camunda.io/docs/next/guides/getting-started-example)
+- [Available connectors](https://docs.camunda.io/docs/next/components/connectors/out-of-the-box-connectors/available-connectors-overview)
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/local-development-with-element-templates

package/.llms/chunks/components.best-practices.development.local-development-with-element-templates.md

@@ -0,0 +1,17 @@
+# Local development with element templates and Camunda 8 Run
+
+Learn how to use Camunda 8 Run with element templates in your local development environment.
+
+When working with [element templates](https://docs.camunda.io/docs/next/components/concepts/element-templates) in your local development environment using [Camunda 8 Run with Docker Compose](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/c8run), ensure all dependencies are provisioned before you start.
+
+This guide explains how to set up element templates in your local environment.
+
+
+## Prerequisites
+
+- [Camunda 8 Run](https://docs.camunda.io/docs/next/self-managed/quickstart/developer-quickstart/c8run) installed on your local machine.
+- Basic knowledge of [element templates with dependencies](https://docs.camunda.io/docs/next/components/modeler/element-templates/element-template-with-dependencies).
+- Familiarity with [custom connectors](https://docs.camunda.io/docs/next/components/connectors/manage-connector-templates).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/local-development-with-element-templates

package/.llms/chunks/components.best-practices.development.local-development-with-element-templates.provisioning-a-custom-connector-runtime.md

@@ -0,0 +1,27 @@
+# Local development with element templates and Camunda 8 Run — Provisioning a custom connector runtime
+
+You can add a custom connector runtime to Camunda 8 Run by copying the `.jar` file containing all connector dependencies into the `custom_connectors` directory in the root folder of your Camunda 8 Run setup.
+
+This guide uses a generic [connector template](https://github.com/camunda/connector-template-outbound) as a reference.
+
+1. Clone the repository and run the following command to generate a deployable file:
+
+   ```bash
+   mvn clean verify package
+   ```
+
+This command creates a file named `target/connector-template-0.1.0-SNAPSHOT-with-dependencies.jar`.
+
+2. Copy the `.jar` file into the `custom_connectors` directory.
+3. Start Camunda 8 Run with Docker Compose. For example, from the Docker Compose directory in your Camunda 8 Run setup, run:
+
+```bash
+docker compose up -d
+```
+
+4. Your connector is ready to execute jobs when a process references it.
+
+If you use a different [connector runtime environment](https://docs.camunda.io/docs/next/components/connectors/custom-built-connectors/connector-sdk#runtime-environments), ensure that secrets are also exposed to that runtime.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/local-development-with-element-templates