Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Lifecycle case runtime

Read a running case before intervening

A lifecycle release is a design snapshot; a case is one execution of a specific release; a state flow is an actual linked child execution. Use the parent’s real case ID to inspect the relationship. Labels and generated key patterns are not execution identity. A later publication changes future starts and explicitly admitted migration/rebind operations, not every existing case.

For the leave example, use lifecycle key leave-request, state ID review and the actual returned case ID. leave-2026-014 is a business reference. The default state-filter query covers RUNNING and SUSPENDED parents; engine waiting is still RUNNING, not a new WAITING instance status. A page of20 results can represent a larger authorized totalItems.

Need Supported read/operation Interpret it carefully
Find cases in Review GET /api/process-instances with definition key/state/page/size Parents only; counts are permission-scoped
Resolve parent and children GET /api/process-operate/instances/{caseId}/lifecycle-context Each actual child has its own model/version coordinates
Inspect one execution Snapshot/replay/history reads for the exact instance A missing historical model is not current draft data
Pause business advancement POST /api/process-instances/{id}/suspend with a reason Cannot retract a request already dispatched externally
Continue a paused case POST /api/process-instances/{id}/activate with a reason Replays admitted retained arrivals; respects independent child pauses

Operator pause/activation is different from Debug Step/Continue and from completing assigned work. Perform mutations only in an environment where the actor has the actual case/object rights. The event timelines below describe current source behavior; they were not executed against a product runtime by this documentation program.

Worked examples

Example FLOW-CR-01 — Count the visible cases waiting in Review

Scenario and inputs. Sara wants a pending-work figure for people-ops. She has the required case-view rights on leave-request, whose published graph contains stable state ID review. Some parents are running, one is paused, and each can have an active child. The following is a complete GET request shape; its deployment origin and authenticated session are supplied by the reader.

GET /api/process-instances?processDefinitionKey=leave-request&lifecycleStateId=review&page=0&size=20

Procedure. Read items, page, size and totalItems together. Open the next page using the same definition/state predicates rather than adding child-instance rows. Keep the state ID separate from its display name. If completed history is needed, deliberately choose the supported status/activeOnly filter rather than assuming the default includes terminal cases.

Expected result. One visible parent contributes one row regardless of token or child fan-out. The state-filter default includes running and suspended cases. The total counts the same authorized scope as the list.

Failure and recovery. Omitting the definition key while sending a state filter is invalid. A failed or denied read is unavailable, not zero. Refresh related counts and lists together because separate reads can straddle a genuine transition.

Sources. WorkflowRuntimeController.java:268; LifecycleCaseRuntimeTest.java:47.

Example FLOW-CR-02 — Inspect a case pinned to an older release

Scenario and inputs. Nadia publishes release 2 after Mohammad’s case started on release 1. Sara follows an admitted case link to the original parent. She must explain its current Review task without substituting the new form or newly renamed flow. The case ID and version values must come from the actual response, not from the tutorial’s business reference.

Procedure. Read GET /api/process-operate/instances/{caseId}/lifecycle-context?processDefinitionKey=leave-request. Inspect the parent’s processDefinitionId, lifecycleVersion and stable state ID. For every selected stateFlows reference, use that child’s actual instance ID, processDefinitionId and processDefinitionVersion when resolving its model/snapshot. Retain completed child references as history; their settlement does not change their original version coordinates.

Expected result. The diagram and inspection belong to release 1 and its exact child pins. Release 2 remains a separate immutable design that does not silently retarget this execution.

Failure and recovery. A null model ID/version means immutable model evidence is unavailable. Keep the known runtime references visible where allowed and show that limitation. Never load the current draft or latest release merely to fill an otherwise empty diagram.

Sources. ProcessOperateController.java:525; ProcessDefinitionVersion.java:1.

Example FLOW-CR-03 — Pause a parent while a valid completion arrives

Scenario and inputs. An authorized operator pauses a vacation case while Sara has its existing Review task open. The parent has one inherited running child and another child already paused independently. Suspension/activation require the actual case permissions and a recorded reason. The JSON below is the complete reason-bearing body for the selected pause operation.

{
  "reason": "Confirm leave coverage before further advancement"
}

Procedure. POST that body to /api/process-instances/{parentId}/suspend, then read the parent/children. If a valid task completion arrives during the pause, retain its normal accepted outcome rather than treating the pause as task cancellation. Activate the parent with a fresh meaningful reason through /activate, then inspect the resulting task and case position. Keep an uncertain completion tied to its canonical task receipt.

Expected result. Inherited children resume only when appropriate; the separately paused child remains paused. A duplicate retained delivery does not advance the same waiting token twice.

Failure and recovery. A child cannot be activated through a paused ancestor. Already-dispatched remote work cannot be recalled by suspension, so do not promise that the pause prevented all external effects or repeat a provider operation merely because the parent was paused.

Sources. WorkflowRuntimeController.java:185; LifecycleCaseRuntimeTest.java:71.

Example FLOW-CR-04 — Recover a retained arrival that cannot replay

Scenario and inputs. The parent activates, but a previously accepted deferred completion fails its declared-variable/output checks. Operations sees RUNTIME_DEFERRED_ARRIVAL_FAILED. This is different from a transaction/database failure and different from a completion the server rejected before retaining it. Keep the original command, case ID and incident reference for investigation.

Procedure. Read the actual incident and waiting step through permitted operations. Determine which allowed input or case value prevents replay. Correct only the supported payload/case data under the current actor’s rights, then submit the appropriate existing completion or signal while the case is active. Read the current token/task position and the canonical receipt or signal result before considering another intervention. Preserve the failed arrival and its diagnostic history.

