Processes (BPM): document how the work gets done¶

Document the procedures your organisation actually runs — onboarding a customer, closing the books, handling a data subject request — as versioned, governed visual graphs you can browse, link to the data they touch, and hand to an auditor.

Processes is Datahub's documentation-first BPM surface: it captures the human-in-the-loop reality as a referable, governed artefact that data products and contracts can attach to. When you want that procedure to actually run, that's Flows.

PurposeDocument · not execute

Node types4

Subprocess depth5 levels

Relationship types4 typed

When to choose this¶

Capture a procedure visually

Drag Start, Task, User Task, and End onto a canvas and connect them — that is a process. No modelling notation to learn.
Decompose a complex process

Link a step to its own subprocess, up to five levels deep — Customer Onboarding → Verify Identity → KYC Check.
Govern it alongside the data

Tag with domain, department, and team; link to glossary terms and — via Data Products — to the contracts the process touches.
Version it as it evolves

Each save can become a new version; exactly one is active at a time, and the platform records which was live when.

When not to reach for Processes

Automating execution end-to-end → use Flows.
Routing an entity through a governance approval gate → use Workflows.
Firing an alert when a step fails → use Alerts.

What a process model looks like¶

A process is a graph of typed steps wired from a Start to an End. Steps carry metadata (who does it, how long, which department), branches fan out with lettered step numbers, and any Task can open into its own subprocess. Nothing here executes — it is the shared picture of how the work is done.

flowchart LR
    S(["Start"]) --> U1["User Task<br/>1 · Collect KYC documents"]
    U1 --> T1["Task<br/>2 · Verify identity<br/>opens subprocess"]
    T1 --> T2["Task<br/>3 · AML screening"]
    T2 -->|cleared| U3["User Task<br/>4a · Open account"]
    T2 -->|flagged| U2["User Task<br/>4b · Manual review"]
    U2 --> U3
    U3 --> E(["End"])
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class T1 accent

Figure 1 — A documented process is typed steps wired from Start to End. A Task can open into its own subprocess (orange), and branches carry lettered step numbers (4a / 4b). Branching is drawn with edges — there is no separate gateway shape.

Why teams reach for this

A documented process becomes one shared, versioned source of truth: a new hire reads it, an auditor traces it, and an automation project starts from it. Every change is versioned, the whole graph is governed and searchable, and each process links to the data products and glossary terms it touches — so the picture never drifts from the data.

What Processes looks like¶

Surface	Where	What you see
List	`/processes`	DataTable with name, category (with colour + icon), parent process, status, created. Filter by category / domain / department / team / tags.
Detail / builder	`/processes/{id}`	Full-page canvas builder: floating palette (top-left), main canvas, floating config panel (right when a node is selected), toolbar with palette toggle + HERC + import / export / publish. Inline-editable name + description. Breadcrumb path through subprocesses.
Subprocess link	Builder → click a Task node	Config panel offers Link as subprocess — pick or create a child process. Click the indicator on the node to navigate into it.

Concepts¶

Concept	What it is
Category	A colour-and-icon grouping (HR, Finance, Operations, Compliance, …). Configurable by admins.
Process definition	The metadata of a process: name, description, category, parent, governance tags, status, owner.
Process version	A snapshot of the graph (nodes + edges + config). Versions auto-increment per definition; each carries its own status in the lifecycle below.
Active version	The single version currently considered the "live" definition. Active versions are read-only.
Definition status	The definition's discoverability: draft → published → archived. Published makes the process discoverable; archived hides it (soft-delete only).
Trigger metadata	What kicks the process off — manual, event, schedule, external. Documentation only at this layer.
Process relationship	A typed edge between two definitions (feeds into, depends on, triggers, alternative to) for cross-process modelling.

Node types¶

The default BPM palette has four shapes:

