Business Glossary: one definition per concept¶

The Business Glossary is Datahub's repository of business terms — the words your organisation uses (Customer, MRR, Active subscription) and the precise definition that backs each one. Every term has an owner, a status lifecycle, related terms, and links to the data assets that implement the concept. Stewards govern the glossary so that arguments about "what does active mean?" stop happening on Slack.

When to choose this¶

Reach for the Glossary when you want to:

Define a business concept once. Pick Customer — define it once, with the steward's name, the date approved, the related concepts, and the catalog assets that implement it.
Make terminology searchable. When someone joins, they should be able to type NRR into the platform and get the definition + the metric that calculates it + the dashboard it appears on.
Govern naming and ownership. Terms transition draft → under-review → published with reviewer approval. Every change is journaled.
Wire vocabulary to data. Customer (term) → customers (catalog asset) → Customer 360 (data product) → contract. The chain holds.

You do not need the Glossary for:

Technical column names (those live in the Catalog as column descriptions).
Process-step labels (those live in the Process module).
Metric names (each metric has its own definition; link the term to the metric, don't duplicate it).

What the Glossary looks like¶

Surface	Where	What you see
Overview	`/glossary`	KPIs (terms total, by status, by domain), top contributors, the filterable terms list.
Term detail — Overview	`/glossary/terms/{id}`	Name, definition, examples, synonyms, abbreviations, owner, status with state-machine actions, domain, tags.
Term detail — Relationships	`/glossary/terms/{id}`	Other terms it relates to: parent, child, related, synonym, antonym.
Term detail — Linked assets	`/glossary/terms/{id}`	Catalog assets that implement this concept.
Term detail — History	`/glossary/terms/{id}`	Audit log of every state change and edit.
Domains	`/glossary` (Domains tab)	The domain registry — Finance, HR, Sales, etc. Each domain owns its own terms.
Builder	`/glossary/terms/new`, `/glossary/terms/{id}/edit`	Full-page workspace with definition, examples, synonyms, abbreviations, related-term picker, tag picker, asset linker.

Concepts¶

Concept	What it is	Notes
Term	A business concept with a name, definition, examples, and metadata.	The atomic unit of the glossary.
Domain	A grouping (Finance, HR, Sales). Owners are by domain.	System table — admins manage.
Term relationship	A typed edge between two terms (parent / child / related / synonym / antonym).	Drives the relationship browser and HERC's term-cluster answers.
Term-asset link	A typed edge from a term to a catalog asset (implements, describes).	Same edge surfaces on the asset's Glossary tab.
Audit log	Every state change and edit, with who and when.	Plus journal in `/admin/audit-log`.

Setup — what an admin needs to do once¶

Prereq	Where	Why
Domains	`/glossary` → Domains tab	Every term belongs to a domain. Six are seeded; tenants typically add a few.
Owner teams	`/admin/teams`	Each domain has an owner team.
Roles	`/rolegroups`	`glossary.terms.read`, `glossary.terms.write`, `glossary.terms.approve`, `glossary.domains.manage`.
AI provider (optional)	`/admin/integrations` → AI Provider Keys	Required for AI-enriched bulk import.

Drafting a term¶

The simplest path:

Open /glossary → New term.
Name it. Net Revenue Retention. Add aliases (NRR) and optional abbreviations.
Define it. One sentence first; expand below. Add 1–2 examples.
Pick a domain and a steward team.
Relate it. Related to → Customer churn. Parent of → Gross Revenue Retention.
Link assets. If the metric nrr exists in the catalog, link to it. If a dashboard renders the term, link to it.
Submit for review. A task lands in the Glossary Approvers role group's inbox.
Approve. Once approved, the term is published and visible to everyone with read access.

Bulk import with AI enrichment¶

When you have a glossary in a spreadsheet, Import on /glossary:

Upload CSV / Excel.
Map columns to fields (name, definition, domain, steward, …).
AI enrichment (optional) — the platform reads each row and proposes: a cleaner definition, missing examples, related terms, and asset link suggestions based on name match.
Review row-by-row. Accept, edit, or skip each enrichment.
Confirm — every accepted term lands as a draft. You then submit them for review in batches.

The AI enrichment step is what turns a 200-row spreadsheet into a usable glossary in an afternoon instead of a quarter.

Lifecycle¶

Status	Meaning	Who can move it
Draft	Author is iterating.	Author or anyone with `glossary.terms.write`.
Under review	Submitted for approval. Task lands in `/tasks`.	Triggered by Submit for review.
Published	Source of truth.	Approver action (`glossary.terms.approve`).
Deprecated	Still findable, marked as superseded.	`glossary.terms.write`.
Archived	Soft-deleted. Hidden from default lists.	`glossary.terms.write` (with confirmation).

The state machine is configurable per workflow definition (/admin/workflows).

Linking a term to a contract¶

Terms link to contracts the same way every other entity does — via Data Products:

Open the term → Register as Data Product in Part of N data products.
Wrap the term (alone, or alongside the asset / metric that implements it).
Contract → Linked Products → link the product.

See Data Products.

How the glossary feeds HERC¶

When you ask HERC "what's our definition of Customer?", the businessglossary agent looks up the term, returns the definition, and offers follow-ups: show linked assets, show related terms, who owns this?. Behind the scenes the agent also pulls the term's tag and domain to filter related questions.

The platform's DNA graph picks term-asset and term-term edges up automatically, so questions like "what depends on Customer?" route via the graph and return downstream entities across modules.

Limitations¶

Limit	Why	Workaround
One canonical definition per term.	The glossary is the one place — if it has three definitions, it's not a glossary.	Use synonyms / antonyms / aliases for variant phrasing. Use the definition itself for nuance.
Term-asset links are typed but not weighted.	We don't model "primary" vs. "secondary" implementation.	Use the description field on the link to add context.
Bulk import is per-row commit (not transactional across the file).	If one row fails validation, the others still land.	The preview shows row-level errors; fix and re-upload only the failed rows.
AI enrichment uses the active provider key — costs come out of your provider quota.	We don't bury usage.	Disable enrichment if you want to import without AI.
Status transitions are governed; you can't bypass review.	Defeats the point of a governed glossary.	Build a fast-track workflow definition with a single approver if your org needs faster turnover.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who defined this term?"	Detail → History tab.
"Who approved the publish?"	Detail → History tab → the published transition row.
"Who owns Customer?"	Detail → Owner team.
"Show every term touched by a specific user."	`/admin/audit-log` filtered by `glossary` + actor.
"Has the definition changed since the audit cut-off?"	Detail → History tab — every edit timestamp.

Troubleshooting¶

Symptom	Likely cause	Fix
"Term name already exists" on create	Same name in same domain.	Pick a different domain, or add a qualifier (Customer (B2B)).
Submit for Review is greyed	Missing required field (definition / domain / steward) or you lack `glossary.terms.write`.	Complete fields; check role.
Linked asset shows not found	The asset was archived.	Update the link or restore the asset.
AI enrichment never finishes	Provider key missing or rate-limited.	`/admin/integrations` → AI Provider Keys; reduce batch size.
Approver doesn't see the task	They're not in the Glossary Approvers role group.	Add them in `/rolegroups`.
Search misses an obvious term	Term is in draft status — drafts are excluded from default search.	Filter by all statuses or publish the term.