Administration¶

Administration is where platform owners configure Datahub itself — who has access, which modules are switched on, what the platform looks like, and where it connects.

It's not a single module: it's the umbrella over the admin-only pages collected at /admin/* plus the identity pages at /users, /orgroles, and /rolegroups. Most sit behind narrow roles, so a typical business user never sees them. This page is the map — what each area does, who needs it, and which other modules it feeds.

Admin surface`/admin/*` · `/users` · `/orgroles` · `/rolegroups`

System tables5 shared lists

SLA policies6 built-in

Permission unitRole group

What you configure here¶

Access, users & roles

Accounts at /users, organisational positions at /orgroles, and permission bundles at /rolegroups.
Modules

Turn whole areas of Datahub on or off, set sidebar visibility, and roll betas out to a group — /admin/modules.
System tables

The shared vocabulary everyone draws on — tags, departments, teams, event categories at /admin/system-tables. (Domains left this list: see Domains.)
Branding & defaults

Theme colour, logos, agent identity, locale, currency, and organisation profile — /admin/branding, /admin/defaults, /admin/organization-profile.
Connections

Wire Datahub to Databricks, storage, AI providers, and export targets — /admin/integrations, /admin/export-targets, /admin/fiscal-calendars.
Operations

SLA policies, approval-workflow design, result caches, and the audit log — /admin/policies, /admin/workflows, /admin/cache, /admin/audit-log.

How Administration fits together¶

Administration is a hub of small configuration surfaces. Each one governs a slice of the rest of the platform — access decides who can act, modules decide what's visible, system tables feed shared lists, branding themes the UI, connections power the query engines, and operations enforces policy.

flowchart LR
    ADMIN(["Administration"])
    ADMIN --> ACC["Access, users & roles<br/>who can do what"]
    ADMIN --> MOD["Modules<br/>which areas are on"]
    ADMIN --> SYS["System tables<br/>shared vocabulary"]
    ADMIN --> BRAND["Branding & defaults<br/>look · locale · currency"]
    ADMIN --> CONN["Connections<br/>Databricks · storage · AI"]
    ADMIN --> OPS["Operations<br/>policies · workflows · caches · audit"]
    ACC -.governs.-> APP[("The rest of Datahub<br/>Metrics · Insights · Flows · Catalog · …")]
    MOD -.governs.-> APP
    SYS -.feeds.-> APP
    BRAND -.themes.-> APP
    CONN -.powers.-> APP
    OPS -.enforces.-> APP
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class ADMIN accent

Figure 1 — Administration is one hub over six configuration areas; each governs a slice of the platform the rest of Datahub reads from.

When you'll come here¶

You want to…	Go to
Switch a whole module on or off (e.g. disable Flows for now)	Modules
Add a tag, department, team, or event category	System tables
Add or govern a domain	Domains — its own module, not system tables
See the trail of "who changed what" across the platform	Audit log
Connect Databricks, Azure, or any external system	Integrations
Configure where exports land (Azure Blob / ADLS)	Export targets
Manage SLA policies (deadlines, reminders, escalation)	Policies
Define or edit approval workflows	Workflows
Manage fiscal calendars (so metrics use your YTD / QTD definitions)	Fiscal calendars
Clear / inspect the metric or insight result cache	Metric query cache / Insights query cache
Change the platform's brand colour, logo, agent name	Branding
Set tenant-wide defaults (date format, currency, locale, chart palette)	Defaults
Capture organisation-level mission, vision, strategy, and goals	Organisation profile
Manage users	Users
Define roles for organisational positions (CFO, Data Steward, …)	Organisation roles
Group platform roles into reusable bundles	Role groups
Manage AI provider keys, model settings, guardrails, observability, experiments	See the AI platform page
Run, monitor, or unblock approval workflows	See the Workflows page

Access, users & roles¶

Datahub separates three things: who someone is (a user account), the position they hold (an organisation role), and what they're allowed to do (platform permissions bundled into role groups). Permissions are never assigned per user — a user gets them by belonging to one or more role groups.

flowchart LR
    U(["User account<br/>/users"])
    U --> RG["Role group<br/>/rolegroups"]
    U --> OR["Organisation role<br/>/orgroles"]
    RG --> PERM["Platform roles<br/>module.resource.action"]
    PERM --> GUARD["Sidebar & page guards<br/>roles.ts"]
    OR --> ROUTE["Workflow assignment · task routing<br/>HERC 'who's responsible?'"]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class RG accent

Figure 2 — Two independent axes hang off a user: role groups grant platform permissions the UI guards consult; organisation roles describe the position that routes work.

Users¶

/users

User accounts in the tenant. Add users, edit profile fields, deactivate. Roles are not assigned per user — they're assigned by membership in role groups.

You cannot archive your own account: the Archive button on your own page is switched off, and the server refuses the request too, because you would be signed out and only another administrator could restore you. Ask another administrator to archive it.

Organisation roles¶

/orgroles

Organisational roles describe positions (CFO, Data Steward of Finance, …) — distinct from platform permissions. They feed:

Workflow assignment rules (role_based, auto_route_domain_steward).
Task routing.
HERC's reasoning about who's responsible for what.

A user can hold multiple org roles.

Put every administrator in the Administrator organisation role

Reviews are routed to organisation roles, never to someone who holds only a role group. When a review's own group has nobody who may approve it, the review goes to the next organisation role that may, and Administrator comes last. An administrator who holds the Administrator role group but is in no organisation role is invisible to that routing, so the workflow builder warns that the reviews go to nobody.

Give every administrator the Administrator organisation role (it carries the Administrator role group, so nothing else changes). If you sign people in through Microsoft Entra, map the Entra group that holds your administrators to the Administrator organisation role on the Entra sync page, not only to the role group. Adding someone by hand at /orgroles works too.

Role groups¶

/rolegroups

This is the central permission lever. A role group is a named bundle of platform roles (e.g. Administrator, MetricSteward, AI.Editor). Users get permissions by being added to one or more role groups.

Built-in role groups cover common personas; tenants typically add a handful of custom groups (e.g. EMEA Finance Reader, Data Catalog Steward).

How a permission string maps to the UI

Each platform role follows the convention module.resource.action (e.g. metric.read, dashboards.manage). The matching frontend constants live in roles.ts, and the sidebar and page guards consult them to decide what a user can see and do.

Modules¶

/admin/modules

Every top-level area of Datahub (Metrics, Insights, Flows, …) is governed by a row in the platform's module settings table. As an admin you control:

Control	What it does
Activate / deactivate	Turn a module on or off. When off, its sidebar item disappears or greys out (configurable per module).
Visibility	`hidden` (vanishes from the sidebar entirely) or `disabled` (visible but non-clickable, with a tooltip explaining how to request access).
Release status	`ga` or `beta` — drives the beta badge in the sidebar.

When a module is off, users who try to navigate there see a request access modal. Submitting it starts a workflow (handled by the Workflows engine); on approval the module auto-activates. A request can also be denied — the requester then sees the reviewer's note, and resubmission may be blocked or held until a cooldown passes.

flowchart LR
    OFF["Module deactivated<br/>hidden or disabled"] --> NAV["User navigates there"]
    NAV --> REQ["Request access modal"]
    REQ --> WF(["Approval workflow"])
    WF -->|approved| ON["Module auto-activates"]
    WF -->|denied| NO["Request declined<br/>reviewer note · optional cooldown"]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class WF accent

Figure 3 — Turning a module off never deletes data. A user's request for a deactivated module routes through the approval workflow: approval flips it back on automatically, while denial declines the request, with an optional cooldown before another try.

The clean way to pilot a beta

Set a module to beta and disabled to roll it out to a specific group through the request-access flow — or retire a module without deleting any of its data.

System tables¶

/admin/system-tables

System tables are the shared vocabulary the whole platform draws on. They're tabbed inside one page:

Tab	What it controls	Used in
Tags	Free-form labels with a colour. Govern PII, sensitivity, lineage hints, ad-hoc grouping.	Catalog assets, glossary terms, metrics, insights, events, transcripts, flows, etc.
Domains	Moved out of system tables. Domains are now their own module at `/domains` — see Domains. They are no longer a flat list: a domain carries membership and stewardship, decides who may edit and approve an asset, nests into sub-domains, and refuses deletion while it still governs something.	Glossary, catalog, metrics, contracts, products, processes.
Departments	Hierarchical organisational units (e.g. Finance → Accounting). Contracts, assets, and tasks are routed by department. Hierarchy via `parent_id`.	Contracts, products, flows, insights, dashboards.
Teams	Cross-functional teams (e.g. Data Engineering, Data Governance). Owns Data Products.	Data Products.
Event categories	Categories used in the Events module.	Events.

Each tab is a small CRUD list with system-flagged seed rows (which can't be deleted) and user-created entries (which can).

Creating, changing or deleting a tag, or a catalog system, appears in the Audit log with who did it and the old and new value of each field it changed. Deleting a tag also records how many assets carried it and names them (up to 500); the audit log shows the first five.

Putting a tag on an asset or taking one off is recorded on that asset: it appears in the asset's History tab and in the Audit log, with who did it and which tags were added and removed. Saving the same tags again records nothing.

Add here once, use everywhere

So many modules read from these tables that the rule of thumb is to define a tag, department, or team once in system tables and reference it everywhere else. Domains work the same way but live in their own module.

Branding & defaults¶

Tenant-wide identity and preferences: how the platform looks, how numbers and dates are formatted, and the organisational context the AI reasons from.

Branding¶

/admin/branding

Per-tenant visual identity:

Setting	What it controls
Theme colour	Preset orange, neutral grayscale, or a custom hex (validated for contrast in light + dark mode).
Logo (light / dark)	Full wordmark on the sidebar and login page.
Icon (light / dark)	Favicon and app icon.
AI agent identity	Name and avatar for HERC.
Regional defaults	Date format (`DD-MM-YYYY` default), time format (24h default).
Page descriptions	Admin-editable header copy on top-level pages.

Brand assets survive restarts

Logos, icons, and avatars are stored in the database (BYTEA), not the container filesystem, so they persist across container restarts and redeploys.

Defaults¶

/admin/defaults

Tenant-wide defaults that users inherit and can optionally override per-account at /account:

Default	Format	Drives
Number locale	BCP-47, e.g. `nl-NL`	`Intl.NumberFormat` — thousands separator, decimal separator, currency formatting.
Default currency	ISO 4217, e.g. `EUR`	Monetary formatting across the platform.
Insights chart palette	up to 5 hex colours	The default chart series in Insights.

Fresh deployments ship with nl-NL and EUR; admins can change both.

Organisation profile¶

/admin/organization-profile

Mission, vision, strategy, and free-form profile text — plus a list of organisational goals and targets.

The AI reads this content

This isn't decorative: HERC and the agent system read the profile when answering open-ended questions ("are we on track to hit X?"), so answers are grounded in your strategy rather than generic. The PUT is partial — only changed fields are sent — so unset fields stay null rather than being overwritten with empty strings.

Connections¶

Where Datahub reaches out to the world: the query backends, the export destinations, and the fiscal calendars metrics resolve against.

Integrations¶

/admin/integrations

The single page where you wire Datahub to external systems:

Connector	Powers
Databricks	Workspaces via Service Principal, OAuth U2M, or PAT. Drives Metrics, Insights, Dashboards, Alerts, Metadata Engine, and several Flows actions.
AI providers	OpenAI, Anthropic, Azure OpenAI, and Datahub Private AI. See AI platform.
Storage & identity backends	Azure AD, Azure Key Vault, etc.

Most integrations support multiple instances; the modules that consume them pick which instance per query.

Per-user Databricks identity

For Unity Catalog row-level security and per-user audit, connect Databricks with per-user OAuth — queries then run under the calling user's identity instead of a shared Service Principal.

When a client secret expires

Secrets die on a schedule; scheduled syncs do not. When the identity provider rejects a stored credential, Datahub marks that integration Credentials rejected in the catalog and on its detail page, and raises one Rotate credentials task for whoever wired it up (or, failing that, a holder of integrations.manage). Repeat failures update that same task instead of raising new ones.

To clear it: open the integration from the task, paste a new client secret, save, and run Test connection. A successful test clears the badge and closes the task automatically — there is nothing to tick off by hand. The same loop covers the shared Service Principal under Metadata Engine → Authentication.

A Databricks integration also clears itself: when the scheduled alert sync (every 6 hours) signs in with the integration's own credential on every workspace linked to it, the badge clears and the task closes without a Test connection. It does not when a Genie service principal signs in for the integration instead, because that says nothing about the integration's own credential.

The integration's lifecycle status is untouched throughout: a published integration with a dead secret stays published. Only its connection health changes.

Publishing views to Databricks¶

A Databricks connection's View publishing tab decides whether, and where, Datahub may publish advanced assets as Databricks views. It is off until an integrations admin sets it up. Until then, an asset's Databricks view subpage says publishing is off and who turns it on.

Sign in as. Choose the login Datahub publishes with:
- This connection's own login: the credentials the connection already reads with, and nothing else to set up.
  - A connection that signs in with a personal access token gets a warning: its views are created and owned by the token's owner, and stop working when the token expires or its owner loses access.
  - A connection that signs in as each user (per-user OAuth) can't publish on its own, so this choice isn't offered.
- A separate service principal: a principal used only for publishing, so the connection's reads keep their own, narrower rights. Choose how it signs in: Microsoft Entra service principal, or Databricks OAuth machine-to-machine. Then enter the names of the two key vault secrets that hold its client ID and client secret, not the values. Each name starts with the connection's own prefix, which the form shows.
Target catalog and schema. Pick them from what that login can see, or type them. The schema must already exist. Datahub creates views there and nowhere else.
Save, then Test. The test signs in with the saved settings and creates nothing. It runs four checks in order: Network, Sign-in, Use the schema and Create views. Each reads Passed, Failed, Skipped (an earlier check failed) or Unverified. Create views reads Unverified when no CREATE TABLE grant on the schema names the login directly: Databricks doesn't list a grant held through a group or the catalog, so the first publish tells. The test doesn't check SELECT on source tables either, since those depend on each asset.
Turn Publishing on. This is possible only once the saved settings are complete and, for a service principal, both secret names are found in the key vault.

The publishing login needs these privileges:

USE CATALOG and USE SCHEMA;
CREATE TABLE on the target schema (the privilege Unity Catalog checks to create a view);
SELECT on every source table it publishes from.

Who can read the views

Anyone who can read the target schema can read through its views. A view runs with its owner's rights, so a reader sees rows from source tables they could not open themselves. Datahub grants nothing: who may read the schema is decided in Databricks. A grant made on one view is kept when Datahub publishes that view again, because it changes the view in place; a view removed and published again, or published under a new name, starts without it.

Export targets¶

/admin/export-targets

Storage destinations that data assets are written to. Each one points at an Azure Data Lake Storage / Blob connection you have already registered, plus the container, path prefix and file format to write. Users with datacatalog.export.manage (administrators, by default) register targets, choose which assets each one receives, and sync an asset to them — from the asset's page or from the target's page. Syncing is manual: nothing writes to storage on a schedule, so after an asset changes its stored copy stays as it was until someone with that role syncs it. Everyone else sees on the asset's page which targets it goes to and whether a copy is behind. Each linked asset shows who linked it and when, and linking, unlinking and every sync attempt — including a failed one — appear in that asset's history with the name of whoever did it.

A target's own page has a History of who created it and every change to it, with the old and new value of each setting. Targets created before Datahub began recording these changes show only what happened since, and say so. Admin → Audit log lists the same changes, and a deleted target's page still opens its history. Changing where a target writes — its connection, container, path prefix or file format — marks every linked asset Behind until it is synced again, because the next sync writes to the new place. Files already written to the old place are not moved or removed. Changing the storage account of the connection itself moves every export target on it too: before you save, the connection form names those targets and how many assets each has linked, and after it their assets read Behind and each target's History records the change, old account → new, with who made it.

A copy marked Behind says why, and when that last happened: Destination moved (the target now writes somewhere else) or Asset changed (the asset was edited after its last sync; the date is its latest edit). A copy that was never synced says Never synced. On the target's page, a failed sync shows its error on that row. After a move, Sync all Behind on the target's page syncs every Behind asset in one go, one at a time, after asking once; it ends by naming any asset that failed and why. Each of those syncs is recorded in its own asset's history, as a sync from the asset's row would be.

Azure storage only

An export target writes to ADLS / Blob. S3, GCS and SharePoint are not export destinations — to get an export elsewhere, download it, or have an alert mail it (see Microsoft 365).

Fiscal calendars¶

/admin/fiscal-calendars

Define your organisation's fiscal year, quarters, and periods. Metrics that use YTD / QTD / MTD / fiscal-year time grains resolve against the calendar attached to the metric definition. Most tenants need one calendar; multinational tenants can register several and pick per-metric.

Operations¶

The levers for keeping the platform running: how approvals are timed and shaped, and how you flush stale query results.

Policies — SLA, deadlines, reminders, escalation¶

/admin/policies

Type-aware policy templates with JSONB config. Today the main type is SLA policies — they govern how long a workflow step has before it's considered overdue, when reminders fire, and when it auto-expires.

Six standard SLA policies ship out of the box:

Policy	Deadline	Behaviour
Critical Escalation	4 h	Tight reminders, immediate escalation.
Quick Acknowledgment	8 h	Fast acknowledgement window.
Urgent Review	24 h	Auto-expire on miss.
Standard Approval	48 h	Default for most approvals.
Extended Review	120 h	For complex changes.
Compliance Review	240 h	Long horizon for audits.

Policies attach to workflow definitions through policy assignments — a workflow can pick a different SLA per step, or fall back to the default. See Workflows.

Workflows admin — design the approval flow¶

/admin/workflows

Visual builder for the platform's approval workflows. Each definition picks the entity type (glossary term, metric, insight, contract, …), the trigger statuses, the steps and their assignee rules, and the SLA policy.

Definitions are versioned; only the active version is in force. Existing instances continue under the version they started on. See Workflows for the user-facing side (Tasks inbox, Submit for Review modal, workflow progress on detail pages).

Result caches — operational levers for query speed¶

Page	Module	What it does
`/admin/cache`	Metric query cache	View, search, and purge cached metric query results. Filter by metric, by version, by user, by warehouse. Useful when a backing table changes and you want fresh numbers.
`/admin/insights-cache`	Insights query cache	Same idea for Insights cards.

Both caches are also auto-invalidated on common signals (definition edits, archive, contract version changes). The admin page is the manual escape hatch.

Audit & change history¶

/admin/audit-log

A read-only ledger of mutating actions across the platform: who did what, when, against which entity. Filterable by user, entity type, action, and date range.

Used for:

Compliance reviews ("show me every change to Customer LTV in the last 90 days").
Incident triage ("who archived this contract?").
HERC's recent activity feed and the home page's trending entities list both read from here.

Audit entries are immutable

The audit log is append-only — entries can't be edited or deleted, which is what makes it usable as evidence in a compliance review.