Node	Visual	Meaning
Start	green-bordered, output only	Where the process begins.
End	red-bordered, input only	Where the process ends.
Task	rectangle with a blue accent strip	An automated step. Carries metadata (priority, duration, department, assignee group, form reference, notes).
User Task	blue-bordered rectangle	A manual step performed by a person or a group.

Each task node displays inline metadata chips on the canvas: a priority dot, the planned duration, and a department icon. Click a node to open the floating config panel.

Setup — what an admin needs to do once¶

Prereq	Where	Why
Categories seeded	`/admin/system-tables` → Process Categories	Grouping (HR, Finance, …). Configurable colour + icon.
Domains, departments, teams	`/glossary` Domains, `/admin/system-tables` Departments / Teams	Required for governance tagging.
Roles	`/rolegroups`	`bpm.viewer` to browse, `bpm.editor` to create / edit / publish, `bpm.admin` to delete versions and archive.

Building a process¶

Create. From /processes click New process → name, description, category, governance tags. The platform auto-creates version 1 with an empty graph.
Drag from the palette. Start → Tasks → User Tasks → End. Connect with edges.
Configure each step. Click a node → floating config panel: type-specific fields (assignee group, priority, duration, department, form reference, notes).
Suggest step numbers. The toolbar's Suggest steps runs a breadth-first pass from Start and assigns sequential numbers, with letter suffixes for branches (1, 2a, 2b, 3, …).
Save. Saves update the current draft version.
Activate. Submit the version for review; once approved it becomes the live version (the lifecycle is detailed below).
Publish the definition → it shows up in lists, search, and HERC.
Iterate. Create a new version → continue editing the graph; activating the new one supersedes the current one.

Subprocesses¶

Processes can be hierarchical. A Task in a parent process links to exactly one child subprocess, which can nest its own subprocesses — up to five levels deep. Step numbers inherit the parent's prefix, so a deep step reads like a path back to the top.

flowchart TD
    A["Customer Onboarding<br/>parent process"] --> B["Step 2 · Verify identity"]
    B -. subprocess .-> C["Verify Identity<br/>subprocess of step 2"]
    C --> D["Step 2.1.1 · Collect documents"]
    C --> E2["Step 2.1.2 · Sanctions screening"]
    C --> F["Step 2.1.3 · KYC check"]
    F -. subprocess .-> G["KYC Check<br/>deeper subprocess"]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class C accent

Figure 2 — Subprocess decomposition. Each Task links to at most one subprocess (exclusive ownership, orange); step numbers inherit the parent's prefix, so 2.1.3 reads "step 3 of subprocess 1 of step 2". Nesting goes up to five levels deep.

