feat: add command to start process at specific element

Author: emaarco

api-impl/src/main/kotlin/dev/bpmcrafters/processengineapi/impl/task/TaskSubscriptionHandle.kt

@@ -31,7 +31,7 @@ data class TaskSubscriptionHandle(
    */
   val taskDescriptionKey: String?,
   /**
-   * Action handler to execute, if the task is delivered.
+   * Action handler to execute if the task is delivered.
    */
   val action: TaskHandler,
   /**

api/src/main/kotlin/dev/bpmcrafters/processengineapi/process/StartProcessByDefinitionAtElementCmd.kt

@@ -0,0 +1,63 @@
+package dev.bpmcrafters.processengineapi.process
+
+import dev.bpmcrafters.processengineapi.PayloadSupplier
+
+/**
+ * Command to start a new process instance at a specific activity.
+ * @since 1.5.0
+ */
+data class StartProcessByDefinitionAtElementCmd(
+  /**
+   * Process definition key.
+   */
+  val definitionKey: String,
+  /**
+   * ID of the element to start the process at.
+   */
+  val elementId: String,
+  /**
+   * Payload supplier to pass to the new process instance.
+   */
+  val payloadSupplier: PayloadSupplier,
+  /**
+   * Restrictions applied for this start command.
+   */
+  val restrictions: Map<String, String> = emptyMap()
+) : StartProcessCommand, PayloadSupplier by payloadSupplier {
+  /**
+   * Constructs a start command with a definition key, element ID, payload, and restrictions.
+   * @param definitionKey process definition key.
+   * @param elementId element ID (activity ID) to start the process at.
+   * @param payload payload to use.
+   * @param restrictions restrictions for the start command.
+   */
+  constructor(definitionKey: String, elementId: String, payload: Map<String, Any>, restrictions: Map<String, String>) : this(
+    definitionKey = definitionKey,
+    elementId = elementId,
+    payloadSupplier = PayloadSupplier { payload },
+    restrictions = restrictions
+  )
+  /**
+   * Constructs a start command with a definition key, element ID, and payload.
+   * @param definitionKey process definition key.
+   * @param elementId element ID (activity ID) to start the process at.
+   * @param payload payload to use.
+   */
+  constructor(definitionKey: String, elementId: String, payload: Map<String, Any>) : this(
+    definitionKey = definitionKey,
+    elementId = elementId,
+    payloadSupplier = PayloadSupplier { payload } ,
+    restrictions = mapOf()
+  )
+
+  /**
+   * Constructs a start command with definition key, element ID, and no payload.
+   * @param definitionKey process definition key.
+   * @param elementId element ID (activity ID) to start the process at.
+   */
+  constructor(definitionKey: String, elementId: String) : this(
+    definitionKey = definitionKey,
+    elementId = elementId,
+    payload = mapOf(),
+  )
+}

docs/process-api.md

@@ -2,20 +2,21 @@
 title: Process API
 ---
 
-The Process API provides functionality, required to control the lifecycle of the processes. It allows to start new process instances.
-It is intended to be used in outbound adapters of the port/adapter architecture, in order to control the process engine
-from your application.
+The Process API provides functionality required to control the lifecycle of the processes.
+It allows to start new process instances.
+It is intended to be used in outbound adapters of the port/adapter architecture 
+to control the process engine from your application.
 
-There are two ways to start processes:
+There are three ways to start processes:
 * by providing a process definition key
 * by providing a start message
+* by providing a process definition key and a specific activity to start at
 
-In both cases, you might provide a process payload passed to the started process instance. 
+In all cases, you might provide a process payload passed to the started process instance. 
 
 Here is an example of usage:
 
 ```java
-
 @Component
 @RequiredArgsConstructor
 public class ProcessStarter {
@@ -33,7 +34,6 @@ public class ProcessStarter {
     ).get();
   }
 
-
   @SneakyThrows
   public void startByMessage(Order order) {
     startProcessApi.startProcess(
@@ -44,10 +44,20 @@ public class ProcessStarter {
       )
     ).get();
   }
-  
-}
 
+  @SneakyThrows
+  public void startByDefinitionAtActivity(Order order) {
+    startProcessApi.startProcess(
+      new StartProcessByDefinitionAtActivityCmd(
+        "MyExampleProcessKey",
+        "Activity_ProcessOrder",
+        () -> Map.of("order", order),
+        Map.of()
+      )
+    ).get();
+  }
 
+}
 ```
 
 For supported engines (currently only C7 Embedded and C7 Remote) it is possible to set a business key by providing it