DEV Community: Benchouia Ahmed Abdelhakim

Oumma from Zero: Installing the Engine, the Web App and Keycloak (A Guide for Absolute Beginners)

Benchouia Ahmed Abdelhakim — Sat, 24 Oct 2026 10:04:58 +0000

Oumma from Zero: Installing the Engine, the Web App and Keycloak

This is the "make it run on my machine" episode of the Oumma series. If you've read the previous articles you know what Oumma does: a platform where business processes are designed in a browser, executed by an engine that mixes **human steps* (a person approves, reviews, fills a form) with AI and system steps (an LLM routes, a tool sends a WhatsApp message, an HTTP call validates data) — with real permissions, real audit logs, and a real database.*

Today: you install all of it yourself. I'll assume you can open a terminal and paste a command — nothing more. If you've ever installed WordPress or Nextcloud, you can follow this. If you've never done anything like that, read the "What is each piece" section first and paste carefully.

You'll end up with a working test environment, exactly like mine:

Piece	URL	What it is
Web app	`http://localhost:5173`	What humans use (login, My Tasks, My Dossiers, Designer)
Engine API	`http://localhost:8095`	The Go engine that executes processes
Keycloak	`http://localhost:8080`	Login / identity (who you are, which groups, which department)
Postgres	`http://127.0.0.1:5433` (local only)	Where everything is stored

What is each piece (before we touch the keyboard)

Think of it like a restaurant:

Keycloak is the bouncer at the door. It checks who you are, gives you a ticket (a token) that says "this is Hassan, he's an Operateur, he works in departments 100,10". Nobody enters the restaurant without this ticket.
The engine (Oumma) is the kitchen. It receives orders (a new process instance), works through the recipe (the process definition), pauses when a human must act, and resumes when the human answers.
The web app is the dining room + waiter. It's what you see: login page, task lists, forms, the process designer.
Postgres is the ledger. Every step, every form value, every audit entry.
An LLM (any OpenAI-compatible API — local or cloud) is the head chef's judgment: it routes steps, answers questions, reads documents.

Two things to know before we start:

Docker does the heavy lifting. The engine, its database, and the mail server all run as containers — one command each. You do not install Go or Postgres on your machine.
Nothing here touches real customers. The WhatsApp/Telegram/email tools run in dry-run mode by default (they build the message, log it, pretend it was sent). This is a safe test environment.

Part 0 — Prerequisites

You need, in order of importance:

