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.
Process Definition Persistence Manual
A practical identity and storage map
Use this guide when reading an exported process, tracing an instance to its published design, or extending the persistence adapters. Normal consultants author the owning lifecycle. Raw definition mutation/import/publication routes remain legacy diagnostic surfaces and are not an alternative around the lifecycle authoring policy.
| Coordinate | Meaning | Common mistake |
|---|---|---|
| Definition key | Business machine key, scoped by workspace | Assuming the same key means the same asset in every workspace |
| Draft ID/revision | Mutable authoring identity and concurrency snapshot | Treating a draft ID as a published definition version |
| Definition ID/version | Stable published chain and its integer release | Loading latest when a case specifies an older version |
| Lifecycle release revision | Saved overlay that produced the release | Reusing current overlay to explain historical work |
| State-flow ownership | Persisted parent/state provenance | Inferring ownership from a generated-looking key |
| BPMN XML | Durable published/draft source representation | Editing an in-memory ProcessModel as if it rewrote the published XML |
The engine derives an executable model from the selected XML. The lifecycle overlay holds authoring structure, layouts, prose and owned-flow content; publication stores immutable snapshots and exact child pins. Keep those roles separate when investigating a mismatch.
For typed case-file examples, requestedDays is Number in the process variable grammar even if the underlying record field is INTEGER. startDate/endDate are Date. Values and bindings still need their own normalization/authorization; copying a record schema does not automatically declare the process case file. The examples below are source/developer inspection recipes, not permission to change production tables or replay migrations. The introduction migration numbers in the retained reference describe history, while current setup uses the current complete ordered set.
Worked examples
Example FLOW-PD-01 — Keep workspace, key, ID and version distinct
Scenario and inputs. The people-ops workspace publishes leave-request twice. A separate test workspace also has a lifecycle with that key. Nadia wants to trace leave-2026-014 to its original released design. All IDs and version numbers must come from the actual authorized release/instance responses, not from the displayed title.
Procedure. Record the selected workspace, published definition key, stable definition ID and integer version together. Read the original parent case’s lifecycle context and compare its definition/version with the immutable release response. Then compare the later release in the same workspace as a separate artifact. If inspecting another workspace, resolve its own chain under that workspace’s current admission rather than reusing the first workspace’s definition ID.
Expected result. Within one workspace/key chain, published versions reuse the stable definition identity while advancing the version. Another workspace may have an independent chain with the same textual key. A case’s pin still identifies the original release.
Failure and recovery. A key match alone is not cross-workspace authorization or a join key for a generic catalog. Missing/denied history remains unavailable. Do not fetch a similarly named current draft to fill the gap or infer that version 2 has replaced the model of a version 1 case.
Sources. ProcessDefinitionVersion.java:1; ProcessDefinitionController.java:1.
Example FLOW-PD-02 — Read typed defaults in an exported BPMN fragment
Scenario and inputs. A developer has permission to export an immutable leave workflow and needs to explain a default numeric value and a typed list. This well-formed XML is a declaration fragment with its namespace; it is not a complete publishable process with nodes/transitions.
<process xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:inflow="https://inflowai.com/bpmn" id="leave-request" name="Leave requests">
<inflow:variable name="requestedDays" type="Number" default="0" />
<inflow:variable name="reviewTags" type="List<Text>" default="["annual-leave"]" />
</process>
Procedure. Inspect the exact exported version’s variable declarations. Check the actual process-variable type grammar and default parser, then trace how the XML mapper derives the runtime model. Compare a case pinned to that version, rather than a mutable Java object from a different load. When changing defaults, return to lifecycle authoring and its compatibility/publication workflow.
Expected result. The reader can explain the original typed declaration and distinguish Number/List<Text> from record-column storage or informal JSON guesses. The XML remains the durable model source.
Failure and recovery. A fragment that parses is not a runnable or valid published lifecycle. Do not POST raw definition mutations around PROCESS_LIFECYCLE_AUTHORING_REQUIRED; use the owning lifecycle and current type/validation gates.
Sources. ProcessDefinitionVersion.java:1; ProcessVariableRoundTripTest.java:164.
Example FLOW-PD-03 — Resolve a generated-looking state flow through its owner
Scenario and inputs. An administrator sees an internal Review definition whose key resembles a compiler-generated child. A consultant asks to share or start it independently. The name looks plausible, but historical references can be unresolved and another definition can already occupy a colliding key.
Procedure. Inspect the permission-scoped catalog classification and persisted ownership metadata. Identify the parent lifecycle and state ID from authoritative provenance, then open that parent for supported authoring/sharing. Use an actual published release to inspect its stateFlows pin. If historical ownership is UNRESOLVED, retain the diagnostic and route conversion planning through the explicit supported authoring process rather than trying to adopt the child.
Expected result. A real owned state flow remains governed by its parent and does not appear as an independently shareable/startable business workflow. Compiler-shaped names, XML resemblance and client-provided ownership fields do not create provenance.
Failure and recovery. Do not grant the child directly, overwrite an ambiguous child key, or remove a restriction because a later overlay no longer names it. Historical execution/read compatibility is separate from permission to publish a new release. Preserve the original ownership evidence and resolve the actual parent relationship before proposing a change.
Sources. ProcessAssetOwnershipService.java:13; ProcessLifecycleController.java:394.
Example FLOW-PD-04 — Review a variable contract change against actual releases
Scenario and inputs. Nadia changes a case-file declaration used by the Review form or an outcome transition. There are running cases on an older leave release and a new saved draft. The change might be more consequential than a display-name edit even when the JSON shape looks small.
Procedure. Inspect the original immutable BPMN, declared variable type/default and output binding alongside the new saved lifecycle revision. Request compatibility for that saved revision and inspect parent/state assessments and permitted impact projection. Review whether a new child version pin, renamed variable or changed type affects the existing contract. Publish only after the appropriate explicit consent, retaining the new immutable release and leaving older case pins identifiable.
Expected result. The persistence story remains explainable: the old XML/version is still the source for old execution, while a new released artifact describes the changed declaration. No raw table update retroactively rewrites the original contract.
Failure and recovery. Do not equate syntactic XML validity with semantic compatibility, and do not use an old migration introduction number as the full current installation threshold. If historical evidence or permission is missing, report the gap rather than borrowing a later model or weakening the compatibility gate.
Sources. ProcessLifecycleController.java:953; ProcessDefinitionVersion.java:1.
Detailed reference
Inflow Platform stores process definitions as BPMN 2.0 XML.
Lifecycle catalog and ownership
Ordinary authoring creates and updates the owning lifecycle through /api/process-lifecycles.
Raw definition draft/import/model mutation and publication routes remain discoverable for legacy
diagnostics but refuse ordinary writes with PROCESS_LIFECYCLE_AUTHORING_REQUIRED. Diagnostic reads,
version export, and existing engine execution remain available with their existing permissions.
The compiler uses a separately wired secured service that retains platform and object grants.
GET /api/process-lifecycles returns PageResult (items, page, size, totalItems).
It accepts query, status, function, page and size (maximum 500), in the existing request workspace
context. Classification and object visibility apply before the final page and total. Draft-only,
published and retired parents remain filterable; legacy definitions and state flows are excluded.
Shared summaries add assetKind (LIFECYCLE, STATE_FLOW, LEGACY_PROCESS), ownerLifecycleKey,
ownerStateId, hasUnpublishedChanges, ownershipStatus, and ownershipDiagnostic. Existing fields retain their meaning.
Migration 236 adds workspace-scoped, immutable process_asset_ownership provenance. Lifecycle publication
registers its parent and each compiled state flow within its transaction. Migration 239 reserves each new
compiler key atomically, preventing duplicate lifecycle/child creation from adopting an existing version
chain; reservations roll back with failed creation and remain tombstones after model deletion.
Reusing an existing child
requires matching ownership before mutation; client commands cannot set ownership. Existing parents
need positive persisted lifecycle-overlay evidence. Migration 241 records trusted creation identities
and durable restrictions for unregistered historical subprocess references. Neither key patterns nor
historical compiler shape can authorize child adoption. Ambiguous referenced workflows carry
ownershipStatus=UNRESOLVED and refuse independent actions; unreferenced legacy definitions retain
explicit legacy compatibility. No definition is deleted, auto-wrapped or republished during reconciliation.
State flows cannot receive independent object grants, workspace contract publication/new grants, or deletion/retire/restore actions. Normal sharing pickers show lifecycle parents. Runtime external start authorization consumes the same ownership service; engine subprocess execution remains trusted. Read/export legacy definitions for explicit conversion planning; create a lifecycle and author its states through the lifecycle API instead of silently converting a stored artifact.
Source of Truth
The canonical process model is the BPMN XML saved in the database:
process_definition_drafts.bpmn_xml
process_definition_versions.bpmn_xml
The internal ProcessModel is not the source of truth. It is derived from BPMN XML when the workflow runtime needs an executable representation.
flowchart TD
Designer["BPMN Designer"] --> XML["BPMN 2.0 XML"]
XML --> Database["PostgreSQL bpmn_xml"]
Database --> Mapper["BpmnModelMapper"]
Mapper --> Internal["Internal ProcessModel"]
Internal --> Runtime["Workflow Runtime"]
Why XML First
BPMN XML is portable and standards-based.
Storing XML first lets the platform:
- Export definitions back to BPMN tools.
- Preserve the original process definition.
- Keep the runtime engine replaceable.
- Avoid locking long-term persistence to one internal Java model.
- Rebuild derived runtime models when mapper behavior improves.
Tables
process_definition_drafts stores editable process definitions.
process_definition_versions stores published versions.
Each published version has:
definition_idversiondefinition_keynamestatusbpmn_xmlpublished_at
Published process definitions are versioned by definition_key within a
workspace, not by draft id. Two drafts with the same BPMN key in one workspace
publish as version 1, then version 2, and so on; the same key can have an
independent version chain in another workspace. The first published draft
creates the stable definition_id for that workspace/key chain, and later
versions reuse it. The database enforces one published row per
(workspace_id, definition_key, version).
Runtime Behavior
When a process is published, the service validates the BPMN XML and saves the published version.
When the runtime starts a process, BpmnXmlProcessModelRepository reads the published XML, maps it through BpmnModelMapper, and returns an internal ProcessModel to the engine.
This means execution is optimized for our engine, while persistence remains BPMN-standard.
Declared Process Variables
A process declares its case-file variables in the BPMN as inflow:variable elements:
<process id="permit" name="Permit">
<inflow:variable name="amount" type="Number" description="The claim amount" default="0" />
<inflow:variable name="tags" type="List<Text>" default="["a"]" />
<inflow:variable name="claim" type="Record<order>" />
...
</process>
The type attribute follows the declared-variable type grammar
(com.inflowai.platform.activity.workitem.ProcessVariableType):
- Primitives (accepted case-insensitively, stored in the canonical casing shown):
Text,Number,Boolean,Date,DateTime,User,Document,Any,Record(an untyped object),List(shorthand forList<Any>). List<T>whereTis a primitive other thanList/Any— no nested lists — orRecord<typeKey>.Record<typeKey>wheretypeKeymatches[A-Za-z_][A-Za-z0-9_.-]*; the key references a published record type.
A type outside the grammar fails at designer compile
(PROCESS_DESIGNER_VARIABLE_TYPE_INVALID) and at publish validation
(PROCESS_VARIABLE_TYPE_INVALID) — the publish check is what a BPMN-imported definition meets.
Typed defaults
A non-blank default is seeded into every new instance, coerced to the declared type, and a
caller-supplied start value always wins over the default. Publish validation refuses a default
that does not coerce (PROCESS_VARIABLE_DEFAULT_INVALID):
Number— BigDecimal-parseable (integral allowed); seeded as aBigDecimal. Number defaults carry double precision through persistence: sub-double digits are lost, and out-of-double-range or underflowing-to-zero literals are refused at publish.Boolean—true/false(case-insensitive); seeded as a boolean.Date— an ISOLocalDate;DateTime— an ISO instant or offset datetime. Both are seeded as their validated ISO strings.List<T>— a strict JSON array (trailing content is refused) whose items coerce toT; seeded as a parsed list.Record/Record<typeKey>— a strict JSON object; seeded as a map.Text,User,Document,Any— any literal is accepted and seeded as text (Documentis the stable document id, the same shape asUser).
Strict JSON means a List/Record default with duplicate object keys (e.g. {"a":1,"a":2}) is
refused, and a list refusal names the failing item by 1-based position. Since this typed-default
gate landed, already-published definitions seed List/Record defaults as real JSON values
(parsed lists and maps) where they previously seeded the raw string, and a previously-lenient
Boolean default such as yes — now refused at publish — seeds as its raw text instead of
false on definitions that predate the gate.
Shared human-task completion
A Shared assignment creates one claimable task for its candidate set. One person's completion finishes that task, whether the candidates come from a named user, a group, a role, a manager, an expression, or a supported participant.
Studio saves new shared assignments with completion policy ALL: all of the one shared task must complete, not all candidate people. The inspector describes this as "One person completes the shared task". Persisted FIRST assignments remain supported when loaded and published; opening an old draft does not rewrite it. Offline confirmers and all human-task patterns use the same shared assignment contract. Individual assignments retain their separate all/first/quorum policies.
Shared QUORUM is refused because there are no separate tasks to count. Ready and Verify identify it before publishing, and the inspector offers an explicit "Use one shared task" repair. Choose Individual when multiple completions are required.
The Initiator participant requires a captured starting user. Message/system starts
without one cannot resolve an initiator assignment. (The former "exclude the initiator"
option was removed on 2026-10-14, SCRUM-3784; a stored excludeInitiator key is ignored.) Task-specific "Performer of..." choices
are disabled because runtime history resolution does not support them. Existing
unsupported values remain visible with a diagnostic; choose a supported participant
rather than publishing a task the runtime cannot assign.
Historical lifecycle provenance and explicit conversion
New lifecycle parents and state flows carry server-created ownership registration. Saving a parent without a state does not make its child an independent process. A compiler can update an existing state flow only when its persisted registration matches that lifecycle and state. A name, old subprocess reference, or even XML identical to compiler output cannot establish permission to overwrite it.
Older referenced workflows with no authoritative registration appear in diagnostic
process listings as assetKind=LEGACY_PROCESS, ownershipStatus=UNRESOLVED, and
ownershipDiagnostic=PROCESS_OWNERSHIP_UNRESOLVED. This includes historical named
workflow bindings as well as potentially generated children. Independent start,
sharing, deletion and compiler adoption are refused. Their saved BPMN, published
versions and trusted execution for existing cases remain available under existing
permissions. Ordinary raw authoring remains lifecycle-only.
To convert this work, inspect the old immutable version and deliberately author a
new lifecycle key or new state ID with an unused child key. Publish the new owned
flow without changing the old workflow. No automatic adoption, wrapping, cleanup
or ownership relabelling takes place. Unreadable history that cannot be reconciled
returns PROCESS_OWNERSHIP_HISTORY_UNAVAILABLE; preserve it for inspection before
conversion or deletion. A current draft is never presented as missing old history.
Migration 241 adds creation receipts and a durable restriction-evidence ledger; it does not alter historical BPMN or previously applied ownership migrations.
Shared lifecycle editing and owned state flows
An EDITOR grant on a lifecycle authorizes editing and publishing its registered state flows even when the user has only VIEWER at the workspace and function. The normal global process API permissions still apply. Grant resolution follows the registered child-to-parent relationship and the canonical process keys used by the grant store; a matching name or legacy reference does not create that link. Existing explicit child denials retain ordinary nearest-scope precedence.
The trusted lifecycle publisher creates a fresh state flow through
LifecycleProcessDefinitionWriter.createStateFlowDraft(parentDraftId, stateId, command).
This checks the actual parent, its EDITOR role, the authored state, workspace,
function and deterministic child key, then creates and registers the child in one
transaction. Creating an unrelated lifecycle still requires function EDITOR.
A verified existing legacy lifecycle may author a fresh registered child without
adopting its old artifacts or relabelling the parent. Ordinary child edit/publish,
independent start and independent sharing remain refused through their raw routes.
If a process reference is both one definition's draft ID and a different definition's
key, ownership and parent-grant lookup fail closed with PROCESS_OWNERSHIP_INVALID.
Neither definition inherits the other's grants through that ambiguous reference.
New keys cannot reuse an existing draft ID or retained registered ownership ID;
creation reports PROCESS_DEFINITION_KEY_CONFLICT. Existing colliding definitions
are preserved for explicit inspection and repair, without automatic renaming or adoption.