Context

From an API perspective, there are two places where users can configure a process instance migration:

• When configuring a migration plan
• When configuring the execution of the migration plan

The migration plan defines a mapping of flow-nodes between the source and target process definition. The state of the process instances is, at this point, not relevant. The migration plan is validated on creation. The selection of process instances happens on configuring the execution of the migration plan. The flow-node instances of the source process definition that are active during the migration plan's execution are transferred to their respective target flow-nodes.

To be evaluated design decision: Variables should be set when executing the migration plan and not when configuring it

Pros

• Separation between the process instance runtime data and model
  • The migration plan describes how flow-nodes will be mapped from the source to the target process definition independently of the process instances' state; The automatic transformation of the process instances' state (runtime data) results from the respective flow-node mapping, i.e., flow-node instances and the related data (e.g., variables) are transferred from one flow node of the source definition to another flow node of the target definition
  • The migration plan configuration is based on the process definitions, and setting a variable is highly dependent on the current process instance's state
    • The concrete process instances to be migrated are only known when executing the migration plan and only, in this case, it makes sense, to set a specific variable, i.e., a process instance in another state might not require a specific variable, e.g., the delegate which requires a specific variable has already been executed
    • It should be possible to reuse migration plans no matter what state the process instances have => would not be possible when setting variables is part of the migration plan configuration
  • This argument is weak since there is no hard technical reason not to mix runtime data and the model (e.g., a strict model-based validation of data)
• On async execution, the migration plan is stored as JSON in the batch configuration column for each execution job which is not a good idea:
  • This argument is weak since a variable can be stored as a batch variable even though the flow-node mapping is stored somewhere else

Cons

• A migration plan should include all operations that are applied to a process instance (flow-node mapping & variable actions); as a user, it is hard to understand why some things are defined in the migration plan and others when executing the migration
• Exporting/importing a migration plan might become a requirement in the future and it could be seen as incomplete if variables are not part of it
• When thinking about making it possible to set a variable into a specific scope, from an API perspective it would be a lower effort to extend the migration plan configuration since we already have the flow-node mapping API here and could simply reuse it
  • This would introduce runtime data in the migration plan configuration API, which would mix up definition and runtime data and might be considered as hacky/not clean
  • In this case, maybe it would make more sense to combine the modification and migration feature (modification API can already set variables into to be started flow-node instances)
    • A combination would also allow migrating flow nodes of different types, e.g., User Task -> Service Task
  • The scope of the feature is limited to set variables into the global scope and not into a specific local scope

Decision & Reasoning

After weighing the pros and cons, I would go for setting variables when configuring the migration plan. The main reasons are that all migration operations should be defined in one place (the migration plan) and it might become a requirement in the future to export/import a migration plan.