BPMN Server videos

npx bpmn-server init makes an application. It starts with no users, and no default password to guess.

Instead, the server prints a setup token, where only whoever runs it can read it.

Every page leads to the setup until there is an administrator. It asks for that token first.

Then the administrator: a user name, an email, and a password.

And, for the tutorials, two sample users: user1, an employee, and manager1, a manager.

Signed in, the Workbench: the models, the tasks waiting, and the instances that ran.

Each model shows its diagram. Open model takes it to the model editor.

The tutorials follow one model, Leave Application, from the browser to code and tests.

Lanes say who does the work in them: the Employee, Manager and HR lanes.

User tasks wait for a person, with a form: Request, then Approve.

A gateway takes one way from the outcome chosen, and a timer on Approve sends a reminder while it waits.

Next, tutorial 2: who may do what.

Security is two settings in .env, and a new application has both on.

REQUIRE_AUTHENTICATION: everyone signs in. ENFORCE_SECURITY: a task is done only by those it is assigned or offered to.

Administration lists the users, each with their groups. Adding one takes a name, an email, a password and groups.

A group is only a name, until a model gives it work. ADMIN and DESIGNER are the server's own.

In a model, a task in a lane is offered to the group of the lane's name.

Approve is in the Manager lane. But a start script can still set its assignee: here, to one user.

Without it, the task goes to everyone in the Manager group, as its lane says.

User assignment names an assignee, candidate users or candidate groups. An expression reads them from the data.

The start event keeps who started the process as requester, so Request goes back to them.

Next, tutorial 3: an employee starts a request.

Each user signs in with their own name. Here, user1, an employee.

My work is a user's page: the tasks assigned to them, those offered to them or their groups, and what they completed.

Start a process lists the processes this user may start.

The new instance: its data has requester, who started it, and the diagram shows where it waits.

Request is assigned to me: the model gives it to whoever started the process.

A task's page shows the instance's data and the task's form, with the fields the model gives it.

Completed, the task leaves Assigned to me, and the process goes on to the next task: Approve, for the Manager group.

Next, tutorial 4: a manager approves it.

Approve waits for the Manager group. Signed in as user1, an employee, it is not there.

Signed in as manager1, who is in the Manager group...

...it is Available to me: offered to my group, and not yet taken by anyone.

The task's page has the data the request was made with, and the form the model gives Approve.

Approval Outcome is a list: each choice takes the process a different way at the gateway.

Completed: it is under Recently completed, and the process has gone on to its end.

Next, tutorial 5: what ran, and why.

Every instance has its page. Its data: what the forms filled in, and requester, from the start.

Show animation replays the run on the diagram, step by step.

The items: each step, who did it, and when. The filters narrow them to a type or an element.

Clear shows every step, the gateways too.

The Rationale tells the run in order, with each decision and why it was taken.

Here, the gateway after Approve: the condition of each way out, the values it read, and the way it took.

What decided who did what is in the model. The editor's Report tab is all of it, in one printable page.

Next, tutorial 6: the same process, from Node.js.

A Node.js script can run the engine itself, on the same database as the server.

BPMNServer.create makes the application's own engine, with its settings and its services; the server keeps the timers.

A script signs nobody in: each call says which user it acts for, with their groups.

engine.start starts a process. engine.invoke completes the waiting task a query finds, with its data.

The same security rules apply: as user1, the Approve call would be refused.

Run with tsx and the application's .env, it prints each step, and who it was assigned to.

The instance is in the Workbench too, as if people had done it in the browser.

Next, tutorial 7: another application, over the REST APIs.

Another application uses the server through its REST APIs, with two keys from the server's .env.

API_KEY starts processes and reads them. API_ACTING_USER_KEY lets it act for one of its own users, on their tasks.

From Node.js, bpmn-client calls the API. engine.start starts the process for one of your users, who becomes its initiator.

The task API answers a user's tasks. Your application signed the user in, so it names them, and their groups.

A user's list holds the tasks of all their processes: the application picks this instance's, by its id.

Complete posts the task's data, recorded as done by that user, under the same rules as in the browser. Each answer is checked.

Run against the server, the process goes from one user's task to the other's, to its end.

In the Workbench, the instance is as if its users had worked on it there.

Next, tutorial 8: calling other services from a process.

A model's tests are Gherkin scenarios, in a .feature file beside it, and they run in the engine.

Each scenario: who signs in, what they start and complete, with which data; then what is checked.

Checks read the instance: its status, the elements it passed and how often, its items and its data.

Run all runs every scenario, each on an instance of its own. Each passes or fails, and a failed check says what it found.

