Bulk identity migration (#922). One validation for the whole batch, because eligibility is a property of the version pair, not of an instance. from_version is the whole bulk key – a bpmn_flow_version row belongs to exactly one flow – and both versions are checked to belong to the same flow before anything moves. Matching no running instance is a 200 with an empty migrated, not an error.
The same per-pair verdict as checkBpmnVersionPair, but resolving this instance’s own current pin and its runtime preconditions (it must not be an inline preview run, and it must still be running).
Runs the identity-migration contract (#922) over two compiled definitions of the same flow and reports every blocker, grouped by rule. Reads no runtime state at all, so the verdict is a property of the (from_version, to_version) pair and applies to every instance pinned to from_version – which is what makes it answerable with no instance and cacheable per version.
Deliver a user task’s form data and unpark the instance. The body is the completion payload; when the task declares form fields it is validated against them server-side (required fields, declared defaults, enum values – see #833), unless the model sets flowable:formFieldValidation=\"false\". Since #1104 the caller must be in the task’s declared audience. This was previously unenforced: anyone who could see an instance could complete any of its user tasks, including one assigned to somebody else.
#919, narrowed to a single flow. Identical shape to the workspace rollup. A flow that exists but has nothing running answers with an empty flows list, not a 404.
Frontend-facing projection of the process instance’s live runtime state (lifecycle, per-activity status, variables, history, incidents), consumed by the live process token overlay. 404 if the instance isn’t in the workspace, or if the engine has not picked it up yet (no runtime state).
#919. Answers "which of my running instances are on an old definition?" for the whole workspace, and per pinned version whether it is migratable to that flow’s latest and if not why (#922’s validator, computed once per version because eligibility is a property of the (version, latest) pair rather than of an instance). Read-only. An instance is pinned at start to one bpmn_flow_version (v2_job.runnable_id) and resolves its model from that row on every step, so instances complete on the version they started on while new starts use the latest. runnable_id is the source here, never the denormalised bpmn_process_status.bpmn_version, which the engine writes on insert and never refreshes. "Running" means a root instance still queued and uncancelled – the same set a bulk migrate would move. Inline preview runs are excluded: they carry their model on the job row and are on no version.
Every <userTask> in the workspace that is parked awaiting a human and that the caller may act on (#1104). This is the read side the completion operation below always presumed: that operation is addressed by (instance id, element id), which a human has no way to discover otherwise. Filtering is server-side and is the same rule the completion operation enforces. A task is returned when the caller is an admin, when the task declares no assignment it can resolve, or when the caller matches a declared literal assignee/owner/candidateUsers entry or one of the candidateGroups. Assignment written as an expression (${approver}) cannot be resolved on this path – there is no runtime identity resolution in the engine – and is reported via assignment_unresolved rather than guessed at. Pagination applies to process instances, not to tasks: one instance can hold several parked tasks on parallel branches.
Validated pointer swap (#922). Validates the (current, target) pair against the identity-migration contract and, only if it passes, moves v2_job.runnable_id to the target version, refreshes the denormalised bpmn_process_status.bpmn_version (which no engine writer ever refreshes) and appends a bpmn_instance_migration ledger row – all in one transaction. process_status is never written and suspend_until is never nudged; the instance runs on the target version from its next step, because the engine re-resolves the pinned definition on every step. A pair that fails the contract is refused with a 400 naming every offending identifier – it is never migrated and flagged.
The same resolution as planBpmnVersionPairMigration, but resolving this instance’s own current pin and its runtime preconditions (it must not be an inline preview run, and it must still be running). Writes nothing.
Runs the mapped migration contract (#925, stage 4) over two compiled definitions of the same flow and, if the document holds, returns the resolved substitution as a plan. POST because the mapping is a document rather than a query parameter – the call reads two definitions and writes nothing. Where the identity contract (checkBpmnVersionPair) asks "may this instance run on the target unchanged", this asks the strictly larger "may it run on the target after renaming the identifiers this document names". It admits renames – of elements, of sequence flows (derived from their endpoints, never declared) and of the process id – and refuses every topological change: a deleted activity with no replacement, an N:1 merge, a cross-scope move, a changed set of incoming flows, a re-attached boundary event. An element the document does not name is implicitly mapped to its own id, and is then subject to every rule an explicit mapping is. An element that is neither named nor present in the target is a hard refusal (activity_deleted), never a silently dropped token. Rule 9 additionally refuses a mapping that renames an identifier away while the target version still defines it (which includes every permutation): the engine derives job, token and scope ids from these identifiers, so a later dispatch at the reused id would re-derive ids the instance has already used and hang there with no incident. A plan this returns is submitted with requestBpmnInstanceMigration.
Start a process instance from an undeployed diagram (#710 stage 3), the "run without deploying" counterpart to POST /bpmn/run/p/{path}. The submitted XML is parsed and validated exactly as a real deploy would – nothing is written to bpmn_flow/bpmn_flow_version.
The write half of the mapped migration contract (#925, stage 4). Resolves the mapping against this instance’s own pin exactly as planBpmnInstanceMigration does and, only if it resolves to a plan, writes a migration request into process_status.control.migrate and pulls an existing park forward so the engine re-pulls the instance promptly. Validate-then-write in one transaction: a mapping that does not hold leaves nothing behind. Unlike migrateBpmnInstance this does not perform the migration. A mapped migration rewrites process_status, which the engine owns, so the pin move, the blob rewrite and the bpmn_instance_migration ledger row all happen together in the engine’s next step. A 200 here means the request was accepted and stored, not that the instance has moved – poll the pin, or the instance’s status, to observe it. The stored request carries the mapping document, never the resolved plan. A plan is a bare identifier substitution, so a control entry carrying one would let anything able to write the control channel substitute arbitrary identifiers into a running instance; the engine re-derives the plan from the document against the two definitions it actually resolved. The plan in this response is informational. The engine can still refuse what this accepts, for the one reason that is not a property of the version pair: an activity Started on a renamed element holds a live child job id derived from the source id. That is refused at apply time and the signal is that the pin did not move. Everything that is a model-vs-model property, including rule 9 (vacating an identifier the target still defines), is refused here with a 400.
Validates the ActivityFailed incident, identified by the original failed child job’s id, and records a retry intent on the process instance. The execution engine does not yet act on this intent: retrying an incident is not yet functional end-to-end. This endpoint only validates ownership of the incident and records the intent for a future engine version to consume.