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

The Processes module is Datahub's Business Process Management surface. Use it to document the procedures your organisation actually runs — onboarding a customer, closing the books, handling a data subject request — as visual graphs you can browse, version, and link to the data they touch.

The same definitions are listed under Contracts → Process contracts for a governance-first view (Process contracts).

It's a documentation tool first: a captured process becomes a referable artefact, governed and discoverable, that data products and contracts can attach to. The execution side (running automated workflows) lives in Flows; Processes is for the human-in-the-loop reality.

When to choose this¶

Use Processes when you want to:

Capture a procedure visually. Drag start, task, user-task, and end nodes onto a canvas; connect them; you have a process.
Decompose a complex process. A subprocess belongs to exactly one parent step, up to five levels deep. Useful for Customer Onboarding → Verify Identity → AML Screening → ….
Govern processes alongside the data they touch. Tag with domain, department, team; link to glossary terms and (via Data Products) to contracts.
Version a procedure as it evolves. Each save can be a new version; only one version is active at a time.
Make procedures findable. HERC indexes processes — ask "how do we onboard a customer?" and the platform points you here.

You do not need this module to:

Automate execution end-to-end — that's Flows.
Track approvals through the workflow engine — that's Workflows.
Trigger alerts when a step fails — that's Logic Engine.

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.
Active version	The single version currently considered the "live" definition. Active versions are read-only.
Status	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: priority dot, duration, 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, priority, duration, department, form reference, notes).
Suggest step numbers. The toolbar's Suggest steps runs a BFS from the start and assigns sequential numbers (with letter suffixes for branches: 1, 2a, 2b, 3, …).
Save. Saves update the current draft version; activate the version when ready.
Publish the definition → it shows up in lists, search, and HERC.
Iterate. Create a new version → continue editing the graph; activate the new one to make it live.

Subprocesses¶

Processes can be hierarchical:

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.

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.
"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 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.
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.