@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-process-tests-in-java-testing-your-process-in-chunks.md

@@ -0,0 +1,161 @@
+# Testing process definitions — Writing process tests in Java — Testing your process in chunks
+
+Divide and conquer by _testing your process in chunks_. Consider the important chunks and paths the invoice approval process consists of:
+
+Diagram (BPMN):
+  start "Invoice received" → user task "Approve invoice" → exclusive gateway "Approved?"
+    — [yes] service task "Archive invoice" → service task "Add invoice to accounting system" → end "Invoice approved"
+    — [no] service task "Send invoice rejection" → end "Invoice rejected"
+
+**(1)**
+
+The _happy path_: The invoice gets approved.
+
+**(2)**
+
+The invoice gets rejected.
+
+**(3)**
+
+A timeout on waiting for approval leads to an automatic approval.
+
+**(4)**
+
+An approved invoice can't get archived.
+
+#### Testing the happy path
+
+The happy path is kind of the default scenario with a positive outcome, so no exceptions or errors or deviations are experienced.
+
+Fully test the happy path in one (big) test method. This makes sure you have one consistent data flow in your process. Additionally, it is easy to read and to understand, making it a great starting point for new developers to understand your process and process test case.
+
+You were already exposed to the happy path in our example, which is the scenario that the invoice gets approved:
+
+```java
+@Test
+public void happyPath() throws Exception {
+    final HashMap<String, Object> variables = new HashMap<String, Object>();
+    variables.put("approver", "Zee");
+    variables.put("invoice", objectMapper.readTree(invoiceJson));
+
+    // Kick off the process instance // <1>
+    final var processInstance =
+        client
+            .newCreateInstanceCommand()
+            .bpmnProcessId("Process_InvoiceApproval")
+            .latestVersion()
+            .variables(variables)
+            .send()
+            .join();
+
+    // assert the User Task and simulate a human decision // <2>
+    assertThat(byElementId("UserTask_ApproveInvoice")).isCreated().hasAssignee("Zee");
+    processTestContext.completeUserTask(
+        byElementId("UserTask_ApproveInvoice"), Map.of("approved", true));
+
+    // This should make the process instance execute till the end // <3>
+    assertThat(processInstance)
+        .hasCompletedElementsInOrder(
+            byId("StartEvent_InvoiceReceived"),
+            byId("UserTask_ApproveInvoice"),
+            byId("ServiceTask_ArchiveInvoice"),
+            byId("ServiceTask_AddInvoiceAccounting"),
+            byId("EndEvent_InvoiceApproved"))
+        .isCompleted();
+
+    // verify that side effects have happened // <4>
+    verify(archiveService).archiveInvoice("INV-1001", objectMapper.readTree(invoiceJson));
+    verify(accountingService).addInvoiceToAccount("0815", "INV-1001");
+  }
+```
+
+#### Testing detours
+
+Test _forks/detours_ from the happy path as well as _errors/exceptional_ paths as chunks in separate test methods. This allows to unit test in meaningful units.
+
+The tests for the exceptional paths are basically very similar to the happy path in our example.
+
+**(2)**
+
+The invoice gets rejected:
+
+```java
+@Test
+public void testRejectionPath() throws Exception {
+    final HashMap<String, Object> variables = new HashMap<String, Object>();
+    variables.put("approver", "Zee");
+    variables.put("invoice", objectMapper.readTree(invoiceJson));
+
+    // We skip HTTP for the simple unit test - mock the http connector
+    processTestContext.mockJobWorker("io.camunda:http-json:1").thenComplete();
+
+    // Kick of the process instance
+    final var processInstance =
+        client
+            .newCreateInstanceCommand()
+            .bpmnProcessId("Process_InvoiceApproval")
+            .latestVersion()
+            .variables(variables)
+            .send()
+            .join();
+
+    // assert the User Task and simulate a human decision
+    assertThat(byElementId("UserTask_ApproveInvoice")).isCreated().hasAssignee("Zee");
+    processTestContext.completeUserTask(
+        byElementId("UserTask_ApproveInvoice"),
+        Map.of( //
+            "approved",
+            false, //
+            "rejectionReason",
+            "it is a test case :-)"));
+
+    // This should make the process instance execute till the end
+    assertThat(processInstance)
+        .hasCompletedElementsInOrder(
+            byId("StartEvent_InvoiceReceived"),
+            byId("UserTask_ApproveInvoice"),
+            byId("Gateway_Approved"),
+            byId("ServiceTask_SendRejection"),
+            byId("EndEvent_InvoiceRejected"))
+        .isCompleted();
+  }
+```
+
+**(3)**
+
+A timeout on waiting for approval leads to an automatic approval:
+
+```java
+@Test
+public void testApprovalTimeout() throws Exception {
+    final HashMap<String, Object> variables = new HashMap<String, Object>();
+    variables.put("approver", "Zee");
+    variables.put("invoice", objectMapper.readTree(invoiceJson));
+
+    final var processInstance =
+        client
+            .newCreateInstanceCommand()
+            .bpmnProcessId("Process_InvoiceApproval")
+            .latestVersion()
+            .variables(variables)
+            .send()
+            .join();
+
+    // assert the User Task and simulate the timeout
+    assertThat(processInstance).hasActiveElements("UserTask_ApproveInvoice");
+    processTestContext.increaseTime(Duration.ofDays(5));
+
+    // This should make the process instance auto approve and run till the end
+    assertThat(processInstance)
+        .isCompleted()
+        .hasCompletedElementsInOrder(
+            byId("StartEvent_InvoiceReceived"),
+            byId("ServiceTask_ArchiveInvoice"),
+            byId("ServiceTask_AddInvoiceAccounting"),
+            byId("EndEvent_InvoiceApproved"))
+        .hasTerminatedElements(byId("UserTask_ApproveInvoice"));
+  }
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-process-tests-in-java.md

@@ -0,0 +1,10 @@
+# Testing process definitions — Writing process tests in Java
+
+This section describes how to write process tests as unit tests in Java. We are working on additional information for writing tests in other languages, such as Node.js or C#.
+
+When using Java, most customers use Spring Boot, so we describe this approach in this best practice. While this is a common setup for customers, it is not the only one. Find more examples of plain Java process tests in [Getting Started with Camunda Process Test](https://docs.camunda.io/docs/next/apis-tools/testing/getting-started).
+
+If your process hands a step to an AI agent, the same Camunda Process Test setup applies, but the tool calls the agent makes are not fixed in advance. See [test your AI agents](https://docs.camunda.io/docs/next/components/agentic-orchestration/evaluate-agents/test-ai-agents#step-4-handle-non-deterministic-flow-paths) for more details.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.writing-good-workers.client-library-examples-c.md

@@ -0,0 +1,70 @@
+# Writing good workers — Client library examples — C#
+
+Using the [C# client](https://github.com/camunda/camunda-platform-get-started/tree/master/csharp), you can write worker code like this:
+
+```csharp
+zeebeClient.NewWorker()
+  .JobType("payment")
+  .Handler(JobHandler)
+  .HandlerThreads(3)
+  .Name("MyPaymentWorker")
+  .Open()
+```
+
+You can observe that you can set a number of handler threads. Interestingly, this is a naming legacy. The C# client uses the [Dataflow Task Parallel Library (TPL)](https://docs.microsoft.com/en-us/dotnet/standard/parallel-programming/dataflow-task-parallel-library) to implement parallelism, so the thread count configures the degree of parallelism allowed to TPL in reality. Internally, this is implemented as a mixture of event loop and threading, which is an implementation detail of TPL. This is a great foundation to scale the worker.
+
+You need to provide a handler. For this handler, you have to make sure to write non-blocking code; the following example shows this for a REST call using the [HttpClient](https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpclient?view=net-5.0) library:
+
+```csharp
+private static async void NonBlockingJobHandler(IJobClient jobClient, IJob activatedJob)
+{
+  Log.LogInformation("Invoke REST call...");
+  var response = await httpClient.GetAsync("/");
+  Log.LogInformation("...finished. Complete Job...");
+  var result = await jobClient.NewCompleteJobCommand(activatedJob).Send();
+  counter.inc();
+}
+```
+
+The code is executed in parallel, [as you can observe in the logs](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution/blob/main/results/dotnet-nonblocking.log). Interestingly, the following code runs even faster for me, but [that’s a topic for another discussion](https://stackoverflow.com/questions/21403023/performance-of-task-continuewith-in-non-async-method-vs-using-async-await):
+
+```csharp
+private static void NonBlockingJobHandler(IJobClient jobClient, IJob activatedJob)
+{
+  Log.LogInformation("Invoke REST call...");
+  var response = httpClient.GetAsync("/").ContinueWith( response => {
+    Log.LogInformation("...finished. Complete Job...");
+    jobClient.NewCompleteJobCommand(activatedJob).Send().ContinueWith( result => {
+      if (result.Exception==null) {
+        counter.inc();
+      } else {
+        Log.LogInformation("...could not do REST call because of: " + result.Exception);
+      }
+    });
+  });
+}
+```
+
+In contrast to Node.js, you can also write **blocking code** in C# if you want to (or more probable: it happens by accident):
+
+```csharp
+private static async void BlockingJobHandler(IJobClient jobClient, IJob activatedJob)
+{
+  Log.LogInformation("Invoke REST call...");
+  var response = httpClient.GetAsync("/").Result;
+  Log.LogInformation("...finished. Complete Job...");
+  await jobClient.NewCompleteJobCommand(activatedJob).Send();
+  counter.inc();
+}
+```
+
+The degree of parallelism is down to one again, [according to the logs](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution/blob/main/results/dotnet-blocking-thread-1.log). So C# is comparable to Java, just that the typically used C# libraries are reactive by default, whereas Java still knows just too many blocking libraries. The recommendations for C#:
+
+|              | Blocking code                                                                                                                          | Reactive code                                                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Parallelism  | Some parallelism is possibly by a thread pool, which is used by the client library.                                                    | A processing loop combined with an internal thread pool, both are details of the framework and runtime platform. |
+| **Use when** | **Rarely**, and only if you don't have requirements to process jobs in parallel or might even want to reduce the level or parallelism. | This should be the **default**                                                                                   |
+|              | Your developers are not familiar with reactive programming                                                                             | You need to scale and have IO-intensive glue code (e.g. remote service calls like REST)                          |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.client-library-examples-java-2.md

@@ -0,0 +1,51 @@
+# Writing good workers — Client library examples — Java (2)
+
+This code uses the reactive approach to use the Zeebe API:
+
+```
+client.newCompleteCommand(job.getKey()).send()
+  .thenApply(jobResponse -> {
+    counter.inc();
+    return jobResponse;
+  })
+  .exceptionally(t -> {
+    throw new RuntimeException("Could not complete job: " + t.getMessage(), t);
+  });
+```
+
+With this reactive glue code, you don’t need to worry about thread pools in the workers anymore, as this is handled under the hood from the frameworks or the Java runtime. [You can observe in the logs](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution/blob/main/results/java-nonblocking.log) that many jobs are now executed in parallel — and even by the same thread in a loop within milliseconds.
+
+```
+10:54:07.105 [pool-4-thread-1] Invoke REST call…
+[…] 30–40 times!
+10:54:07.421 [pool-4-thread-1] Invoke REST call…
+10:54:07.451 [ctor-http-nio-3] …finished. Complete Job…
+10:54:07.451 [ctor-http-nio-7] …finished. Complete Job…
+10:54:07.451 [ctor-http-nio-2] …finished. Complete Job…
+10:54:07.451 [ctor-http-nio-5] …finished. Complete Job…
+10:54:07.451 [ctor-http-nio-1] …finished. Complete Job…
+10:54:07.451 [ctor-http-nio-6] …finished. Complete Job…
+10:54:07.451 [ctor-http-nio-4] …finished. Complete Job…
+[…]
+10:54:08.090 [pool-4-thread-1] Invoke REST call…
+10:54:08.091 [pool-4-thread-1] Invoke REST call…
+[…]
+10:54:08.167 [ault-executor-2] …completed (56). Current throughput (jobs/s ): 56, Max: 56
+10:54:08.167 [ault-executor-1] …completed (54). Current throughput (jobs/s ): 54, Max: 54
+10:54:08.167 [ault-executor-0] …completed (55). Current throughput (jobs/s ): 55, Max: 55
+```
+
+These observations yield the following recommendations for Java:
+
+|              | Blocking code on platform threads                                                                                                                                                      | Blocking code on virtual threads                                                                                      | Reactive code                                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Parallelism  | Some parallelism is possible with a thread pool, which is used by the client library. The default thread pool size is one, which needs to be adjusted in the config in order to scale. | Many blocked operations can run concurrently without tying each blocked operation to a platform thread.               | A processing loop combined with an internal thread pool, both are details of the framework and runtime platform.                           |
+| **Use when** | You don't have requirements to process jobs in parallel.                                                                                                                               | You use Java 21 or later, need to process I/O-bound jobs in parallel, and want to keep straightforward blocking code. | Your client stack already uses reactive programming, or you need extremely high throughput or low latency and have measured the tradeoffs. |
+|              | You intentionally want to limit parallelism with a small worker thread pool.                                                                                                           | This should be the default for Java workers that need parallel I/O and don't otherwise require reactive programming.  | Your developers are familiar with reactive programming and the added complexity is acceptable.                                             |
+
+#### Size `maxJobsActive` against execution threads
+
+For workers backed by a fixed execution thread pool (blocking or virtual threads), `maxJobsActive` defines the queue length and bounds the number of jobs a worker holds at once, but it isn't a throughput knob: throughput is `numJobWorkerExecutionThreads / handlerDuration`. Increasing `maxJobsActive` beyond what your execution threads and job timeouts can support only lengthens the queue within the worker; it does not make jobs complete faster.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.client-library-examples-java-3.md

@@ -0,0 +1,17 @@
+# Writing good workers — Client library examples — Java (3)
+
+Size `maxJobsActive` so your worker's queue stays within its job deadlines, with some margin:
+
+```text
+maxJobsActive < numJobWorkerExecutionThreads × (jobTimeout / averageHandlerDuration)
+```
+
+For example, with 30 execution threads, a job timeout of 1,800 ms, and an average handler duration of 300 ms, `maxJobsActive` should remain below 180 (`30 × (1800 / 300)`). A higher value allows more jobs to queue behind busy threads than can be completed before their deadlines. As a result, jobs may time out and be redelivered to other workers instead of completing.
+
+Size the job timeout against your worst-case handler duration, not the average. The timeout serves two purposes at once: it's the broker's deadline for redelivering a job to another worker, and, if [job streaming](https://docs.camunda.io/docs/next/components/concepts/job-workers#job-streaming) is enabled, it also determines how long a pushed job can wait for an available capacity slot before it is dropped and retried. A handler that occasionally takes longer than average will exceed a timeout sized only for the average case.
+
+**Note**
+This formula and the `maxJobsActive` capacity model it describes are specific to the Java client’s worker implementation, which uses a shared semaphore to limit both pushed and polled jobs. Other client SDKs implement worker capacity differently. Check your client’s documentation for the equivalent tuning parameters.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.client-library-examples-java.md

@@ -0,0 +1,91 @@
+# Writing good workers — Client library examples — Java
+
+Using the [Java Client](https://github.com/camunda/camunda-platform-get-started/tree/master/java) you can write worker code like this:
+
+```java
+client.newWorker().jobType("retrieveMoney")
+  .handler((jobClient, job) -> {
+     //...
+  }).open();
+```
+
+The [Camunda Spring Boot Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started) provides a more elegant way of writing this, but also uses a normal worker from the Java client underneath. In this case, your code might look like this:
+
+```java
+@JobWorker(type = "retrieveMoney", autoComplete = false)
+public void retrieveMoney(final JobClient client, final ActivatedJob job) {
+  //...
+}
+```
+
+In the background, a worker starts a polling component and [a thread pool](https://github.com/camunda-cloud/zeebe/blob/d24b31493b8e22ad3405ee183adfd5a546b7742e/clients/java/src/main/java/io/camunda/zeebe/client/impl/ZeebeClientImpl.java#L179-L183) to [handle the polled jobs](https://github.com/camunda/camunda/blob/d24b31493b8e22ad3405ee183adfd5a546b7742e/clients/java/src/main/java/io/camunda/zeebe/client/impl/worker/JobPoller.java#L109-L111). The [**default thread pool size is one**](https://github.com/camunda-cloud/zeebe/blob/760074f59bc1bcfb483fab4645501430f362a475/clients/java/src/main/java/io/camunda/zeebe/client/impl/ZeebeClientBuilderImpl.java#L49). If you need more, you can enable a thread pool:
+
+```java
+ZeebeClient client = ZeebeClient.newClientBuilder()
+  .numJobWorkerExecutionThreads(5)
+  .build();
+```
+
+In the Camunda Spring Boot Starter, you can do this using a [configuration](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/configuration#execution-threads).
+
+Now, you can **leverage blocking code** for your REST call, for example, the `RestTemplate` inside Spring:
+
+```java
+@JobWorker(type = "rest", autoComplete = false)
+public void blockingRestCall(final JobClient client, final ActivatedJob job) {
+  LOGGER.info("Invoke REST call...");
+  String response = restTemplate.getForObject( // <-- blocking call
+    PAYMENT_URL, String.class);
+  LOGGER.info("...finished. Complete Job...");
+  client.newCompleteCommand(job.getKey()).send()
+    .join(); // <-- this blocks to wait for the response
+  LOGGER.info(counter.inc());
+}
+```
+
+Doing so **limits** the degree of parallelism to the number of threads you have configured. You can [observe in the logs](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution/blob/main/results/java-blocking-thread-1.log) that jobs are executed sequentially when running with one thread ([the code is available on GitHub)](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution/blob/main/java-worker/src/main/java/io/berndruecker/experiments/cloudclient/java/RestInvocationWorker.java):
+
+```
+10:57:00.258 [pool-4-thread-1] Invoke REST call…
+10:57:00.258 [ault-executor-0] Activated 32 jobs for worker default and job type rest
+10:57:00.398 [pool-4-thread-1] …finished. Complete Job…
+10:57:00.446 [pool-4-thread-1] …completed (1). Current throughput (jobs/s ): 1
+10:57:00.446 [pool-4-thread-1] Invoke REST call…
+10:57:00.562 [pool-4-thread-1] …finished. Complete Job…
+10:57:00.648 [pool-4-thread-1] …completed (2). Current throughput (jobs/s ): 2
+10:57:00.648 [pool-4-thread-1] Invoke REST call…
+10:57:00.764 [pool-4-thread-1] …finished. Complete Job…10:57:00.805 [pool-4-thread-1] …completed (3). Current throughput (jobs/s ): 3
+```
+
+If you experience a large number of jobs, and these jobs are waiting for IO the whole time — as REST calls do — Java 21 virtual threads are usually a good default. You can also use **reactive programming**, especially for extremely high-throughput or low-latency scenarios where you have measured that its lower overhead matters. For the REST call, this means for example the Spring WebClient:
+
+```java
+@JobWorker(type = "rest", autoComplete = false)
+public void nonBlockingRestCall(final JobClient client, final ActivatedJob job) {
+  LOGGER.info("Invoke REST call...");
+  Flux<String> paymentResponseFlux = WebClient.create()
+    .get().uri(PAYMENT_URL).retrieve()
+    .bodyToFlux(String.class);
+
+  // non-blocking, so we register the callbacks (for happy and exceptional case)
+  paymentResponseFlux.subscribe(
+    response -> {
+      LOGGER.info("...finished. Complete Job...");
+      client.newCompleteCommand(job.getKey()).send()
+         // non-blocking, so we register the callbacks (for happy and exceptional case)
+         .thenApply(jobResponse -> { LOGGER.info(counter.inc()); return jobResponse;})
+         .exceptionally(t -> {throw new RuntimeException("Could not complete job: " + t.getMessage(), t);});
+    },
+    exception -> {
+       LOGGER.info("...REST invocation problem: " + exception.getMessage());
+       client.newFailCommand(job.getKey())
+         .retries(1)
+         .errorMessage("Could not invoke REST API: " + exception.getMessage()).send()
+         .exceptionally(t -> {throw new RuntimeException("Could not fail job: " + t.getMessage(), t);});
+    }
+  );
+}
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.client-library-examples-node.js-client.md

