Skip to content

Build a workflow application#

Journey B: your own application on BPMN Server, with your models, users and services. The tutorials take you through it with one example.

What init makes is a skeleton: bpmn-web with your models and services, working from the first start. Keep its pages for a team that works inside it, or replace its sign-in and pages with your own application's, keeping bpmn-web's APIs and Administration behind it, and its model editor as a stand-alone design server: see From the skeleton to your application.

1. Install#

Install Node.js 20 or later. To avoid database setup for a first run:

npx bpmn-server init my-app --memory
cd my-app
npm start

Open http://localhost:3000. The first page asks for the administrator: give the setup token the server printed when it started, and choose a name and password. See The first start. The in-memory database is temporary and is cleared when the application stops.

For data that is kept, create the application without --memory: it uses MongoDB, or SQLite as Custom persistence shows. See Installation.

The generated project contains:

Location Role
processes/ BPMN process models and DMN decisions, with their tests
connectors/appServices.ts TypeScript services called by service tasks
delegates/appDelegate.ts Application lifecycle hooks and service provider
settings/config.ts How the application behaves
.env What differs per machine, and secrets
index.ts Starts the host web application

2. Configure#

What goes in .env and what in settings/config.ts, and every setting: Settings. Add users and their groups from Administration: Security.

3. Design and test#

Model in the model editor: its Problems tab checks the model as you edit, its Test tab records and runs scenarios. Run a process from My work, complete its tasks, and look at the instance and its history.

Tests are Gherkin files beside the models, run in the engine: Testing and debugging models, and Tutorial 7.

Try this first: a "Request approval" process: Start → Submit request (user task) → Approve request (user task) → End. Once that works, add a gateway for Approved? and a rejection path. It exercises most of what a real process needs.

4. Integrate services#

Once your workflow behaves correctly, replace demonstration operations with real application behavior:

  1. Connect service tasks to your TypeScript services, or to REST APIs with connectors: Connect external services.
  2. Use DMN decisions for business-rule tables, or application code for complex logic.
  3. Keep authoritative business records in your application database; store workflow state separately. See Application integration.

5. Deploy#

Choose how it runs, with the engine in the web application's process or its own: Ways to run it. Before real users reach it: sign-in and task authorization (Security), persistent storage, the settings production refuses to start without, and how a crashed step is recovered (Advanced). Re-run model checks and tests after each change. Docker and a one-line server install: Docker, Installation.

Comments