Events: the why behind your data¶

Datahub's log of the organisational events — decisions, strategy shifts, market moves, regulatory changes, incidents, milestones, and the rare black swan — that carry the why behind your data, the context no metric trend or dashboard chart can give you on its own.

Events are user-declared knowledge artefacts: different from system audit logs (which capture what the platform did) and from notifications (which deliver what just happened). An event captures what you think mattered, with enough metadata for HERC and your colleagues to find it later.

SourcesManual · Transcription · Chat

Categories8 seeded

Impact levelslow → critical

LifecycleDraft · Confirmed · Archived

When to choose this¶

Annotate a metric trend

"NPS jumped 12 points in May because we shipped the redesigned onboarding." The note lives forever next to the metric.
Record a strategic decision

"In Q2 we decided to deprecate the on-prem connector." Tagged, dated, and owned — not lost in a chat thread.
Capture a market or regulatory event

"GDPR enforcement update — 12 June 2026." Linked by shared tags to the assets and processes it affects.
Build a domain's timeline

Filter by domain or category to see everything that happened in Finance this year at a glance.

When not to reach for Events

Audit logs — what the platform did lives in /admin/audit-log, fed automatically. Events are what you declare mattered.
Notifications — push delivery of what just happened → events are durable records, not pings.
Tasks — decisions still waiting for you → an event is a decision already made. See Tasks.

How the event log works¶

Events enter the log by hand, from a meeting transcript, or through HERC. Once recorded, a single event surfaces everywhere that needs the why — the timeline, the compliance view, HERC's recall, the DNA graph, and the audit trail — because it is dated, categorised, and tagged with the same vocabulary as the rest of the platform.

flowchart LR
    Manual["Manual entry<br/>New event"] --> LOG
    Trans["Transcription<br/>Extract events"] --> LOG
    Chat["HERC chat<br/>ask to log it"] --> LOG
    LOG[("Events log<br/>title · date · impact · status · tags")]
    LOG --> TL["Timeline & KPIs"]
    LOG --> COMP["Compliance view<br/>Regulatory category"]
    LOG --> HERC["HERC recall<br/>tag-based search"]
    LOG --> DNA["Organisation DNA<br/>event-tag edges"]
    LOG --> AUD["Audit log<br/>field-level changes"]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class LOG accent

Figure 1 — Three on-ramps feed one durable log; from there each event fans out to every surface that needs the context — the timeline chart, the compliance view, HERC recall, the DNA knowledge graph, and the audit trail.

Why teams reach for this

A metric tells you what moved; an event tells you why. Because every event is dated, owned, categorised, and tagged with the same vocabulary as the catalog and glossary, the why stays findable years later — by a colleague, by the compliance view, or by HERC in a single question.

Concepts¶

Concept	What it is
Event	A user-declared organisational event with title, description, date, type, impact, status, categories, tags.
Event category	A system-table classification (Strategic, Operational, Regulatory, Market, Technology, Security, Financial, Organizational). Each has a colour and icon. Events can have multiple categories.
Tag	A free-form classification from the catalog tags system table (PII, Customer, Sales, …).
Impact level	low / medium / high / critical. Drives the timeline chart's colour and HERC's prioritisation.
Status	draft → confirmed → archived. Lightweight lifecycle — no heavy approval flow by default.
Source type	manual / transcription / chat — where the event came from.

What Events looks like¶

Surface	Where	What you see
List	`/events`	KPIs (total events, by status, by impact, this-week count), stacked timeline bar chart (events over time by impact), category breakdown sidebar, filterable DataTable.
Detail	`/events/{id}`	Title, description, event date, type, impact, status, categories, tags, audit metadata. Grid layout: main content + metadata sidebar.
Create / edit modal	List page → New event	Title, description, type (with AI suggestion), date, impact, categories (multi-select), tags.

Setup — what an admin needs to do once¶

Prereq	Where	Why
Categories seeded	`/admin/system-tables` → Event Categories	Eight ship out of the box. Tenants can add more. System categories cannot be deleted.
Tags seeded	`/admin/system-tables` → Tags	Catalog tags are reused for events.
Roles	`/rolegroups`	`events.read` to view, `events.write` to create / edit / delete. Ships with Events.Viewer and Events.Editor role groups.

Creating an event¶

Every event lands as a draft, whichever on-ramp you use. The Concepts table's source type records which one it came from, so you can always trace an event back to its origin.

ManualFrom a transcriptFrom HERC

/events → New event. Fill in title, description, event date, and type — the platform's AI suggests an event type from your description as you type, which you accept or override. Pick an impact level, then optionally add categories (multi-select) and tags.

Open a completed transcription session → Extract events. The AI scans the transcript and proposes events with a title, type, impact, and a source excerpt. Accept the ones that matter — each is deep-linked back to the transcript it came from. See Transcription.

