@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.architecture.understanding-human-tasks-management.deciding-about-your-task-list-frontend-considerations-for-using-third-party-task-lists.md

@@ -0,0 +1,27 @@
+# Understanding human task management — Deciding about your task list frontend — Considerations for using third party task lists
+
+When integrating a third party tasklist, you must plan for the following aspects. You will need to take care of:
+
+- _Creating_ tasks in the third party tasklist based on the user tasks created by Camunda.
+- _Completing_ tasks in Camunda and move on process execution based on user action in the third party tasklist.
+- _Cancelling_ tasks, triggered by Camunda or triggered by the user in the third-party tasklist.
+- Transferring _business data_ to be edited in the third-party tasklist back and forth.
+
+Your third party tasklist application also needs to allow for some programmatic control of the lifecycle of its tasks. The third-party application _must have_ the ability:
+
+- To programmatically _create_ a new task.
+- To _hook in code_ which programmatically informs other systems that the user is about to change a task's state.
+- To _manage custom attributes_ connected to a task and programmatically access them.
+
+Additionally, it _should have_ the ability
+
+- To programmatically _delete_ a task which was cancelled in Camunda. Without this possibility such tasks remain in the users tasklist and would need to be removed manually. Depending on the way you integrate the task completion mechanism, when the user tries to complete such tasks, they would immediately observe an error or the action would just not matter anymore and serve as a removal from the list.
+
+Transfer just the minimal amount of business data in between Camunda and your third-party tasklist application.
+
+For creating tasks, transfer just the taskId and important business data references/ids to your domain objects. As much as possible should be retrieved later, and just when needed (e.g. when displaying task forms to the user) by requesting data from the process engine or by requesting data directly from other systems.
+
+For completing tasks, transfer just the business data which originated from Camunda and was changed by the user. This means, in case you just maintain references, nothing needs to be transferred back. All other business data changed by the user will be directly transferred to the affected systems.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/understanding-human-tasks-management

package/.llms/chunks/components.best-practices.architecture.understanding-human-tasks-management.deciding-about-your-task-list-frontend-task-lists-may-not-look-like-task-lists.md

@@ -0,0 +1,25 @@
+# Understanding human task management — Deciding about your task list frontend — Task lists may not look like task lists
+
+There are situations where you might want to show a user interface that does not look like a task list, even if it is fed by tasks. The following _example_ shows such a situation in the document _input management_ process of a company. Every document is handled by a separate process instance, but users typically look at complete mailings consisting of several such documents. In a customer scenario, there were people in charge of assessing the scanned mailing and distributing the individual documents to the responsible departments. It was important to do that in one step, as sometimes documents referred to each other.
+
+So you have several user tasks which are heavily _interdependent_ from a business point of view and should therefore be completed _in one step_ by the same person.
+
+The solution to this was a custom user interface that basically queries for human tasks, but show them grouped by mailings:
+
+![custom tasklist mockup](understanding-human-tasks-management-assets/tasklist-mockup.png)
+
+**(1)**
+
+The custom tasklist shows each mailing as one "distribution task", even though they consist of several human tasks fetched from the workflow instance.
+
+**(2)**
+
+The custom user interface allows you to work on all four human tasks at once. By dragging and dropping a document within the tree, the user can choose to which department the document is delivered to.
+
+**(3)**
+
+In case the user detects a scanning problem, they can request a new scan of the mailing. But as soon
+as all documents are quality assured, the button **Distribute Mailing** gets enabled. By clicking on it, the system completes all four human tasks - one for each document - which moves forward the four process instances associated with the documents.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/understanding-human-tasks-management

package/.llms/chunks/components.best-practices.architecture.understanding-human-tasks-management.deciding-about-your-task-list-frontend.md