A Task in Onboarding can be linked to its own subprocess Verify Identity (via the node's config panel).
The subprocess can have its own subprocesses — up to five levels deep.
A subprocess belongs to exactly one parent step (exclusive ownership) — no cross-parent reuse.
The builder shows a breadcrumb so you can navigate Onboarding → Verify Identity → KYC Check without losing context.
Step numbering propagates down — 2.1.3 is "step 3 of subprocess 1 of step 2 of the parent".

If you want reusable, executable atomic steps, model them as flows in the Flows module instead.

Version lifecycle and approval¶

Every version moves through its own status lifecycle, separate from the definition's discoverability status. A version is edited as a draft, submitted for review, and only becomes active once a reviewer approves — so a human consciously signs off before a new version goes live.

stateDiagram-v2
    direction LR
    [*] --> Draft
    Draft --> UnderReview: Submit for review
    UnderReview --> Draft: Reject / Withdraw
    UnderReview --> Active: Approve
    Active --> Draft: New version (edit)
    Active --> Superseded: Newer version activated
    Superseded --> [*]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class Active accent

Figure 3 — A version's lifecycle. Submitting for review freezes the graph and raises a review task; approval activates the version (orange) and supersedes the previously active one. Datahub records which version was live at every point in time.

Build — edit the graph in a draft version.
Submit for review — validates the graph and opens a review task; the version freezes while under review.
Review — a user with bpm.editor sees the task in their Tasks inbox and approves or rejects.
Approve — the version becomes active with the previously active version superseded, recorded on the version's activation timeline.
Reject / Withdraw — the version returns to draft for further editing. You can withdraw while the review is open. The people who may are whoever submitted it, the team or person it is waiting on, and an administrator; see Workflows.

Each version can also carry optional governance metadata: an SLO target (hours, with a description) that sets the expected turnaround for the process, and an accountable owner — a user or a team.

How the history stays auditable

Datahub keeps version history as a gapless timeline (SCD Type 2): when a new version is activated, the previous one is superseded at the exact same instant, so there is never a gap or an overlap. Ask "which version was live last quarter?" and the activation timestamps answer it.

Process relationships¶

Processes can declare typed connections to other processes (no graph edges, just metadata):

Type	Meaning
feeds_into	This process produces inputs another process consumes.
depends_on	This process needs another process to have run.
triggers	This process initiates another.
alternative_to	A different way to achieve the same outcome.

Manage relationships from the right sidebar of the builder when no node is selected.

Importing and exporting¶

Processes are portable JSON envelopes:

Export (/processes/{id} → toolbar Export) downloads a JSON file with name, description, category, tags, trigger metadata, and the full graph.
Import (/processes list → Import JSON) accepts the envelope and creates a brand-new definition + version 1. Roundtrip-safe — exporting and re-importing produces an equivalent process.

Use this to share processes across tenants, version-control them in git, or back up before a major restructure.

How HERC sees processes¶

The BPM agent indexes process definitions. You can ask:

"Show me processes tagged with PII."
"What's the Customer Onboarding process?"
"Find all processes in the Finance domain."

The agent surfaces the process by name (no raw IDs), with the category and the link to open it.

Limitations¶

Limit	Why	Workaround
Processes don't execute.	Documentation, not runtime.	Use Flows for execution.
Subprocess depth is capped at 5.	Hierarchies beyond 5 levels are usually wrong.	Refactor the deepest layer into a sibling process linked via feeds_into.
Active versions are read-only.	History integrity.	Create a new version to keep editing.
One version active at a time.	Single source of truth.	Activating a new version automatically deactivates the previous.
Process delete is admin-only and can't delete an active version.	Safety.	Archive instead; deactivate first if you must delete.
Step numbering is suggested, not enforced.	Some processes have non-linear flow.	Override the suggestion in the node config; numbers are display-only.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who edited this process and when?"	Each version row carries created_by + published_at. Audit log: `/admin/audit-log` filtered by `bpm`.
"Which version was live at this point in history?"	Version list shows activation timestamps (a gapless SCD Type 2 timeline).
"Who approved this version going live?"	The version's approval is recorded when the review task is completed.
"Can a viewer change a process?"	No — `bpm.editor` required for any mutation.
"How are processes linked to data?"	Via Data Products (DPB). A process can be wrapped in a Data Product, which a Data Contract can link to.

Troubleshooting¶

Symptom	Likely cause	Fix
Can't edit the graph	Active (or under-review) version is read-only.	Create a new version.
Subprocess link shows raw UUID	Stale cache.	Refresh; the resolver should show the process name.
Step numbers feel wrong after restructuring	Cached suggestion from before the restructure.	Click Suggest steps again.
Activate fails	Validation error on a node config.	Open the failing node; required fields are red.
Version stuck in "Under Review"	The reviewer hasn't acted yet.	Ask them to approve in the Tasks inbox, or withdraw the review.
Import returns 400	JSON envelope is from an incompatible older version.	Re-export from the source tenant or fix the format manually.
Edit toolbar buttons missing	Process is archived.	Restore it from the archived view.

Arriving from a domain's detail page narrows this list to that domain automatically — a banner names it, with a one-click way back out. See Domains.