Bpmn Interop

@module automation/bpmn-interop

BPMN XML Interoperability Protocol

Defines the specification for importing and exporting BPMN 2.0 XML

process definitions. This enables interoperability with external BPM

tools (Camunda, Activiti, jBPM, etc.) via a plugin-based approach.

Priority: Low — long-term planning, not a core requirement.

Source: packages/spec/src/automation/bpmn-interop.zod.ts

TypeScript Usage

import { BpmnDiagnostic, BpmnElementMapping, BpmnExportOptions, BpmnImportOptions, BpmnInteropResult, BpmnUnmappedStrategy, BpmnVersion } from '@objectstack/spec/automation';
import type { BpmnDiagnostic, BpmnElementMapping, BpmnExportOptions, BpmnImportOptions, BpmnInteropResult, BpmnUnmappedStrategy, BpmnVersion } from '@objectstack/spec/automation';

// Validate data
const result = BpmnDiagnostic.parse(data);

BpmnDiagnostic

Diagnostic message from BPMN import/export

Properties

Property	Type	Required	Description
severity	`Enum<'info' \| 'warning' \| 'error'>`	✅	Diagnostic severity
message	`string`	✅	Diagnostic message
bpmnElementId	`string`	optional	BPMN element ID related to this diagnostic
nodeId	`string`	optional	ObjectStack node ID related to this diagnostic

BpmnElementMapping

Mapping between BPMN XML element and ObjectStack FlowNodeAction

Properties

Property	Type	Required	Description
bpmnType	`string`	✅	BPMN XML element type (e.g., "bpmn:parallelGateway")
flowNodeAction	`string`	✅	ObjectStack FlowNodeAction value
bidirectional	`boolean`	✅	Whether the mapping supports both import and export
notes	`string`	optional	Notes about mapping limitations

BpmnExportOptions

Options for exporting an ObjectStack flow as BPMN 2.0 XML

Properties

Property	Type	Required	Description
version	`Enum<'2.0' \| '2.0.2'>`	✅	Target BPMN specification version
includeLayout	`boolean`	✅	Include BPMN DI layout data from canvas positions
includeExtensions	`boolean`	✅	Include ObjectStack extensions in BPMN extensionElements
customMappings	`Object[]`	optional	Custom element mappings for export
prettyPrint	`boolean`	✅	Pretty-print XML output with indentation
namespacePrefix	`string`	✅	XML namespace prefix for BPMN elements

BpmnImportOptions

Options for importing BPMN 2.0 XML into an ObjectStack flow

Properties

Property	Type	Required	Description
unmappedStrategy	`Enum<'skip' \| 'warn' \| 'error' \| 'comment'>`	✅	How to handle unmapped BPMN elements
customMappings	`Object[]`	optional	Custom element mappings to override or extend defaults
importLayout	`boolean`	✅	Import BPMN DI layout positions into canvas node coordinates
importDocumentation	`boolean`	✅	Import BPMN documentation elements as node descriptions
flowName	`string`	optional	Override flow name (defaults to BPMN process name)
validateAfterImport	`boolean`	✅	Validate imported flow against FlowSchema after import

BpmnInteropResult

Result of a BPMN import/export operation

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether the operation completed successfully
diagnostics	`Object[]`	✅	Diagnostic messages from the operation
mappedCount	`integer`	✅	Number of elements successfully mapped
unmappedCount	`integer`	✅	Number of elements that could not be mapped

BpmnUnmappedStrategy

Strategy for unmapped BPMN elements during import

Allowed Values

skip
warn
error
comment

BpmnVersion

BPMN specification version for export

Allowed Values

2.0
2.0.2

On this page