Merge branch 'release/0.3.0'

Author: zambrovski

docs/process-engine-worker.md

@@ -0,0 +1,82 @@
+---
+title: Process Engine Worker
+---
+
+Process Engine Worker is an independent component built on top of Process Engine API in order to accelerate the development of agnostic workers
+for any process engine supported by Process Engine API in Spring Boot ecosystem. By doing so, it abstracts from specific worker clients and 
+API and allows to build universal workers.
+
+First of all add the Process Engine Worker dependency to you project classpath. In Maven add the following to you `pom.xml`:
+
+```xml
+<dependency>
+  <groupId>dev.bpm-crafters.process-engine-worker</groupId>
+  <artifactId>process-engine-worker-spring-boot-starter</artifactId>
+  <version>${process-engine-worker.version}</version>
+</dependency>
+```
+
+Now create a simple Spring component and annotate a method with a special annotation `@ProcessEngineWorker`:
+
+```java
+@Component
+@RequiredArgsConstructor
+public class MySmartWorker {
+
+  private final FetchGoodsInPort fetchGoodsInPort;
+
+  @ProcessEngineWorker(topic = "fetchGoods")
+  public Map<String, Object> fetchGoods(
+    @Variable(name = "order") Order order
+  ) {
+    // execute some business code
+    var fetched = fetchGoodsInPort.fetchGoods(order);
+    
+    return Map.of("shipped", fetched);
+  }
+}
+```
+
+## Method parameter resolution
+
+Parameter resolution of the method annotated with `ProcessEngineWorker` is based on a set of strategies
+registered by the `ParameterResolver` bean. Currently, the following parameters are resolved:
+
+| Type                                   | Purpose                                                                   |
+|----------------------------------------|---------------------------------------------------------------------------|
+| TaskInformation                        | Helper abstracting all information about the external task.               |
+| ExternTaskCompletionApi                | API for completing the external task manually                             |
+| VariableConverter                      | Special utility to read the process variable map and deliver typed value  | 
+| Map<String, Object>                    | Payload object containing all variables.                                  |
+| Type annotated with @Variable("name")  | Marker for a process variable.                                            |
+
+Usually, the requested variable is mandatory and the parameter resolver reports an error, if the requested variable is not
+available in the process payload. If you want to inject the variable only if it exists in the payload you have two options.
+Either you set the parameter `@Variable(name = "...", mandatory = false)` or you use `Optional<T>` instead of `T` as a variable
+type. If you are using Kotlin and don't like `Optional`, make sure to declare variable type as nullable (`T?` instead of `T`) and
+set the mandatory flag to `false`. 
+
+## Method return type
+
+If the return type of the method is of type `Map<String, Object>` or compatible and the `autoComplete` flag is turned
+on the annotation (defaults to `true`), the library will try to automatically complete the External Task
+using the returned map as completion variables. If `autoComplete` is `true`, but no return value is provided, the task
+will be completed without empty payload. This functionality is provided by the `ResultResolver` based on registered strategies.
+
+## Throwing a BPMN Error
+
+If you want to throw a BPMN error, please throw an instance of a `BPMNErrorOccured` exception from the method body. The exception
+is a checked exception, in order to comply with Spring behavior of not rolling back transaction on checked exceptions.
+
+## Transactional support
+
+The worker method can be marked transactional by adding Spring or Jakarta EE transactional annotations to the method or to the worker class.
+If the annotation `@org.springframework.transaction.annotation.Transactional` with propagation `REQUIRES`, `REQUIRES_NEW`, `SUPPORTS` and `MANDATORY`
+is used, the library will execute the worker method and the completion of the external task via API in the same transaction. This will lead to 
+a transaction rollback, if the external task can't be completed (e.g. due to a network error).
+
+
+
+
+
+

examples/camunda7-remote-starter-native/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>dev.bpm-crafters.process-engine-worker</groupId>
     <artifactId>process-engine-worker-examples</artifactId>
-    <version>0.2.0</version>
+    <version>0.3.0</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 

examples/order-fulfillment/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>dev.bpm-crafters.process-engine-worker</groupId>
     <artifactId>process-engine-worker-examples</artifactId>
-    <version>0.2.0</version>
+    <version>0.3.0</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 

examples/order-fulfillment/src/main/java/dev/bpmcrafters/example/order/fulfillment/order/adapter/out/usertasks/UserTaskPool.java

