Context:
See OPT-3497

Currently, we cannot distinguish whether process instances are suspended when process definitions are suspended. We are working on a fix of that on the engine side, after that has been implemented the import needs adjusted to read the new operations log correctly.

AT:

• the userOperationLogImport correctly suspends/unsuspends processInstances when they are suspended/unsuspended using any of the following API endpoints:
  • suspend/activate process instance by process instance id
  • suspend/activate process instance by definition id
  • suspend/activate process instance by definition key
  • suspend/activate definition by process id (with includeProcessInstances true)
  • suspend/activate definition by key (with includeProcessInstances true)
  • [[suspnd/activate instances via batch||https://docs.camunda.org/manual/latest/reference/rest/process-instance/post-activate-suspend-in-batch/] https://docs.camunda.org/manual/latest/reference/rest/process-instance/post-activate-suspend-in-batch/ []|https://docs.camunda.org/manual/latest/reference/rest/process-instance/post-activate-suspend-in-batch/]
• the tests are adjusted to correctly handle the import flow, instead of importing from scratch after setting the suspension state (and importing the state from the running instance) they use `importAllEngineEntitiesFromLastIndex` after the suspension was executed
• the migration script is adjusted so that the import for the user operations log is starting from scratch after upgrading to Optimize 3.1.0
• it should be documented that the user operations log should be enabled regardless of user authentication context

Hint:

Here are the different use-cases from CAM-11723 and how you could distinguish them in the user operations log:

• 1 - suspend process instances:
  • 1A - by process instance id:  operationType: "Suspend"/"Activate", entityType: "ProcessInstance", newValue: "suspended"/"active", processDefinitionKey: "someKey", processDefinitionId: "someProcessDefinitionIdFoo", processInstanceId: "someProcInstId123"
  • 1B - by process definition id: operationType: "Suspend"/"Activate", entityType: "ProcessInstance", newValue: "suspended"/"active", processDefinitionKey: "someKey", processDefinitionId: "someProcessDefinitionIdFoo", processInstanceId: null
  • 1C - by process definition key: operationType: "Suspend"/"Activate", entityType: "ProcessInstance", newValue: "suspended"/"active", processDefinitionKey: "someKey", processDefinitionId: null, processInstanceId: null
• 2 suspend process definition:
  • 2A - by process definition id: operationType: "SuspendProcessDefinition"/"ActivateProcessDefinition", entityType: "ProcessDefinition", property: "includeProcessInstances", newValue: "true"/"false", processDefinitionKey: "someKey", processDefinitionId: "someProcessDefinitionIdFoo", processInstanceId: null
  • 2B - by process definition key: operationType: "SuspendProcessDefinition"/"ActivateProcessDefinition", entityType: "ProcessDefinition", property: "includeProcessInstances", newValue: "true"/"false", processDefinitionKey: "someKey", processDefinitionId: null, processInstanceId: null
• 3 - suspend process instances via batch:
  • 3A - by process instance ids: operationType: "SuspendJob"/"ActivateJob", entityType: "ProcessInstance", property: "nrOfInstances"/"async", newValue: "12"/"true"/"false", processDefinitionKey: null, processDefinitionId: null, processInstanceId: null
  • 3B - by query, etc: same as by process instance ids -> one solution for this scenario could be a reimport of all running process instances

Limitation:
The suspension of definitions API (cases of 2A and 2B described above) offers the optional parameter `executionDate`, which adds the option to trigger a delayed suspension. This parameter is not documented in the user operation log and for now, we will ignore it. We are going to reimport all instances related to suspended definitions at the time when we detect a definition suspension operation, though if `executionDate` implies a later suspension, those instances will not be suspended yet at the point of reimport, and we currently do not have a way to trigger a new import whenever the instances actually are suspended. They will be updated whenever the running instances are reimported due to other operations, which can lead to a delayed instance state update on our side.