BPMN-as-Code

Write business processes as plain text, get standard BPMN 2.0 diagrams.

process "Order Fulfillment"

start: order_received "Order Received"
end:   order_complete "Order Complete"

task: validate "Validate Order" user by "Sales Team"
task: payment  "Process Payment" service
task: ship     "Ship Order"     by "Warehouse"

gateway: is_valid "Is Order Valid?" exclusive

order_received -> validate -> is_valid
is_valid --[yes]--> payment -> ship -> order_complete
is_valid --[no]-->  order_complete

Install

npm install bpmn-as-code

CLI Usage

# Compile DSL to BPMN XML
npx bpmn-compile process.bac

# Compile with PNG export
npx bpmn-compile process.bac --png

# Specify output path
npx bpmn-compile process.bac output.bpmn

Library Usage

import { compile } from 'bpmn-as-code';

const result = compile(`
  process "My Process"
  start: a "Start"
  end: b "Done"
  a -> b
`);

if (result.xml) {
  console.log(result.xml);       // BPMN 2.0 XML string
  console.log(result.nodeCount); // 2
  console.log(result.flowCount); // 1
} else {
  console.error(result.error);   // Parse error with line/col
}

For more control, import individual modules:

import { parse } from 'bpmn-as-code/parser';
import { generate } from 'bpmn-as-code/generator';

const ast = parse(source);
const xml = generate(ast);

Web Editor

Open editor/index.html in a browser for an interactive editor with live preview, syntax highlighting, and a dark/light theme toggle.

DSL Syntax Reference

Process Declaration

process "Process Name"

Events

start:    id "Label"                                    # plain start
start:    id "Label" message                            # message start
start:    id "Label" timer                              # timer start
end:      id "Label"                                    # plain end
end:      id "Label" terminate                          # terminate end
end:      id "Label" error                              # error end
catch:    id "Label" timer                              # intermediate catch
throw:    id "Label" signal                             # intermediate throw
boundary: id "Label" error on parent_id                 # interrupting boundary
boundary: id "Label" timer on parent_id noninterrupting # non-interrupting

Event subtypes: message, timer, signal, error, terminate, escalation, compensate, conditional, link, none

Tasks

task: id "Label"                          # generic task
task: id "Label" user by "Role"           # user task with performer
task: id "Label" service                  # service task
task: id "Label" script                   # script task
task: id "Label" send                     # send task
task: id "Label" receive                  # receive task
task: id "Label" manual                   # manual task
task: id "Label" businessrule             # business rule task
task: id "Label" service loop             # standard loop
task: id "Label" service loop parallel    # multi-instance parallel
task: id "Label" service loop sequential  # multi-instance sequential

Activities

subprocess: id "Label"
call:       id "Label"

Gateways

gateway: id "Label" exclusive    # XOR (default if omitted)
gateway: id "Label" parallel     # AND
gateway: id "Label" inclusive    # OR
gateway: id "Label" eventbased  # event-based

Flows

a -> b -> c                # sequence flow (chainable)
a --[condition]--> b       # conditional flow
a ==> b                    # default flow
a ~> b                     # message flow (between pools)

Pools & Lanes

pool: id "Pool Name"
lane: id "Lane Name" in pool_id

Annotations & Data

note:      id "Text" on element_id    # text annotation
data:      id "Label"                 # data object
datastore: id "Label"                 # data store

Comments

# This is a comment

Examples

See the examples/ directory:

• order-fulfillment.bac — basic workflow with gateways
• employee-onboarding.bac — parallel gateway pattern
• comprehensive.bac — all element types in one diagram

License

MIT