Tasks: your work inbox¶

The Tasks module is the single place to find what's waiting for you across Datahub. Anything that needs your attention — a glossary term to approve, a contract to review, a metric to validate, a workflow step to action, an alert to acknowledge — shows up here as a task. Complete it, dismiss it, or hand it off; once you act, the source module is notified and the affected entity moves forward.

It's the platform's "stop pinging me on Slack" surface — every module funnels its inbox here, with provenance, deadlines, and links to whatever needs doing.

When to choose this¶

Open Tasks when you want to:

See what's on your plate today. Open count, overdue count, completed-this-week — at a glance, then drill into the items.
Approve or reject something that's waiting on you. Glossary term review, contract sign-off, metric promotion, custom workflow step.
Acknowledge a notification. A workflow result ("contract was rejected", "your metric is now live") needs you to confirm you've read it.
Hand a task off / decompose it. Link a task to subtasks, or mark a task as blocking another.
See where a task came from. Provenance shows which module raised it, which workflow it belongs to, and the entity it's about.

You do not need this module to:

Track engineering work — Tasks is for governance / business decisions, not project-level engineering tickets (use Jira / Linear).
Notify users in real time — Tasks is the durable inbox; toasts and emails are the push channel.
Manage SLA / triage — that's role-group + workflow definition territory.

What Tasks looks like¶

Surface	Where	What you see
Inbox list	`/tasks`	KPI row (Open, Overdue, Completed this week, Avg resolution), tabs (Open / Completed), DataTable: title, priority, source module, deadline, age.
Task detail	`/tasks/{id}`	Three-column layout: tabs (Overview + Linked Tasks) on the left, provenance + what's-waiting + metadata on the right. Inline approve / reject / dismiss / acknowledge buttons.
Sidebar badge	Sidebar: Tasks	Pending-count badge — kept up-to-date by React Query.
HERC	`/` (home)	Pending count surfaced on the home page.

Concepts¶

Concept	What it is
Task	A unit of work with a title, description, assignee, optional deadline, and an action.
Action type	What the task wants from you — `workflow_step` (approve / reject), `workflow_result` (acknowledge), or a module-specific custom action.
Priority	low / normal / high / urgent. Affects sort and visual weight.
Source module	Which module raised the task (e.g. `workflows`, `glossary`, `metric`). Tracked for provenance.
Source context	Structured metadata about why — e.g. workflow definition + instance IDs.
Deadline	Optional. A task past deadline is overdue and is prioritised in lists.
Result	After completion, the outcome (e.g. approved / rejected) plus an optional comment.
Task link	A relationship between two tasks: subtask, related, or blocked-by.

The lifecycle¶

pending  ──────►  completed     ← user took the action
   │
   ├──────────►  dismissed      ← user dismissed (e.g. acknowledged a notification)
   │
   └──────────►  expired        ← deadline passed, no action taken

A pending task can transition only forward; once completed / dismissed / expired it cannot be reopened. If new action is needed on the same entity, a new task is created.

Where tasks come from¶

Almost every task in your inbox is created by the Workflows engine — when a workflow is started for an entity (a glossary term submitted for review, a metric promoted, a contract awaiting sign-off), the workflow definition specifies which step requires which role group, and the engine creates a task for each reviewer.

Other modules can also create tasks directly via ITaskService — e.g. the metric module creates a workflow_result task to tell a metric owner the result of a review. The pattern is always:

A module decides "this needs human attention".
It calls the task service with title, description, assignee, action type, and source context.
The task lands in the assignee's inbox; they act; the source module is notified via the action result.

The implication: the inbox is the source of truth for "what's pending" — there is no parallel inbox in any module's UI.

Setup — what an admin needs to do once¶

Prereq	Where	Why
Roles	`/rolegroups`	`tasks.read` is included in every authenticated role group by default — every user has an inbox.
Workflow definitions	`/admin/workflows`	What governs which entities create tasks, who reviews, and on which status transitions. See Workflows.
Role groups for reviewers	`/rolegroups`	Workflow steps assign tasks to a role group — make sure reviewer groups exist and have members.

Acting on a task¶

The detail page has the action buttons inline:

Approve / Reject for workflow_step tasks — picks the next step in the workflow, with an optional comment.
Acknowledge / Dismiss for workflow_result tasks — closes the loop on a notification.
Custom action if a module defined one — handled by the source module.

Comments are stored on the task and propagated to the workflow's history (visible on the entity's Activity tab).

Linking tasks¶

Tasks can be linked to each other:

Subtask. A child task that belongs to a parent. Useful for decomposing a complex review.
Related. Bidirectional — "these two tasks share context".
Blocked-by. Source task is blocked until the target completes. Visualised in the what's waiting sidebar.

Links are managed from the Linked Tasks tab on the task detail page.

Stats panel¶

The list page's KPI row is computed live for you:

KPI	What it counts
Open	All your pending tasks.
Overdue	Pending tasks with a deadline in the past.
Completed this week	Your completed tasks in the last 7 days.
Avg resolution	Mean hours from creation to completion over the last 30 days.

Stewards and managers should look at the open and overdue counts daily; the resolution average is a good proxy for review-throughput health.

Limitations¶

Limit	Why	Workaround
Tasks are user-scoped — no team inbox by default.	Each task is assigned to a user (resolved from the role group at the time of creation).	Configure the workflow to assign to the first available member, or rotate via role-group membership.
No native re-assign UI.	Re-assigning would break the audit trail.	Decline the task → another reviewer in the role group is assigned automatically by the workflow.
No SLA / escalation engine.	We rely on deadlines + visibility.	Use the deadline field; for escalation, configure a workflow with a "no decision in N days" branch.
Notifications are in-app only.	We don't push to email by default.	If your tenant needs email, configure via the integration roadmap.
Once completed, a task can't be reopened.	History stays clean.	Restart the source workflow or create a new task.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who approved this contract?"	Detail page → Result + Result comment. Plus `/admin/audit-log` filtered by `tasks` + entity ID.
"How long did review X take?"	Detail page → Avg resolution; full history in audit log.
"Can a user dismiss a task that wasn't theirs?"	No — tasks are scoped to the assignee; the API rejects cross-user actions.
"Did anyone bypass the workflow?"	Workflow steps must complete via tasks; bypass attempts are blocked at the service layer and audit-logged.
"Where do task comments live?"	On the task row + propagated to the workflow's activity log.

Troubleshooting¶

Symptom	Likely cause	Fix
Inbox is empty but I expect a task	Workflow not configured for the entity, or you're not in the reviewer role group.	Check `/admin/workflows` for the entity type; check your role group membership.
Task created for the wrong person	Workflow assigns to first member of the reviewer role group; that person changed.	Re-decline; the workflow re-assigns.
Approve / Reject buttons greyed out	You don't have the role required for that workflow step.	Have an admin grant the role.
Task shows for an entity that no longer exists	Source entity was hard-deleted (rare — most modules archive).	Dismiss the task.
Stats KPI is 0 but I see tasks in the list	Stats are scoped to you; the list may be showing tasks for your role group via the team filter.	Check the team filter toggle.
Sidebar pending-count badge is stale	Cached in React Query.	Refresh the page.