@bpmnkit/camunda-docspack 0.0.0

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

@@ -0,0 +1,48 @@
+# Local development with element templates and Camunda 8 Run — Provisioning other dependencies
+
+### Using Desktop Modeler
+
+Deploy element template dependencies using [Desktop Modeler](https://docs.camunda.io/docs/next/components/modeler/desktop-modeler/index) by following the [self-managed deployment guide](https://docs.camunda.io/docs/next/self-managed/components/modeler/desktop-modeler/deploy-to-self-managed).
+
+This process applies to BPMN diagrams, forms, DMN diagrams, and RPA scripts.
+
+### Using the Cluster API
+
+For an automated approach, write scripts that use the [Orchestration Cluster REST API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview) to deploy dependencies.
+
+To deploy additional dependencies—such as forms, DMN diagrams, or subprocesses—send a [POST request](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-deployment.api) with the relevant files.
+
+For example:
+
+```
+
+curl -L 'http://localhost:8080/v2/deployments' \
+-H 'Accept: application/json' \
+-F resources=@/pathToYourForm/user-signup.form
+
+```
+
+You will get a response containing the details of the deployed elements:
+
+```json
+{
+  "deployments": [
+    {
+      "form": {
+        "formKey": "KEY_OF_THE_FORM",
+        "formId": "user-signup",
+        "version": 1,
+        "resourceName": "user-signup.form",
+        "tenantId": "<default>"
+      }
+    }
+  ],
+  "deploymentKey": "KEY_OF_THE_DEPLOYMENT",
+  "tenantId": "<default>"
+}
+```
+
+You can use element templates that reference the `user-signup.form`.
+
+---
+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-secrets.md

@@ -0,0 +1,27 @@
+# Local development with element templates and Camunda 8 Run — Provisioning secrets
+
+If your element templates use secrets, you must provide these values to the connector runtime.
+
+Add secrets to the `connector-secrets.txt` file in the root directory of your Camunda 8 Run setup. Use the following format, with one secret per line:
+
+```
+NAME=VALUE
+```
+
+These secrets will then be available in the connector runtime using the format `secrets.NAME`.
+
+For example:
+
+```
+MY_TOKEN=value
+AWS_KEY=keyValue
+...
+```
+
+In this case, the `MY_TOKEN` secret can be referenced as `secrets.MY_TOKEN`.
+
+This applies when custom connectors are deployed as part of the Camunda 8 Run Docker Compose setup.
+If you choose to run connectors differently, as described in the [custom connector hosting guide](https://docs.camunda.io/docs/next/components/connectors/custom-built-connectors/host-custom-connector#wiring-your-connector-with-a-camunda-cluster), configure secrets as environment variables instead.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/local-development-with-element-templates

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.choosing-the-right-bpmn-event-intermediate-events.md

@@ -0,0 +1,26 @@
+# Routing events to processes — Choosing the right BPMN event — Intermediate events
+
+Several BPMN intermediate events (and the receive task) can be used to make a process instance _wait_ for and _react_ to certain triggers.
+
+|                         | Message Event                                                                | Receive Task                                                                                    | Timer Event                                                                    | Signal Event                                                              | Conditional Event                                                            |
+| ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+|                         | ![message intermediate](/img/bpmn-elements/message-intermediate.svg)         | ![task receive](/img/bpmn-elements/task-receive.svg)                                            | ![timer intermediate](/img/bpmn-elements/timer-intermediate.svg)               | ![signal intermediate](/img/bpmn-elements/signal-intermediate.svg)        | ![conditional intermediate](/img/bpmn-elements/conditional-intermediate.svg) |
+| Use when                | You route an incoming **message** to a specific and unique process instance. | As alternative to message events (to leverage BPMN boundary events, for example, for timeouts). | You want to make your process instance wait for a certain (point in) **time**. | You route an incoming **signal** to all process instances waiting for it. | When a specific **condition** is met, the waiting process instance moves on. |
+| Supported for Execution | ✔                                                                            | ✔                                                                                               | ✔                                                                              | ✔                                                                         | Not yet supported in Camunda 8                                               |
+|                         | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/message-events/message-events)      | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/receive-tasks/receive-tasks)                           | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/timer-events/timer-events)            | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/signal-events/signal-events)     |                                                                              |
+
+Consider this example:
+
+Diagram (BPMN):
+  start "Order received" → "Send order confirmation" → intermediate catch event "Payment received" → call activity "Order fulfillment" → end "Order fulfilled"
+
+**(1)**
+
+This intermediate message event causes the process instance to wait unconditionally for a _specific_ event...
+
+**(2)**
+
+...whereas the intermediate message event attached to the boundary of an activity waits for an _optional_ event, potentially arriving while we are occupied with the activity.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.choosing-the-right-bpmn-event-start-events.md