Ask HERC in chat to log something ("record an event: we deprecated the on-prem connector in Q2"). It creates the event conversationally and records the source type as chat. See HERC.

The event lifecycle¶

Events carry a deliberately thin three-state lifecycle — captured, then confirmed, then eventually archived — with no approval gate standing between an author and a recorded event.

stateDiagram-v2
    direction LR
    [*] --> Draft: Create
    Draft --> Confirmed: Confirm
    Draft --> Archived: Archive
    Confirmed --> Archived: Archive
    Archived --> [*]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class Confirmed accent

Figure 2 — The event lifecycle. New events start as Draft (hidden from default lists and the timeline); confirming makes them visible; archiving is a soft-delete that hides the event without losing its history.

Status	Meaning
Draft	Captured but not yet confirmed by an owner.
Confirmed	Reviewed and locked. Visible in default lists and the timeline chart.
Archived	Soft-deleted. Hidden from default lists.

Lightweight by design

Events are knowledge artefacts, not governance artefacts, so the lifecycle stays intentionally light. If your tenant needs a real approval gate on events, configure a workflow definition for the event entity type in /admin/workflows.

Categories and impact¶

Categories classify the event so different audiences see different timelines. A regulatory event carries the Regulatory category and shows up on the Compliance dashboard automatically. An incident has Operational + Technology; a strategy pivot has Strategic.

Events can carry multiple categories. The list view's category column shows the first + a +N badge for the rest; the detail page shows them all.

Impact levels drive the visual weight of the event:

Impact	Colour on timeline	When to use
critical	red	Black swan, major incident, board-level decision.
high	orange	Significant strategy change, contract breach, regulatory enforcement.
medium	yellow	Notable shift, new capability launch.
low	grey	Routine — the kind you'd note in a stand-up.

Linking events to the rest of the platform¶

Events use the same tag system as the catalog and glossary, which means HERC and the DNA graph can connect them automatically:

"What events touched the customers asset this year?" → tag-based search.
"Show Regulatory events from May." → category filter.
The DNA graph picks up event-tag edges, so a tag's neighbourhood includes recent events.

Tags are the bridge

Richer linkage — events wired directly to specific assets, metrics, and contracts — is on the roadmap. For now, shared tags are the connector: tag an event the same way you tag the asset it concerns, and every surface that reasons over tags will draw the line for you.

Stats and the timeline chart¶

The list page's chart is a stacked bar — each bar is one day (or week, depending on range), each stack is one impact level. It tells a story at a glance:

A wall of grey/yellow → routine quarter.
A spike of red on one day → an incident; click to drill into the events.
A cluster of orange around a category → a strategy push.

The KPIs above the chart give the headline counts; the sidebar breaks the period down by category.

Limitations¶

Limit	Why	Workaround
Events don't link directly to assets/metrics/contracts (only via tags).	We're working on first-class linkage.	Use shared tags as the connector.
No approval workflow by default.	Events are lightweight.	Wire one in `/admin/workflows` if your tenant needs it.
AI event-type suggestions need an active provider.	The suggester uses an LLM.	Disable the AI suggestion or configure a provider.
Stats roll up at list-load time.	Cheap, no background job.	For very large tenants this can be slow — paginate by date range.
Archive is soft-delete; permanent delete is admin-only via the database.	Events are knowledge — irreversible delete by default would lose history.	Archive widely; admin can purge a specific row if legally required.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who recorded this event?"	Detail page → audit metadata.
"Show me every regulatory event in 2026."	List → filter by category Regulatory + date range.
"Did anything change about this event after the fact?"	`/admin/audit-log` filtered by `events` + entity ID.
"Where did this event come from?"	Detail → source type field (manual / transcription / chat). Transcript-sourced events deep-link to the transcript.
"Can users delete events to hide a decision?"	Archive only. Permanent delete is admin-supervised at the DB layer.

Troubleshooting¶

Symptom	Likely cause	Fix
AI type suggestion never shows	Provider key missing or rate-limited.	`/admin/integrations` → AI Provider Keys.
Tag picker is empty	Catalog tags not seeded.	Admin → `/admin/system-tables` → Tags.
Category picker missing a category	Not seeded (or an admin deleted it).	Admin → `/admin/system-tables` → Event Categories.
Timeline chart looks empty for a date range with known events	Events are in draft — drafts are excluded from the default chart.	Confirm the events, or change the chart filter to all statuses.
Promoted-from-transcript event missing context	Transcript was thin in that section.	Add description manually; link to the transcript via the source field.
Category column shows raw IDs	Display molecule got the wrong shape.	Refresh; if persistent, file a ticket — categories should always render the resolved name.