---
title: Bpmn Interop
description: Bpmn Interop protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

@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.

<Callout type="info">
**Source:** `packages/spec/src/automation/bpmn-interop.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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`


---

