Add support for starting process instances at specific elements

[emaarco]

Scenario

I want to start a process instance at a specific element/activity within the process definition, not just at start events. This capability exists in the underlying engines:

• Camunda 7: for instance in ProcessInstantiationBuilder
• Zeebe: for instance in CamundaClient

Use cases could be, for example:

• Testing: Start processes in specific states without executing all preceding steps
• Process Recovery: Restart failed processes from a specific recovery point
• Data Migration: Create process instances at specific points when migrating from other systems
• Workflow Simulation: Set up specific scenarios for demonstrations or analysis

Note: Starting at arbitrary elements may result in process instances with missing variables that would normally be set by skipped activities. However, i think this is acceptable in specific use-cases, in case the user is aware of this.

Current Behaviour

The API supports starting processes via:

• StartProcessByDefinitionCmd: Starts at the process start event
• StartProcessByMessageCmd: Starts at a message start event

Both always begin at start events. There is no support for starting at arbitrary elements/activities within the process definition. The existing CommonRestrictions.ACTIVITY_ID is used for task subscription filtering and message correlation, not for selecting process start points.

Wanted Behaviour

Support for starting a process instance at a specific element/activity ID. Possible approaches:

Option 1: New dedicated command

data class StartProcessByElementCmd(
  val definitionKey: String,
  val elementId: String,  // BPMN element ID to start at
  val payloadSupplier: PayloadSupplier,
  val restrictions: Map<String, String> = emptyMap()
) : StartProcessCommand, PayloadSupplier by payloadSupplier

Option 2: Extend existing command with optional parameter

data class StartProcessByDefinitionCmd(
  val definitionKey: String,
  val payloadSupplier: PayloadSupplier,
  val startElementId: String? = null,  // Optional: element ID to start at
  val restrictions: Map<String, String> = emptyMap()
) : StartProcessCommand, PayloadSupplier by payloadSupplier

Process instance starts at the specified element, skipping all prior activities. Variables can be provided via payload supplier.

Implementation could be phased across adapters:

• CIB-Seven (initial),
• Camunda 7 (using Process Instantiation Modification API),
• Camunda 8/Zeebe (using process instance creation with instructions).

Adapters without support should throw UnsupportedOperationException

Possible Workarounds

1. Multiple Start Events: Add test-specific start events to process definitions
   • Limitation: Only works at predefined start events, not arbitrary activities; pollutes the process model

[zambrovski]

Nice one. I like the idea. On the implementation side I would go for the option one and create a dedicated command (slightly modified version of your proposed to be more consistent to our current naming).

data class StartProcessByDefinitionAtActivityCmd(
  val definitionKey: String,
  val activityId: String,  // BPMN element ID to start at
  val payloadSupplier: PayloadSupplier,
  val restrictions: Map<String, String> = emptyMap()
) : StartProcessCommand, PayloadSupplier by payloadSupplier

We still start by definition, but this time provide the start activity.
Would you like to implement a PR for this?

[emaarco]

alright. will have a look at this 👍