Expected result. Activation itself can commit while an individual replay’s writes roll back to its savepoint. A successful supported correction advances the waiting token once; the failed retained row is not automatically retried indefinitely.

Failure and recovery. Do not delete the deferred row, replace it with another paused arrival or use raw database edits to manufacture progress. Infrastructure failures retain their full rollback behavior and must not be reclassified as payload incidents.

Sources. WorkflowRuntimeServiceImpl.java:1857.

Detailed reference

A case uses its pinned processDefinitionKey and integer processDefinitionVersion. The instance detail and search records additionally expose currentLifecycleStateId and nullable integer lifecycleVersion. Lifecycle position comes from the most recently entered state node in the instance's immutable published BPMN, using compiler metadata lifecycle.role=STATE. Labels, generated child keys and current drafts do not determine position. Missing published model/state history is unavailable (null), never a substitute current draft.

Query and counts

GET /api/process-instances?processDefinitionKey=onboarding&lifecycleStateId=review&page=0&size=20

The state filter requires the parent definition key. It excludes subprocess instances and authoring debug executions. A parent contributes one row regardless of token or child fan-out. The existing X-Workspace-Id workspace context (id or key) and instance-view ACL apply before final pagination and authorized totalItems.

With a state filter, omitted status and activeOnly select RUNNING and SUSPENDED. Engine waiting cases have instance status RUNNING; there is no separate WAITING instance enum. activeOnly=false includes terminal statuses. An explicit status selects that status, overriding the active default. Legacy searches without a state filter preserve their previous all-status behavior unless activeOnly=true is supplied.

Use PageResult.totalItems for counts, not the returned page length. A missing draft-only state yields zero. A failed query is unavailable, not zero. Counts and lists use identical predicates; separate SQL/HTTP reads can observe transitions at different instants and should refresh together.

Case and child inspection

GET /api/process-operate/instances/{caseId}/lifecycle-context?processDefinitionKey=onboarding checks the selected parent and optional expected key. The response contains its key, lifecycle version, stable state ID, runtime status and stateFlows execution references. Each child reference has its actual instance ID, owning state ID, definition key and pinned integer version, including settled children. Parent and child view permissions are checked before returning references. The existing child instance snapshot/replay endpoints show that child's tokens and tasks. A state task with no authored assignment is offered to the case initiator; see Who receives a state's human task in Lifecycle authoring. An invalid or mismatched case never falls back to another case or a draft. Immutable authored lifecycle release snapshots remain the publication API's responsibility.

Pause and activation

POST /api/process-instances/{id}/suspend pauses the parent and its active linked descendants. POST /api/process-instances/{id}/activate resumes only descendants paused by that parent; independently paused children stay paused. Both require a reason and existing object permissions. HTTP actor identity is taken from authentication. Repeating an operation already in its requested status returns current state without another audit or replay. Terminal cases cannot be suspended or activated. A child cannot be activated through a suspended ancestor.

Runtime mutation locks are acquired from root parent to child. Once suspension is acknowledged, new token advancement is gated and queued worker claims are excluded. Timers retain their original due time and use the existing suspension retry path. Normal task/external completions and signals arriving during pause are persisted in runtime_deferred_commands; activation replays them under the same instance locks and transaction. Duplicate pending completion deliveries for the same token/node retain one arrival. Token guards prevent re-advancing a token already consumed by another arrival. /resume remains token continuation, never operator activation.

A worker lease already claimed for dispatch is in-flight work. Suspension cannot recall a remote request or undo its side effect. Local workers recheck suspension before execution, and an already-dispatched completion is retained without redispatching the completed external run. The UI should communicate this limit when pausing a case with external work.

Migration 000238 adds the runtime projection view and event index, inherited suspension marker and deferred arrival table. It derives old case positions from existing published BPMN and runtime events without republishing or modifying historical definitions. Rollback removes the projection/queue and must only occur after retained arrivals are drained or explicitly accounted for.

Suspended completions and matching signals use the same output bindings and declared-variable validation as immediate delivery before they are accepted. Invalid payloads are refused without consuming work, changing variables, or creating a deferred row. Trusted asynchronous delivery retains its existing merge policy across restart.

If an already accepted arrival fails at replay, activation commits while that arrival's database writes roll back to a savepoint. The original command remains retained with its failure code and an actionable RUNTIME_DEFERRED_ARRIVAL_FAILED incident; activation does not automatically retry that failed row. Inspect the incident and waiting step, correct the payload or case variables, and submit the completion or signal through the existing API while the case is active. Successful correction advances the token once. A failed completion cannot be silently replaced by another paused delivery. Infrastructure/database failures still roll back the transaction rather than being treated as payload incidents.

Current lifecycle state follows the durable engine event sequence, including when a later worker has an earlier wall-clock timestamp. Forward migration 000240 updates the projection view and supporting index; 000238 remains unchanged. The migration preserves existing instance/event data, pinned release matching, and child exclusion. Its down script restores the earlier view/index only; it does not remove the deferred queue.

The Operate lifecycle-context response supplies nullable processDefinitionId on the parent and every actual stateFlows child. IDs may differ from definition keys. Resolve the parent model with its ID and lifecycleVersion; resolve each selected child's model with its own ID and processDefinitionVersion. These IDs come only from the exact stored version in the authorized instance workspace. Retired/completed cases retain their original coordinates. A null ID or null parent lifecycle version means immutable model evidence is unavailable; retain the runtime references and show that state explicitly, without loading a current draft/latest model. Existing parent and child guards apply to the entire context response, and model endpoints keep their own authorization.

Try “document generation”, “integrations” or “first form”.