govoplan-workflow-engine/docs/BPMN_INTEROPERABILITY.md

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.