A machine with Docker + Docker Compose.
- Mac/Windows: install Docker Desktop. That's it.
- Linux VPS (5€–10€/month is enough): install the Docker Engine + Compose plugin.
- 4 GB RAM minimum, 8 GB comfortable (Keycloak is the heaviest piece, it likes ~1 GB).
Git — to download the two repositories. (brew install git / sudo apt install git)
Node.js 20+ — only for the web app, if you run it in "development" mode (I recommend this for a test environment). node -v should print v20 or higher.
An LLM endpoint that speaks the OpenAI API format. Three easy options:
- an OpenAI / Groq / Mistral account + API key (fastest to try, a few cents of usage),
- a local Ollama (free, http://localhost:11434/v1),
- a local vLLM server (free, what I use in production).

For this guide I'll use a generic key — swap in whatever you have.

Patience. The first build downloads ~1 GB of images.

Check your setup:

docker version        # prints client + server versions → OK
docker compose version
git --version
node -v               # v20 or newer

If docker version complains about permissions (Linux), add your user to the docker group and log out/in.

Part 1 — Keycloak: the bouncer

We'll run the official Keycloak image with a persistent database. Create a folder and put everything in it:

mkdir -p ~/oumma && cd ~/oumma

1.1 Start Keycloak

Save this as keycloak/docker-compose.yml:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: ["start-dev", "--http-port=8080"]
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ChangeMe_Admin_102030
      KC_DB: postgres
      KC_DB_URL: "jdbc:postgresql://postgres:5432/keycloak_db"
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ChangeMe_KC_102030
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: keycloak_db
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ChangeMe_KC_102030
    volumes:
      - kc-pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 5s
      retries: 10

volumes:
  kc-pg-data:

start-dev mode is for test environments only — it prints everything and skips TLS. Never put this on the internet as-is.

cd keycloak
docker compose up -d
docker compose logs -f keycloak   # wait for "started in Xs" (≈30s first time)

Open http://localhost:8080 → Administration Console → log in with admin / ChangeMe_Admin_102030.

If you see the console: congratulations, the hardest infra piece is done.

1.2 Create the realm (a "tenant" inside Keycloak)

In the admin console:

Crown icon (top-left) → Create realm → name: brief-test-realm → Create.
Click into it.

A realm is a self-contained identity world: its own users, groups, clients. Oumma lives in one realm.

1.3 Create the clients (the "apps" that are allowed to ask for tickets)

Client A — the web app (this is what your browser logs in with):

Clients → Create client
- Client ID: briefuserapp
- Client type: Confidential (or Public — both work; the engine only validates tokens, it doesn't log people in)
- Client authentication: off if Public
Client tab → Valid redirect URIs: http://localhost:5173/* (and http://127.0.0.1:5173/* for good measure)
Authentication tab → leave defaults. The web app logs in via the resource owner password flow through a small proxy — see below.

Client B — the engine (a "service account" the backend uses for admin operations):

Clients → Create client
- Client ID: oumma-admin
- Client authentication: on
Copy the Client secret from the Credentials tab — you'll need it in the engine's .env.
Service account roles tab → add: realm-admin (for a test environment; a production setup would scope this down).

Why two clients? The browser and the backend have different relationships with Keycloak: the browser needs to log in people, the backend needs to be trusted on its own (service account). Mixing them is a classic beginner security mistake.

1.4 Create the groups (who can do what)

Groups → Create group. Make these four (the names are what Oumma's processes will reference):

Operateur
cashier
management
Designer

That's it — no roles needed for a first test. Oumma maps groups to process access: "the Operateur group can act on the confirm order step". (If you want to read the theory: episode 3 of the series.)

1.5 Create your first user (and the `department` attribute)

Users → Create user:

Username: operateur10, email: anything, Enabled: on
Credentials tab → set password: password (test environment!)
Groups tab → join group: Operateur
Attributes tab → add one attribute:
- Name: department
- Value: 100,10

This department attribute is the one people miss. Oumma can gate tasks per department ("only branch 10 sees these dossiers"). It travels inside the user's token. If the attribute is missing, the token says department: null and department-gated lists will look empty. Comma-separated codes are supported (100,10 = the user belongs to two).

Repeat with two more users so you can test the full chain (this is what I use):

User	Group	`department` attr
`operateur10`	`Operateur` (+ `cashier`)	`100,10`
`branchmanager_1001`	`management`	`10`
`fake_admin`	`Designer`	(none)

Save the admin password of your Keycloak console somewhere safe. You'll use it to add users later.

Part 2 — The engine (the kitchen)

2.1 Clone it

cd ~/oumma
git clone https://github.com/AHBench/oumma.git
cd oumma

2.2 Configure it

cp .env.example .env
nano .env

You only really need to touch four blocks:

# --- 1. The LLM (head chef) ---
OPENAI_BASE_URL=https://api.groq.com/openai/v1     # or your Ollama: http://host.docker.internal:11434/v1
OPENAI_MODEL=llama-3.3-70b-versatile               # any model that endpoint serves
OPENAI_API_KEY=sk-your-key-here

# --- 2. Keycloak (the bouncer) ---
KEYCLOAK_URL=http://host.docker.internal:8080      # host.docker.internal = "the machine running docker"
KEYCLOAK_REALM=brief-test-realm
KEYCLOAK_CLIENT_ID=briefuserapp
KEYCLOAK_ADMIN_CLIENT_ID=oumma-admin
KEYCLOAK_ADMIN_CLIENT_SECRET=paste-the-secret-from-1.3

# --- 3. Tools: keep dry-run ON for a test environment ---
MCP_TOOLS_DRY_RUN=true

Everything else in .env.example has working defaults — the file is commented, read it once.

host.docker.internal — containers can't say "localhost" to mean your machine (they'd mean the container). On Docker Desktop (Mac/Windows) host.docker.internal works out of the box. On Linux you need extra_hosts: ["host.docker.internal:host-gateway"] — the shipped compose files already include it.

2.3 Start it

docker compose -f docker-compose.yaml -f docker-compose.local.yml up -d --build

First build takes a few minutes (it compiles Go). Then:

curl http://localhost:8095/health
# → {"status":"ok"}

That's the whole engine. Postgres started with it (on 127.0.0.1:5433, loopback only), and all tables are created automatically — there is no manual migration step. A reference snapshot of the full schema lives in the repo at migrations/schema-reference-latest.sql if you're curious what it looks like.

Part 3 — The web app (the dining room)

3.1 Clone + install

cd ~
git clone https://github.com/AHBench/oumma-app.git
cd oumma-app
npm install

3.2 Tell it where things are

Create a .env.local in the same folder (the defaults already point at localhost — this file only matters if your layout differs):

VITE_PROCESS_URL=http://localhost:8095
VITE_AUTH_BACKEND_URL=http://localhost:8095/api/auth
VITE_USER_PROCESSES_URL=http://localhost:8095/api/user-processes

Beginner warning #1: if you change a VITE_ variable, restart npm run dev — Vite reads these at startup, not live.

3.3 Start it

npm run dev
# → Local: http://localhost:5173/

Open http://localhost:5173 — you should see the login page. Log in with operateur10 / password.

If you land on the process apps list: the full stack is working. 🎉

Part 4 — First smoke test (2 minutes)

As operateur10: open the order-processing sample process (it ships in the repo's workflows/ folder — the engine loads it at startup).
You'll see a My Tasks view. To get a task there, launch an instance (create a form in the My Dossiers tab, or via the Request tab).
Complete the first task with Yes — approve.
Log out, log in as operateur10 again (same user is also the cashier) → a manual review task appears. Approve → the instance finishes.

You've just executed a 4-step agentic process with 2 human steps, an HTTP validation step, and (dry-run) WhatsApp notifications. That's the whole product in 2 minutes.

Troubleshooting — the 10 things that go wrong (and their fixes)

#	Symptom	Almost always the cause → fix
1	`curl :8095/health` → connection refused	Engine not up yet → `docker compose logs oumma`. First build is slow; also check `docker compose ps` for crashed containers
2	Login fails with `invalid_credentials`	Wrong user/password, or you created the user in the master realm instead of `brief-test-realm` → check the realm selector (crown)
3	Login OK but no processes visible	The user's Keycloak groups don't match the process's role requirements → join the user to `Operateur` (Groups tab of the user)
4	Processes visible but My Dossiers / department lists empty	Missing `department` user attribute (not a group!) → Attributes tab → `department` = `10`, then re-login (the value lives in the token)
5	Tasks complete but nothing advances	LLM not reachable from the engine → `docker compose logs oumma \
6	Port already in use ({% raw %}`:8080` taken)	Something else uses 8080 → change the host side: `"8081:8080"` in the Keycloak compose, and update `KEYCLOAK_URL` in the engine's `.env`
7	Web app loads but login page errors in the browser console	CORS or wrong auth URL → check `VITE_AUTH_BACKEND_URL` points at `:8095/api/auth` and the redirect URIs include `http://localhost:5173/*`
8	Designer chat doesn't answer	The designer LLM variables (`DESIGNER_OPENAI_*`) are empty or broken → it falls back to the main LLM; check those vars too
9	`npm run dev` says `EADDRINUSE`	Another dev server on 5173 → `npm run dev -- --port 5174` (then use 5174 everywhere in that session)
10	Everything worked, then broke after you changed a process in the designer	The browser caches process config aggressively → hard reload (Cmd/Ctrl+Shift+R) and re-login

The universal debug trio, when in doubt:

docker compose ps                     # what's actually running?
docker compose logs --tail 50 oumma   # what did the engine just say?
docker compose logs --tail 20 keycloak

Security checklist before you share the environment

Even a test environment should be tidy:

[ ] Keycloak admin password ≠ admin/admin (yours: ChangeMe_Admin_102030 — change it)
[ ] Keycloak not exposed publicly — bind to 127.0.0.1:8080 if on a VPS, or put it behind a VPN/Tailscale
[ ] Engine Postgres stays on 127.0.0.1:5433 (loopback only) — it's there so you can peek with a DB tool
[ ] MCP_TOOLS_DRY_RUN=true until the day you deliberately wire real WhatsApp/Telegram credentials
[ ] Rotate any LLM API key that was ever pasted into a chat, a screenshot, or a repo

What's next

You now own a full agentic workflow platform on your machine. The natural next episodes:

Episode 2 — design your first process in the designer (no code)
Episode 3 — how roles, groups and permissions actually gate tasks
Episode 5 — a full day in the life of a normal user
Episode 7 — wiring real external systems (MCP-like tools)

The whole series is cross-linked on Dev.to — and the engine's README has the production-oriented notes (TLS, real Postgres sizing, monitoring).

Found a step that fails on your machine? That's a bug report waiting to happen — the issues tab is open, beginners especially welcome. This guide is only as good as the installs it survives.

You Know n8n (or Camunda, or Zapier). Here's What's Different About Oumma

Benchouia Ahmed Abdelhakim — Thu, 22 Oct 2026 06:31:21 +0000

You Know n8n (or Camunda, or Zapier). Here's What's Different About Oumma

You've automated the easy stuff. The hard stuff — the stuff with patients, approvals, money and audit trails — still runs on email and "call me when it's ready." If you run n8n, Camunda, or Zapier, this article is the honest comparison: where those platforms stop, and what it takes to cross the line into regulated business processes.

You already know the category. n8n gave you visual automations with 400+ integrations. Zapier glued your SaaS stack together in an afternoon. Camunda gave you real BPMN in your production systems. All of them are excellent — for what they are: automation of steps.

Oumma is a different animal: an agentic workflow platform for business processes where humans are the primary workers and AI is the orchestrator around them. Not the other way around. That one sentence explains most of the design. Here's the breakdown on the subjects that actually matter when a workflow touches real people.

1. Human-in-the-loop: a citizen, not a "wait node"

In n8n the human appears when the workflow runs out of machine: you bolt on a form, an email, an external ticket system, and then a polling webhook waits for a human to do something outside the platform. The human's work is next to the automation — and the state of that work lives somewhere else.

In Camunda, human tasks are first-class (a userTask in BPMN) — that's the closest relative. But the task assignment model is yours to build: who can see it, who can act, what they can do on the artifacts — all of it is code you write against the Task API.

In Oumma, the human is the main loop of the process:

A "dossier" is a process instance, and the user's home screen is their task queue — the same queue the engine maintains in Postgres, not a view over some external ticket system.
Permission is per step and per action: each step declares which role can complete it, which can comment, which can attach. The engine re-checks all of it server-side on every completion — the UI hiding a button is cosmetics, not security.
Forms are pinned to the step (version-pinned, even — an instance keeps the form structure it was launched with), so the person sees exactly what the process needs at that moment, in three languages (EN/FR/AR in the shipped i18n).
Notifications follow the user's own tasks: new task, task moved, process advanced — the bell is driven by the engine's state, not by a cron email.

The practical difference: with n8n you built a workflow that occasionally asks a human for input; with Oumma you have a process the humans work, with the machine doing everything else — documents, routing, integrations, reminders.

2. Controlled automation: BPM discipline instead of free-form wiring

n8n and Zapier optimize for developer velocity: drag nodes, connect, run. The freedom is the point — and it's exactly why, at scale, nobody can tell you what a workflow actually does, who approved it, or what changed when. Your "processes" are node graphs with the semantics of a shell script: no gateways, no roles, no version, no audit of the design itself.

Camunda has the formalism (BPMN 2.0) but you pay for it in modeling tools, a separate runtime, and a Java/Zeebe operational footprint.

Oumma takes the BPMN core of what regulated processes actually need — tasks, exclusive gateways, parallel fork/join, start/end — and ships it as a product, with the controls an enterprise needs around it:

The design is the source of truth — one YAML document per process, versioned in Postgres, rendered on the interactive canvas. No drift between a modeling tool and a runtime: there is only one artifact.
Single pending version + semantic versioning: every change lands in one pending document; the engine computes major/minor/patch from what changed (topology = major, roles/step ids = minor, labels = patch). Deploying is a human act in the Versions tab — the AI can propose, never deploy.
Instance pinning: instances running on v4.0.5 keep their v4.0.5 semantics even after you deploy v5. No surprise behavior changes mid-flight — the thing that makes BPM platforms trustworthy in production.
Deterministic first, AI second: single-successor hops and unconditional fork/join merges route with zero LLM tokens — no model in the money path, no latency, no cost. The LLM appears only where a decision is genuinely undecidable (and even then its output is a structured choice against your defined branches, written into the process data).
Tool steps are zero-token system tasks: a Telegram notification, a Gmail send, a WhatsApp alert, a generic HTTP call — configured in the designer, executed deterministically from process data. In n8n these are nodes; in Oumma they're engine steps with an audit trail, dry-run by default so nobody accidentally fires production messages during a redesign.

The practical difference: an n8n workspace is a collection of clever automations; an Oumma deployment is a set of governed, versioned, auditable business processes — the difference between "it automates" and "the audit can trace it."

3. Roles: enterprise identity is the permission model

This is where the no-code tools fall off the map. In n8n, "who can run/edit this workflow" is a workspace seat — there are no per-step roles, no claim that only a manager may complete the manager_review step of your process. In Zapier, it's an account. Your real org chart (the one in your IdP) simply doesn't exist inside the platform.

Camunda has user/role groups, but wiring them into a real enterprise IdP — SSO, group sync, claims — is integration work you build and maintain.

Oumma's answer: the platform has no user database of its own. Identity is Keycloak; the platform validates the bearer token, reads the groups and department from the claims, and that's it:

One login, every system. The same token authenticates the workspace, the designer, the agent, and the engine APIs.
Roles are defined *in the process design* (the Roles tab: which role per step, which actions), and synced to the IdP as groups. When you change a role's scope in the design, the sync follows — no separate identity administration.
Enforcement is server-side and claim-based: the engine re-validates the token on every task completion, comment and attachment. A user's token is the sole source of who they are; there is no app-side "trust me" path.
Self-service onboarding with governance: users register from the login page, activate via an emailed one-time token (Mailpit in the dev stack), and get a role-based monthly token quota — normal users 20k, designers 50k — enforced on every AI call, with a claim-a-top-up flow that emails the administrator. The platform meters its own AI usage per user, per department, per process.

The practical difference: in n8n you explain your org chart to the platform (or don't, and ship it); in Oumma the org chart already exists — the platform just reads it and enforces it on every single action.

4. The other differences that compound

The three above are the headline; these are the ones people discover in week two:

The AI designs the process — and you still hold the pen.
Ask the designer chat "add a manager review for orders above 1000 euros" and it edits the actual design document: new task, gateway, condition, role, form — all in the one pending version, visible on the canvas instantly, draggable if you disagree, and only live when you deploy. In n8n the AI (where it exists) edits node graphs; here it edits a governed BPMN artifact with versions, semver and a deploy gate.

Every AI call is metered and attributable.
Tokens are captured per call, per user, per department, per process, with a monthly cost rollup. The badge in the UI shows what this process has consumed this month. No LLM invoice mystery — the ledger is a Postgres table.

One port, one binary, one Postgres.
The whole platform — engine, auth proxy, forms, documents, agent, designer APIs, even the Mailpit inbox (proxied at /mailpit/) — is one Go binary on one port with a Postgres database. No node cluster, no worker fleet, no separate identity service, no separate task service. You can read the whole backend in an afternoon; the entire source is Apache-2.0.

The app knows its place.
The React workspace has zero LLM configuration — no model names, no endpoints, no keys. Every AI capability (designer chat, AI Assist, document analysis) flows through the engine, where it's quota-gated and logged. That's why you can swap your LLM backend by editing one env var in docker compose and nothing in the app changes.

So, who should care?

You're running…	You'll hit this wall…	Oumma is for you when…
n8n / Zapier	The workflow needs a real human step, a real approval chain, or an auditor will ask "prove who did what"	your automation is a business process (onboarding, claims, orders with thresholds) rather than an integration glue
Camunda	You'd rather not operate a Java/Zeebe platform + build the identity and UI layers yourself	you want the same BPMN discipline with a working UI, IdP integration, metered AI and one-port deploy
Spreadsheet + email + "call me"	Nothing above, and your process still works — at the price of every handoff	you want the process to exist somewhere — designed, versioned, audited, and mostly self-driving

The honest caveat: if you're gluing two SaaS tools together with no humans, no approvals and no compliance questions, stay on n8n or Zapier — that's their job and they do it well. Oumma earns its keep when the workflow is the business: regulated, multi-role, long-lived, and full of people.

Try it

Everything in this article is reproducible from the repos:

Engine & backend (Go): github.com/AHBench/oumma
Agentic workspace (React): github.com/AHBench/oumma-app

Both Apache-2.0. docker compose up — one port, one Postgres — and you can watch a human task get created, permission-checked, completed, and routed, with the AI handling everything around it.

This is the first article of the Oumma series on Dev.to — the follow-ups take you inside the platform: the designer's tabs, roles & permissions, forms, the normal user's day, AI Assist, external integrations, versioning, the engine under the hood, and identity & quotas. New articles land on the series page as they publish — follow the tag so you don't miss them.

Build a Business Process by Talking to an AI — Oumma Designer Mode, Walkthrough with the Order Processing Process

Benchouia Ahmed Abdelhakim — Sat, 17 Oct 2026 21:03:11 +0000

Build a Business Process by Talking to an AI — Oumma Designer Mode, Walkthrough with the Order Processing Process

Building the "Order Processing" process in the Oumma Designer: half by clicking and dragging on a BPMN canvas, half by typing plain-English prompts into a design chat — and why the deployment button is the only one the AI cannot press.

What we end up with by the end of this article:

start → validate_order (inventory API) → manual_review (cashier)
        → [>$1000] manager_review (management) → process_payment (payment API) → end

a tool step that calls the inventory API with zero LLM tokens at runtime
two human review steps owned by different roles, with a conditional business rule
forms the people on each step will actually fill (EN/FR/AR labels)
a trilingual label catalog, a menu icon, and role permissions synced to identity
one pending design version — and a human who presses Deploy

This is article 1 of the Oumma series. The next one tears apart every tab of the design view; later ones cover roles & permissions end-to-end, the normal user's day, AI Assist, external integrations, versioning/pinning, and the Go + PostgreSQL engine under the hood.

If you have ever been asked to digitize a business procedure, you know the shape of the job: a flowchart on a whiteboard, three roles who disagree about who approves what, a form that nobody agrees on, and an integration ("just ping the inventory API") that ends up living in someone's head.

Oumma is an agentic workflow platform: processes run as engines, tasks are owned by roles, and an LLM handles the parts that need judgment. The part I want to show you is the Designer mode — where a process comes into existence — using a real scenario: building the Order Processing process from an empty project, mixing manual canvas work with AI prompts, exactly as it happens in the product.

The prompts below are the actual tool vocabulary of the designer agent. Every AI proposal is shown to you as a diff-like tool call and only lands after you press Apply. Deployment is never an agent action.

0. The two seats at the table

Before the scenario, the two actors you are coordinating as a designer:

The canvas — an interactive BPMN view: human steps (👤, with their role), system steps (⚙), start/end nodes, parallel fork/join gateways. Click a step to configure it; drag any step anywhere to untangle the diagram; four layout algorithms (left→right, top→down, circular, force-directed).
The design chat — an agent with a described, MCP-style tool catalog: create/rename processes, add steps, connect them, build forms, assign roles and permissions, set trilingual labels, plug in external tools, manage versions.

Everything the two of them do lands in a single pending version. You deploy it when it is ready; running dossiers keep the version they started on (version pinning).

1. Start from a blank project (AI)

A Designer-role account gets the mode orientation right after login — pick Designer mode for the full design experience, or Normal mode to work the processes like everyone else (you can switch any time from the top bar):

Then, in the designer chat, type:

Create a new process called "Order Processing" — it validates customer
orders, checks inventory, gets reviewed, then charges the customer.

The agent responds with the tool call it wants to run:

{ "name": "create_process",
  "args": { "processName": "Order Processing",
            "processId": "order-processing",
            "processDescription": "Validates customer orders, checks inventory,
                                   reviews and charges the customer." } }

Apply. The project appears in the left menu — scaffolded with just start → end:

That is the whole trick of "new process = project": the chat now has a canvas to build on immediately.

Designers can also rename the display name of a process at any time
(works on deployed processes — it is a label), and change the technical
process_id while the project was never deployed.

2. The automatic first mile (AI + tool step)

The first real step is not a person — it is an API call: validate the order and check inventory. This is a tool step (the MCP-like system tasks: Gmail, Telegram, WhatsApp, generic HTTP):

Add a system step "validate_order" that POSTs the order to our
inventory service. It takes order_id, items and customer_id from the
process context.

The agent builds it with the add_tool_task tool — a mcp.http.request
system task whose inputs map tool parameters to process-context keys
(order_id ← $order_id, …). Two properties matter:

Zero LLM tokens at runtime. When an order flows through this step, the engine resolves the $context keys and fires a plain HTTP call. Deterministic, repeatable, free.
Dry-run by default. Until you flip MCP_TOOLS_DRY_RUN=false and put real endpoints/credentials on the task, the engine builds the exact payload, logs it and simulates success — you can design and test flows without any integration being live.

3. Put people on the flow (manual)

Open the project's Process design — the canvas shows the live (pending) design in BPMN notation:

Now the diagram needs humans. This is where I grab the mouse:

Toolbar → "Add human step" → manual_review, role cashier.
Click manual_review → the right-hand configuration panel opens → set the role, the description ("Operations team reviews the order before payment"), save:

Connect — click Connect on validate_order, then click manual_review: the edge appears. Click Connect on start → validate_order.
Drag manual_review down and right to open breathing room — the connections follow. For a busy design this free placement is how you keep the BPMN readable (a Reset layout button returns everything to the algorithm).

Clicking around is still the fastest way to make small, precise edits — the AI is for the shaping, the mouse is for the furniture.

4. The business rule (AI)

The heart of order processing is a conditional: big orders need a manager.

Orders above $1000 must also be approved by a manager before payment.
Add a "manager_review" step for the management role and route
manual_review to it when the amount exceeds 1000 dollars.

The agent proposes, in sequence:

{ "name": "add_task", "args": { "name": "manager_review", "group": "management" } }
{ "name": "add_edge", "args": { "from": "manual_review", "to": "manager_review",
  "condition": "order amount exceeds $1000 — route to manager for approval before payment" } }
{ "name": "add_edge", "args": { "from": "manager_review", "to": "process_payment" } }

You apply each one. The canvas re-renders — you can see the exclusive branch appear, and you can drag manager_review aside so the main path stays a straight line.

Routing note: branches with conditions are decided by the LLM at
runtime; single-successor hops and unconditional fork/join merges are
routed deterministically, with zero tokens. The engine only spends
intelligence where judgment is actually needed.

5. Close the loop: payment and exit (AI)

After an approval, charge the customer with a system step
"process_payment" that calls the payment service, then finish.
Connect both review steps to it and it to the end.

The process_payment step is another tool step (HTTP POST to the
payment service, inputs order_id, amount, payment_method ← context).
All tool steps of the project are visible in the Tools tab:

After three applies, the topology is the real one:

start → validate_order ─┬→ manual_review ─┬→ (>$1000) manager_review ─┬→ process_payment → end
                         │                 ├→ (approved, ≤$1000) ─────┤
                         └→ (invalid) ─────┴→ (rejected) → end        └→ (manager rejected) → end

6. The forms people will actually fill (AI)

A step is only as good as its form. The designer builds them conversationally — the chat JSON becomes a real form step (field types, required flags, labels in EN/FR/AR):

Build the form for the launch: customer name, customer id, items
(list), total amount (number, required), payment method.

Give manual_review and manager_review a small form: the order summary
(read context), a decision (approve/reject, required) and reviewer notes.

Each lands via update_form_step. In the Forms tab you can now inspect every step's form visually and fix any field by hand:

7. Labels, icon, polish (manual + AI)

Search items tab — the trilingual label catalog. Type "label the 'total amount' field 'Montant total' in French and 'المبلغ الإجمالي' in Arabic" — or just edit the rows in the UI. The app resolves every UI label through this catalog:

Icon — the header's icon picker (284 icons, searchable): a 💳 card fits.
Roles tab — confirm the three roles (launch role Operateur, cashier, management) and their per-step permissions. Role changes can be synced to the identity provider (Keycloak groups) from here:

8. The part the AI may not do for you (human)

Open the Design versions tab. The single pending version shows every accumulated change with an automatic semantic version — a new task is a major, a role change a minor, a label tweak a patch. You read it, then press Deploy (or Discard):

That asymmetry is deliberate:

Agent can do	Only a human can do
Propose any design change (with your Apply on each)	Deploy the version
Create, rename, rewire, label, tool-wire	Discard the pending version
Inspect versions, list tasks, explain the design	Delete a project

And after deployment, running instances stay pinned to the version they started on — your in-flight orders keep their exact behavior while v2 serves the next launches.

And the people it was built for

Deployed, the process disappears into everyday work. A cashier or customer-relations operator signs in, picks Normal mode, and never sees a designer surface — just their processes, their dossiers, their tasks:

Their My Tasks tab shows exactly the steps that are waiting on their role — manual_review for cashiers, manager_review for management — with only the actions their permissions allow:

What this workflow buys you

Speed where it matters — topology, forms, labels, tools: described once, applied as validated writes.
Safety where it counts — nothing applies without a confirm, nothing deploys without a click, and the design is BPMN-validated before it may be deployed.
An auditable design history — every version, its semver and its document, stored in Postgres alongside execution states and the LLM usage ledger.
A canvas that respects you — the AI's changes appear on the same live canvas you drag on; you can always take the mouse back.

The result of the scenario is a shippable, role-gated, API-integrated Order Processing process — built in one sitting, mostly by asking.

Article 2 of the Oumma series on Dev.to — it starts with Oumma vs n8n/Camunda/Zapier. The designer agent's tool catalog, versioning and pinning are all visible in the oumma backend; the canvas and chat in the oumma-app frontend — both Apache-2.0.

Stop Hardcoding Workflows: How We Turned Kogito Into a Full-Scale Automation Platform

Benchouia Ahmed Abdelhakim — Sun, 07 Jun 2026 23:52:34 +0000

The Spark: What’s Missing in Cloud-Native BPMN?

If you’ve ever used the Kogito VS Code extension to design cloud-native workflows, you already know it’s an incredibly powerful tool. Built on top of Quarkus and Drools, it’s designed from the ground up for Kubernetes speed and efficiency.
But as my co-founder and I started deploying workflows into our production environments, we hit a major architectural roadblock.
Kogito is exceptional at handling automated, high-throughput system tasks. However, in the real world, most business processes still heavily rely on the human factor. Whether it’s an operator validating a high-value transaction, a team leader launching a complex workflow, or even a "Human-in-the-Loop" architecture auditing an AI agent's decisions, human intervention provides the governance, trust, and confidence that enterprises require.
Out of the box, building a seamless, end-to-end web interface for human tasks in Kogito felt like putting a puzzle together with missing pieces. So, we decided to build what was missing.
What started as a simple idea to wrap Kogito in a clean web UI evolved into FlowIQ—a comprehensive enterprise platform featuring dynamic forms, Role-Based Access Control (RBAC), Kafka event streaming, and robust document management, task management and many more.

In this first episode, I’ll take you behind the scenes of how we kicked off the architecture and built our core user portal.

The Architecture: Managing Governance and Security

To ground our idea, we designed a classic enterprise use case: a digital banking onboarding process.
We needed a system that could handle both the launching phase of a process and its execution phase whenever a human operator needed to step in. This led us to build our first core component: the User App.

1. Enterprise Auth & RBAC

Security wasn't an afterthought. We integrated FlowIQ natively with Keycloak. This allows enterprises to effortlessly hook up third-party authentication providers like Active Directory (LDAP).
Once authenticated, our backend calculates the user's explicit privileges via RBAC (Role-Based Access Control). This dictates exactly which processes they can see, which forms they can access, and what actions they are allowed to take.
When a user logs in, they are greeted by a clean, centralized workspace:

From this single portal, authorized users can check their tasks, manage attached documents, investigate active process executions, create dossiers, or spin up new workflows.

Dynamic Forms and Dossier Management

Let’s walk through what happens when an operator launches a new customer onboarding workflow.

2. Creating a Dossier

If the user’s RBAC permissions allow it, they can initiate a new dossier. Instead of hardcoding UI forms for every single BPMN process, we built a dynamic form engine.

The UI reads the data schema defined by the Kogito process design and renders the form dynamically. The FlowIQ backend saves these form configurations and tracks their version history over time.

3. State Tracking & Parallel Execution
Once a user successfully creates a dossier, they can view it inside their form actions list. If they make changes or update a field before official execution, every single modification is completely traceable back to the initial version.

When the operator decides the data is pristine, they select the desired form and click Launch. For advanced workflows, our UI allows users to select multiple process forms and spin them up completely in parallel.

What happens under the hood? For a Kogito developer, the magic is straightforward: FlowIQ iteratively triggers the Kogito onboarding process endpoints via its standard REST API, handling state synchronization seamlessly.

Bringing Our Own Flavor to "My Tasks"

The core of any human task framework is the inbox. When a process spins up and requires human validation, it lands directly in the My Tasks menu.
Using Kogito’s REST endpoints, our backend extracts only the tasks relevant to the logged-in user's roles. But we wanted to go a step further for complex organizational structures, so we added a Department Filter.

FlowIQ automatically maps and filters tasks based on organizational department attributes already baked inside the process data. An risk-assessment agent only sees risk-assessment tasks, while a regional manager sees theirs—keeping noise to an absolute minimum.

What’s Next?

We've successfully laid down the foundation: authenticating users, dynamically rendering forms, and triggering Kogito processes via REST. But how do we keep the user interface updated in real-time when system-level steps complete?
In the next episode, I’ll dive into task attributes and how we track live process statuses using event streaming with Apache Kafka.
Have you worked with Kogito or built custom worklists for BPMN engines before? Let me know your thoughts, questions, or architectural pain points in the comments below!

DEV Community: Benchouia Ahmed Abdelhakim

Oumma from Zero: Installing the Engine, the Web App and Keycloak (A Guide for Absolute Beginners)

Oumma from Zero: Installing the Engine, the Web App and Keycloak

What is each piece (before we touch the keyboard)

Part 0 — Prerequisites

Part 1 — Keycloak: the bouncer

1.1 Start Keycloak

1.2 Create the realm (a "tenant" inside Keycloak)

1.3 Create the clients (the "apps" that are allowed to ask for tickets)

1.4 Create the groups (who can do what)

1.5 Create your first user (and the department attribute)

Part 2 — The engine (the kitchen)

2.1 Clone it

2.2 Configure it

2.3 Start it

Part 3 — The web app (the dining room)

3.1 Clone + install

3.2 Tell it where things are

3.3 Start it

Part 4 — First smoke test (2 minutes)

Troubleshooting — the 10 things that go wrong (and their fixes)

Security checklist before you share the environment

What's next

You Know n8n (or Camunda, or Zapier). Here's What's Different About Oumma

You Know n8n (or Camunda, or Zapier). Here's What's Different About Oumma

1. Human-in-the-loop: a citizen, not a "wait node"

2. Controlled automation: BPM discipline instead of free-form wiring

3. Roles: enterprise identity is the permission model

4. The other differences that compound

So, who should care?

Try it

Build a Business Process by Talking to an AI — Oumma Designer Mode, Walkthrough with the Order Processing Process

Build a Business Process by Talking to an AI — Oumma Designer Mode, Walkthrough with the Order Processing Process

0. The two seats at the table

1. Start from a blank project (AI)

2. The automatic first mile (AI + tool step)

3. Put people on the flow (manual)

4. The business rule (AI)

5. Close the loop: payment and exit (AI)

6. The forms people will actually fill (AI)

7. Labels, icon, polish (manual + AI)

8. The part the AI may not do for you (human)

And the people it was built for

What this workflow buys you

Stop Hardcoding Workflows: How We Turned Kogito Into a Full-Scale Automation Platform

The Spark: What’s Missing in Cloud-Native BPMN?

The Architecture: Managing Governance and Security

Dynamic Forms and Dossier Management

Bringing Our Own Flavor to "My Tasks"

What’s Next?

1.5 Create your first user (and the `department` attribute)