@@ -25,7 +25,6 @@
 public class UserTaskPool implements UserTaskOutPort {
 
   private final TaskSubscriptionApi subscriptionApi;
-
   private final ConcurrentHashMap<TaskInformation, Map<String, ?>> tasks = new ConcurrentHashMap<>();
 
   @PostConstruct
@@ -48,8 +47,8 @@ public void subscribe() throws ExecutionException, InterruptedException {
             tasks.put(taskInformation, payload);
           }
         },
-        taskId -> {
-          tasks.keySet().stream().filter(ti -> ti.getTaskId().equals(taskId)).findFirst().ifPresent(ti -> {
+        (TaskInformation taskInformation) -> {
+          tasks.keySet().stream().filter(ti -> ti.getTaskId().equals(taskInformation.getTaskId())).findFirst().ifPresent(ti -> {
             tasks.remove(ti);
             log.info("EXAMPLE: <USER TASKS> Removed user task {} ({}:{})",
               ti.getTaskId(),

examples/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>dev.bpm-crafters.process-engine-worker</groupId>
     <artifactId>process-engine-worker-root</artifactId>
-    <version>0.2.0</version>
+    <version>0.3.0</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 

pom.xml

@@ -11,16 +11,16 @@
 
   <groupId>dev.bpm-crafters.process-engine-worker</groupId>
   <artifactId>process-engine-worker-root</artifactId>
-  <version>0.2.0</version>
+  <version>0.3.0</version>
   <name>${project.artifactId}</name>
   <description>Process Engine Worker</description>
   <url>https://github.com/bpm-crafters/process-engine-worker/</url>
   <packaging>pom</packaging>
 
   <properties>
     <spring-boot.version>3.4.4</spring-boot.version>
-    <process-engine-api.version>1.0</process-engine-api.version>
-    <process-engine-adapters-c7.version>2025.04.1</process-engine-adapters-c7.version>
+    <process-engine-api.version>1.1</process-engine-api.version>
+    <process-engine-adapters-c7.version>2025.04.2</process-engine-adapters-c7.version>
     <process-engine-adapters-c8.version>2025.04.1</process-engine-adapters-c8.version>
     <!-- TEST -->
     <mockito.version>5.4.0</mockito.version>

spring-boot-starter/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <groupId>dev.bpm-crafters.process-engine-worker</groupId>
     <artifactId>process-engine-worker-root</artifactId>
-    <version>0.2.0</version>
+    <version>0.3.0</version>
   </parent>
 
   <artifactId>process-engine-worker-spring-boot-starter</artifactId>

spring-boot-starter/src/main/kotlin/dev/bpmcrafters/processengine/worker/registrar/ProcessEngineStarterRegistrar.kt

@@ -181,7 +181,7 @@ class ProcessEngineStarterRegistrar(
 
     },
     termination = {
-      logger.debug { "PROCESS-ENGINE-WORKER-010: Terminating task from topic $topic." }
+      logger.debug { "PROCESS-ENGINE-WORKER-010: Terminating task ${it.taskId} from topic $topic" }
     }
   )
 

spring-boot-starter/src/test/kotlin/dev/bpmcrafters/processengine/worker/TestHelper.kt

@@ -10,12 +10,11 @@ import org.testcontainers.utility.DockerImageName
 object TestHelper {
 
   class Camunda7RunTestContainer(tag: String) : GenericContainer<Camunda7RunTestContainer>("camunda/camunda-bpm-platform:$tag") {
-
     init {
+
       withCommand("./camunda.sh", "--rest")
       withEnv("CAMUNDA_BPM_DEFAULT-SERIALIZATION-FORMAT", "application/json")
       withExposedPorts(8080)
-      addFixedExposedPort(38080, 8080)
       waitingFor(
         Wait
           .forHttp("/engine-rest/engine/")

spring-boot-starter/src/test/kotlin/dev/bpmcrafters/processengine/worker/registrar/ResultResolverTest.kt

@@ -27,7 +27,7 @@ class ResultResolverTest {
   fun `detects method returning generic map`() {
     class Worker {
       @ProcessEngineWorker
-      fun work(): Map<String, out Any> {
+      fun work(): Map<String, Any> {
         return mapOf("string" to "value", "string2" to "other")
       }
     }