23.0.2 API Reference

Engine
- new Engine([options])
Execution API
Engine 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.

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.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API.md

API.md

23.0.2 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

Files

API.md

Latest commit

History

API.md

File metadata and controls

23.0.2 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

`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]])`

`getActivityById(activityId)`

`getState()`

`signal(message[, options])`

`cancelActivity(message)`