@@ -0,0 +1,37 @@
+# Writing good workers — Client library examples — Node.js client
+
+Using the [Node.js client](https://github.com/camunda/camunda-8-js-sdk), your worker code will look like this, assuming that you use Axios to do rest calls (but of course any other library is fine as well):
+
+```js
+zbc.createWorker({
+  taskType: "rest",
+  taskHandler: (job) => {
+    console.log("Invoke REST call...");
+    axios
+      .get(PAYMENT_URL)
+      .then((response) => {
+        console.log("...finished. Complete Job...");
+        job.complete().then((result) => {
+          incCounter();
+        });
+      })
+      .catch((error) => {
+        job.fail("Could not invoke REST API: " + error.message);
+      });
+  },
+});
+```
+
+This is **reactive code**. And a really interesting observation is that reactive programming is so deep in the JavaScript language that it is impossible to write blocking code, even code that looks blocking is still [executed in a non-blocking fashion](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution/blob/main/results/nodejs-blocking.log).
+
+Node.js code scales pretty well and there is no specific thread pool defined or necessary. The Camunda 8 Node.js client library also [uses reactive programming internally](https://github.com/camunda/camunda-8-js-sdk/blob/main/src/zeebe/zb/ZBWorker.ts#L27).
+
+This makes the recommendation very straight-forward:
+
+|              | Reactive code                  |
+| ------------ | ------------------------------ |
+| Parallelism  | Event loop provided by Node.js |
+| **Use when** | Always                         |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.client-library-examples.md

@@ -0,0 +1,6 @@
+# Writing good workers — Client library examples
+
+Let’s go through a few code examples using Java, Node.js, and C#, using the corresponding client libraries. All [code is available on GitHub](https://github.com/berndruecker/camunda-cloud-clients-parallel-job-execution) and a [walk through recording is available on YouTube](https://youtu.be/ZHKz9l5yG3Q).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.md

@@ -0,0 +1,12 @@
+# Writing good workers
+
+Service tasks within Camunda 8 require you to set a task type and implement job workers who perform whatever needs to be performed.
+
+[Service tasks](https://docs.camunda.io/docs/next/components/modeler/bpmn/service-tasks/service-tasks) within Camunda 8 require you to set a task type and implement [job workers](https://docs.camunda.io/docs/next/components/concepts/job-workers) who perform whatever needs to be performed. This describes that you might want to:
+
+1. Write all glue code in one application, separating different classes or functions for the different task types.
+2. Think about idempotency and read or write as little data as possible from/to the process.
+3. If you use Java 21 or later, prefer virtual threads for parallel workers that perform blocking I/O. Use reactive or async code when your runtime already uses it, or when you need extremely high throughput or low latency.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.organizing-glue-code-and-workers-in-process-solutions.md

@@ -0,0 +1,44 @@
+# Writing good workers — Organizing glue code and workers in process solutions
+
+Assume the following order fulfillment process, that needs to invoke three synchronous REST calls to the responsible systems (payment, inventory, and shipping) via custom glue code:
+
+![order fulfillment example](writing-good-workers-assets/order-fulfillment-process.png)
+
+Should you create three different applications with a worker for one task type each, or would it be better to process all task types within one application?
+
+As a rule of thumb, we recommend implementing **all glue code in one application**, which then is the so-called **process solution** (as described in [Practical Process Automation](https://processautomationbook.com/)). This process solution might also include the BPMN process model itself, deployed during startup. Thus, you create a self-contained application that is easy to version, test, integrate, and deploy.
+
+![Process solution](writing-good-workers-assets/process-solution.png)
+Figure taken from [Practical Process Automation](https://processautomationbook.com/)
+
+Thinking of Java, the three REST invocations might live in three classes within the same package (showing only two for brevity):
+
+```java
+public class RetrieveMoneyWorker {
+  @JobWorker(type = "retrieveMoney", autoComplete = false)
+  public void retrieveMoney(final JobClient client, final ActivatedJob job) {
+    // ... code
+  }
+}
+```
+
+```java
+public class FetchGoodsWorker {
+  @JobWorker(type = "fetchGoods", autoComplete = false)
+  public void fetchGoods(final JobClient client, final ActivatedJob job) {
+    // ... code
+  }
+}
+```
+
+You can also pull the glue code for all task types into one class. Technically, it does not make any difference and some people find that structure in their code easier. If in doubt, the default is to create one class per task type.
+
+There are exceptions when you might not want to have all glue code within one application:
+
+1. You need to specifically control the load for one task type, like _scaling it out_ or _throttling it_. For example, if one service task is doing PDF generation, which is compute-intensive, you might need to scale it much more than all other glue code. On the other hand, it could also mean limiting the number of parallel generation jobs due to licensing limitations of your third-party PDF generation library.
+2. You want to write glue code in different programming languages, for example, because writing specific logic in a specific language is much easier (like using Python for certain AI calculations or Java for certain mainframe integrations).
+
+In this case, you would spread your workers into different applications. Most often, you might still have a main process solution that will also still deploy the process model. Only specific workers are carved out.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.performance-best-practices.md

@@ -0,0 +1,18 @@
+# Writing good workers — Performance best-practices
+
+Most of the business logic in your process models will likely end up being worked on as a job. As such, optimizing how jobs are handled in Zeebe can have
+a big impact on the performance of your system as a whole. Here are some best practices to keep things running smoothly.
+
+### Reduce latency by enabling job streaming
+
+We recommend enabling [job streaming](https://docs.camunda.io/docs/next/components/concepts/job-workers#job-streaming) in order to reduce latency to a maximum. Essentially, when using long polling,
+your job workers have to periodically poll every partition in your Zeebe cluster to check if there are new jobs available. Additionally, they have to
+balance polling aggressively with minimizing their impact on the cluster, which still has to handle all requests, even when no jobs are available. In large clusters, this can add a noticeable delay in the order of seconds, which can be unacceptable for certain workloads.
+
+> [!Note]
+> You can read more about the difference between long polling and job streaming [in this blog post](https://camunda.com/blog/2024/03/reducing-job-activation-delay-zeebe/).
+
+As such, we recommend using job streaming if possible.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.scaling-workers-blocking-code-with-virtual-threads.md

@@ -0,0 +1,8 @@
+# Writing good workers — Scaling workers — Blocking code with virtual threads
+
+Virtual threads let you keep a straightforward blocking programming model while avoiding the cost of assigning one platform thread to every blocked operation. This makes them a good default for Java workers that spend most of their time waiting for I/O, such as REST calls or database requests.
+
+Use virtual threads when you run on Java 21 or later and want to process many I/O-bound jobs in parallel without rewriting your worker code into a reactive style. Reactive programming can still be useful for extremely high-throughput or low-latency scenarios where the lower overhead matters enough to justify the added complexity.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.scaling-workers-blocking-synchronous-code-and-thread-pools.md

@@ -0,0 +1,12 @@
+# Writing good workers — Scaling workers — Blocking / synchronous code and thread pools
+
+With blocking code a thread needs to wait (is blocked) until something finishes before it can move on. In the above example, making a REST call requires the client to wait for IO — the response. The CPU cannot compute anything during this time period, however, the thread cannot do anything else.
+
+Assume that your worker shall invoke 20 REST requests, each taking around 100ms, this will take 2s in total to process. Your throughput can’t go beyond 10 jobs per second with one thread.
+
+A common approach to scaling throughput beyond this limit is to leverage a thread pool. This works as blocked threads are not actively consuming CPU cores, so you can run more threads than CPU cores — since they are only waiting for I/O most of the time. In the above example with 100ms latency of REST calls, having a thread pool of 10 threads increases throughput to 100 jobs/second.
+
+The downside of using thread pools is that you need to have a good understanding of your code, thread pools in general, and the concrete libraries being used. Typically, we do not recommend configuring platform thread pools yourself. In Java 21 and later, prefer virtual threads for workers that perform blocking I/O.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.scaling-workers-non-blocking-reactive-code.md

@@ -0,0 +1,8 @@
+# Writing good workers — Scaling workers — Non-blocking / reactive code
+
+Reactive programming uses a different approach to achieve parallel work: extract the waiting part from your code.
+
+With a reactive HTTP client you will write code to issue the REST request, but then not block for the response. Instead, you define a callback as to what happens if the request returns. Most of you know this from JavaScript programming. Thus, the runtime can optimize the utilization of threads itself, without you the developer even knowing.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.scaling-workers-recommendation.md

@@ -0,0 +1,6 @@
+# Writing good workers — Scaling workers — Recommendation
+
+In Java 21 and later, prefer virtual threads for I/O-bound job workers that need parallel processing. They keep worker code easier to read while avoiding most of the scalability limits of platform threads. Use reactive programming when your client stack already uses it, or when you need extremely high throughput or low latency and have measured that the lower overhead is worth the complexity.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.scaling-workers.md

@@ -0,0 +1,12 @@
+# Writing good workers — Scaling workers
+
+If you need to process a lot of jobs, you need to think about optimizing your workers.
+
+Workers can control the number of jobs retrieved at once. In a busy system it makes sense to not only request one job, but probably 20 or even up to 50 jobs in one remote request to the workflow engine, and then start working on them locally. In a lesser utilized system, long polling is used to avoid delays when a job comes in. Long polling means the client’s request to fetch jobs is blocked until a job is received (or some timeout hits). Therefore, the client does not constantly need to ask.
+
+You will have jobs in your local application that need to be processed. The worst case in terms of scalability is that you process the jobs sequentially one after the other. While this sounds bad, it is still a valid approach for many use cases, as most projects do not need any parallel processing in the worker code as they simply do not care whether a job is executed a second earlier or later. Think of a business process that is executed only some hundred times per day and includes mostly human tasks — a sequential worker is totally sufficient. In this case, you can skip this paragraph section.
+
+However, you might need to do better and process jobs in parallel. In such a case, you should read on and understand the difference between writing blocking code on platform threads, blocking code on virtual threads, and non-blocking code.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.development.writing-good-workers.thinking-about-transactions-exceptions-and-idempotency-of-workers.md

@@ -0,0 +1,22 @@
+# Writing good workers — Thinking about transactions, exceptions and idempotency of workers
+
+Visit [dealing with problems and exceptions](https://docs.camunda.io/docs/next/components/best-practices/development/dealing-with-problems-and-exceptions) to gain a better understanding of how workers deal with transactions and exceptions to the happy path, and find more details on how to write idempotent workers.
+
+
+## Data minimization in workers
+
+If performance or efficiency matters in your scenario, there are two rules about data in your workers you should be aware of:
+
+1. Minimize what data you read for your job. In your job client, you can define which process variables you will need in your worker, and only these will be read and transferred, saving resources on the broker as well as network bandwidth.
+2. Minimize what data you write on job completion. You should explicitly not transmit the input variables of a job upon completion, which might happen easily if you simply reuse the map of variables you received as input for submitting the result.
+
+Not transmitting all variables saves resources and bandwidth, but serves another purpose as well: upon job completion, these variables are written to the process and might overwrite existing variables. If you have parallel paths in your process (e.g. [parallel gateway](https://docs.camunda.io/docs/next/components/modeler/bpmn/parallel-gateways/parallel-gateways), [multiple instance](https://docs.camunda.io/docs/next/components/modeler/bpmn/multi-instance/multi-instance)) this can lead to race conditions that you need to think about. The less data you write, the smaller the problem.
+
+While the easiest way is to avoid large variables, one option to keep things light during job activation is to use the `FetchVariables` parameter.
+Remember, by default, when this parameter is omitted, the job payload will contain _all_ variables visible within the scope ([see the variables documentation for more on that](https://docs.camunda.io/docs/next/components/concepts/variables).
+This could mean tens or more variables, of arbitrary size, and it can be difficult to estimate how much this will represent in general.
+
+We recommend you use the `FetchVariables` parameter, and only fetch the variables which your job handler needs. This will keep the amount of data transferred to a minimum, and will greatly help performance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/writing-good-workers

package/.llms/chunks/components.best-practices.management.doing-a-proper-poc.defining-a-scope-relevant-to-your-business-involving-the-right-people.md

@@ -0,0 +1,12 @@
+# Doing a proper POC — Defining a scope relevant to your business — Involving the right people
+
+It does make sense to implement a POC together with the software vendor and/or specialized consultants to get _quick results_ and _focused feedback_ with respect to your specific challenges. However, you should always at least _co-develop_ the POC to really understand what is going on.
+
+When planning for your team, consider that successful process modeling requires not just knowledge about the business and the targeted technical solution, but experience with BPMN modeling and methodology as well as analytical and moderation skills. We therefore typically bring together _business people_ with _IT staff_ and internal _business analysts_, _train them properly_ and let them continue to _learn on the job_ by carrying out the POC together with an _experienced consultant_. A team size of up to a maximum of _four people_ has proven to be quite optimal.
+
+In case you want to access _system interfaces_ during your POC, also determine who will be a technically knowledgeable and available _contact person_ for that system. To integrate into existing _user interfaces_, you might need help from colleagues within your organization.
+
+Define a _moderator_ to avoid too many detours and keep your POC on track.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/management/doing-a-proper-poc