ObjectStackBpmn Interop — Automation Protocol reference
Defines the specification for importing and exporting BPMN 2.0 XML process definitions.
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 { BpmnDiagnosticSchema, BpmnElementMappingSchema, BpmnExportOptionsSchema, BpmnImportOptionsSchema, BpmnInteropResultSchema, BpmnUnmappedStrategySchema, BpmnVersionSchema } from '@objectstack/spec/automation';
import type { BpmnDiagnostic, BpmnElementMapping, BpmnExportOptions, BpmnImportOptions, BpmnInteropResult, BpmnUnmappedStrategy, BpmnVersion } from '@objectstack/spec/automation';
// Validate data
const result = BpmnDiagnosticSchema.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 | optional (default: true) | 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'> | optional (default: "2.0") | Target BPMN specification version |
| includeLayout | boolean | optional (default: true) | Include BPMN DI layout data from canvas positions |
| includeExtensions | boolean | optional (default: false) | Include ObjectStack extensions in BPMN extensionElements |
| customMappings | { bpmnType: string; flowNodeAction: string; bidirectional?: boolean; notes?: string }[] | optional | Custom element mappings for export |
| prettyPrint | boolean | optional (default: true) | Pretty-print XML output with indentation |
| namespacePrefix | string | optional (default: "bpmn") | XML namespace prefix for BPMN elements |
Nested Shape: BpmnExportOptions.customMappings[number]
Mapping between BPMN XML element and ObjectStack FlowNodeAction
| Property | Type | Required | Description |
|---|---|---|---|
| bpmnType | string | ✅ | BPMN XML element type (e.g., "bpmn:parallelGateway") |
| flowNodeAction | string | ✅ | ObjectStack FlowNodeAction value |
| bidirectional | boolean | optional (default: true) | Whether the mapping supports both import and export |
| notes | string | optional | Notes about mapping limitations |
BpmnImportOptions
Options for importing BPMN 2.0 XML into an ObjectStack flow
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| unmappedStrategy | Enum<'skip' | 'warn' | 'error' | 'comment'> | optional (default: "warn") | How to handle unmapped BPMN elements |
| customMappings | { bpmnType: string; flowNodeAction: string; bidirectional?: boolean; notes?: string }[] | optional | Custom element mappings to override or extend defaults |
| importLayout | boolean | optional (default: true) | Import BPMN DI layout positions into canvas node coordinates |
| importDocumentation | boolean | optional (default: true) | Import BPMN documentation elements as node descriptions |
| flowName | string | optional | Override flow name (defaults to BPMN process name) |
| validateAfterImport | boolean | optional (default: true) | Validate imported flow against FlowSchema after import |
Nested Shape: BpmnImportOptions.customMappings[number]
Mapping between BPMN XML element and ObjectStack FlowNodeAction
| Property | Type | Required | Description |
|---|---|---|---|
| bpmnType | string | ✅ | BPMN XML element type (e.g., "bpmn:parallelGateway") |
| flowNodeAction | string | ✅ | ObjectStack FlowNodeAction value |
| bidirectional | boolean | optional (default: true) | Whether the mapping supports both import and export |
| notes | string | optional | Notes about mapping limitations |
BpmnInteropResult
Result of a BPMN import/export operation
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Whether the operation completed successfully |
| diagnostics | { severity: Enum<'info' | 'warning' | 'error'>; message: string; bpmnElementId?: string; nodeId?: string }[] | optional (default: []) | Diagnostic messages from the operation |
| mappedCount | integer | optional (default: 0) | Number of elements successfully mapped |
| unmappedCount | integer | optional (default: 0) | Number of elements that could not be mapped |
Nested Shape: BpmnInteropResult.diagnostics[number]
Diagnostic message from BPMN import/export
| 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 |
BpmnUnmappedStrategy
Strategy for unmapped BPMN elements during import
Allowed Values
skipwarnerrorcomment
BpmnVersion
BPMN specification version for export
Allowed Values
2.02.0.2
Time Relative Trigger
A declarative trigger for time-relative business rules — "act on records whose date field is coming up (or overdue) relative to today".
Webhook
Webhook schemas of the ObjectStack Automation Protocol: Webhook, WebhookTriggerType — each property with its type, default and a TypeScript example.