Workflows: the platform-wide approval engine¶

The Workflows module is the engine behind every "Submit for Review" button on the platform. When a user proposes a change to a glossary term, a metric, an insight, a contract, a data product, or a data asset — the workflow engine routes the request through a configurable approval chain and lands the resulting work in each reviewer's Tasks inbox.

Workflows is cross-cutting: business users typically don't open the workflow admin UI. They submit something, see under review, then approve / reject / request revision in their inbox. Admins design the workflow once; every supported entity uses it from then on.

When workflows kick in¶

Entity	What triggers a workflow	Module
Glossary term	Submit for Review on draft	Business glossary
Metric definition	Submit for Review on draft	Metrics
Insight dashboard	Submit for Review (publish gate)	Insights
Data asset	Promote to Certified / Archive	Data catalog
Data contract	Submit a new version	Data contracts
Module access request	User requests access to an inactive module	Administration → Modules
(More entities can be added by registering an `IWorkflowEntityHandler`.)

If the entity has no active workflow definition for its type, it transitions directly without review (configurable per entity).

What you'll see in the UI¶

Surface	Where	What it does
Submit for Review modal	Detail page of the entity (when in `draft` status)	Shows the workflow timeline, assigned roles, SLA per step, completion outcome. Submitter optionally picks the first step's assignee.
WorkflowProgress	Detail page of the entity (when an instance is active)	A horizontal step bar — completed steps in green, current step animated, future steps muted. Each step shows the assignee + SLA countdown.
Tasks inbox	`/tasks`	Each step generates a `workflow_step` task for the assignee. Approve / Reject / Request Revision lives here. After completion, a `workflow_result` task notifies the submitter.
Admin workflow builder	`/admin/workflows`	Visual graph editor (React Flow). Drag step / decision / notification nodes; wire them with edges; pick assignee rules and SLA per step. Versioned.

Concepts¶

Concept	What it is
Workflow definition	The reusable template — entity type, trigger statuses, completion / rejection statuses, ordered steps.
Workflow version	A snapshot of the definition's graph. Only one version is active at any time. Existing instances continue under the version they started on.
Workflow step definition	A node in the graph — defines the assignee rule, SLA, and (for decision nodes) the result-based branching.
Workflow instance	A running execution tied to one entity (e.g. Approve metric `Net Revenue` v2). Tracks current step + overall status.
Workflow step instance	One step of a running instance. Tracks assignee, linked task, result (approved / rejected / revision_requested), timing.
Webhook registration	An external URL the engine fires events to — see Webhooks below.
SLA policy	A timing template (deadline, reminders, escalation) attached per step. See Administration → Policies.

Assignee rules — who gets the task¶

Each step picks one of:

Rule	What it does
`submitter_picks`	The submitter chooses a reviewer at submit time (typed-ahead user picker).
`role_based`	Resolves to the first user holding a given organisational role.
`auto_route_domain_steward`	Looks up the domain steward for the entity's domain (used heavily by the metric approval workflow).
`entity_owner`	Routes to the entity's owner.
`specific_user`	Hard-coded to one user.

If auto_route_domain_steward can't resolve a steward, the engine falls back to submitter_picks and the modal asks the submitter — never silently fails.

Decision nodes & graph routing¶

Workflows don't have to be linear. You can drop decision and gateway nodes into the graph and route based on the previous step's result:

An Approval Step node has handles for approved, rejected, and (optionally) revision_requested.
A Decision node branches on a condition (e.g. risk classification, requested change size).
A Notification node sends a notification but does not block the chain.
End Approved / End Rejected terminal nodes determine the entity's final status (drives the entity status transition via the IWorkflowEntityHandler).

Pass-through (notification, decision) nodes are traversed transparently — they don't create tasks.

SLA, reminders, escalation¶

Each step can carry an SLA policy (defined in Administration → Policies). The scheduler runs every few minutes and:

Sends graduated reminders to the assignee at configured fractions of the deadline (e.g. 50% → soft, 80% → urgent).
Escalates to a supervisor / role at the configured threshold.
Auto-expires the task on policy-mandated expiry; the step (and instance) close as expired.

Six standard SLA policies ship — Critical Escalation (4 h) through Compliance Review (240 h). Default is Standard Approval (48 h).

The Tasks inbox shows a countdown timer per task so reviewers always see how long they have.

Lifecycle¶

draft → (Submit for Review) → under_review → (workflow runs) → approved or rejected
                                            ↓
                                        cancelled / expired (by submitter or SLA)

The entity's status is driven by the workflow, not by the user. The workflow engine calls into the entity module's IWorkflowEntityHandler to perform the actual status transition once the workflow completes.

Submit for Review — the user experience¶

