Using the Java API I can modify a Process Instance's Execution State

AT:

• In a single action, I can modify a process instance such that
  • new path(s) of execution are started before or after activities
  • One or more existing activity instances are cancelled
• I can pass variables when starting an activity
• i can switch off custom listeners and io mappings
• out of scope: loops and multi instance

====
notes:

Context

Users want to modify the execution state of a process instance at runtime.
For example, they want to "go back in the process" or "skip some of activities".
The usage context is an "exceptional" one. This is why these transitions are not modeled in the diagram.

General usecases:

• repair process instances,
• testing
• version migration

Concrete usecases:

Provide an API which allows users to

• start a new execution at a given activity
• cancel an execution

API:

runtimeService.createProcessInstanceModification(pid)
  .cancelActivityInstance("someActivityInstanceId")
  .cancelAllInActivity("someActivityId")

  .startBeforeActivity("someActivityId")
    .setVariable("someVarName", "someVarValue")
    .setVariableLocal("someVarName", "someVarValue")

  .startAfterActivity("someActivityId", "ancestorActivityInstanceId")
    .setVariables(variableMap)

  .startTransition("someTransitionId")

.execute(); // alternative execute(boolean skipCustomListeners, boolean skipIoMappings);

Questions for clarification:

History

How should this be reflected in History?

• Historic activity instances are created / canceled regularly
• There should be a user operation log entry showing that the a state modification operation was performed (separate ticket CAM-3622)

Relation to suspension

It should be possible to perform execution state modifications while a process instance is suspended.
This way a user can suspend a process instance and then "repair" it;
see separate ticket CAM-3621 for details

Multi Instance

How will the starting of activities within a multi instance subprocess be handled?

Naming

Should the API be formulated in terms of

• Exectuions
• Tokens
• Activity Instances

What is the name of this feature?

Out of scope

batch

In the future we may support this as a batch operation, but for now we focus on an individual execution of the operation

process hierarchy

It will not be possible to modify multiple process instances at once. Usecases for this is:

1. a process has a call activity. in the given instance, the call activity is not yet stated. I will not be able to start the call activity such that the sub process instance will start at a given activity.

Expected behavior for various BPMN constructs

• Tasks: Start before simply executes a task
• Events:
  • Start: Start event treats all events like a none-event, or put differently: all events as if the event trigger has already occurred. That means, no message event subscriptions/timer jobs etc. are created
  • Intermediate: Catching and throwing are executed as usual
  • Boundary: Start before executes the event's cancelling semantics; start after does not
  • End: Execution as usual; start after does nothing
  • Event-based Subprocess start event: behavior as a combination of start event and boundary event; start before executes as if the event has occurred and respects the subprocess's cancelling semantics; start after does not cancel anything; users are still able to cancel other activities as they wish, so they can also create the situation in which a task is started in the middle of an event-based subprocess and other activities are cancelled
• Gateways: start after must always provide a sequence flow (if there is more than one outgoing sequence flow). This is also required with gateways. This flow's condition expression is not evaluated.