Features#
What bpmn-server, bpmn-web and bpmn-client do, area by area, each with where it is documented, its code and its tests.
Made from docs/features.yaml by npm run features; edit the catalog, not this page.
Modeling — BPMN elements and their settings#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| User task | Waits for a user; assignee, candidate users and groups, due and follow-up dates, priority, a form. | data, modeler, security | engine, buy-used-car, leave-application, invoice | Tasks |
| Service task | Calls a service of the application (delegateExpression, implementation) with inputs and outputs, or a connector. | customization, serviceTask, connectors | engine-basics, services, serviceTask | Tasks, IOBehaviour |
| Script task | Runs JavaScript on the instance's data, compiled under a name the debugger shows. | scripting, scriptTask | script-names, sandbox | Tasks, ScriptHandler |
| Send and receive tasks | A send task throws a message; a receive task waits for one. | msg-throw-catch | messageFlow, messages-and-signals, invoice | Tasks, MessageSignal |
| Business rule task | Evaluates a decision (DMN) with the instance's data, and maps its result. | decisions, Business Rules | dmn | Tasks, DMNEngine |
| Call activity | Starts another model as a child instance and waits for it. | callProcess | callTask, call-activity-loops | Tasks |
| Manual task, plain task (partial) | Work done outside the system; the engine passes through. Loaded as a plain node; passes through. Not tested. | NodeLoader | ||
| Embedded sub-process | A part of the process with its own data scope (data. |
subProcess, data | subprocess, subProcess, cancel-application | Tasks |
| Event sub-process | Starts on an event (error, message, timer, escalation) while its process runs. | error_events | error | Process |
| Transaction, compensation and cancel | A transaction sub-process; compensation handlers; a cancel end event and boundary. | transactions | trans | Transaction, TransEvents |
| Ad hoc sub-process | Its tasks run in any order, until its completion condition holds. | adHoc | github-issues | Tasks |
| Exclusive gateway, conditions, default flow | Takes one flow, the first whose condition holds, else the default flow. | gateways, conditionalFlow, execution | gateway, gateway1 | Gateway, Flow |
| Parallel gateway | Splits into all its flows; a join waits for every branch, as one item. | gateways | engine, gateway2, scenarios | Gateway |
| Inclusive gateway | Takes every flow whose condition holds; its join waits for the branches taken. | gateways | buy-used-car, gateway3 | Gateway |
| Event-based gateway | Waits for the first of its events; the others are cancelled. | ebg | eventBasedGateway, invoice | Gateway |
| Complex gateway (not supported) | A gateway with its own activation condition. Loaded as a plain node. Problems should say so. | NodeLoader | ||
| Start events, several per model | None, message, signal and timer starts; with several, the one a user can start is used unless one is named. | multiStartEvent, invokation | engine, dashboards | Events, Definition |
| End events, terminate | A path ends; a terminate end event ends the whole instance. | executionStructure | ebg, invoice | Events, Terminate |
| Boundary events, interrupting or not | Timer, message, signal, error and escalation events on a task; a non-interrupting one leaves the task running. | boundary-events | boundaryEvent, boundaryEvent2, leave-application | Events |
| Timers — duration, cycle, date | ISO 8601 durations, repeating cycles (R3/PT1H) and dates; long timers waited out in steps. | timers | timers-long, timerSample, timer-patterns | Timer, Cron |
| Messages and signals | Thrown and caught by events and tasks; a message starts a model or reaches the instance waiting for it. | msg-throw-catch, signal-throw-catch | messages-and-signals, signals, throw-catch | MessageSignal |
| Errors and escalations | A BPMN error caught by its error event; an escalation, interrupting or not. | execution, error_events | error, github-issues, escalation | Error, Escalation |
| Conditional event (not supported) | An event that happens when a condition on the data holds. Loaded as a plain node. Problems should say so. | NodeLoader | ||
| Link events (not supported) | A link throw continues at the link catch of the same name (a jump in a large diagram). Loaded as plain nodes, so a link throw ends its path. To implement. | NodeLoader | ||
| Multi-instance, parallel and sequential | A task or sub-process once per item of a collection, all at once or one after another. | loop | loop, loop2, github-issues, multi-instance-vote, call-activity-loops | Loop, Loop |
| Standard loop (partial) | A task repeated until its loop condition no longer holds. In the code and the docs; not tested. | loop | Loop | |
| Pools, lanes and message flows | Several processes in a collaboration; lanes; message flows between pools. | modeler | messageFlow | Definition |
| Data objects and data stores | A data object fills a field of the instance data from the application (loadDataObject). | data-objects | data-objects, data-objects | DataHandler |
| Forms | Form fields on user tasks and start events (string, long, boolean, date, enum), with default values. | inputFields, modeler | dashboards, testing | Form |
| Input and output mapping | A task's inputs from the data, and its outputs back into it (camunda:inputOutput). | data | serviceInput | IOBehaviour |
| Scripts on events (listeners) | Scripts on an element's or the process's events (enter, start, wait, end, assign, validate, take ...). | scripting, scriptEvents | script-events, script-names | Script |
| Assignment and access | Assignee and candidates as values or expressions; who can start a model (candidate starters). | security, data | api-security, buy-used-car | Process, SecureUser |
| Expressions and conditions | JavaScript expressions in conditions and attributes ($(...), data.x, item, services). | scripting, data | expressions | Expressions |
| Model verification | Checks a model without running it (structure, gateways, scripts, services, connectors, decisions). | verify | verify-model, verify-application | verifyModel |
Engine — running instances#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| Start, invoke, assign | Start an instance (optionally at a start event, with its id); complete a waiting item with data; assign it. | invokation, execution, api-summary | engine, runtime-api | Engine, Execution |
| Restart and rewind | Restart an ended instance at an item, or take a running one back to an earlier item (save points). | whats-new-3.5 | restart1, restart2, restart | Execution |
| Failed tasks and Retry; exceptions as BPMN errors | A task whose work throws is saved as failed and can be retried; or its exception raises a BPMN error. | execution | task-exceptions, run-errors | Node, Token |
| Why it went this way (decisions in the log) | Each decision logged as a block (seq, element, action, why); shown as the instance page's Rationale. | execution | engine, pages | Execution, Gateway |
| One element by itself | flags.only — an instance that runs the element it starts at, and ends once it is done. | modeler, testing | engine, testing | Token |
| Sandboxed scripts | Scripts run in a sandbox (isolated-vm) when the configuration asks; the demo mode. | security, scripting | sandbox | SandboxScriptHandler |
| Locking and several servers | An instance is locked while it runs; servers share the store; a stale lock is taken over. | advanced | engine, lifecycle-isolation | InstanceLocker |
| Upgrading running instances | Instances started on an earlier version of a model carry on after the model changes. | advanced | upgrade-running | upgradeRunning |
| The application's delegate and services | The application's services, its events (started, ended, messages), and data objects. | customization | services, engine-basics | DefaultAppDelegate |
Decisions (DMN)#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| Decision tables (DMN) | DMN decision tables, literal expressions and requirements; hit policies; FEEL. | decisions | dmn, decisions | DMNEngine, DMNParser |
| The decision editor and its tests | dmn-js in the browser, with a Test tab of its own (inputs, outputs, the rules matched). | decisions, modeler | decision-tests, decisions | decision, decisionTests |
Connectors — REST APIs#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| REST connectors (OpenAPI) | An API added from its OpenAPI document; its key encrypted; a service task calls an operation; a non-2xx status is the BPMN error HTTP_ |
connectors | connectors, connectors, connector | Connectors, OpenAPI, Secrets |
| Connectors administration and the catalog | Administration → Connectors: add from the catalog or a document, set the key, test, enable operations, delete. | connectors | connectors-admin, connectors | dashboards, connectorCatalog |
| The connector wizard in the editor | A service task's connector, its operation found by a search, its inputs and the outputs to keep. | connectors, modeler | connectors, connectors-interactions | connectors |
Data and storage#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| MongoDB storage | Instances, models, locks and users in MongoDB; indexes made at install. | setup, data | mongo.integration, integration.mongo, database-name | MongoDB, DataStore |
| SQLite storage | A table per collection in one file (node:sqlite, Node 22.5 or later). | setup | sqlite-store | SqliteDocumentStore |
| In-memory storage, custom stores | An in-memory document store (tests, demos), and the interface a custom store implements. | customization | datastore | MemoryDocumentStore, storage |
| Finding instances and items | Queries on instances and items (status, element, data, assignee, dates), paged and sorted. | data_find, data | datastore, runtime-api | QueryTranslator, DocumentQuery |
| Models, tests and history as files | Each model, its diagram, its scenarios and its saved versions are files in the models folder, ready for Git. | modeler | model-history, scenarios | ModelsDatastore, ModelHistory |
| Backup | Administration's backup: the database's collections and the models folder, as one download. | bpmn-web | dashboards | dashboards, zip |
APIs and the client#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| The engine's API (in process) | api.engine (start, invoke, assign, throwMessage, throwSignal, restart, retry) and api.data / api.model, as a user. | api-summary, invokation | runtime-api, api-boundary | API |
| The REST API | bpmn-web's /api routes, with an API key; an administrator's key for administration. | client-api, security | api, api-admin, apikey-auth | api, api2 |
| bpmn-client (remote) | A Node client for another application to start, invoke and find instances over the REST API. | bpmn-client, client-api | processEditor | BPMNClient, WebService |
| Tests in code and scenario files | testApp() — the application in memory for tests; scenario files run with runScenario. | testing | scenarios, buy-used-car, invoice | testApp, scenarios |
The web app — editor, Test tab, history#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| The model editor and its properties panel | bpmn-js with a panel shaped for bpmn-server (only what it runs), code fields with completion, element templates. | modeler | modeler, panel, code, templates | index, properties |
| Problems and modeling rules | The model checked as it is edited (verifyModel and bpmnlint); the team's rule levels in bpmnlint.json. | modeler, verify | problems, lint, lint-rules | problems, lint |
| The model's Report | The whole model as one document, in the editor, on an instance's page, and as what History compares. | modeler | report | report |
| The Test tab | Scenarios run step by step, checks, Run all, Simulate, Debug and Restart here, a task by itself. | modeler, testing | testing, scenarios | TestPanel, scenarios |
| Model history | Every save kept; two versions compared (text, moved or resized, marks on the diagram); a version viewed alone (diagram in the main area, report in the tab), restored into the editor (Save keeps it as a new version) or deleted; purge. | modeler | history, model-history | history, ModelHistory |
| The model catalog | Models to import from a catalog. | bpmn-web | catalog, catalog | catalog |
The web app — dashboards, instances, administration#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| The menu and the Workbench | One menu on every page, the editors' included; the Workbench, home. | bpmn-web | menu, menu-no-signin, workbench, navigation | menu, editorMenu |
| Dashboards — My work, Design, Administration | My work (tasks, starts); Design (models, their checks and tests); Administration (server, users, locks). | bpmn-web | dashboards, dashboards | dashboards |
| Starting a process | Run asks which start event and its start form when there is a choice or a form (the start page). | bpmn-web | dashboards | start, workflow |
| The instance page | Data, diagram (tokens, replay), items, the Rationale, the model's report, logs; filters; Retry. | bpmn-web, execution | pages, instance-filters | InstanceDetails, SVGHelper |
| Doing a task in the browser | Execute a user task with its form; assign it; force a waiting event. | bpmn-web | workflow | workflow |
| Users and groups | Sign up, sign in, accounts, groups (ADMIN, DESIGNER, ...); the first administrator. | security, bpmn-web | users, auth | UserService, UserManager |
| Guests (the demo) | A guest gets models and instances of their own; demo limits. | bpmn-web | guests | guests |
Security#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| Web security | CSRF tokens, sessions, security headers, rate limits on sign-in, error pages without secrets. | security | web-security, csrf, error-details | middleware |
| Roles and access | Who may design, administer, start and act on what; API keys; administration disabled by setting. | security | designer, admin-disabled, admin-route-boundary, api-security | roles, SecureUser |
Monitoring and logs#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| Logs | The engine's log (to the console, a file, the instance); decisions; log levels. | execution | engine | Logger |
| Health and operations | /healthz; the server's state on Administration (locks, timers, versions); restart; graceful shutdown. | bpmn-web, README | operations, pages | shutdown, dashboards |
| Monitoring from a client (partial) | bpmn-client's monitor of a remote server's instances. Not tested. | monitor |
Performance and load#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| Performance, load and memory | Throughput of starts and steps, long-running load, memory over time, and a benchmark. | advanced | perf, speed, stress, memory | CacheManager |
Command line#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| bpmn-server command line | init (a new application), verify (models), lint (modeling rules). | setup, verify | cli | cli, init |
| The console | npm run cli — an interactive console (start, list, complete, connectors); one command from the command line. | advanced | console-args | console |
| bpmn-client command line (partial) | The client's commands against a remote server. Not tested. | bpmn-client | cli |
Install, setup and deployment#
| Feature | What it does | Docs | Tests | Code |
|---|---|---|---|---|
| Setup and settings (.env) | The application's settings from .env (database, models folder, keys, MODEL_HISTORY, DISABLE_*), checked at start. | setup | app-hosting, database-name | start, loadEnv, bootConfig |
| A new application | bpmn-server init makes an application (settings, delegate, models) to start from. | setup, first-workflow | cli | init |
| One-line server install (partial) | install.sh on Ubuntu — Node, MongoDB (kernel 6.19+ included), nginx, the service, the bpmn command, HTTPS. Tested by hand and in a container, not in the test suite. | README | install.sh | |
| Docker (partial) | An image and a compose file with MongoDB. Not tested in the suite. | docker, README | docker-compose.yml |
Gaps#
- Not supported (loaded, not run): Complex gateway, Conditional event, Link events
- No test: Manual task, plain task, Standard loop, Monitoring from a client, bpmn-client command line, One-line server install, Docker
- No documentation: Manual task, plain task, Monitoring from a client