bpmn-engine

25.0.1 API Reference

• Engine
  • new Engine([options])
    • execute([options[, callback]])
      • Execution listener
      • Execution variables
      • Execution services
    • async getDefinitionById(id)
    • addSource({sourceContext})
    • getDefinitions()
    • getState()
    • stop()
    • recover(state[, recoverOptions])
    • resume([options, [callback]])
• Execution API
  • getActivityById(activityId)
  • getState()
  • signal(message[, options])
  • cancelActivity(message)
• Engine events
  • Activity events
  • Event Api
  • Sequence flow events
• Expressions

Engine

The engine. Executes passed BPMN 2.0 definitions.

new Engine([options])

Creates a new Engine.

Arguments:

• options: Optional options, passed to environment:
  • disableDummyScript: optional boolean to disable dummy script supplied to empty ScriptTask
  • elements: optional object with element type mapping override
  • expressions: optional override expressions handler
  • extendFn: optional extend serializer function
  • Logger: optional Logger factory, defaults to debug logger
  • moddleContext: optional BPMN 2.0 definition moddle context
  • moddleOptions: optional bpmn-moddle options to be passed to bpmn-moddle
  • name: optional name of engine,
  • scripts: optional inline script handler, defaults to nodejs vm module handling, i.e. JavaScript
  • source: optional BPMN 2.0 definition source as string
  • sourceContext: optional serialized context supplied by moddle-context-serializer
  • timers: Timers instance
  • typeResolver: optional type resolver function passed to moddle-context-serializer
  • extensions: optional behavior extensions

Returns:

• name: engine name
• broker: engine broker
• state: engine state
• activityStatus: string, activity status
  • executing: at least one activity is executing, e.g. a service task making a asynchronous request
  • timer: at least one activity is waiting for a timer to complete, usually only TimerEventDefinition’s
  • wait: at least one activity is waiting for a signal of some sort, e.g. user tasks, intermediate catch events, etc
  • idle: idle, no activities are running
• stopped: boolean stopped
• execution: current engine execution
• environment: engine environment
• logger: engine logger
• async execute(): execute definition
• async getDefinitionById(): get definition by id
• async getDefinitions(): get all definitions
• async getState(): get execution serialized state
• recover(): recover from state
• async resume(): resume execution
• async stop(): stop execution
• waitFor(): wait for engine events, returns Promise

import fs from 'node:fs';
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';

import { Engine } from 'bpmn-engine';

const camunda = createRequire(fileURLToPath(import.meta.url))('camunda-bpmn-moddle/resources/camunda.json');

const engine = new Engine({
  name: 'mother of all',
  source: fs.readFileSync('./test/resources/mother-of-all.bpmn'),
  moddleOptions: {
    camunda,
  },
});

execute([options[, callback]])

Execute definition.

Arguments:

• options: Optional object with options to override the initial engine options
  • listener: Listen for activity events, an EventEmitter object
  • variables: Optional object with instance variables
  • services: Optional object with service functions
  • expressions: Optional expression handling override
• callback: optional callback
  • err: Error if any
  • execution: Engine execution

Execute options overrides the initial options passed to the engine before executing the definition.

Returns Execution API

import { EventEmitter } from 'node:events';

import { Engine } from 'bpmn-engine';

const source = `
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <dataObjectReference id="inputFromUserRef" dataObjectRef="inputFromUser" />
    <dataObject id="inputFromUser" />
    <startEvent id="theStart" />
    <userTask id="userTask">
      <ioSpecification id="inputSpec">
        <dataOutput id="userInput" />
      </ioSpecification>
      <dataOutputAssociation id="associatedWith" sourceRef="userInput" targetRef="inputFromUserRef" />
    </userTask>
    <endEvent id="theEnd" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="userTask" />
    <sequenceFlow id="flow2" sourceRef="userTask" targetRef="theEnd" />
  </process>
</definitions>`;

const engine = new Engine({
  name: 'first',
  source,
  variables: {
    data: {
      inputFromUser: 0,
    },
  },
});