User opens the entity detail page in draft status.
Clicks Submit for Review.
The shared SubmitForReviewModal opens, showing:
- The active workflow definition (name, description).
- Each step in order with the resolved assignee role + SLA badge.
- The completion + rejection outcomes.
- A user picker if submitter_picks applies (or auto_route failed).
Submit. Entity transitions to under_review. Reviewers see the task.
Each reviewer approves / rejects from their inbox.
The engine advances to the next step automatically. On final approval, the entity transitions to its completion status (e.g. published, active). On any rejection, it transitions to its rejection status (typically draft) and the submitter gets a workflow_result task with the rejection reason.

Withdraw and cancel¶

The submitter can withdraw a request before the first approval (the engine cancels the active instance; the entity returns to draft).
An admin (or a workflow with sufficient permissions) can cancel an instance at any time.

Webhooks — push events to external systems¶

Workflows is also the home of outbound webhooks. Every event on the platform's event bus (entity created, status changed, workflow completed, task assigned, …) can be subscribed to by registering a webhook:

Field	What it does
URL	HTTPS endpoint to deliver to. SSRF defence rejects private / loopback / link-local hosts at write-time and at every dispatch (DNS rebinding defence).
Event types	One or more event names to subscribe to.
Secret	HMAC-SHA256 signing key. Every delivery includes `X-Datahub-Signature` so receivers can verify authenticity.
Retry	3 attempts with exponential backoff (1m → 5m → 30m).
Delivery log	Per-attempt audit trail.

Common uses: notify Slack / MS Teams when a metric is approved, push a contract publication into a downstream catalog, kick off a CI pipeline.

Roles¶

Role	What you can do
`workflow.definitions.manage`	Create / edit / delete workflow definitions.
`workflow.versions.manage`	Create, edit, activate, delete versions.
`workflow.instances.read`	View workflow instances and history.
`workflow.webhooks.manage`	Manage webhook registrations.

The Workflow.Administrator role group bundles workflow.definitions.manage + workflow.instances.read + tasks.read.

Designing a workflow — the basics¶

/admin/workflows → New definition.
Pick an entity type (must be one supported by an IWorkflowEntityHandler).
Pick trigger statuses (entity status that fires the workflow, e.g. draft → under_review), completion statuses (e.g. [active], [published]), and rejection status (typically [draft]).
Drag steps onto the canvas. Each step picks an assignee rule and (optional) SLA policy.
Wire the edges. For multi-outcome steps, label the edges with approved / rejected / revision_requested.
Drop terminal nodes (End Approved / End Rejected).
Save → activate. The graph compiles into ordered step definitions; the active version is now in force for new instances.

Limitations¶

Limit	Why	Workaround
Only one active version per definition.	Avoid ambiguity.	Existing instances continue on their original version.
Existing instances don't migrate to a new version.	Auditability — instance must be reproducible.	Cancel + restart if the new version must apply.
Decision nodes evaluate on the previous step's result, not on entity attributes.	Engine simplicity.	Use a Flow (Flows) for attribute-driven branching.
Webhook deliveries are best-effort with finite retries.	Receiver may be down.	Inspect delivery log; manually re-dispatch from the admin UI.
Workflow steps can't run arbitrary code.	Security.	Use Flows for code-driven automation; trigger the flow from a workflow step's notification node.
The engine does not understand "and / or" parallel approvers.	Single-track for now.	Model as sequential steps; planned.

Audit & compliance¶

Question	Where to look
"Who approved this metric?"	Detail page → workflow progress → step instance audit.
"How long did the review take?"	Each step instance has start / end timestamps.
"Did the SLA fire?"	Reminder log table; `policies` event stream.
"Was the webhook signed?"	Yes — every dispatch includes `X-Datahub-Signature` (HMAC-SHA256).
"Can a reviewer approve their own submission?"	Workflow definitions can require a different reviewer than the submitter (configurable per step).
"Where do webhook URLs go?"	Stored against the registration; SSRF-validated at write time and on every dispatch.

Troubleshooting¶

Symptom	Likely cause	Fix
"Submit for Review" button missing	No active workflow definition for the entity type — entity transitions directly.	`/admin/workflows` → register a definition.
Reviewer sees no task	Assignee rule didn't resolve.	Check the workflow step instance — `submitter_picks` fallback should engage automatically; if not, file a ticket.
Workflow stuck in `under_review`	Step task is not approved + no SLA expiry.	Check the inbox of the assignee; reassign if needed.
Webhook deliveries failing	Receiver returned 4xx/5xx, or URL was rejected by SSRF defence.	`/admin/workflows` → webhook detail → delivery log. Edit URL if rejected.
Webhook signature mismatch on receiver	Receiver computing HMAC differently.	Use HMAC-SHA256 over the raw body with the registration secret; header is `X-Datahub-Signature`.
"Submit for Review" modal lists wrong reviewers	Workflow definition's assignee rules don't match your org.	Edit the definition + activate a new version.