@@ -0,0 +1,12 @@
+# Understanding human task management — Deciding about your task list frontend
+
+If you are orchestrating human tasks in your process, you must make up your mind on how exactly you want to let your users work on their tasks and interact with the workflow engine. You have basically three options:
+
+- [Camunda Tasklist](https://docs.camunda.io/docs/next/components/tasklist/introduction-to-tasklist): The Tasklist application shipped with Camunda. This works out-of-the-box and has a low development effort. However, it is limited in terms of customizability and how much you can influence the user experience.
+
+- Custom task list application: You can develop a custom task list and adapt this to your needs without compromises. User tasks are shown inside your custom application, following your style guide and usability concept. You will use the [Orchestration Cluster REST API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview) in the background. This is very flexible, but requires additional development work.
+
+- Third party tasklist: If our organization already has a task list application rolled out to the field, you might want to use this for tasks created by Camunda. You will need to develop some synchronization mechanism. The upside of this approach is that your end users might not even notice that you introduce a new workflow engine.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/understanding-human-tasks-management

package/.llms/chunks/components.best-practices.architecture.understanding-human-tasks-management.md

@@ -0,0 +1,39 @@
+# Understanding human task management
+
+Use Camunda task management features or implement your requirements in a generic way for readable models.
+
+
+## Using task assignment features
+
+The lifecycle of human task orchestration (like assigning, delegating, and completing tasks) is mostly a generic issue. There is no need to model common aspects into all your processes, if often makes models unreadable. Use Camunda task management features or implement your requirements in a generic way.
+
+![Task assignment](understanding-human-tasks-management-assets/human-tasks.png)
+
+So every task can be assigned to either a group of people, or a specific individual. An individual can 'claim' a task, indicating that they are picking the task from the pool (to avoid multiple people working on the same task).
+
+As a general rule, you should assign human tasks, like [user tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/user-tasks/user-tasks) or [manual tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/manual-tasks/manual-tasks), in your business process to _groups of people_ instead of specific individuals.
+
+```xml
+<bpmn:userTask id="task_approve_vacation">
+  <bpmn:extensionElements>
+    <zeebe:assignmentDefinition candidateGroups="manager" />
+  </bpmn:extensionElements>
+```
+
+Then, require individual members of that group to explicitly _claim tasks_ before working on them. This way, you avoid different people working on the same task at the same time. Refer to [`assign`](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/assign-user-task.api).
+
+You can also directly claim tasks in Camunda Tasklist with the click of a button.
+
+![Claim](understanding-human-tasks-management-assets/claim.png)
+
+While assigning users to groups is advised, it's not the only option. You could always assign a task to a _single person_ who is supposed to complete the task (e.g. the individual 'customer' of your process or a coworker having specific knowledge for the case). You will need to have access to the specific person relevant for your process instance, e.g. via a process variable:
+
+```xml
+<bpmn:userTask id="task_approve_vacation">
+  <bpmn:extensionElements>
+    <zeebe:assignmentDefinition assignee="=assistant_username" />
+  </bpmn:extensionElements>
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/architecture/understanding-human-tasks-management

package/.llms/chunks/components.best-practices.best-practices-overview.md

@@ -0,0 +1,10 @@
+# Best Practices
+
+Condensed Camunda project experience covering process modeling, development, architecture, operations, and agentic orchestration, as a mix of conceptual and practical implementation guidance.
+
+The Camunda Best Practices distill Camunda's experience with BPMN, DMN, and agentic orchestration on the Camunda toolstack, drawing on consulting engagements, community feedback, and customer projects. They offer a blend of conceptual and practical guidance, generalized from current project experience. They are not definitive: learning is ongoing, and how well a practice applies depends on your situation.
+
+Note that Camunda extends the same guarantee to Best Practices as to the core product. However, Camunda cannot ensure the absolute accuracy or timeliness of the information provided, and disclaims any liability for damages resulting from applying these recommendations.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/best-practices-overview

package/.llms/chunks/components.best-practices.best-practices-overview.project-management.md

@@ -0,0 +1,18 @@
+# Best Practices — Project management
+
+## Architecture
+
+
+## Development
+
+
+## Modeling
+
+
+## Operations
+
+
+## CI/CD guidelines
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/best-practices-overview

package/.llms/chunks/components.best-practices.cicd-guidelines.element-templates-at-scale.make-templates-available-in-camunda-hub.md

@@ -0,0 +1,57 @@
+# Element templates at scale — Make templates available in Camunda Hub
+
+Make templates available in Camunda Hub with the Camunda Hub API ([SaaS](https://docs.camunda.io/docs/next/apis-tools/hub-api-saas/overview) or [Self-Managed](https://docs.camunda.io/docs/next/apis-tools/hub-api-sm/overview)).
+
+### Get the workspace key
+
+Search for your workspace to get the `workspaceKey`:
+
+```bash
+POST /api/v2/workspaces/search
+{
+    "filter": {
+        "name": "(WORKSPACE NAME)"
+    }
+}
+```
+
+You'll use the `workspaceKey` to filter projects to the target workspace.
+
+### Get projects
+
+With the `workspaceKey`, retrieve the projects that belong to the workspace:
+
+```bash
+GET /api/v2/workspaces/(WORKSPACE KEY)
+```
+
+Under `content`, get the `projectKey` for the project you want to update.
+
+### Get file metadata
+
+With the `projectKey`, retrieve a list of files and metadata:
+
+```bash
+GET /api/v2/projects/(PROJECT KEY)
+```
+
+Using `content`, compare the files in Camunda Hub to the files in your repository.
+
+### Create or update files
+
+For each file in your repository that doesn't match the content in Camunda Hub, [create](https://docs.camunda.io/docs/next/apis-tools/hub-api-saas/specifications/create-file.api) or [update](https://docs.camunda.io/docs/next/apis-tools/hub-api-saas/specifications/update-file.api) the appropriate file resource.
+
+### Create new file versions
+
+If desired, [create a new file version](https://modeler.camunda.io/swagger-ui/index.html#/Versions) for each of the affected files:
+
+```bash
+POST /api/v2/versions
+{
+  "fileKey": "(FILE KEY)",
+  "name": "(VERSION NAME)"
+}
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/cicd-guidelines/element-templates-at-scale

package/.llms/chunks/components.best-practices.cicd-guidelines.element-templates-at-scale.making-templates-available-in-desktop-modeler.md

@@ -0,0 +1,12 @@
+# Element templates at scale — Making templates available in Desktop Modeler
+
+To set up your local environment:
+
+- Access the VCS repository containing the templates.
+- Choose how to [configure them](https://docs.camunda.io/docs/next/components/modeler/desktop-modeler/element-templates/configuring-templates) depending on your needs. If your templates are reused across multiple projects, configuring them globally will make it easier to maintain. For project-specific templates, consider making them available only for that project to avoid exposing templates to projects that should not be using them.
+
+**Note**
+If you are the template creator/maintainer, include a `README` file in your repository that lists the requirements for using your templates -- for example, which dependencies need to be provisioned in advance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/cicd-guidelines/element-templates-at-scale

package/.llms/chunks/components.best-practices.cicd-guidelines.element-templates-at-scale.md

@@ -0,0 +1,17 @@
+# Element templates at scale
+
+Learn how to provision element templates at runtime and make them available at design time across your Camunda Hub organization and Desktop Modeler.
+
+To effectively manage large libraries of reusable building blocks ([element templates](https://docs.camunda.io/docs/next/components/concepts/element-templates)), you can create a pipeline that:
+
+- Provisions the [dependencies of element templates](https://docs.camunda.io/docs/next/components/modeler/element-templates/element-template-with-dependencies) to required clusters.
+- Makes templates available at design time to multiple [workspaces](https://docs.camunda.io/docs/next/components/hub/organization/manage-workspaces/index) within an organization.
+
+<!--- source: https://www.figma.com/design/VyyoV0hNbazXV8DKcMMEU9/Camunda-Documentation-Assets?node-id=2078-301&t=YNT70ktAMXBBupbJ-1 --->
+
+![Pipeline goal](./img/pipeline-goal.png)
+
+This guide covers conceptually what your pipeline needs to do, from obtaining credentials to runtime provisioning and template syncing.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/cicd-guidelines/element-templates-at-scale

package/.llms/chunks/components.best-practices.cicd-guidelines.element-templates-at-scale.next-steps.md

@@ -0,0 +1,6 @@
+# Element templates at scale — Next steps
+
+Refer to [integrate Camunda Hub in CI/CD](https://docs.camunda.io/docs/next/components/hub/workspace/modeler/integrate-modeler-in-ci-cd) for additional CI/CD-related guidance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/cicd-guidelines/element-templates-at-scale

package/.llms/chunks/components.best-practices.cicd-guidelines.element-templates-at-scale.prerequisites.md

@@ -0,0 +1,20 @@
+# Element templates at scale — Prerequisites
+
+Before building your pipeline, ensure you have the following:
+
+| Prerequisite                                                                                                                           | Purpose                                                                                                                                                                                                                                                         |
+| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Git Repository](https://en.wikipedia.org/wiki/Git)                                                                                    | Store all element templates                                                                                                                                                                                                                                     |
+| Template state management                                                                                                              | Maintain an authoritative inventory (for example, via Git or an IaC tool like Terraform) that defines which templates are applied to each cluster and which workspaces depend on them. This source acts as the single source of truth for template deployments. |
+| Camunda Hub API token ([SaaS](https://docs.camunda.io/docs/next/apis-tools/hub-api-saas/authentication) or [Self-Managed](https://docs.camunda.io/docs/next/apis-tools/hub-api-sm/authentication)) | Access Camunda Hub programmatically                                                                                                                                                                                                                             |
+| [Orchestration Cluster API client](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-authentication)        | Provision dependencies to clusters                                                                                                                                                                                                                              |
+
+For simplicity, this guide assumes:
+
+- One organization
+- One cluster
+- One [workspace](https://docs.camunda.io/docs/next/components/hub/organization/manage-workspaces/index)
+- A pipeline handling runtime provisioning and template syncing
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/cicd-guidelines/element-templates-at-scale

package/.llms/chunks/components.best-practices.cicd-guidelines.element-templates-at-scale.runtime-provisioning.md

@@ -0,0 +1,65 @@
+# Element templates at scale — Runtime provisioning
+
+### Secrets
+
+You can use sensitive information in your element templates without exposing it in your BPMN processes by referencing secrets.
+
+These guides show you how to configure them depending on the environment you are using:
+
+- **SaaS**: Use the [Administration API](https://docs.camunda.io/docs/next/apis-tools/administration-api/administration-api-reference) or [Camunda Hub UI](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/manage-secrets) to configure secrets.
+- **Self-Managed/local development**: Configure secrets outside the pipeline. See [connector secrets](https://docs.camunda.io/docs/next/self-managed/components/connectors/connectors-configuration#secrets).
+
+### Job Workers
+
+As part of the pipeline, you may spin up a service that will connect to a Camunda cluster to perform specific tasks. For example, you can use the [Spring Boot Camunda Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started) to start a job worker.
+
+Recommended resources:
+
+- [Outbound connectors vs. job workers](https://docs.camunda.io/docs/next/components/concepts/outbound-connectors-job-workers)
+- [Host custom connectors](https://docs.camunda.io/docs/next/components/connectors/custom-built-connectors/host-custom-connector)
+
+### Other dependencies
+
+The following dependency types are provisioned at runtime using the [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview):
+
+| Dependency                                                            | Purpose                     |
+| --------------------------------------------------------------------- | --------------------------- |
+| [Camunda forms](https://docs.camunda.io/docs/next/components/modeler/forms/camunda-forms-reference) | Used in user tasks          |
+| [RPA scripts](https://docs.camunda.io/docs/next/components/rpa/overview)                            | Used in service tasks       |
+| [BPMN processes](https://docs.camunda.io/docs/next/components/modeler/bpmn/bpmn)                    | Used in call activities     |
+| [DMN decisions](https://docs.camunda.io/docs/next/components/modeler/dmn/dmn)                       | Used in business rule tasks |
+
+To deploy dependencies, send a [POST request](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-deployment.api) with the files. This works for SaaS, Self-Managed, and local development.
+
+For example:
+
+```bash
+curl -L 'http://localhost:8080/v2/deployments' \
+-H 'Accept: application/json' \
+-F resources=@/path/to/your/form/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>"
+}
+```
+
+When referencing a dependency such as a form, Camunda recommends using a `versionTag` as your [binding type](https://docs.camunda.io/docs/next/components/best-practices/modeling/choosing-the-resource-binding-type#supported-binding-types). This option ensures the right version of the target resource is always used.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/cicd-guidelines/element-templates-at-scale

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.connectors.md

@@ -0,0 +1,41 @@
+# Connecting the workflow engine with your world — Connectors
+
+The glue code is relatively simple, but you need to write code. You might prefer using an out-of-the-box component, connecting Zeebe with the technology you need just by configuration. This component is called a **Connector**.
+
+A connector can be uni or bidirectional and is typically one dedicated application that implements the connection that translates in one or both directions of communication. Such a connector might also be helpful in case integrations are not that simple anymore.
+
+![Connectors](connecting-the-workflow-engine-with-your-world-assets/connector.png)
+
+For example, the [HTTP connector](https://github.com/camunda-community-hub/zeebe-http-worker) is a one-way connector that contains a job worker that can process service tasks doing HTTP calls as visualized in the example in the following figure:
+
+![REST connectors](connecting-the-workflow-engine-with-your-world-assets/rest-connector.png)
+
+Another example is the [Kafka connector](https://github.com/camunda-community-hub/kafka-connect-zeebe), as illustrated below.
+
+![Kafka connector](connecting-the-workflow-engine-with-your-world-assets/kafka-connector.png)
+
+This is a bidirectional connector which contains a Kafka listener for forwarding Kafka records to Zeebe and also a job worker which creates Kafka records every time a service task is executed. In other words, the connector helps Kafka exchange events with Zeebe; it does not replace Zeebe's own workflow execution or state handling. This is illustrated by the following example:
+
+![Kafka connector Details](connecting-the-workflow-engine-with-your-world-assets/kafka-connector-details.png)
+
+### Out-of-the-box connectors
+
+As well as Camunda-maintained connectors, additional connectors are maintained by the community (made up of consultants, partners, customers, and enthusiastic individuals). You can find a list of connectors in the [Camunda Marketplace](https://marketplace.camunda.com/).
+
+### Reusing your own integration logic by extracting connectors
+
+If you need to integrate with certain infrastructure regularly, for example your CRM system, you might also want to create your own CRM connector, run it centralized, and reuse it in various applications.
+
+In general, we recommend not to start such connectors too early. Don’t forget that such a connector gets hard to adjust once in production and reused across multiple applications. Also, it is often much harder to extract all configuration parameters correctly and fill them from within the process, than it would be to have bespoke glue code in the programming language of your choice.
+
+Therefore, only extract a full-blown connector if you understand exactly what you need.
+
+Don’t forget about the possibility to extract common glue code in a simple library that is then used at different places.
+
+**Note**
+Updating a library that is used in various other applications can be harder than updating one central connector. In this case, the best approach depends on your scenario.
+
+Whenever you have such glue code running and really understand the implications of making it a connector, as well as the value it will bring, it can make a lot of sense.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.designing-process-solutions-containing-all-glue-code.md

@@ -0,0 +1,18 @@
+# Connecting the workflow engine with your world — Designing process solutions containing all glue code
+
+Typical applications will include multiple pieces of glue code in one codebase.
+
+![Architecture with glue code](connecting-the-workflow-engine-with-your-world-assets/architecture.png)
+
+For example, the onboarding microservice shown in the figure above includes:
+
+- A REST endpoint that starts a process instance (1)
+- The process definition itself (2), probably auto-deployed to the workflow engine during the startup of the application.
+- Glue code subscribing to the two service tasks that shall call a remote REST API (3) and (4).
+
+A job worker will be started automatically as part of the application to handle the subscriptions. In this example, the application is written in Java, but again, it could be [any supported programming language](https://docs.camunda.io/docs/next/apis-tools/working-with-apis-tools).
+
+As discussed in [writing good workers](https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers), you typically will bundle all workers within one process solution, but there are exceptions where it makes sense to have single workers as separate application.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.md

@@ -0,0 +1,17 @@
+# Connecting the workflow engine with your world
+
+To sketch the basic architecture of your solution, learn how to connect the Zeebe workflow engine with your application or remote system.
+
+One of your first tasks to build a process solution is to sketch the basic architecture of your solution. To do so, you need to answer the question of how to connect the workflow engine (Zeebe) with your application or with remote systems.
+
+The workflow engine is a remote system for your applications, just like a database. Your application connects with Zeebe via remote protocols (like [gRPC](https://grpc.io/) or REST), which is typically hidden from you, like when using a database driver based on ODBC or JDBC.
+
+With Camunda 8 and the Zeebe workflow engine, there are two basic options:
+
+1. Write some **programming code** that typically leverages the client library for the programming language of your choice.
+2. Use some **existing connector** which just needs a configuration.
+
+The trade-offs will be discussed later; let’s look at the two options first.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.programming-glue-code-calling-zeebe.md

@@ -0,0 +1,57 @@
+# Connecting the workflow engine with your world — Programming glue code — Calling Zeebe
+
+Using the Zeebe client’s API, you can communicate with the workflow engine. The two most important API calls are to start new process instances and to correlate messages to a process instance.
+
+**Start process instances using the** [**Java Client**](https://docs.camunda.io/docs/next/apis-tools/java-client/getting-started)**:**
+
+```java
+processInstance = zeebeClient.newCreateInstanceCommand()
+  .bpmnProcessId("someProcess").latestVersion()
+  .variables( someProcessVariablesAsMap )
+  .send()
+  .exceptionally( throwable -> { throw new RuntimeException("Could not create new instance", throwable); });
+```
+
+<!-- **Start process instances using the** **Node.js client****:**
+
+```js
+const processInstance = await zbc.createWorkflowInstance({
+  bpmnProcessId: "someProcess",
+  version: 5,
+  variables: {
+    testData: "something",
+  },
+});
+``` -->
+
+**Correlate messages to process instances using the Java Client**:
+
+```java
+zeebeClient.newPublishMessageCommand() //
+  .messageName("messageA")
+  .messageId(uniqueMessageIdForDeduplication)
+  .correlationKey(message.getCorrelationid())
+  .variables(singletonMap("paymentInfo", "YeahWeCouldAddSomething"))
+  .send()
+  .exceptionally( throwable -> { throw new RuntimeException("Could not publish message " + message, throwable); });
+```
+
+**Correlate messages to process instances using the Node.js client**:
+
+```js
+zbc.publishMessage({
+  name: "messageA",
+  messageId: messageId,
+  correlationKey: correlationId,
+  variables: {
+    valueToAddToWorkflowVariables: "here",
+    status: "PROCESSED",
+  },
+  timeToLive: Duration.seconds.of(10),
+});
+```
+
+This allows you to connect Zeebe with any external system by writing some custom glue code. We will look at common technology examples to illustrate this in a minute.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.programming-glue-code-subscribing-to-tasks-using-a-job-worker.md

@@ -0,0 +1,63 @@
+# Connecting the workflow engine with your world — Programming glue code — Subscribing to tasks using a job worker
+
+To implement service tasks of a process model, you can write code that subscribes to the workflow engine. In essence, you will write some glue code that is called whenever a service task is reached (which internally creates a job, hence the name).
+
+**Glue code in Java:**
+
+```java
+class ExampleJobHandler implements JobHandler {
+  public void handle(final JobClient client, final ActivatedJob job) {
+    // here: business logic that is executed with every job
+    client.newCompleteCommand(job.getKey()).send()
+      .exceptionally( throwable -> { throw new RuntimeException("Could not complete job " + job, throwable); });;
+  }
+}
+```
+
+**Glue code in Node.js:**
+
+```js
+function handler(job, complete, worker) {
+  // here: business logic that is executed with every job
+  complete.success();
+}
+```
+
+Now, this handler needs to be connected to Zeebe, which is generally done by subscriptions, which internally use long polling to retrieve jobs.
+
+**Open subscription via the Zeebe Java client:**
+
+```java
+zeebeClient
+  .newWorker()
+  .jobType("serviceA")
+  .handler(new ExampleJobHandler())
+  .timeout(Duration.ofSeconds(10))
+  .open()) {waitUntilSystemInput("exit");}
+```
+
+**Open subscription via the Zeebe Node.js client:**
+
+```js
+zbc.createWorker({
+  taskType: "serviceA",
+  taskHandler: handler,
+});
+```
+
+You can also use integrations in certain programming frameworks, like the [Camunda Spring Boot Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started) in the Java world, which starts the job worker and implements the subscription automatically in the background for your glue code.
+
+**A subscription for your glue code is opened automatically by the Spring integration:**
+
+```java
+@JobWorker(type = "serviceA")
+public void handleJobFoo(final JobClient client, final ActivatedJob job) {
+  // here: business logic that is executed with every job
+  // you do not need to call "complete" on the job, as autoComplete is turned on above
+}
+```
+
+There is also documentation on [how to write a good job worker](https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.programming-glue-code.md

@@ -0,0 +1,15 @@
+# Connecting the workflow engine with your world — Programming glue code
+
+To write code that connects to Zeebe, you typically embed [the Zeebe client library](https://docs.camunda.io/docs/next/apis-tools/working-with-apis-tools) into your application. An application can of course also be a service or microservice.
+
+If you have multiple applications that connect to Zeebe, all of them will require the client library. If you want to use a programming language where no such client library exists, you can [generate a gRPC client yourself](https://camunda.com/blog/2018/11/grpc-generating-a-zeebe-python-client/).
+
+![Clients to Zeebe](connecting-the-workflow-engine-with-your-world-assets/clients.png)
+
+Your application can basically do two things with the client:
+
+1. **Actively call Zeebe**, for example, to start process instances, correlate messages, or deploy process definitions.
+2. **Subscribe to tasks** created in the workflow engine in the context of BPMN service tasks.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.recommendation.md

@@ -0,0 +1,18 @@
+# Connecting the workflow engine with your world — Recommendation
+
+As a general rule of thumb, prefer custom glue code whenever you don’t have a good reason to go with an existing connector.
+
+A good reason to use connectors is if you need to solve complex integrations where little customization is needed, such as the [Camunda RPA bridge](https://docs.camunda.org/manual/latest/user-guide/camunda-bpm-rpa-bridge/) to connect RPA bots (soon to be available for Camunda 8).
+
+Good use of connectors are also scenarios where you don’t need custom glue code. For example, when orchestrating serverless functions on AWS with the [AWS Lambda connector](https://github.com/camunda-community-hub/zeebe-lambda-worker). This connector can be operated once and used in different processes.
+
+Some use cases also allow you to create a **reusable generic adapter**; for example, to send status events to your business intelligence system.
+
+But there are also common downsides with connectors. First, the possibilities are limited to what the creator of the connector has foreseen. In reality, you might have slightly different requirements and hit a limitation of a connector.
+
+Second, the connector requires you to operate this connector in addition to your own application. The complexity associated with this depends on your environment.
+
+Third, testing your glue code gets harder, as you can’t easily hook in mocks into such a connector as you could in your own glue code.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world

package/.llms/chunks/components.best-practices.development.connecting-the-workflow-engine-with-your-world.technology-examples.md

@@ -0,0 +1,47 @@
+# Connecting the workflow engine with your world — Technology examples
+
+Most projects want to connect to specific technologies. Currently, most people ask for REST, messaging, or Kafka.
+
+REST and messaging are common core integration patterns. Kafka is different: it is optional infrastructure that you would typically introduce for event streaming or broader event-driven architectures, not because Zeebe requires it to execute workflows.
+
+### REST
+
+You could build a piece of code that provides a REST endpoint in the language of choice and then starts a process instance.
+
+The [Ticket Booking Example](https://github.com/berndruecker/ticket-booking-camunda-cloud) contains an example using Java and Spring Boot for the [REST endpoint](https://github.com/berndruecker/ticket-booking-camunda-cloud/blob/master/booking-service-java/src/main/java/io/berndruecker/ticketbooking/rest/TicketBookingRestController.java#L35).
+
+Similarly, you can leverage the [Spring Boot extension](https://github.com/zeebe-io/spring-zeebe/) to startup job workers that will [execute outgoing REST calls](https://github.com/berndruecker/ticket-booking-camunda-cloud/blob/master/booking-service-java/src/main/java/io/berndruecker/ticketbooking/adapter/GenerateTicketAdapter.java#L29).
+
+![REST example](connecting-the-workflow-engine-with-your-world-assets/rest-example.png)
+
+You can find [Spring Boot sample code for the REST endpoint](https://github.com/berndruecker/flowing-retail/blob/master/zeebe/java/checkout/src/main/java/io/flowing/retail/checkout/rest/ShopRestController.java) in the [Flowing Retail example](https://github.com/berndruecker/flowing-retail).
+
+### Messaging
+
+You can do the same for messages, which is often [AMQP](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol) nowadays.
+
+The [Ticket Booking Example](https://github.com/berndruecker/ticket-booking-camunda-cloud) contains an example for RabbitMQ, Java, and Spring Boot. It provides a message listener to correlate incoming messages with waiting process instances, and [glue code to send outgoing messages onto the message broker](https://github.com/berndruecker/ticket-booking-camunda-cloud/blob/master/booking-service-java/src/main/java/io/berndruecker/ticketbooking/adapter/RetrievePaymentAdapter.java).
+
+![Messaging example](connecting-the-workflow-engine-with-your-world-assets/messaging-example.png)
+
+[Service integration patterns](https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns) goes into details of if you want to use a send and receive task here, or prefer simply one service task (spoiler alert: send and receive tasks are used here because the payment service might be long-running; think about expired credit cards that need to be updated or wire transfers that need to happen).
+
+<!-- The same concept will apply to other programming languages. For example, you could use the [Node.js client for RabbitMQ](https://www.rabbitmq.com/tutorials/tutorial-one-javascript.html) and the [Node.js client for Zeebe](https://github.com/camunda-community-hub/zeebe-client-node-js) to create the same type of glue code as shown above. -->
+
+### Apache Kafka
+
+Kafka is not required for Camunda 8 or Zeebe to work. Zeebe executes workflows itself, while Kafka can optionally be used as an event backbone around the workflow engine.
+
+Typical Kafka-based patterns are:
+
+- **Kafka to Zeebe**: Consume records from a Kafka topic and translate them into Zeebe API calls, such as starting a process instance or correlating a message.
+- **Zeebe to Kafka**: When a workflow reaches a service task or other integration point, write a record to Kafka so downstream systems can react asynchronously.
+
+You can implement these patterns with custom glue code. The [Flowing Retail example](https://github.com/berndruecker/flowing-retail) shows this using Java, Spring Boot, and Spring Cloud Streams. There is [code to subscribe to a Kafka topic and start new process instances for new records](https://github.com/berndruecker/flowing-retail/blob/master/kafka/java/order-zeebe/src/main/java/io/flowing/retail/kafka/order/messages/MessageListener.java#L39), and there is some glue code to create new records when a process instance executes a service task. Of course, you could also use other frameworks to achieve the same result.
+
+This means Kafka is a good fit if you already use Kafka, need loose coupling, or want to broadcast workflow-related events to multiple consumers. If you simply need to call a remote system from a workflow, a job worker or connector is often the more direct option.
+
+![Kafka Example](connecting-the-workflow-engine-with-your-world-assets/kafka-example.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/connecting-the-workflow-engine-with-your-world