const listener = new EventEmitter();
listener.on('activity.wait', (elementApi) => {
  elementApi.owner.logger.debug(`<${elementApi.executionId} (${elementApi.id})> signal with io`, elementApi.content.ioSpecification);
  elementApi.signal({
    ioSpecification: {
      dataOutputs: [
        {
          id: 'userInput',
          value: 2,
        },
      ],
    },
  });
});

engine.execute(
  {
    listener,
    variables: {
      data: {
        inputFromUser: 1,
      },
    },
  },
  (err, execution) => {
    if (err) throw err;
    console.log('completed with overridden listener', execution.environment.output);
  }
);

Execution listener

An EventEmitter object with listeners. Listen for activity events.

import { EventEmitter } from 'node:events';

import { Engine } from 'bpmn-engine';

const source = `
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <userTask id="userTask" />
  </process>
</definitions>`;

const engine = new Engine({
  name: 'first listener',
  source,
});

const listener = new EventEmitter();
listener.on('activity.enter', (elementApi, engineApi) => {
  console.log(`${elementApi.type} <${elementApi.id}> of ${engineApi.name} is entered`);
});

listener.on('activity.wait', (elemntApi, instance) => {
  console.log(`${elemntApi.type} <${elemntApi.id}> of ${instance.name} is waiting for input`);
  elemntApi.signal('don´t wait for me');
});

engine.execute({
  listener,
});

Execution variables

Execution variables are passed as the first argument to #execute.

import fs from 'node:fs';

import { Engine } from 'bpmn-engine';

const engine = new Engine({
  name: 'using variables',
  source: fs.readFileSync('./test/resources/simple-task.bpmn'),
});

const variables = {
  input: 1,
};

engine.execute(
  {
    variables,
  },
  (err, engineApi) => {
    if (err) throw err;
    console.log('completed');
  }
);

Execution services

A service is a function exposed on environment.services.

import { Engine } from 'bpmn-engine';
import bent from 'bent';

const source = `
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <startEvent id="theStart" />
    <scriptTask id="scriptTask" scriptFormat="Javascript">
      <script>
        <![CDATA[
          const get = environment.services.get;

          const self = this;

          get('https://example.com/test').then((body) => {
            environment.variables.scriptTaskCompleted = true;
            next(null, {result: body});
          }).catch(next)
        ]]>
      </script>
    </scriptTask>
    <endEvent id="theEnd" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="scriptTask" />
    <sequenceFlow id="flow2" sourceRef="scriptTask" targetRef="theEnd" />
  </process>
</definitions>`;

const engine = new Engine({
  name: 'services doc',
  source,
});

engine.execute(
  {
    services: {
      get: bent('json'),
    },
  },
  (err, engineApi) => {
    if (err) throw err;
    console.log('completed', engineApi.name, engineApi.environment.variables);
  }
);

async getDefinitionById(id)

Get definition by id, returns Promise

addSource({sourceContext})

Add definition source by source context.

Arguments:

• source: object
  • sourceContext: serializable source

import { EventEmitter } from 'node:events';

import BpmnModdle from 'bpmn-moddle';
import * as elements from 'bpmn-elements';
import { Engine } from 'bpmn-engine';
import Serializer, { TypeResolver } from 'moddle-context-serializer';

const engine = new Engine({
  name: 'add source',
});

(async function IIFE(source) {
  const sourceContext = await getContext(source);
  engine.addSource({
    sourceContext,
  });

  const listener = new EventEmitter();
  listener.once('activity.wait', (api) => {
    console.log(api.name, 'is waiting');
    api.signal();
  });

  await engine.execute({
    listener,
  });

  await engine.waitFor('end');
})(`
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <startEvent id="start" />
    <sequenceFlow id="flow1" sourceRef="start" targetRef="task" />
    <userTask id="task" name="lazy source user" />
    <sequenceFlow id="flow2" sourceRef="task" targetRef="end" />
    <endEvent id="end" />
  </process>
</definitions>
`);