@@ -0,0 +1,32 @@
+# Routing events to processes — Choosing the right BPMN event — Start events
+
+Several BPMN start events can be used to start a new process instance.
+
+|                         | None Event                                                                    | Message Event                                                           | Timer Event                                                            | Signal Event                                                          | Conditional Event                                                                |
+| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+|                         | ![none start](/img/bpmn-elements/none-start.svg)                              | ![message start](/img/bpmn-elements/message-start.svg)                  | ![timer start](/img/bpmn-elements/timer-start.svg)                     | ![signal start](/img/bpmn-elements/signal-start.svg)                  | ![conditional start](/img/bpmn-elements/conditional-start.svg)                   |
+| Use when                | You have only **one start event** or a start event which is clearly standard. | You have to differentiate **several start events**.                     | You want to automatically start process instances **time controlled**. | You need to start **several process instances** at once. Rarely used. | When a specific **condition** is met, a process instance is created.             |
+| Supported for Execution | ✔                                                                             | ✔                                                                       | ✔                                                                      | ✔                                                                     | Determine occurrence of condition externally yourself and use the message event. |
+|                         | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/none-events/none-events)             | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/message-events/message-events) | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/timer-events/timer-events)    | [Learn more](https://docs.camunda.io/docs/next/components/modeler/bpmn/signal-events/signal-events) |                                                                                  |
+
+Diagram (BPMN): TwitterDemoProcess
+  start "New Tweet written" → exclusive gateway → 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"
+  start "Tweet suggested by robot" → user task "Formulate tweet" → (back to exclusive gateway)
+  start "Tweet received by legacy adapter" → service task "Transform tweet data" → (back to exclusive gateway)
+
+**(1)**
+
+This none start event indicates the typical starting point. Note that only _one_ such start event can exist in one process definition.
+
+**(2)**
+
+This message start event is defined to react to a specific message type...
+
+**(3)**
+
+...hence you can have _multiple_ message start events in a process definition. In this example, both message start events seems to be exceptional cases - for equivalent cases we recommend to just use message instead of none start events.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.handling-messages-sent-by-a-user.md

@@ -0,0 +1,28 @@
+# Routing events to processes — Handling messages sent by a user
+
+Sometimes explicit "user tasks" are not an appropriate choice to involve a human user to participate in a process: the user does not want to observe a task in Tasklist, but rather have the possibility to actively trigger some action right at the time when it becomes necessary from a business perspective. The difference is which event gives the _active trigger_.
+
+Diagram (BPMN): Payment (Manager)
+  start "Daily" → "Check new payments on bank account" → "Mark order as paid" → end "Payments processed"
+  note: Approved invoices are those waiting for the 'Payment received' message
+  note: For all payed orders found
+
+Diagram (BPMN): Invoice Receipt (Process Engine)
+  start "Invoice received" → business rule task "Validate order" → intermediate catch event "Payment received" → call activity "Order Shipping" → end "Order processed"
+
+**(1)**
+
+We did not model a user task in this process, as the user will not immediately be triggered. The user cannot do anything at the moment when the process enters this event. Instead, we made it wait for a "message" which is later triggered by a human user.
+
+**(2)**
+
+The accountant actually receives the "external trigger" by actively looking at new payments in the bank account.
+
+**(3)**
+
+Every new payment now has to be correlated to the right waiting process instance manually. In this situation it is often the better choice not to model a user task, but let the process wait for a "message" generated from a user.
+
+These scenarios are not directly supported by Camunda Tasklist. A custom search screen built for the accountant might allow you to observe and find orders waiting for a payment. By interacting with such a screen, the accountant communicates with those process instances all at once. When hitting a 'Paid' button, a piece of custom code using the API must now correlate the user's message to the affected process instance(s).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.md

@@ -0,0 +1,8 @@
+# Routing events to processes
+
+To start a new process instance or to route a message to a running instance, choose the appropriate technology option to do so.
+
+To start a new process instance or to route a message to an already running instance, you have to choose the appropriate technology option to do so, like using the existing API or using customized possibilities including SOAP, AMQP, or Kafka. Leverage the possibilities of the universe of your runtime (like Java or Node.js) and the frameworks of your choice to support the technologies or protocols you need.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.reacting-to-process-internal-events.md

@@ -0,0 +1,29 @@
+# Routing events to processes — Reacting to process-internal events
+
+Events relevant for the process execution can occur from within the workflow engine itself.
+
+Consider the following loan application process - or at least the initial part with which the applicant's income is confirmed either via the employer or via the last income tax statement.
+
+Diagram (BPMN):
+  start "Loan application received" → exclusive gateway "Applicant is employed?"
+    — [No: =not(employed)] exclusive gateway → end "Loan application declined"
+    — [Yes: =employed] send task "Request income confirmation"
+      — receive task "Confirm income via employer" → end "Loan application confirmed and to be reviewed"
+      — (back to receive task "Confirm income via employer")
+
+**(1)**
+
+In case the employer does not confirm the income within three business days, a **timer event** triggers and a human clerk now tries to contact the employer and investigate the situation.
+
+**(2)**
+
+This could end with a successful income confirmation. However, it could also end with new findings regarding the applicant's employment status. We learn that the applicant is actually unemployed.
+
+**(3)**
+
+In this case, a **conditional event** watching this data (for example, a process variable changed by the user task) triggers and causes the process to reconsider the consequences of the new findings.
+
+A conditional event's condition expression is evaluated at it's "scope" creation time, too, and not just when variable data changes. For our example of a boundary conditional event, that means that the activity it is attached to could principally be left immediately via the boundary event. However, our process example evaluates the data via the exclusive gateway - therefore such a scenario is semantically impossible.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.routing-events-from-the-outside-to-the-workflow-engine.md

@@ -0,0 +1,83 @@
+# Routing events to processes — Routing events from the outside to the workflow engine
+
+Most events actually occur somewhere external to the workflow engine and need to be routed to it. The core workflow engine is by design not concerned with the technical part of receiving external messages, but you can receive messages and route them to the workflow engine by the following ways:
+
+- Using API: Receive the message by means of your platform-specific activities such as connecting to a AMQP queue or processing a REST request and then route it to the process.
+- Using connectors: Configure a connector to receive messages such as Kafka records and rote it to the process. Note that this possibility works for Camunda 8 only.
+- Using the Processes MCP Server: Apply the [MCP start event element template](https://docs.camunda.io/docs/next/components/connectors/out-of-the-box-connectors/agentic-ai-mcp-start-event) to a message start event, and the [Processes MCP Server](https://docs.camunda.io/docs/next/apis-tools/processes-mcp/processes-mcp-overview) registers the process as a tool that MCP clients, such as AI agents, can call to start an instance. See [expose a process as an MCP tool](https://docs.camunda.io/docs/next/components/agentic-orchestration/expose-process-as-mcp-tool).
+
+### Starting process instance by BPMN process ID
+
+If you have only one starting point (none start event) in your process definition, you reference the process definition by the ID in the BPMN XML file.
+
+**Note**
+This is the most common case and requires using the [`CreateProcessInstance`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#createprocessinstance-rpc) API.
+
+Example in Java:
+
+```java
+processInstance = zeebeClient.newCreateInstanceCommand()
+  .bpmnProcessId("invoice").latestVersion()
+  .send()
+  .exceptionally( throwable -> { throw new RuntimeException("Could not create new process instance", throwable); });
+```
+
+Example in Node.js:
+
+```js
+zbc.createWorkflowInstance({
+  bpmnProcessId: "invoice",
+});
+```
+
+This starts a new process instance in the latest version of the process definition. You can also start a specific version of a process definition:
+
+```java
+processInstance = zeebeClient.newCreateInstanceCommand()
+  .bpmnProcessId("invoice").version(5)
+  //...
+```
+
+or
+
+```js
+zbc.createWorkflowInstance({
+  bpmnProcessId: "invoice",
+  version: 6,
+});
+```
+
+You can also use [`CreateProcessInstanceWithResult`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#createprocessinstancewithresult-rpc) instead, if you want to block the execution until the process instance has completed.
+
+### Starting process instance by message
+
+As soon as you have multiple possible starting points, you have to use named messages to start process instances. The API method is [`PublishMessage`](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#publishmessage-rpc):
+
+```java
+client.newPublishMessageCommand()
+  .messageName("message_invoiceReceived") // <1>
+  .corrlationKey(invoiceId) // <2>
+  .variables( // <3>
+	  //...
+  ).send()
+  .exceptionally( throwable -> { throw new RuntimeException("Could not publish message", throwable); });
+```
+
+**(1)**
+
+Message name as defined in the BPMN.
+
+**(2)**
+
+Correlation key has to be provided, even if a start event does not require correlation.
+
+**(3)**
+
+_Payload_ delivered with the message.
+
+On one hand, now you do not have to know the key of the BPMN process. On the other hand, you cannot influence the version of the process definition used when starting a process instance by message.
+
+The message name for start events should be unique for the whole workflow engine - otherwise you might experience side effects you did not intend (like starting other processes too).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.sending-messages-to-other-processes.md

@@ -0,0 +1,51 @@
+# Routing events to processes — Sending messages to other processes
+
+If messages are exchanged between different processes deployed in the workflow engine you have to implement the communication yourself by writing some code that starts a new process instance.
+
+Diagram (BPMN): Invoice Receipt (Process Engine)
+  start "Order received" → business rule task "Validate order" → intermediate catch event "Payment received" → call activity "Order Shipping" → end "Order processed"
+
+Diagram (BPMN):
+  start "Input received" → "Do OCR and classify input data" → send task "Route input" → end "Input processed"
+
+Diagram (BPMN):
+  start "Daily" → service task "Retrieve new payments" → send task "Notify waiting order" → end "Payment checked"
+
+**(1)**
+
+Use some simple code on the sending side to route the message to a new process instance, for example by starting a new process instance by the BPMN ID in Java:
+
+```java
+@JobWorker(type="routeInput")
+public void routeInput(@Variable String invoiceId) {
+  Map<String, Object> variables = new HashMap<String, Object>();
+  variables.put("invoiceId", invoiceId);
+  zeebeClient.newCreateInstanceCommand()
+    .bpmnProcessId("invoice").latestVersion()
+	.variables(variables)
+    .send()
+    .exceptionally( throwable -> { throw new RuntimeException("Could not create new process instance", throwable); });
+}
+```
+
+**(2)**
+
+Use some simple code on the sending side to correlate the message to a running process instance, for example in Java:
+
+```java
+@JobWorker(type="notifyOrder")
+public void notifyOrder(@Variable String orderId, @Variable String paymentInformation) {
+  Map<String, Object> variables = new HashMap<String, Object>();
+  variables.put("paymentInformation", paymentInformation);
+
+  zeebeClient.newPublishMessageCommand()
+    .messageName("MsgPaymentReceived")
+    .corrlationKey(orderId)
+    .variables(variables)
+    .send()
+    .exceptionally( throwable -> { throw new RuntimeException("Could not publish message", throwable); });
+}
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.technology-examples-for-messages-sent-by-external-systems.md

@@ -0,0 +1,15 @@
+# Routing events to processes — Technology examples for messages sent by external systems
+
+In this section, we give examples for _technical messages_, which are received from other systems, typically by leveraging technologies like SOAP, REST, JMS, and others.
+
+Diagram (BPMN): Invoice Receipt (Process Engine)
+  start "Invoice received" → business rule task "Validate order" → intermediate catch event "Payment received" → call activity "Order Shipping" → end "Order processed"
+
+**(1)**
+
+You will need a mechanism receiving that message and routing it to the workflow engine. That could be a direct API call to Camunda. It could also be a AMQP or Kafka consumer or a SOAP endpoint using the Camunda API internally. It could even be a hotfolder polled by some framework like Apache Camel.
+
+API examples for REST, AMQP, and Kafka are shown in [connecting the workflow engine with your world](https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.routing-events-to-processes.using-the-camunda-bpmn-framework.md

@@ -0,0 +1,22 @@
+# Routing events to processes — Using the Camunda BPMN framework
+
+If you use the **Camunda BPMN Framework** as described in the book ["Real Life BPMN"](https://page.camunda.com/wp-real-life-bpmn-book-excerpt) you will typically have message start events (even if you only have a single start event) to connect the surrounding human flows to the technical flow via messages:
+
+Diagram (BPMN): TwitterDemoProcess
+  start "New Tweet written" → user task "Review tweet" → exclusive gateway "Tweet approved?"
+    — [No] service task "Send rejection notification" → end "Tweet rejected"
+    — [Yes] service task "Publish on Twitter" → end "Tweet published"
+
+Diagram (BPMN):
+  start "Great Idea" → "Write tweet" → "Publish tweet" → event-based gateway
+    — intermediate catch event "Tweet published" → end "Employee happy"
+    — intermediate catch event "Rejection notification received" → "Complain about boss" → end "Employee sad"
+
+**(1)**
+
+This is a message start event, which allows you to show the collaboration between the human and the technical flows. However, it is the only the starting point of the technical pool and could be a none start event in terms of execution.
+
+If there is _exactly one message start event_ for the whole process definition, it can also be treated as if it were a none start event when starting a process instance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/routing-events-to-processes

package/.llms/chunks/components.best-practices.development.service-integration-patterns.hiding-technical-complexity-behind-call-activities.md

@@ -0,0 +1,12 @@
+# Service integration patterns with BPMN — Hiding technical complexity behind call activities
+
+Whenever technical details of one service integration become complicated, you can think of creating a separate process model for the technicalities of the call and use a [call activity](https://docs.camunda.io/docs/next/components/modeler/bpmn/call-activities/call-activities) in the main process.
+
+An example is given in chapter 7 of [Practical Process Automation](https://processautomationbook.com/):
+
+![Hiding technical details behind call activity](service-integration-patterns-assets/hiding-technical-details-behind-call-activity.png)
+
+In the customer scenario, a document storage service was long-running, but could not do a real callback or response message for technical reasons (in short, firewall limitations). As a result, the document storage service needed to be regularly polled for the response. In the customer scenario, this was done by a "document storage adapter" process that leveraged workflow engine features to implement the polling every minute, and especially the persistent waiting in between. In the main business process, this technical adapter process was simply invoked via a call activity, meaning no technicalities bloated that diagram.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-events-handling-different-response-messages.md

@@ -0,0 +1,35 @@
+# Service integration patterns with BPMN — Integrating services with BPMN events — Handling different response messages
+
+Very often the response payload of the message will be examined to determine how to move on in the process.
+
+![Gateway handling response](service-integration-patterns-assets/response-gateway.png)
+
+In this case, you receive exactly one type of message for the response. As an alternative, you could also use different message types, to which the process can react differently. For example, you might wait for the validation message, but also accept a cancellation or rejection message instead:
+
+![Boundary message event to capture different response messages](service-integration-patterns-assets/response-boundary-message-events.png)
+
+This modeling has the advantage that it is much easier to note the expected flow of the process (also called the happy path), with exceptions deviating from it. On the other hand, this pattern mixes receive tasks and events in one model, which can confuse readers. Keep in mind that it only works for a limited number of non-happy messages.
+
+To avoid the task/event mixture you could use a so-called event-based gateway instead, this gateway waits for one of a list of possible message types to be received:
+
+![Event based gateway to capture different response messages](service-integration-patterns-assets/response-event-based-gateway.png)
+
+We typically try to avoid the event-based gateway, as it is hard to understand for non-BPMN professionals. At the same time, it shares the downside of the first pattern with the decision gateway after the receive task: the happy path cannot be easily spotted.
+
+As a fourth possibility, you can add event subprocesses, which get activated whenever some event is received while the process is still active in some other area. In the above example, you could model the happy path and model all deviations as event subprocesses.
+
+![Event subprocess to capture different response messages](service-integration-patterns-assets/response-event-subprocess.png)
+
+This pattern is pretty handy, but also needs some explanation to people new to BPMN. It has one downside you need to know: once your process instance moves to the subprocess, you can’t easily go back to the typical flow. To some extent this problem can be solved by advanced modeling patterns like shown in the [allow for order cancellation anytime](https://docs.camunda.io/docs/next/components/best-practices/modeling/building-flexibility-into-bpmn-models#allow-for-order-cancellation-any-time) example.
+
+At the same time, the event subprocess has a superpower worth mentioning: you can now wait for cancellation messages in whole chunks of your process — it could arrive anytime.
+
+|                   | Receive task with boundary events                                                                     | Payload and XOR-gateway                                                                   | Event-based gateway                                                                          | Event subprocess                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+|                   | ![Boundary Events](service-integration-patterns-assets/response-boundary-message-events.png)          | ![XOR Gateway](service-integration-patterns-assets/response-gateway.png)                  | ![Event-based Gateway](service-integration-patterns-assets/response-event-based-gateway.png) | ![Event Subprocess](service-integration-patterns-assets/response-event-subprocess.png) |
+| Understandability | Easy                                                                                                  | Very easy                                                                                 | Hard                                                                                         | Medium                                                                                 |
+| Assessment        | Limitation on how many message types are possible                                                     | Happy path not easily visible                                                             |                                                                                              | Might need some explanation for readers of the model                                   |
+| Recommendation    | Use when it is important to observe message types in the visual, limit to two boundary message events | Use when there are more response types or if the response type can be treated as a result | Try to avoid                                                                                 | Use if you need bigger scopes where you can react to events                            |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-events-message-type-on-the-wire-bpmn-message-type.md

@@ -0,0 +1,11 @@
+# Service integration patterns with BPMN — Integrating services with BPMN events — Message type on the wire != BPMN message type
+
+There is one important detail worth mentioning in the context of message response patterns: The message type used in BPMN models does not have to be exactly the message type you get on the wire. When you correlate technical messages, e.g. from AMQP, you typically write a piece of glue code that receives the message and calls the workflow engine API. This is described in [connecting the workflow engine with your world](https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world), including a code example. In this glue code you can do various transformations, for example:
+
+- Messages on different message queues could lead to the same BPMN message type, probably having some additional parameter in the payload indicating the origin.
+- Some message header or payload attributes could be used to select between different BPMN message types being used.
+
+It is probably not best practice to be as inconsistent as possible between technical message types and BPMN message types. Still, the flexibility of a custom mapping might be beneficial in some cases.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-events-tasks-vs.-events.md

@@ -0,0 +1,23 @@
+# Service integration patterns with BPMN — Integrating services with BPMN events — Tasks vs. events
+
+The **execution semantics of send and receive events is identical with send and receive tasks**, so you can express the very same thing with tasks or events.
+
+However, there is one small difference that might be relevant: **only tasks can have boundary events**, which allows to easily model when you want to cancel waiting for a message:
+
+![Boundary events](service-integration-patterns-assets/boundary-event.png)
+
+Despite this, the whole visual representation is of course different. In general, tasks are easier understood by most stakeholders, as they are used very often in BPMN models.
+
+However, in certain contexts, such as event-driven architectures, events might be better suited as the concept of events is very common. Especially, if you apply domain-driven design (DDD) and discuss domain events all day long, it might be intuitive that events are clearly visible in your BPMN models.
+
+Another situation better suited for events is if you send events to your internal reporting system besides doing “the real” business logic. Our experience shows that the smaller event symbols are often unconsciously treated as less important by readers of the model, leading to models that are easier to understand.
+
+|                | Send task                | Receive task             | Send event                                                                                                              | Receive event                                                                                                           |
+| :------------- | :----------------------- | :----------------------- | :---------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
+| Recommendation | Prefer tasks over events | Prefer tasks over events | Use only if you consistently use events over tasks and have a good reason for doing so (e.g. event-driven architecture) | Use only if you consistently use events over tasks and have a good reason for doing so (e.g. event-driven architecture) |
+
+**Note**
+The choice about events vs. commands also [needs to be reflected in the naming of the element](https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements), as a task emphasizes the action (e.g. "wait for response") and the event reflects what happened (e.g. "response received").
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-events.md

@@ -0,0 +1,10 @@
+# Service integration patterns with BPMN — Integrating services with BPMN events
+
+Instead of using send or receive **tasks**, you can also use send or receive **events** in BPMN.
+
+![Events vs tasks](service-integration-patterns-assets/events-vs-tasks.png)
+
+Let's first explore when you want to do that, and afterwards look into some more advanced patterns that become possible with events.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-tasks-receive-task.md

@@ -0,0 +1,10 @@
+# Service integration patterns with BPMN — Integrating services with BPMN tasks — Receive task
+
+A [receive task](https://docs.camunda.io/docs/next/components/modeler/bpmn/receive-tasks/receive-tasks) waits for an asynchronous message. Receive tasks **should be used for incoming asynchronous messages or events**, like AMQP messages or Kafka records.
+
+![Receive task](service-integration-patterns-assets/receive-task.png)
+
+Receive tasks can be used to receive the response in asynchronous request/response scenarios, which is discussed next.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-tasks-send-task.md

@@ -0,0 +1,25 @@
+# Service integration patterns with BPMN — Integrating services with BPMN tasks — Send task
+
+Technically, **send tasks behave exactly like service tasks**. However, the alternative symbol makes the meaning of sending a message easier to understand for some stakeholders.
+
+You **should use send tasks for sending asynchronous messages**, like AMQP messages or Kafka records.
+
+![Send task](service-integration-patterns-assets/send-task.png)
+
+There is some gray area whenever you call a synchronous service that then sends an asynchronous message. A good example is email. Assume your process does a synchronous request/response call to a service that then sends an email to inform the customer. The call itself is synchronous because it gives you a confirmation (acknowledgement, or ACK for short) that the email has been sent. Now is the "inform customer" task in your process a service, or a send task?
+
+![Asynchronous ACK](service-integration-patterns-assets/synchronous-ack.png)
+
+This question is not easy to answer and **depends on what your stakeholders understand more intuitively**. The more technical people are, the more you might tend towards a service task, as this is technically correct. The more you move towards the business side, the more you might tend to use a send task, as business people will consider sending an email an asynchronous message.
+
+In general, we tend to **let the business win** as it is vital that business stakeholders understand business processes.
+
+However, if you follow a microservice (or service-oriented architecture) mindset, you might argue that you don’t need to know exactly how customers are informed within the process. Hiding the information if the notification is synchronous or asynchronous is good to keep your process model independent of such choices, making it more robust whenever the implementation of the notification service changes. This is a very valid concern too, and might motivate for a service task.
+
+**Note**
+In case you can’t easily reach a conclusion, save discussion time and just use a service task.
+
+You could also argue to use send tasks to invoke synchronous request/response calls when you are not interested in the response. However, this is typically confusing, and we do not recommend this.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-tasks-service-task-vs.-send-receive-task-combo-2.md

@@ -0,0 +1,30 @@
+# Service integration patterns with BPMN — Integrating services with BPMN tasks — Service task vs. send/receive task combo (2)
+
+This is also balanced by the fact that service tasks are simply very handy. The concept is by far the easiest way to implement asynchronous request/response communication. The job instance key is generated for you and unique for every message interchange. You don’t have to think about race conditions or idempotency constraints yourself. [Timeout handling and retry logic](https://docs.camunda.io/docs/next/components/concepts/job-workers#timeouts) is built into the service task implementation of Zeebe. There is also [a clear API to let the workflow engine know of technical or business errors](https://docs.camunda.io/docs/next/components/concepts/job-workers#completing-or-failing-jobs).
+
+**Technical implications of using send and receive tasks**
+
+Using send and receive tasks means to use [the message concept built into Zeebe](https://docs.camunda.io/docs/next/components/concepts/messages). This is a powerful concept to solve a lot of problems around cardinalities of subscriptions, correlation of the message to the right process instances, and verification of uniqueness of the message (idempotency).
+
+When using messages, you need to provide the correlation ID yourself. This means that the correlation ID is fully under your control, but it also means that you need to generate it yourself and make sure it is unique. You will most likely end up with generated UUIDs.
+
+You can leverage [message buffering](https://docs.camunda.io/docs/next/components/concepts/messages#message-buffering) capabilities, which means that the process does not yet need to be ready to receive the message. You could, for example, do other things in between, but this also means that you will not get an exception right away if a message cannot be correlated, as it is simply buffered. This leaves you in charge of dealing with messages that can never be delivered.
+
+Retries are not built-in, so if you need to model a loop to retry the initial service call if no response is received. And (at least in the current Zeebe version), there is no possibility to trigger error events for a receive task, which means you need to model error messages as response payload or separate message types — both are discussed later in this post.
+
+A final note for high-performance environments: These powerful messaging capabilities do not come for free and require some overhead within the engine. For pure request/response calls that return within milliseconds, none of the features are truly required. If you are looking to build a high-performance scenario, using service tasks instead of message correlation for request/response calls, you can tune your overall performance or throughput. However, as with everything performance related, the devil is in the detail, so [reach out to us](https://docs.camunda.io/docs/next/reference/contact) to discuss such a scenario in more depth.
+
+**Summary And recommendations**
+
+The following table summarizes the possibilities and recommendations.
+
+| Case                   | Synchronous request/response                                                                                                | Synchronous request/response                                                                                          | Asynchronous request/response                                                                                                                                                                        | Asynchronous request/response                                                                                                                                                                     |
+| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| BPMN element           | Service task                                                                                                                | Send task                                                                                                             | Service task                                                                                                                                                                                         | Send + receive task                                                                                                                                                                               |
+|                        | ![Service task](/img/bpmn-elements/task-service.svg)                                                                        | ![Send task](/img/bpmn-elements/task-send.svg)                                                                        | ![Service task](/img/bpmn-elements/task-service.svg)                                                                                                                                                 | ![Send and receive task](/img/bpmn-elements/send-and-receive-task.png)                                                                                                                            |
+| Technical implications |                                                                                                                             | Behaves like a service task                                                                                           | A unique correlation ID is generated for you. You don’t have to think about race conditions or idempotency. Timeout handling and retry logic are built-in. API to flag business or technical errors. | Correlation ID needs to be generated yourself, but is fully under control. Message buffering is possible but also necessary. Timeouts and retries need to be modeled. BPMN errors cannot be used. |
+| Assessment             | Very intuitive.                                                                                                             | Might be more intuitive for fire and forget semantics, but can also lead to discussions.                              | Removes visual noise which helps stakeholders to concentrate on core business logic, but requires use of internal job instance keys.                                                                 | More visual clutter, but also more powerful options around correlation and modeling patterns.                                                                                                     |
+| Recommendation         | Default option, use unless it is confusing for business stakeholders (e.g. because of fire and forget semantics of a task). | Use for fire and forget semantics, unless it leads to unnecessary discussions, in this case use service task instead. | Use when response is within milliseconds and you can pass the Zeebe-internal job instance key around.                                                                                                | Use when the response will take time (> some seconds), or you need a correlation ID you can control.                                                                                              |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns