Coder Legion - Recent posts tagged bpmn

BPMN as Code: From a Text-Based Model to a Working Microservices Sagas

Mon, 26 Oct 2026 08:43:45 +0000

Contents

Issues With Conventional BPMN Tools
Discovering Mermaid-BPMN
Making It Practical
A Real-World Example: Modeling a Payment Saga
From BPMN Source to an Executable Saga
Conclusions

I've used Documentation as Code for years when designing backends and entire applications. Most of my diagrams are written in PlantUML, with their source stored alongside other design documents. It suits me much better than drawing everything by hand.

Then I had to model a microservices Saga for Camunda. The process involved parallel checks, deadlines, human decisions and compensation. I wanted to write BPMN the same way I wrote UML, but couldn't find a toolchain I was comfortable using. Eventually I found Mermaid-BPMN and built a workbench around it.

Issues With Conventional BPMN Tools

I tried the obvious options. I find arranging shapes in draw.io or Camunda Modeler slow, particularly when a process keeps changing. I'd rather edit source and immediately see what the diagram looks like.

BPMN XML is source too, technically. But it is cumbersome to write from scratch and not much better to edit by hand. I also looked at other BPMN DSLs. Their diagrams didn't look right to me.

I wanted readable source and conventional BPMN diagrams, including horizontal pools and lanes. I also wanted a live editor on my own host and a CLI for generating SVGs from local files. Although my implementation used Camunda, I didn't want the modeling tools tied to one process engine.

And the diagrams had to be readable by people besides developers: architects, product owners, business analysts and anyone reviewing the process.

Discovering Mermaid-BPMN

After I inspected a few other tools, I came across the great derari/mermaid-bpmn, an external Mermaid plugin with its own BPMN DSL, rich and comprehensive. It supports vertical and horizontal BPMN directions, activities, pools and lanes, gateways, events and annotations. There was also a basic live-editor example.

I liked the language and the diagrams it generated. The DSL, parser, renderer and original editor are all the original author's work. I started with that project and added what I needed for day-to-day use. The result is Mermaid BPMN Workbench.

Making It Practical

First, I packaged the editor for deployment with Docker. It builds to static files served by Nginx, so I can run it on my own host without keeping the development server running. The image is available on Docker Hub.

I then worked on the editor itself. With a large process diagram, I need to zoom in, move around and quickly return to the full view. So I added pan, zoom and fit controls. I added source-pane width presets and font-size controls, too. The source and these settings are saved in the browser and restored after a reload. There is also a clear-source button and an option to open the full SVG in a separate tab.

One detail took a little care. Pan and zoom change the SVG displayed in the editor. Exporting that modified SVG could give you the part you were looking at rather than the complete diagram. I keep a clean snapshot for downloads and the Open SVG action.

I also needed SVGs for documentation, without opening the browser editor each time. I built a Mermaid-BPMN CLI for that. It generates an svg with this one-liner.

npx mermaid-bpmn-cli --browser /path/to/chrome payment-process.mmd

It writes payment-process.svg next to the source. Currently it requires Node.js 22.12 or later and an installed Chrome or Chromium executable; you have to pass the browser path explicitly. I have used the CLI in my project's documentation workflow since that. It simplifies the workflow a lot. Also can be used in automated CI workflows for Documentation-as-Code.

A Real-World Example: Modeling a Payment Saga

The process that prompted all this was a payment Saga (here is the link to the anonymized source).

It starts by debiting the payer, then runs anti-fraud and compliance/restriction checks in parallel. The results can lead to approval, denial, manual review or suspicious-payment handling.

The checks have a 30-second deadline. If they don't finish in time, the process refunds the payer. Manual review has a 20-minute deadline, with the same default outcome if nobody makes a decision. We chose these defaults because processing an erroneous payment would cost considerably more than rejecting a valid one. I put that reasoning in annotations next to the relevant paths.

The Diagram

![The Diagram](./images/payment-saga.svg)

The transfer to the payee is marked as an irreversible pivot point. Earlier failures are handled by compensation: an automatic refund and a rollback of payment status. Suspicious payments also trigger a security notification in parallel with the refund, with the paths joining before the final outcome.

This is the kind of process I wanted to keep in a text file: branches, timers, compensation, and the business reasons for some of the decisions. I can change the source, review the diff and regenerate the diagram.

From BPMN Source to an Executable Saga

I also took the Saga through implementation. The microservices were deployed, the Saga coordinated them, and I tested the cases in the implemented process.

For the engine, I needed BPMN XML. I had an AI agent translate the DSL, reviewed the result myself, manually validated it and used Camunda Modeler for static debugging before deployment. I was glad to have the Modeler for that part, even though I didn't want to use it for writing the original model.

This translation step isn't a Workbench feature. The workbench gives me the source editor and SVG generation; translation, engine validation, deployment and testing are steps in my project. I checked that the executable process preserved the deadlines, branches and compensation behavior in the model.

Conclusions

I believe, this tooling is useful for any modeler - architects, developers, business analyst and product owners - all who has to model and align the business processes with the stakeholders conveniently and quickly.

You can try my hosted editor. The Workbench repository includes deployment instructions, and the CLI is on npm.

Also, it were not be possible without the Mermaid-BPMN implementation project by Derari.

What even is orchestration?

Thu, 19 Feb 2026 20:41:09 +0000

I accidentally ended up in the process automation and orchestration space when I started my career, and somehow even more accidentally I'm still there. As Taylor Swift says, "help, I'm still at the restaurant."

Being in the enterprise software space this long, I feel like the pendulum has swung back and forth between "buy a full suite platform, it has everything you need" and "avoid vendor lock-in" and something in between. AI has certainly left it's mark, but hasn't changed things all that dramatically.

You'll find people and companies saying you need a specialized purpose-built platform with a very specific set of use cases or personas or one that's agnostic and fits any and all needs.

It's no different in the process automation and orchestration space.

All of this to say, we still have the same problem - this separation in ownership and responsibilities from the thing we want to improve and how it's actually going to be improved. You often here this positioned as "the business" and "the development team". "The business" gets pitched as this non-technical group of diagram drawing, process optimizing suits while "the development team" adds the code and system integrations to make the diagram actually work, but doesn't own the process.

I still look back on my early career days and remember our business partner asking if she could just give me a Visio diagram and could I turn that into BPMN for her because the standards were too technical. BPMN... as in the standards that were supposed to be the literal language that filled this "gap" between "the business" and "the development team"... was too technical. Interesting.

I have this hypothesis that people in tech generally understand process automation and why it's beneficial, but only certain areas and roles within tech seem to really resonate with the term "orchestration". So maybe let's talk about that a bit and give you a few examples of where orchestration really shines. Then you can tell me your definition.

Ok, so what is orchestration?

You would think it's overdone, but the analogy of a conductor with an orchestra really fits here. You have a bunch of different instruments kind of doing their own thing, but together, with the help of a conductor, making a beautiful coherent piece of music happen. They get clues on when to speed up, slow down, or when to play with more or less intensity.

But I can see how that doesn't translate super well to tech.

Let's get some help from the internets.

Orchestration is the coordinated execution of multiple IT automation tasks or processes. Orchestration is usually applied across multiple computer systems, applications, and services to ensure that deployment, configuration management, and other processes are performed in the proper sequence.

Via RedHat

Orchestration is the coordination and management of multiple computer systems, applications and/or services, stringing together multiple tasks in order to execute a larger workflow or process. More specifically, orchestration is the coordinated execution of multiple IT automation tasks or processes across multiple computer systems, applications and services. These processes can consist of multiple tasks that are automated and can involve multiple systems.

Via Databricks

Orchestration is the process of coordinating distributed software components and systems so that they execute seamlessly as an automated, repeatable process.

Via Orkes

These definitions read a lot like the DevOps definitions - multiple systems, coordination, working together with automation, etc.

Basically, anytime you want to do something complex and chain together a sequence of tasks or coordinate and manage multiple systems, applications, or services either ad-hoc, scheduled, or when something happens somewhere you probably want to do it in a clear and reusable way with orchestration. Got it? So clear!

You'll see orchestration and automation together quite often, but it's typically positioned around the involvement of humans where automation is helping humans, without intervention, complete a single task. Orchestration tends to be more complex, but may involve humans (human-in-the-loop). To what extent humans participate depends.

I think I get it, but I need examples...

Let's try to make this a little more tangible.

Data Orchestration

You have data everywhere, in multiple disparate systems, and now you want to do something with it. Very everything, everywhere, all at once. This is where you see data pipelines, ETL, etc. come into play. You don't necessarily want to merge all the data together into one big database, but you do want to coordinate across the systems to, say, use the data to make informed decisions.

Business Orchestration

This tends to be where process automation and orchestration live in the traditional IT, HR, and finance workflows. My favorite example in this space is a two-step approval process, because it involved a human-in-the-loop aspect (maybe even two!), but many people have seen this at work or in their personal life.

If you know what "signature authority" is you've definitely been a part of a process like this, and the larger the organization, the more systems might be involved to make decisions.

You may encounter a set of rules that fast track you through the process (like my "signature authority" was once $100, which was basically desk trinkets) and anything more than that was escalated to my manager until his "signature authority" limit was hit and then it escalated to his manager. So this system needs to know the org chart, the individuals' "signature authority", the price of the items to be purchased, etc. All of that info is definitely in different databases, if not completely different systems.

AI Orchestration

This is relatively new and gets us into murky territory as well. Agent orchestration, multi-agent systems (MAS), AI pipelines can all fall into this bucket of AI orchestration. MAS for me is really the foundation for where we are at now with AI agents and potentially having them do coordinated work together.

The agents need data, then with that data they do something with other agents, and something complex happens.

I'm intentionally being a bit handwavy here because I don't have a great real world example of this yet, just a lot of marketing blogs around specialized agents working together to complete a common goal.

But when do you need an orchestrator?

It depends, of course.

Some organizations will start building some stitched together, homegrown solution and ultimately hit a point where there is a maintenance or scale issue. Others will realize they want to do something beyond CRON and scheduled jobs, something more real-time and event-based where they need listeners or webhooks.

Others still will realize they need to do a mix of scheduled, event-based, and manual executions with responsibilities spanning across technical and non-technical roles, and this is usually when they start investigating platforms to handle some of this.

So, how do you define orchestration?

Hopefully, I've given you a bit to think about and start to formulate your own opinion on orchestration.

What's your definition of orchestration? Are you doing orchestration within your organization? And how did you evaluate your options?