85 lines
4.0 KiB
Markdown
85 lines
4.0 KiB
Markdown
# Native BPMN Graph
|
|
|
|
GovOPlaN uses BPMN 2.0 as Workflow's canonical graph language while keeping
|
|
notation support distinct from executable runtime support.
|
|
|
|
## Current Contract
|
|
|
|
- The native Workflow graph stores BPMN element and flow types, process
|
|
membership, containment, geometry, properties, and preserved extension
|
|
content. There is one editor and one graph representation.
|
|
- BPMN XML import maps standard elements and BPMN DI into the native graph.
|
|
Export deterministically renders XML and DI from the current graph. The
|
|
normalized XML artifact, its hash, and the native profile version are pinned
|
|
with every immutable revision.
|
|
- No browser-side BPMN modeler is required. The WebUI uses the same graph
|
|
surface and shared controls as the rest of GovOPlaN.
|
|
- `GET /api/v1/workflow/bpmn/profile` publishes all installed, versioned
|
|
conformance profiles.
|
|
- `POST /api/v1/workflow/bpmn/inspect` safely parses bounded BPMN 2.0 XML,
|
|
inventories every BPMN model element, detects duplicate IDs and selected
|
|
dangling references, and classifies elements as interchange-only, natively
|
|
mappable, or natively executable.
|
|
- `POST /api/v1/workflow/bpmn/compile` imports a bounded BPMN document into the
|
|
canonical native graph.
|
|
- `POST /api/v1/workflow/bpmn/render` exports a native graph as normalized BPMN
|
|
XML with BPMN DI geometry.
|
|
- `GET /api/v1/workflow/definitions/{id}/revisions/{revision}/bpmn` returns
|
|
the exact pinned document and its current availability/conformance
|
|
assessment.
|
|
- XML entities, DTD-based expansion, oversized documents, and malformed roots
|
|
are rejected.
|
|
|
|
Inspection is not XML Schema validation and does not claim that every editable
|
|
BPMN construct can be executed. Notation and interchange remain available when
|
|
the native runtime cannot activate the document.
|
|
|
|
## Built-In Profiles
|
|
|
|
- `govoplan.native.bpmn@1.0.0` is the canonical graph and interchange profile.
|
|
It maps the supported BPMN vocabulary into native nodes and edges. Activation
|
|
separately validates whether every execution semantic is implemented.
|
|
- `govoplan.native.linear@1.0.0` and `bpmn.interchange@1.0.0` remain registered
|
|
for historical revision compatibility; new editor revisions use the native
|
|
BPMN profile.
|
|
|
|
Gateways, subprocesses, event definitions, transactions, compensation,
|
|
collaboration, and choreography remain editable and exportable even when their
|
|
token or lifecycle semantics are not yet implemented.
|
|
|
|
## Execution Boundary
|
|
|
|
Adding a BPMN shape is not equivalent to implementing its token semantics,
|
|
event subscriptions, compensation, transactions, choreography, or conformance
|
|
behavior. Each executable mapping therefore needs:
|
|
|
|
1. an explicit native semantic mapping;
|
|
2. validation rules and lifecycle behavior;
|
|
3. resumability and idempotency tests;
|
|
4. migration and round-trip fixtures;
|
|
5. a declared fallback when the installed runtime cannot execute it.
|
|
|
|
Unsupported execution constructs remain visible in the native graph, but
|
|
activation remains blocked until an execution adapter declares support.
|
|
|
|
## Adapter Boundary
|
|
|
|
Adapter packages register through the
|
|
`govoplan.workflow.bpmn_adapters` Python entry-point group. Workflow discovers
|
|
them without importing a concrete module. An adapter publishes a stable ID,
|
|
version, runtime kind, conformance statement, supported elements and event
|
|
definitions, operational requirements, validation, and canonical graph
|
|
materialization.
|
|
|
|
Revisions pin the exact adapter version. If that version is unavailable after
|
|
an installation change, the document remains readable and exportable but
|
|
cannot activate. External-engine adapters must still materialize lifecycle,
|
|
handoff, retry, cancellation, and audit evidence through the canonical
|
|
Workflow instance contract; a remote engine's private state is not the
|
|
platform record.
|
|
|
|
The conformance fixtures under `tests/fixtures/bpmn` cover processes,
|
|
collaboration, choreography, events, transactions, compensation, and data
|
|
elements. Every fixture must import and export through the native graph without
|
|
losing modeled nodes or flows; activation has its own narrower test matrix.
|