bpmn-middleware

Express middleware for BPMN engine.

Under construction so breaking changes will occur until v1.

Usage

import express from 'express';
import { bpmnEngineMiddleware, HttpError } from 'bpmn-express-middleware';

const app = express();
app.use('/rest', bpmnEngineMiddleware({ idleTimeout: 90000 }));

app.use(errorHandler);

app.listen(3000);

function errorHandler(err, req, res, next) {
  if (!(err instanceof Error)) return next();
  if (err instanceof HttpError) return res.status(err.statusCode).send({ message: err.message });
  res.status(502).send({ message: err.message });
}

Middleware

`bpmnEngineMiddleware([options])``

Create BPMN engine middleware.

Options:

• adapter: Optional storage adapter. Defaults to in-memory adapter based on LRU cache
• engineOptions: Optional BPMN Engine options
• engineCache: Optional engine LRU cache, defaults to new LRUCache({ max: 1000 })
• broker: Optional smqp broker, used for forwarding events from executing engines
• idleTimeout: Optional positive integer, engine execution timeout in milliseconds before engine execution is considered idle and is stopped, defaults to 120000ms

Returns Expressjs Router with extra properties:

• middleware: middleware route functions
• engines: BPMN engines handler

Routes

• GET (*)?/version
• GET (*)?/deployment
• POST (*)?/deployment/create
• POST (*)?/process-definition/:deploymentName/start
• GET (*)?/running
• GET (*)?/status/:token
• GET (*)?/status/:token/:activityId
• POST (*)?/resume/:token
• POST (*)?/signal/:token
• POST (*)?/cancel/:token
• POST (*)?/fail/:token
• GET (*)?/state/:token
• DELETE (*)?/state/:token
• DELETE (*)?/internal/stop
• DELETE (*)?/internal/stop/:token

GET (*)?/version

Get app version.

Response body:

• version: string, resolved from process.cwd() + '/package.json

GET (*)?/deployment

Get app name.

Response body:

• name: string, resolved from process.cwd() + '/package.json

POST (*)?/deployment/create

Create deployment by passing multipart form with BPMN diagram file.

Content-type: multipart/form-data

Form fields:

• deployment-name: string, deployment name;
• deployment-source: string, deployment source;

Response body:

• id: string, same as deployment name
• deploymentTime: date, now
• deployedProcessDefinitions: object
  • [deploymentName]: object, key as deployment name
    • id: string, same as deployment name

POST (*)?/process-definition/:deploymentName/start

Start deployment.

Params:

• deploymentName: deployment name

Request body:

• businessKey: string, business key
• variables: optional object with variables to pass to engine

Response body:

• id: string, unique execution token

GET (*)?/running

Get all running instances.

Response body:

• engines: list of executing engines
  • token: string, unique execution token
  • name: string, deployment name
  • state: string, engine status, idle, running, stopped, or error
  • activityStatus: string, running activity status, idle, executing, timer, or wait

GET (*)?/status/:token

Get process status

GET (*)?/status/:token/:activityId

Get process activity status

POST (*)?/resume/:token

Resume process run

POST (*)?/signal/:token

Signal process activity.

Request body:

• id: activity id
• executionId: optional activity execution id
• message: optional message to signal activity with

POST (*)?/cancel/:token

Cancel process activity.

Request body:

• id: activity id
• executionId: optional activity execution id

POST (*)?/fail/:token

Fail process activity.

Request body:

• id: activity id
• executionId: optional activity execution id
• message: optional message to send to activity

GET (*)?/state/:token

Get process engine state.

DELETE (*)?/state/:token

Delete process engine state.

DELETE (*)?/internal/stop

Stop all running instances on this specific app instance.

DELETE (*)?/internal/stop/:token

Stop running instances by token on this specific app instance.

Events

BPMN Engine will forward BPMN engine events to app prefixed by bpmn/.

Event bpmn/end

BPMN Engine has completed successfully.

Handler arguments:

• engine: Engine instance

Event bpmn/stop

BPMN Engine execution has stopped.

Handler arguments:

• engine: Engine instance

Event bpmn/error

BPMN Engine execution has failed.

Handler arguments:

• err: Error
• engine: Engine instance

Storage adapter

Persistent storage adapter, defaults to in memory storage.

Three types will be saved to adapter:

• deployment: BPMN deployment with references to BPMN files
• file: BPMN file with meta and content
• state: BPMN engine state

async upsert(type, key, value[, options])

Set entry with key.

• type: string, storage type, deployment, file, or state
• key: string, storage key
• value: object, value
• options: optional object with options

async delete(type, key)

Delete entry by key.

• type: string, storage type, deployment, file, or state
• key: string, storage key

async fetch(type, key[, options])

Fetch entry by key.

• type: string, storage type, deployment, file, or state
• key: string, storage key
• options: optional object with options
  • exclude: optional list of fields to exclude

async query(type, qs[, options])

Query entries.

• type: string, storage type, deployment, file, or state
• qs: object, storage query
  • exclude: optional list of fields to exclude
  • state: optional string, get engine states by state of engine, idle, running, etc
  • caller: optional object, get engines by call activity caller
    • token: string, calling process token
    • deployment: string, calling process deployment name
    • id: string, calling activity id
    • type: string, calling activity type
    • executionId: string, calling activity execution id
• options: optional object with options

Returns:

• records: List of entries