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.
Current behavior note: The preserved body below includes a historical link to Simulation Studio as a synthetic, zero-side-effect simulation. That description applies only to modeled Interactive Token Sandbox journeys. It does not apply to Inject simulated data, which writes synthetic lifecycle, task, document and KPI records into a workspace. For the current boundaries, use the Simulation Studio practical guide.
Debug a lifecycle state
Learn with an isolated, captured execution
Debug is for an authorized author testing a saved model. Operate/Live is for inspecting and intervening in actual cases. A Debug session captures source models and uses private execution identities; it does not create a normal customer queue item or confer ordinary task rights on the selected participant.
Prepare the people-ops leave example with a saved lifecycle, actual state/node IDs, declared case-file inputs and a published task form. Choose either the exact saved draft revision or an explicit published version. Editing or publishing later does not rewrite that session’s captured source.
| Setup field | Meaning |
|---|---|
source |
DRAFT or PUBLISHED; choose deliberately |
lifecycleDraftId, expectedRevision |
The saved draft being captured, not unsaved browser state |
processDefinitionKey, version |
Explicit published source identity |
entryStateId |
Entry for a new session; later canvas selection is inspection |
stateBreakpoints |
State-qualified child node selections {stateId,nodeId} |
beforeNodeBreakpoints |
Parent state-entry IDs on lifecycle requests |
variables |
Values judged against the selected source’s actual declared inputs |
A participant simulation additionally needs its own permission and current captured Screen access. Stop session is a separate confirmed operation; preparing a new session does not stop an existing one. The older migration242 paragraph below explains that slice’s introduction, while current installation still follows the current complete migration/readiness policy. These are source-reviewed examples, with product runtime/ordinary-user/video acceptance not run here.
Session operations beyond the first run
All routes below are relative to /api/process-debug-sessions and retain current authentication, workspace and session/model admission. A successful read does not authorize a later intervention. The actual session statuses are PAUSED, WAITING_FOR_INPUT, COMPLETED, FAILED and STOPPED; inspect returned state instead of interpreting an inspected canvas as execution progress.
| Purpose | Route | Body/read contract |
|---|---|---|
| Reconcile current state | GET /{sessionId} |
Actual current session; no Step side effect |
| Advance one controlled step | POST /{sessionId}/step |
Existing captured session and intervention rights |
| Continue | POST /{sessionId}/continue |
Different from operator case activation |
| Stop | POST /{sessionId}/stop |
Explicit confirmed intervention |
| Replace watches | PUT /{sessionId}/watches |
{watches:[{id,label,expression}]} typed contract |
| Export transcript | GET /{sessionId}/transcript |
Authorized value-safe export, not a production audit mutation |
| Page transcript | GET /{sessionId}/transcript/entries |
beforeSequence, limit (default25) and optional query |
| Record scenario | POST /{sessionId}/scenarios |
name and typed assertions; no made-up generic test format |
| List scenarios | GET /scenarios |
Actual processDefinitionKey and bounded result selection |
| Replay one scenario revision | POST /scenarios/{scenarioId}/revisions/{revision}/replay |
checkpointSequence and suppliedInputs VariableMap |
A watch has ID, label and expression; its result separately carries value, protectedValue and error. Protected/unavailable values are not an invitation to change actor or copy raw snapshots into a public bug report. A saved scenario and revision are also not a complete production model or permission to replay customer effects. Use only the admitted authoring scenario/replay boundary and inspect its actual receipt.
For nested replay input, the controller’s suppliedInputs is a VariableMap rather than the flat human-task formData. Do not copy request shapes between those APIs. Typed assertions, checkpoint meaning and replayable effects must be taken from the current scenario source/receipt. A page refresh reads; it must never repeat Start, Step, Continue, completion or replay just to rebuild the display.
Source contracts: controller operations and DTOs, watch/transcript model, session state.
Worked examples
Example FLOW-DB-01 — Start at the saved Review flow and pause before its task
Scenario and inputs. Nadia has authoring/debug rights for a saved leave-request draft. Its actual revision is7, its working state ID is review, and the authored task node ID is reviewLeave. Replace those sample coordinates with the values read from the owned model. requestedDays is a declared numeric case input; supply any other required values declared by the real source.
{
"source": "DRAFT",
"lifecycleDraftId": "actual-draft-id",
"expectedRevision": 7,
"entryStateId": "review",
"variables": {
"requestedDays": 5
},
"stateBreakpoints": [
{
"stateId": "review",
"nodeId": "reviewLeave"
}
],
"beforeNodeBreakpoints": []
}
Procedure. POST the complete setup body to /api/process-debug-sessions. Read the returned session and captured lifecycleContext. Use the session’s own Step/Continue controls to enter its actual child, then inspect the state-qualified paused location. Keep the session identity and source identity separate in notes.
Expected result. The breakpoint refers to Review’s authored node, not another state’s similarly named task. The new session captures the saved revision and does not start a production case.
Failure and recovery. If the draft revision or state/node selector is stale, save/re-read and prepare a new valid setup. Never silently substitute the initial state, latest draft or an unqualified bare child node ID.
Sources. ProcessDebugSessionController.java:45; ProcessDebugSessionController.java:116.
Example FLOW-DB-02 — Investigate release1 even after release2 is published
Scenario and inputs. A support reproduction must use the old released Review flow. Nadia has access to published leave-request version 1 and its captured form; another consultant can independently publish version 2. The scenario deliberately tests source selection, not whether the newest design looks better.
{
"source": "PUBLISHED",
"processDefinitionKey": "leave-request",
"version": 1,
"entryStateId": "review",
"variables": {
"requestedDays": 5
},
"stateBreakpoints": [],
"beforeNodeBreakpoints": []
}
Procedure. Start the session with that explicit published selector. Read the captured release identity and the private snapshot/execution coordinates returned by the session. After another publication, refresh the existing session and inspect its original state canvas. Select another visible state only to inspect it; restarting from a different entry requires a new setup.
Expected result. The existing session continues with release 1’s captured parent and state flows. Its private execution snapshot version is not misreported as the user’s published release version.
Failure and recovery. If historical evidence is absent or inaccessible, report that explicit state. Do not fall back to version 2 or latest draft and then describe the run as a release 1 reproduction. Starting another session also does not implicitly stop this one.
Sources. ProcessDebugSessionController.java:45; ProcessDebugSessionService.java:190.
Example FLOW-DB-03 — Test an eligible participant on the captured form
Scenario and inputs. Nadia wants to check Sara’s approval path in Debug. Nadia has PROCESS_DEBUG_PARTICIPANT_SIMULATE; the captured form is viewable under the applicable Screen/object permissions. The selected participant comes from the server’s eligible participant result, not a username copied into an arbitrary task command.
Procedure. Open the existing session task with its actual task/child frame. Read /api/process-debug-sessions/{sessionId}/task/participants, select a permitted participant through the session’s participant operation, and fill the captured form. Complete through the session’s task-completion route, then read the session/transcript and any newly waiting work. Check that the task’s child instance, token, node and form version match the captured frame before using its controls.
Expected result. The isolated debug execution records a supported simulated response and follows its authored result. This is useful design feedback, but it is not proof that Sara’s ordinary App Shell session can complete a production task.
Failure and recovery. A denied participant selection or missing form access must be resolved by the actual owner. Do not borrow another actor’s session, inject a development identity or mistake a visible participant name for permission to act as that person.
Sources. ProcessDebugSessionController.java:238; ProcessDebugSessionController.java:269; ProcessDebugSessionController.java:294.
Example FLOW-DB-04 — Recover the display without repeating an uncertain intervention
Scenario and inputs. A network interruption occurs immediately after Nadia presses Step once. The current session read also fails to establish access. The previous diagram remains in browser memory, but the client has no current permission/effect witness. Retain the original session and any available request/support reference without logging raw case values.
Procedure. Use the existing retry/read path to recheck access and read the current session. On a successful fresh read, inspect transcript entries, waiting tasks and paused location to determine what actually happened. Distinguish an access-check outage from a successful session read whose failure-information subread is unavailable. Restore only the controls authorized by that fresh result.
Expected result. The screen can recover its state without another Step, Continue, task completion or external action. A stale diagram or missing failure summary does not prove rollback or recovery.
Failure and recovery. If access is denied, show the neutral unavailable state. If access cannot currently be checked, keep previous protected content and controls absent. Never turn a redraw failure into permission to repeat the last consequential POST.
Sources. ProcessDebugSessionController.java:160; ProcessDebugSessionService.java:1.
Detailed reference
Current source owners are ProcessDebugSessionService and
ProcessDebugSessionController: start and intervention require current authoring
permission and the authorized saved session/revision. Selecting a participant does
not grant ordinary-user task rights. The journeys below are instructions or
recorded evidence, not a new runtime verification by this documentation refresh.
Open Debug from the lifecycle or a state's Open flow view. The canvas shows the selected state's authored BPMN, including tasks, gateways, conditions and end events. The lifecycle breadcrumb and state picker keep that work inside its parent lifecycle. A pause in the synthesized parent orchestration is labeled separately from the selected state’s authored flow. The composed Flow overview remains read-only context.
Choose what to run
Choose Draft to capture the saved draft revision, or select a published release to run that release's pinned parent and state flows. Save draft edits before starting. Changing a draft or publishing another release does not change an existing debug session. A new published-version session also retains the selected release even when a newer release exists.
The initial state is selected by default. Choosing another state before starting makes it the execution entry for that new session. During an existing session, selecting another state is inspection: it changes the canvas without restarting or advancing execution. The selected state, source context, release version when applicable and session are represented in the Debug URL. Refresh, copied links and browser navigation retain those coordinates. An invalid or unavailable state fails explicitly; it does not silently open another state or the latest draft.
An empty state displays an actionable empty view. A terminal state without a flow can still appear in the lifecycle overview; it does not invalidate the authored work of other states. Starting directly in a state with no authored flow is refused.
Pause, step and follow work
Use Pause before this step on a node in the state's BPMN. The selected count and breakpoint list show state-qualified selections, so identically named nodes in different states remain distinct. Use Pause before entering this state to set an entry breakpoint in the synthesized parent. Resume or Step once into its child flow to see the actual tokens and waiting work. Breakpoint selections belong to session setup; use Set up a new session to choose another entry or breakpoint set. This prepares another run; it does not stop the existing session. Stop session is a separate confirmed action.
Start Debug creates an isolated test execution, not a production case or customer-queue item. Step once and Resume follow the current execution. To complete work in Studio, choose an eligible participant and fill the captured published form. The participant picker requires the existing PROCESS_DEBUG_PARTICIPANT_SIMULATE permission, and the published Screen requires SCREEN_VIEW plus the applicable object access. Opening Debug does not grant these rights. The own-actor task-completion API retains its separate task claim/complete authorization.
When work enters another state, the debugger can follow its actual child flow and updates the lifecycle-to-state breadcrumb. If several children are active, Debug resolves the server-selected waiting task against its actual child frame. Use Show waiting task to open that task’s state; ambiguous or missing coordinates show an error. A selected task must match its real child instance, token, node and captured form version. Missing or ambiguous execution evidence is displayed explicitly.
Background timers and workers retain the session's captured models and execution isolation. Refresh reconciles the session controls with the latest runtime position. Waiting, paused, completed and failed are runtime states; changing the inspected canvas does not change them.
Permissions and separation
Debug uses the existing parent lifecycle definition-update/debug authorization and runtime/task permissions. State flows inherit their verified parent access; independent rights on generated child assets are not required. Workspace scope and explicit denials still apply. Captured debug models are private to authorized debug execution and cannot be started as ordinary processes or exposed as independent catalog assets.
Operate remains the place to inspect and control production cases. Operator Pause/Resume uses suspend/activate, while Debug Step/Resume controls a test session. Neither action replaces completion of assigned human work.
API clients
POST /api/process-debug-sessions accepts an explicit lifecycle source. Draft requests supply source: "DRAFT", lifecycleDraftId and expectedRevision. Published requests supply source: "PUBLISHED", processDefinitionKey and an explicit version. entryStateId selects the new execution entry; omission selects the captured initial state. Use stateBreakpoints: [{stateId, nodeId}] for child nodes. On lifecycle requests, beforeNodeBreakpoints contains parent state-entry IDs, not bare child node IDs. Contradictory or stale selectors are refused. Existing standalone requests that omit lifecycle selectors retain their legacy contract.
Session responses include lifecycleContext: captured source identity, authored state canvases, read-only parent overview, pinned execution models, actual child frames and the qualified paused location. Read the source release version separately from the private snapshot execution version. Do not reconstruct models from generated names or fall back to current drafts or latest published definitions.
Existing session GET, step, continue and task routes keep their authentication, workspace and permission checks. Stop session asks for confirmation in Studio. New controls expose stable agent IDs. The UI canvas reports data-agent-state as loading during recovery, then empty, ready, waiting or error; the API canvas-state vocabulary excludes loading.
Database upgrade and rollback
This API requires a clean PostgreSQL schema at version 242 or newer. Apply the shipped migrations through 000242 before starting the new API. Migration 000242 adds durable private model snapshots, execution-instance bindings and lifecycle coordinates on Debug sessions. Existing session rows retain nullable/defaulted fields; the migration does not publish lifecycle assets or create production cases.
The down migration removes those snapshots, bindings and session coordinates. It cannot preserve captured lifecycle Debug sessions, and this API will refuse a schema below its required version. Use the deployment's reviewed backup/restore and application rollback procedure; account for retained Debug sessions before a downgrade.
Understanding an execution failure
When failure information is available, the failure summary explains the recorded cause in English, the permitted failed location, and the next check. Runtime readers can use this explanation without opening the designer. A person who cannot change the workflow is directed to its owner rather than offered configuration actions. Unknown or legacy causes explicitly say that detailed information is unavailable.
Current failures and recorded history are separate. An older failure can remain in history after recovery; it does not mean the run is still failing. More failures continues the same held history read. Refresh loads current information. A support reference identifies the occurrence; copying evidence excludes raw engine text, credentials, expressions and business values.
Locate appears only when the current view can represent that exact permitted execution and its original model. It inspects the step without resuming, retrying or changing case data. An inaccessible or stale location shows Not available. A missing location action does not grant access to a newer or different run.
Statements about saved case values or completed external actions are shown only when confirmed. An unknown outcome is not permission to retry an external action.
For a missing required input, a consultant permitted to inspect the captured configuration sees its input name in the summary and Safe details. The name comes from that captured step's declared input; values and mapping expressions remain excluded. Readers without the required configuration access retain the general missing-value explanation and workflow-owner guidance. Copy safe evidence includes the same permitted name.
Request logs mask diagnostic continuation and inspection selectors, including encoded URL names and selector text echoed by an exception. Ordinary diagnostic codes, request status and error type remain available for support correlation; the selectors do not grant access.
If a current failure-information read cannot be established, the API reports “Failure information could not be loaded just now.” It supplies no diagnostic details from that refused read. This does not mean the execution recovered, and it does not authorize retrying a workflow step or an external action.
When Debug cannot establish current access to the session, it replaces the session content and execution controls with “Your access could not be checked right now. Try again shortly.” Retry checks access and reads the current session; it does not repeat Start, Step, Resume, task completion or an external action. Content returns only after a successful fresh read. If access is denied, Debug shows the neutral Not available state.
A session read that succeeds but has unavailable failure information is different: its independently authorized session controls remain available while the failure summary reports that information could not be loaded. Neither state proves that the execution recovered or that an uncertain action is safe to repeat.
Simulation Studio (SCRUM-3398)
For synthetic, zero-side-effect simulation of any Lifecycle or Process Flow—including scoped variable declarations (UNSET, NULL, FALSE, ZERO, EMPTY_STRING, DEFAULTED, WRITTEN), human-task outcome and custom form output mapping, XOR/Inclusive/Lifecycle gateway routing explainability, non-destructive rewind and run branching, reusable scenario assertions, and redacted run reports—see Simulation Studio (docs/manuals/simulation-studio.md).