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 publication
Publish the reviewed design as one release
Publication turns a saved lifecycle overlay and its owned state work into an immutable parent/child release. It is not a Save button, a runtime start, or a blanket instruction to move existing cases. The safe learning sequence is Save → Validate → Assess impact → explicitly consent where required → Publish → read the exact release.
For leave-request, first prepare Review’s actual human task, published form pin, assignment, output contract and declared terminal outcomes. Record the draft ID/revision from the current response. The request’s actor comes from authentication. Draft changes invalidate earlier validation and compatibility evidence.
| Operation | Evidence to retain | What it does not establish |
|---|---|---|
POST /{draftId}/validate |
Saved revision, valid, state/node-qualified issues |
Publication permission or acceptance |
POST /{draftId}/compatibility |
Revision, nested parent/state assessments, acknowledgement/content/impact coordinates | Consent on a later revision |
Direct POST /{draftId}/publish |
Actual released definition/version, with reviewed request fields | A generic idempotency/operationId contract |
| Original-attempt release | Issued intent, original command and observation | Permission to replay UNKNOWN/STALE/DENIED/CONFLICT |
GET /{definitionKey}/versions/{version} |
Immutable lifecycle and exact stateFlows pins |
A replacement current draft for missing history |
All routes here are below /api/process-lifecycles. Original-attempt clients first issue a release intent and then execute/observe that original attempt; existing direct callers retain their own documented route. Use the protocol actually supplied by the native client, not a made-up hybrid. Examples below are source-reviewed requests/projections, not newly executed publication evidence.
Understand original-intent receipts before reconnecting
An original lifecycle mutation has a server-owned intent bound to workspace, actor/type, operation, target and a command hash. The public type’s operations are CREATE, EDIT, RELEASE and START; receipt states are ISSUED, STARTED and COMMITTED. Its identifiers/digests are generated/validated by the native owner, not assembled by a client to imitate accepted work.
| Observation | What the reader can conclude | Supported next decision |
|---|---|---|
COMMITTED with its receipt |
That original operation has committed proof under current admission | Use its actual result/release/start birth coordinates |
UNKNOWN |
No committed proof is supplied by this observation | Retain uncertainty; do not automatically repeat |
STALE |
No committed proof is supplied for the current observation | Reconcile current original intent/source with its owner |
DENIED |
The observation is not disclosing committed evidence | Preserve denial; do not broaden credentials/scope |
CONFLICT |
The original/current operation cannot be treated as the requested accepted result | Resolve actual conflict before proposing another mutation |
Only a COMMITTED observation can expose a receipt. A missing or uncommitted record is not permission to replay; that rule matters especially for starting a business case, where a lost reply can otherwise create duplicates. A committed release receipt carries its actual draft/key/revision/version/content hash and child pins. START has additional captured source/birth evidence; an enriched mutable instance response is not a substitute for that original acceptance witness.
The direct controller’s publish DTO remains releaseNotes, acknowledgeBreakingChange, expectedRevision; do not add a generic client-defined operationId to it. An original-attempt caller follows its separate issue/execute/observe routes with the original body. Keep those protocols separate even though they ultimately publish the same governed lifecycle.
Source contracts: native original routes, receipt invariants, observation boundary.
Worked examples
Example FLOW-LP-01 — Validate the saved draft before reviewing impact
Scenario and inputs. Nadia has saved the leave lifecycle but Review lacks its owned BPMN business flow. She can view the parent and run the permitted validation operation. The draft ID is read from the actual saved object; the story’s business key and visible title are not substitutes for it.
Procedure. Send POST /api/process-lifecycles/{draftId}/validate with no request body. Inspect draftId, saved revision, valid and every issue’s severity, code, message, stateId, nodeId, transitionId and pointer where present. Open the state/node indicated by the issue and add/correct its real work. Save, then validate the new saved revision; do not reuse the earlier result as if it described the changed draft.
Expected result. The incomplete model reports actual authoring errors and valid:false. Validation is non-mutating: it does not publish children, reserve a new release, update the overlay or create customer cases.
Failure and recovery. An authorized valid model can still fail publication governance or object rights. Treat a forbidden/backend failure as its actual error, never as an empty issue list. A generated placeholder is not evidence that the missing business flow is valid.
Sources. ProcessLifecycleController.java:651.
Example FLOW-LP-02 — Publish precisely the assessed revision
Scenario and inputs. The saved Review flow is complete at sample revision 7. Nadia has update/publish rights and has read the corresponding compatibility result. She reviewed the actual affected changes and consents only to those requiring acknowledgement. The following direct publish body is complete for that controller; it is not the original-attempt envelope.
{
"releaseNotes": "Add the reviewed manager approval flow",
"acknowledgeBreakingChange": false,
"expectedRevision": 7
}
Procedure. Use the exact assessed revision. For a direct caller, POST the body to /api/process-lifecycles/{draftId}/publish. For a native original-attempt client, issue /{draftId}/attempts/release-intents with the same original command, retain its issued intent and execute /{draftId}/attempts/{intentId}/release; observe /attempts/{intentId} when the outcome is uncertain. Inspect the real immutable release and child pins after accepted publication.
Expected result. The parent, owned child versions, overlay revision and release history are committed consistently. An explicit breaking-change acknowledgement remains an actual decision, not a default the server invents.
Failure and recovery. If acknowledgement is required, this false value is refused until the real consequence is reviewed and consented to. Missing revision is428; stale revision is409. Never manufacture an operationId or issue a fresh intent merely because an accepted publication response was lost.
Sources. ProcessLifecycleController.java:440; ProcessLifecycleController.java:920; ProcessLifecycleController.java:953; ProcessLifecycleController.java:963.
Example FLOW-LP-03 — Renew consent after another author changes the draft
Scenario and inputs. Nadia reviewed revision 7, including its current running-case impact. Another author saves revision 8 before Nadia publishes. The pending request therefore describes a different design than the authoritative draft. Retain the assessed revision and original body so that the conflict can be understood rather than hidden.
Procedure. Attempt only the original reviewed command through its actual route. On PROCESS_LIFECYCLE_CONFLICT, read the saved lifecycle again and compare the changed graph/flow. Request a new compatibility assessment for that saved revision and inspect the nested state changes and current impact projection. Obtain any newly required acknowledgement and release notes before submitting a command built from that new assessment.
Expected result. The stale publication is refused before an old assessment can authorize a different design. No child release from the failed transaction becomes a partial hidden publication, and no existing case is implicitly retargeted.
Failure and recovery. Do not automatically set acknowledgement true, copy the new revision into the old body, or add parent and child impact counts as though they were independent affected cases. If the original attempt is UNKNOWN, reconcile it through observation instead of assuming the conflict proves no other original operation committed.
Sources. ProcessLifecycleController.java:114; ProcessLifecycleController.java:920.
Example FLOW-LP-04 — Read the exact parent and state-flow release manifest
Scenario and inputs. Operations needs to explain why a leave case still uses its original Review flow after another release changed the form. The reader can view the parent’s published release. The example below is a response projection, not a complete release response or an importable lifecycle model.
{
"version": 1,
"revision": 7,
"stateFlows": {
"review": {
"definitionKey": "actual-owned-child-key",
"version": 1
}
}
}
Procedure. GET /api/process-lifecycles/leave-request/versions/1 and inspect the actual integer version, authoring revision, lifecycle model and stateFlows map. Compare a later release as a separate document. Resolve each child using the returned exact definition key/version rather than deriving its key from the state label. A terminal marker with no authored flow has no artificial child entry.
Expected result. The manifest records what was published together. Existing cases load their pinned parent and child versions; a later publication alone does not move those cases onto the new work.
Failure and recovery. When the historical snapshot is absent, PROCESS_LIFECYCLE_RELEASE_NOT_FOUND is an honest limitation. Never replace the missing version with latest/draft content or treat a client-supplied child-key pattern as ownership evidence.
Sources. ProcessLifecycleController.java:687; ProcessDefinitionVersion.java:1.
Detailed reference
Author lifecycle states and transitions through /api/process-lifecycles. The Lifecycle toolbox creates states; approved plugin actions are available when authoring a state's BPMN Flow. A draft may have incomplete connections or missing flows. PUT /api/process-lifecycles/{draftId} requires expectedRevision from the last read; stale saves return a conflict and require reloading. The overlay preserves layouts, other state flows, case-file declarations, outputs, residue, subject binding and prose.
Publication requires a complete, reachable state graph and an explicit owned BPMN flow for every working state. Empty start-to-end scaffolds are not business work; a lifecycle consisting only of completion markers cannot be published. Human work is an authored BPMN task. A terminal state without a flow completes automatically and has no outgoing transition. An authored terminal flow runs before completion, including a state that is both initial and terminal. Existing named-workflow/plugin bindings remain readable but require conversion into owned BPMN before a new lifecycle publication.
The existing compiler validates references, outcome routing, declared outputs and variable types. Every child draft goes through the shared process validator before child activation. Publication checks normal process permissions and the existing compatibility/acknowledgement gates. Changed child version pins are configuration changes and may require acknowledgeBreakingChange: true; publication never adds that acknowledgement on the caller's behalf.
One transaction creates or updates owned child drafts, publishes their exact versions, publishes the parent with those version pins, advances the overlay revision and inserts immutable release history. Any child, parent, snapshot or stale-revision failure rolls back the release. A retry cannot retain half of an attempted release. A deterministic child-key collision is refused unless the existing definition is verified as that state's owned flow.
GET /api/process-lifecycles/{definitionKey}/versions/{version} returns an immutable release with integer version, source authoring revision, lifecycle, stateFlows, subject binding, prose and publication timestamp. stateFlows maps each authored state ID to {definitionKey, version}. A terminal marker without a flow has no manifest entry. lifecycle.subprocessModels carries the authored flow content for that release. Historical versions without stored snapshots return PROCESS_LIFECYCLE_RELEASE_NOT_FOUND; current draft content is never substituted.
Running cases load their pinned parent model. Both ordinary and foreach subprocess dispatch read subprocess.definitionVersion from that model, so publishing a later lifecycle cannot retarget an existing case's state flows. Published artifacts predating version pins keep their existing execution behavior. All release storage and lookups are scoped to the current workspace, and release reads retain process definition permissions.
GET /api/process-lifecycles lists lifecycle parents through the permission-scoped catalog. Query parameters remain query, status, function, page and size (maximum 500); the response uses the existing PageResult JSON contract.
Assess and publish the reviewed revision
POST /api/process-lifecycles/{draftId}/compatibility assesses the saved overlay without a request body or authoring writes. The direct response identifies draftId, definitionKey and revision, with parent, stateFlows: [{stateId, definitionKey, assessment}] and aggregate requiresAcknowledgement. Each nested assessment retains compatibility changes, node rebind reports and nullable impact projections. Node IDs are qualified by their state; parent and state impact counts must not be added together. The aggregate acknowledgement flag is the OR of the nested flags, including prospective parent child-pin changes.
After reviewing that response, POST /api/process-lifecycles/{draftId}/publish with {releaseNotes, acknowledgeBreakingChange, expectedRevision}. Send the exact assessed revision. Missing expectedRevision, including an absent or null body, returns HTTP 428 LIFECYCLE_REVISION_REQUIRED; a stale revision returns HTTP 409 PROCESS_LIFECYCLE_CONFLICT. Reconcile edits and obtain a new assessment before renewing consent. The transaction checks the revision before child writes and retains its final revision check and rollback. A required acknowledgement is explicit; the server does not supply it.
Standalone assessment retains its existing validation, instance-view and parent-view access checks. Internal publication assessment uses the existing publication permissions and parent access; it does not introduce an instance-view prerequisite for publication. Authentication supplies the actor and workspace scope remains enforced.
An explicit state-flow rebind is a saved edit followed by assessment of the new revision. MCP and Studio Agent expose assess_lifecycle through the shared registry, and publish_lifecycle requires the same expectedRevision. Required or explicitly supplied acknowledgement also requires confirm: true and nonblank release notes in MCP. The Agent endpoint separately requires caller confirmation. See revision-bound publication and explicit state rebind.
Validate saved authoring without mutation
POST /api/process-lifecycles/{draftId}/validate takes no body. Existing parent view permission and workspace scope apply before reading the overlay. The response identifies draftId and saved revision, with valid and issues. Each issue contains severity (INFO, WARNING, ERROR), code, message, and nullable stateId, nodeId, transitionId, pointer. Pointers address the lifecycle model (for example /subprocessModels/review); state coordinates distinguish identical node IDs in different flows. Any ERROR makes valid false.
This analyzes the authoritative graph and explicit owned flow models, outcomes, executable BPMN/type checks, SLA pause/duration expressions and escalation scheduling. Publish runs the same preparation before writing children. An incomplete draft's generated placeholder cannot make it valid. A completion-only starter remains invalid; a terminal completion marker alongside authored business work is valid.
Validation writes no draft, overlay, ownership record, version or release; clients must discard evidence after the revision changes. Authorization, governance, ownership restrictions and runtime-supported SLA actions remain publish gates, so valid authoring does not guarantee publication. Missing/forbidden/backend failures retain their normal error response instead of masquerading as clean validation.
Historical ownership and explicit conversion
Saving and publishing first reconcile retained historical parent references inside the lifecycle transaction. Reconciliation records durable restrictions; it never adopts an existing workflow based on its key, compiler-shaped BPMN or the latest overlay. New children receive ownership only after the trusted definition writer records their reserved key and actual draft identity. Existing children require matching authoritative registration before any update.
Creating a lifecycle reserves its key in the workspace. Discard Draft Only on a never-published lifecycle releases that reservation in the same transaction, so the key can be created again. It stays reserved if the lifecycle still owns an existing state flow, so a new lifecycle cannot take that flow over. A purge (Delete Model & Instances) keeps the key reserved: history, audit and integrations may still name it, and creating it again is refused with PROCESS_DEFINITION_KEY_CONFLICT (SCRUM-3810). Each discarded draft is audited as PROCESS_MODEL_DRAFT_DELETED on the key, naming the requester (requestedBy) and whether the key was released (keyReleased). Escalation policies bound to the key are not removed by Discard Draft Only (a purge removes them), so a lifecycle created again under the key finds them in place.
A historical reference with no authoritative registration remains readable with ownershipStatus=UNRESOLVED and diagnostic PROCESS_OWNERSHIP_UNRESOLVED. Independent start/share/mutation is refused. Save-only state removal, later parent releases, or loss of a current overlay do not revive those capabilities. Retained versions and trusted old-parent/child execution continue unchanged.
Converting a legacy external workflow binding into an authored flow may be saved, but publication refuses to overwrite an ambiguous existing child key. Deliberately author a fresh lifecycle key or state ID with an unused generated child key. There is no automatic adoption, copying, deletion or overwrite. Creation receipts, reconciliation, publication and the overlay revision share the transaction and roll back together on failure.
SCRUM-4476 — native lifecycle root invocation
The Studio caller no longer runs publication-impact assessment/commit before either a confirmed lifecycle release or its already-reviewed rebind continuation. Optional publicationContentHash and impactRevision remain compatibility response data, not a reverse-impact permission requirement. Native lifecycle validation, current compatibility, reviewed expectedRevision, exact content/context, mutation lock and explicit breaking acknowledgement still govern the request. The existing direct publish endpoint and original-attempt protocol are unchanged. No dependent mutation, running-case migration, automatic retry or propagation-complete receipt is introduced. This source change has separate native/runtime/UI/adoption qualification; it is not evidence that those workflows ran.