Events: the why behind your data¶

The Events module is Datahub's log of organisational events — decisions, strategy changes, market shifts, regulatory changes, incidents, milestones, and the rare "black swan". Each event answers questions a metric trend or a dashboard chart cannot: why did this happen, and what does it mean?

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

When to choose this¶

Reach for Events when you want to:

Annotate a metric trend. "NPS jumped 12 points in May because we shipped the redesigned onboarding." The event lives forever next to the metric.
Record a strategic decision. "In Q2 we decided to deprecate the on-prem connector." Tagged, dated, owned.
Capture a market or regulatory event. "GDPR enforcement update — XYZ on 12 June 2026." Linked to the assets / processes affected.
Promote a transcribed meeting to a structured record. Open the transcript → Extract events → events are auto-suggested → accept the ones that matter.
Build the timeline of a domain. Filter events by domain or category to see "everything that happened in Finance this year".

You do not need Events for:

Audit logs (those live in /admin/audit-log, fed by the platform).
Notifications (push delivery — events are records, not pings).
Tasks (decisions waiting for you — events are decisions already made).

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.

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.

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.

Creating an event¶

The two on-ramps:

Manual. /events → New event. Fill in title, description, event date, type. The platform's AI suggests an event type from your description as you type — accept the suggestion or override. Pick impact, optionally pick categories and tags.
From a transcript. Open /ai/transcription/{id} (a completed session) → Extract events. The AI scans the transcript and proposes events with title, type, impact, and an excerpt. Accept the ones that matter.

Status defaults to draft on creation. The lifecycle is:

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.

The lifecycle is intentionally lightweight — events are knowledge artefacts, not governance artefacts. If your tenant needs an approval flow on events, configure a workflow definition for the entity type (/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 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.

The richer linkage (events directly linked to specific assets / metrics / contracts) is on the roadmap; for now, tags are the bridge.

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.