Appearance
Business Reference Conventions
Every governed entity in OrviQ has two identities, and they are never confused.
The two-identity model
| Internal identifier | Business reference | |
|---|---|---|
| Purpose | Technical primary key | Human-facing identity |
| Shape | Opaque, system-generated | PREFIX-YYYY-NNNN |
| Used by | Relationships, links, API routes, query parameters | Displays, lists, drawers, registers, audit views, exports |
| Shown to users | Never | Everywhere |
| Changes | Never | Never |
Human-facing references never expose internal identifiers
No register, drawer, export, notification, calendar entry or deep link presents a raw internal identifier to a user.
Deep links resolve business references directly: opening INC-2026-0014 works on first load, on refresh, and from Workbench tasks and notifications, with no technical key leaking into the address.
Format
PREFIX-YYYY-NNNN
| Element | Meaning |
|---|---|
PREFIX | The entity type |
YYYY | The year of creation |
NNNN | A strictly sequential number within the tenant, entity type and year |
Properties:
- Tenant-scoped — two tenants both have a
CTL-2026-0001, and they are different controls - Entity-type-scoped — a control and a risk both created first in 2026 are
CTL-2026-0001andRSK-2026-0001 - Year-scoped — sequences restart each year
- Immutable — assigned once at creation, never regenerated or reassigned
- Never derived from a UUID
- Never contains department, owner, or any other mutable organisational attribute
The prefix registry
| Entity | Prefix | Example |
|---|---|---|
| Third Party | TP | TP-2026-0018 |
| Engagement | ENG | ENG-2026-0041 |
| Risk | RSK | RSK-2026-0014 |
| Finding | FND | FND-2026-0071 |
| Action Plan | ACT | ACT-2026-0188 |
| Assessment | ASM | ASM-2026-0004 |
| Control | CTL | CTL-2026-0041 |
| Audit Engagement | AUD | AUD-2026-0003 |
| Policy | POL | POL-2026-0009 |
| Asset | AST | AST-2026-0001 |
| Scope | SCP | SCP-2026-0007 |
| Mapping | MAP | MAP-2026-0233 |
| Connection | CON | CON-2026-0001 |
| Collector | COL | COL-2026-0003 |
| Collector Run | CRN | CRN-2026-1841 |
| Evidence Assertion | ASN | ASN-2026-0442 |
| Indicator Definition | IND | IND-2026-0009 |
| Indicator Result | INR | INR-2026-8813 |
| Exception | EXC | EXC-2026-0031 |
| Requirement Assessment | RAS | RAS-2026-0117 |
| Regulatory Inspection | INS | INS-2026-0002 |
| Business Impact Analysis | BIA | BIA-2026-0003 |
| Continuity Plan | BCP | BCP-2026-0004 |
| Resilience Exercise | EXE | EXE-2026-0009 |
| Resilience Assessment | RES | RES-2026-0005 |
| Incident | INC | INC-2026-0014 |
| Framework Adoption | FAD | FAD-2026-0004 |
| Applicability Record | APP | APP-2026-0117 |
Generation guarantees
Sequence generation is centralised. Every module calls the same service rather than maintaining its own counter.
| Guarantee | How |
|---|---|
| No duplicates | An atomic increment on a shared counter, guarded by a database advisory lock keyed on tenant, entity type and year |
| Race-free across processes | The advisory lock serialises writers across connections and processes |
| No scanning | Never a SELECT MAX(id)+1, which is race-prone without an explicit lock |
| Per-tenant uniqueness | Backed by a partial unique index on tenant and business reference |
| Immutable | Persisted once at creation |
Why this matters more than it sounds
A reference scheme that occasionally issues duplicates, or that renumbers records, destroys the ability to cite a record in a board minute, a regulatory response or an audit workpaper.
Every reference in this documentation's worked examples is the shape a real one takes, and every real one is stable for the life of the record.
Sequences after a backfill
Where an existing module is brought onto the standard, historical records are backfilled deterministically:
- Ordered by tenant, creation time ascending, with the internal identifier as a tiebreaker
- One sequence per tenant and year-of-creation, so a historical record receives the reference its actual creation year would have assigned
- The live counter is primed to continue immediately after the highest backfilled number
Backfills are idempotent and safe to rerun.
Reading a reference
EXC-2026-0031 tells you:
- It is an exception
- It was created in 2026
- It was the 31st exception created in this tenant that year
It tells you nothing about who owns it, which department raised it, or what it relates to — deliberately. Those are mutable attributes and belong in fields, not in an identifier that must never change.