A stub replaces a service, for that scenario's instances only: a test sends no email and calls nothing real.

The Design dashboard runs every model's tests; they are files, so they also run from the command line and in CI.

This is the model editor: the diagram, its properties on the right, and under it Problems, Report, Test and History.

Problems checks the model as you edit it, with the server's own checks and the standard modeling rules.

Conditions are JavaScript. The editor completes the names a script can use, like the model's data fields.

User tasks are assigned in the panel: an assignee, an expression such as the user who started it, or candidate groups.

A script task's script is checked as you type, the way the server compiles it.

Fixed fields clear their problems at once; what is left is information, not an error.

The Report is the whole model as one document: every element in flow order, with its settings.

Saved: the model is a file in the models folder, ready for Git. Next: testing it.

The Test tab records a run of a model as a scenario, and runs it again.

Record starts the process and shows what waits: Complete step does it, with the data you give.

The data decides the path. At the end the recording closes by itself and says Passed; the diagram marks what ran.

Full window gives the panel the whole page.

Add as a check turns what the run shows into a check: an item in its state, or a value.

A check reads as a sentence, with Edit. Add check writes one by hand: here, what must not run.

A second scenario takes the other path; each step done becomes part of the scenario, with its data.

A check added while recording goes where the run is: under the step just done.

Run all repeats every scenario on a fresh instance, and checks it. Each scenario keeps its last run.

Simulate replays the run on the diagram, numbered in order, so the panel makes room for it.

Now the model changes…

…Run all marks the scenario that broke; open it, and its step says why.

The Design dashboard: every model's tests, and Run all tests.

Scenarios are a Gherkin file beside the model: into Git, and run in CI. Next: History.

Every save of a model is kept. History lists them, newest first, with who saved each one, and when.

View shows one version as it was: its diagram in the main area, read only, and its report in the tab.

Tick two versions, then Compare: the changes, read as the model's report, not as XML.

Each change sits under its element and its process. What only moved on the diagram is listed apart.

The newer diagram opens in the main area, marked: plus added, M changed, grey M only moved, red what was removed.

Restore loads a version into the editor, unsaved: Save keeps it as a new version, so nothing is lost.

Delete removes one saved version; the others keep their numbers.

Each version is a plain file in the models folder, ready for Git. Next: the instance page.

Debug opens a test run, to see why it went the way it did.

Debug opens its panel with the variables now; each step done can be gone back to.

Restart here takes the instance back to a step done, with its data, to run it again differently.

The engine rewinds the instance to that step. Run with other data, it takes another path, and the scenario's checks now fail.

And one task, by itself: select it on the diagram, then New, The task selected.

It ran that task alone, with that input: nothing before it, nothing after.

Its instance page tells why: it ran this element only. Next: connectors.

A connector is a REST API, added once by an administrator from its OpenAPI document.

Its key is kept on the server, encrypted: models never hold it.

Designers see the operations left enabled here.

In the model, a service task calls it: select the task, then Calls: Connector.

Pick an operation: type to search every connector you may use.

Its inputs come from the document, filled in from the data of the same name.

Then the parts of the answer to keep in the instance's data.

The task now shows what it calls: the operation, its inputs, its outputs, the errors it can answer.

New, The task selected, runs it alone, with a customer's id: the API is called, and the answer kept.

No code, and no keys in the model. Next: model history.

Connectors are REST APIs that service tasks call. The catalog lists APIs ready to add, each by its published OpenAPI document.

Add reads GitHub's own document: every operation of its API, at once.

Its base URL, who may design with it, and its key. Public repositories need none; a token would be kept encrypted on the server, never in a model.

Each operation can be enabled for designers, or not. A model calls one by its id: github, then the operation.

The service task calls github/repos/get: its inputs from the instance's data, and the parts of the answer to keep.

An answer of 404 is a BPMN error: the boundary event takes the Not found path.

Run: the start form asks for an owner and a repository.

GitHub answered: the repository's description and its stars are now the instance's data.

Again, with a repository that does not exist.

GitHub answered 404: the error event caught it, and the instance ended at Not found.

Every instance has its page: its data, its diagram, and every step it took.

Show animation replays the run on the diagram, step by step.

The page opens on the user tasks: who did what, and when.

Clear shows every step, the flows and the gateways too.

The Rationale tells the run as it happened, in order, and why.

Each flow's condition, with the values it read and its result; and what each gateway chose, and why.

Filtered to one element: a joining gateway waits for its branches, then goes on, as one item.

And the full log is still there, filtered the same way. Next: debugging a run.