async function getContext(source, options) {
  const moddleContext = await getModdleContext(source, options);

  if (moddleContext.warnings) {
    moddleContext.warnings.forEach(({ error, message, element, property }) => {
      if (error) return console.error(message);
      console.error(`<${element.id}> ${property}:`, message);
    });
  }

  const types = TypeResolver({
    ...elements,
    ...options?.elements,
  });

  return Serializer(moddleContext, types, options?.extendFn);
}

function getModdleContext(source, options) {
  const bpmnModdle = new BpmnModdle(options);
  return bpmnModdle.fromXML(source);
}

getDefinitions()

Get all definitions

import { Engine } from 'bpmn-engine';

const source = `
<?xml version="1.0" encoding="UTF-8"?>
<definitions id="Definition_42" xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <startEvent id="theStart" />
    <userTask id="userTask" />
    <endEvent id="theEnd" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="userTask" />
    <sequenceFlow id="flow2" sourceRef="userTask" targetRef="theEnd" />
  </process>
</definitions>`;

const engine = new Engine({
  source,
});

engine.getDefinitions().then((definitions) => {
  console.log('Loaded', definitions[0].id);
  console.log('The definition comes with process', definitions[0].getProcesses()[0].id);
});

getState()

Asynchronous function to get state of a running execution.

The saved state will include the following content:

• state: running or idle
• engineVersion: module package version
• moddleOptions: Engine moddleOptions
• definitions: List of definitions
  • state: State of definition, pending, running, or completed
  • processes: Object with processes with id as key
    • variables: Execution variables
    • services: Execution services
    • children: List of child states
      • entered: Boolean indicating if the child is currently executing

import fs from 'node:fs/promises';
import { EventEmitter } from 'node:events';

import { Engine } from 'bpmn-engine';

const processXml = `
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <startEvent id="theStart" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="userTask" />
    <userTask id="userTask" />
    <sequenceFlow id="flow2" sourceRef="userTask" targetRef="theEnd" />
    <endEvent id="theEnd" />
  </process>
</definitions>`;

const engine = new Engine({
  source: processXml,
});

const listener = new EventEmitter();

let state;
listener.once('activity.wait', async () => {
  state = await engine.getState();
  await fs.writeFile('./tmp/some-random-id.json', JSON.stringify(state, null, 2));
});

listener.once('activity.start', async () => {
  state = await engine.getState();
  await fs.writeFile('./tmp/some-random-id.json', JSON.stringify(state, null, 2));
});

engine.execute({
  listener,
});

stop()

Stop execution. The instance is terminated.

import { EventEmitter } from 'node:events';

import { Engine } from 'bpmn-engine';

const source = `
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <process id="theProcess" isExecutable="true">
    <startEvent id="theStart" />
    <userTask id="userTask" />
    <endEvent id="theEnd" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="userTask" />
    <sequenceFlow id="flow2" sourceRef="userTask" targetRef="theEnd" />
  </process>
</definitions>`;

const engine = new Engine({
  source,
});
const listener = new EventEmitter();

let state;
listener.once('activity.wait', async () => {
  engine.stop();
  state = await engine.getState();
});

engine.execute({
  variables: {
    executionId: 'some-random-id',
  },
  listener,
});

recover(state[, recoverOptions])

Recover engine from state.

NB! Will throw an error if the engine is running.

Arguments:

• state: engine state
• recoverOptions: optional object with options that will override options passed to the engine at init, but not options recovered from state

import { Engine } from 'bpmn-engine';

const state = fetchSomeState();
const engine = new Engine().recover(state);

resume([options, [callback]])

Resume execution function with previously saved engine state.

NB! Attempting to resume a running engine returns error in callback or throws if callback is not passed.

Arguments:

• options: optional resume options object
  • listener: execution listener
• callback: optional callback
  • err: Error if any
  • execution: Resumed engine execution

import { EventEmitter } from 'node:events';

