bpmn-engine

An execution listener is an EventEmitter passed to execute() that allows you to intercept BPMN activity lifecycle events. This is useful for injecting data, handling user tasks, or triggering external logic.

Common Events:

• activity.enter: Fired when an activity is entered.
• activity.wait: Fired when an activity is waiting for an external signal (e.g., a User Task or Catch Event).
• activity.start: Fired when an activity starts.

When an activity is in a wait state, you can use elementApi.signal(data) to provide the required input and resume the process.

import { EventEmitter } from 'node:events';

const listener = new EventEmitter();

listener.on('activity.wait', (elementApi) => {
  // Provide data to the waiting activity
  elementApi.signal({
    ioSpecification: {
      dataOutputs: [{ id: 'userInput', value: 2 }]
    }
  });
});

engine.execute({ listener });

In versions prior to v14, the engine output was shared between definitions and processes. From v14 onwards, these are decoupled. If you are attempting to load a saved state created with a version older than v14, you must manually add the process environment to the state to ensure compatibility with newer engine versions.

You can use the following script to polyfill the process environment by copying the definition's environment into each process within the state.

export function upgradeStateToVersion14(state) {
  const stateVersion = getSemverVersion(state.engineVersion);
  if (!stateVersion || stateVersion.major >= 14) return state;

  return polyfillProcessEnvironment(state);
}

function polyfillProcessEnvironment(state) {
  if (!state.definitions?.length) return state;

  const polyfilledState = JSON.parse(JSON.stringify(state));
  for (const definition of polyfilledState.definitions) {
    if (!definition.environment) continue;
    if (!definition.execution) continue;
    if (!definition.execution.processes) continue;

    for (const bp of definition.execution.processes) {
      addProcessEnvironment(definition.environment, bp);
    }
  }

  return polyfilledState;
}

function addProcessEnvironment(environment, processState) {
  processState.environment = JSON.parse(JSON.stringify(environment));
}

function getSemverVersion(version) {
  if (typeof version !== 'string') return;
  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
  if (!match) return;
  const [, major, minor, patch] = match;
  return {
    major: Number(major),
    minor: Number(minor),
    patch: Number(patch),
  };
}

The engine supports persistence by allowing you to capture the current execution state and later recover it to resume a process.

1. Capture State with getState()

getState() is an asynchronous method that returns a serialized object representing the current engine state, including variables, services, and the status of all definitions and processes.

2. Prepare for Recovery with recover(state)

To prepare an engine to resume from a saved state, call recover(state). Warning: This will throw an error if the engine is currently running.

3. Resume with resume([options])

Once recovered, call resume() to continue execution. You can pass an options object (e.g., containing a listener) to resume() to configure the resumed session. Warning: Attempting to resume a running engine will return an error in the callback or throw an error.

// To Save
const state = await engine.getState();

// To Resume
const engine = new Engine().recover(state);
engine.resume({ listener }, (err, execution) => {
  if (err) throw err;
  console.log('Resumed and completed');
});

To persist the state of a BPMN execution, you can subscribe to specific engine events using a listener. By listening to activity lifecycle events, you can capture the current state of the execution and publish it to an external system (like a database or message broker).

Key events for state persistence include:

• activity.wait: Triggered when an activity enters a waiting state.
• activity.end: Triggered when an activity completes.
• activity.timer: Triggered when a timer event is encountered; provides expiration timing via api.content.startedAt and api.content.timeout.
• activity.timeout: Triggered when a timer expires.
• end: Triggered when the entire engine execution completes.
• error: Triggered when an error occurs during execution.

import { Engine } from 'bpmn-engine';
import { EventEmitter } from 'node:events';

// ... setup code ...

const listener = new EventEmitter();

// Capture state on activity wait
listener.on('activity.wait', (_, execution) => {
  const state = execution.getState();
  // Persist state here
});

// Capture state on activity completion
listener.on('activity.end', (_, execution) => {
  const state = execution.getState();
  // Persist state here
});

// Handle timer expiration
listener.on('activity.timer', (api, execution) => {
  const expires = new Date(api.content.startedAt + api.content.timeout);
  const state = execution.getState();
  // Persist expiration info and state
});

// Handle engine completion
engine.once('end', () => {
  // Handle completion
});

// Handle engine errors
engine.once('error', (err) => {
  // Handle error
});

Script tasks execute JavaScript code defined within the BPMN XML.

• Context: The script has access to this.environment.services and this.environment.variables.
• Completion: You must call the next(err, result) callback to complete the task.
• Services: You can inject custom logic (like API clients) into the engine via the services option in .execute(), making them available to the script via this.environment.services.

// In BPMN XML
/*
<scriptTask id="scriptTask" scriptFormat="Javascript">
  <script>
    <![CDATA[
      const self = this;
      const getJson = self.environment.services.get;
      getJson('https://example.com/test').then((result) => {
        next(null, {result});
      });
    ]]>
  </script>
</scriptTask>
*/
*/

// In JavaScript execution
engine.execute({
  services: {
    get: (url) => fetch(url).then(r => r.json()),
  },
});