Controlled Reference Data
Epic summary
The Controlled Reference Data workspace maintains the stable values used by setup and operational modules.
It replaces the legacy generic Category, Location, and Occupation masters with explicitly owned code sets. Every set has a purpose, owner, scope, extension policy, and usage contract. A user cannot create an arbitrary category merely because a dropdown needs another value.
Examples include organisation types, relationship types, facility types, academic group types, programme families, document types, and mapping dictionaries for external source codes.
Before you start
The platform must identify the business owner for the reference set. For an external mapping, the source system and its code format must also be known. Because many screens use reference values, the system always shows where a value is already being used before it is changed or retired.
Actors and access
| Access source | Access in this epic |
|---|---|
| Platform Admin | Maintains platform-wide technical and product-owned code sets |
| Business Catalogue Owner role | Maintains values for an assigned business domain |
| Tenant Admin | Maintains permitted tenant extensions and local aliases |
| Integration Administrator role | Maintains external-code mappings without changing canonical meaning |
| Auditor role | Reviews purpose, ownership, mappings, versions, and usage |
Screen structure and data captured
The workspace contains Code Sets, Values, Extension Policy, Aliases and Translations, External Mappings, Usage, and History.
Code-set fields
| Field | Required | Meaning and validation |
|---|---|---|
| Set code/name | Yes | Stable identity and readable name |
| Business purpose | Yes | Explains exactly where and why the set is used |
| Owning domain/module | Yes | Accountable owner for meaning and lifecycle |
| Scope | Yes | Platform or tenant |
| Extension policy | Yes | Closed, tenant alias only, tenant extension with approval, or open local set |
| Value schema | Yes | Required attributes and allowed hierarchy/mapping behaviour |
| Effective dates/status | Yes | Set validity and publication state |
Value fields
| Field | Meaning |
|---|---|
| Stable code | Immutable machine identity within the set |
| Display name | User-facing label with language support |
| Parent value | Optional classification hierarchy within the set |
| Sort order | Display order only; not business precedence unless explicitly defined |
| Effective dates | Selection validity |
| Tenant scope | Present only for permitted local values or aliases |
| Mapping | Source system, source code, canonical target, and mapping validity |
Use case 1: Create or revise a governed code set
As a user with Business Catalogue Owner role
I want to define a reference set with an explicit contract
So that applications use consistent values and ownership.
Acceptance criteria
- The set records purpose, owner, scope, extension policy, schema, and consumers.
- Code-set creation requires platform review because it becomes a shared contract.
- A schema change previews affected values and consumers.
- A generic “miscellaneous category” set is rejected.
Use case 2: Add or retire a reference value
As a user with Business Catalogue Owner role
I want to publish a new value or retire an obsolete value
So that users see current choices without losing historical meaning.
Acceptance criteria
- Stable codes are unique and cannot be reused after retirement.
- Effective dates determine when a value is selectable.
- Retirement shows current setup and operational usage.
- Referenced values are archived for new selection but remain resolvable historically.
- Renaming a label does not change the code.
Use case 3: Create a tenant extension or alias
As a tenant member with Governance Registrar role
I want to add an allowed local value or familiar label
So that local operations are represented without creating a separate copy of the platform-wide set.
Acceptance criteria
- The parent set’s extension policy permits the requested action.
- A local alias points to the canonical value and does not create a new meaning.
- A local extension records tenant scope, purpose, approval, and interoperability mapping.
- Tenant values cannot appear in another tenant.
Use case 4: Map an external source code
As a user with Integration Administrator role
I want to map an authority or legacy-system code to a canonical value
So that imports are repeatable and do not create duplicate values.
Acceptance criteria
- Mapping includes source system, code, target value, validity, and confidence/review state.
- One active source code resolves to one target in a mapping context.
- Unknown codes enter an exception queue rather than silently creating values.
- Mapping changes are versioned and reprocessing requires an explicit import action.
Business rules
- Every code set has an owner and documented consumer contract.
- Display text can change; stable codes and historical resolution cannot.
- Tenant extensions are allowed only by policy and remain tenant-isolated.
- Reference hierarchies are classification trees, not organisation/access LTREEs.
- Occupation, reservation category, and similar data belong to the domain that understands and governs their meaning.
- Deactivation never rewrites values stored on historical records.
Technical design
Conceptual schema
| Record | Important fields |
|---|---|
catalog.code_set | code, name, purpose, owning_domain, scope, extension_policy, value_schema_version, validity, status |
catalog.code_value | set, stable code, display name, parent value, sort order, validity, status |
catalog.code_value_translation | value, language, display name, description |
catalog.tenant_code_alias | tenant, canonical value, local code/name, validity |
catalog.tenant_code_extension | tenant, set, code/name, interoperability parent/mapping, approval, validity |
integration.code_mapping | source system/context/code, target set/value, validity, review state |
catalog.code_value_usage | derived consumer type/id, value, last observed, active-reference count |
Process-layer responsibilities
- Validate code uniqueness, hierarchy cycles, extension policy, and effective intervals.
- Resolve the user-facing label by tenant, language, and date while returning the canonical code.
- Resolve import codes by source context and place unknown/ambiguous values in an exception queue.
- Calculate usage and impact before retirement, merge, or schema revision.
- Cache published sets by version and invalidate consumers through events.
Success outcome
Shared dropdowns and classifications remain consistent, traceable, interoperable, and locally usable without becoming an uncontrolled dumping ground.