import { Engine } from 'bpmn-engine';

const state = fetchSomeState();
const engine = new Engine().recover(state);

const listener = new EventEmitter();

engine.resume({ listener }, () => {
  console.log('completed');
});

Execution API

• name: engine name
• state: execution state
• stopped: is execution stopped?
• broker: engine message broker
• environment: execution environment
• definitions: list of definitions
• activityStatus: string, execution activity status, e.g. if wait or timer no activities are executing, if executing there can be both running timers and waiting tasks, if timer there can be waiting activities but no executing activities, and so forth
  • executing: at least one activity is executing, e.g. a service task making a asynchronous request
  • timer: at least one activity is waiting for a timer to complete, usually only TimerEventDefinition’s
  • wait: at least one activity is waiting for a signal of some sort, e.g. user tasks, intermediate catch events, etc
  • idle: idle, no activities are running, the engine is not running at all
• isRunning: are any definition running?
• getActivityById(activityId)(#getactivitybyid-activityid): get activity/element by id, returns first found among definitions
• getState(): get execution state
• getPostponed(): get postponed activities, i.e. activities waiting for some interaction, signal, or timer
• signal(message): send signal to execution, distributed to all definitions
• cancelActivity(message): send cancel activity to execution, distributed to all definitions
• stop(): stop execution
• waitFor(event): wait for engine events, returns Promise

getActivityById(activityId)

Get activity/element by id. Loops the definitions and returns the first found activity with id.

• activityId: Activity or element id

Returns activity.

getState()

Get execution state.

signal(message[, options])

Delegate a signal message to all interested parties, usually MessageEventDefinition, SignalEventDefinition, SignalTask (user, manual), ReceiveTask, or a StartEvent that has a form.

Arguments:

• message: optional object
  • id: optional task/element id to signal, also matched with Message and Signal id. If not passed only anonymous Signal- and MessageEventDefinitions will pick up the signal.
  • executionId: optional execution id to signal, specially for looped tasks, also works for signal tasks that are not looped
  • [name]*: any other properties will be forwarded as message to activity
• options: optional options object
  • ignoreSameDefinition: boolean, ignore same definition, used when a signal is forwarded from another definition execution, see example

An example on how to setup signal forwarding between definitions:

engine.broker.subscribeTmp(
  'event',
  'activity.signal',
  (routingKey, msg) => {
    engine.execution.signal(msg.content.message, { ignoreSameDefinition: true });
  },
  { noAck: true }
);

cancelActivity(message)

Delegate a cancel message to all interested parties, perhaps a stalled TimerEventDefinition.

Arguments:

• message: optional object
  • id: optional activity id to cancel execution
  • executionId: optional execution id to signal, useful for an event with multiple event defintions
  • [name]*: any other properties will be forwarded as message to activity

Engine events

Engine emits the following events:

• error: An non-recoverable error has occurred
• stop: Executions was stopped
• end: Execution completed

Activity events

Each activity and flow emits events when changing state.

• activity.enter: An activity is entered
• activity.start: An activity is started
• activity.wait: The activity is postponed for some reason, e.g. a user task is waiting to be signaled or a message is expected
• wait: Same as above
• activity.end: An activity has ended successfully
• activity.leave: The execution left the activity
• activity.stop: Activity run was stopped
• activity.throw: An recoverable error was thrown
• activity.error: An non-recoverable error has occurred

Event Api

Events are emitted with api with execution properties

• name: engine name
• state: state of execution, i.e running or idle
• stopped: is the execution stopped
• environment: engine environment
• definitions: executing definitions
• stop(): stop execution
• getState(): get execution serializable state
• getPostponed(): get activities in a postponed state

Sequence flow events

• flow.take: The sequence flow was taken
• flow.discard: The sequence flow was discarded
• flow.looped: The sequence is looped

Expressions

If not overridden bpmn-elements expressions handler is used.

Try out aircall-expression-parser by Aircall if you expect advanced expressions with operators.

This site is open source. Improve this page.