Reference Data

Overview

Reference Data provides centrally managed lookup/reference tables used across PCSIR modules to
classify and standardize values such as units of measurement, country/province names, committee
statuses, categories, and other lookup lists. Reference entries are typically stable or change rarely, and
consist of a unique identifier (code/ID), a display name, optional description, display order, and optional
hierarchy (parent). The Reference Data module exposes dedicated interfaces per reference list, supports
import/export and bulk maintenance, enforces uniqueness and hierarchical integrity, and supplies valid
values for dropdowns and filters across the application. Only authorized users can create, edit, disable or
import reference values; general users see reference values but cannot modify them. All changes are
versioned and audited to preserve traceability and data integrity.

1. Use Case ID: DTMC-DRD-01

Use Case: Dynamic Reports & Dashboard
1.1 Primary Actor

 System Administrator
 Reference Data Manager
 Master Data Admin

1.2 Pre-Conditions:

 The user logs into the system with appropriate permissions to manage reference data.
 Reference table metadata (list of reference list names and module scope) is configured in system
settings.
 Database connectivity and schema for reference tables are available and writable.
 Audit logging, versioning, and background job services (for import/export) are operational.
 Role-based access control definitions are in place so only authorized roles can modify reference
data.

1.3 Post-Conditions:

 Reference data additions/edits/disables are persisted, versioned, and recorded in the audit trail.
 Dependent dropdowns and lookups reflect updated reference values after cache refresh.
 Disabled or deprecated reference values are excluded from active lookups but retained in history.
 Import/export jobs complete with success/failure logs and user notification.
 If deletion is prevented due to dependencies, the system provides an explanatory message and
action guidance.

1.4 Main Success Scenario

1. The user logs into the system with appropriate permissions.

2. The user navigates to the Reference Data Management module.
3. The system displays the Reference Data List screen showing registered reference tables and the
selected table’s entries.
4. The user selects a reference table or clicks Add New to create a new reference entry.
5. The system displays the Reference Data Create/Edit screen with fields for Code/ID,
 6. Display Name, Description, Display Order, Parent Reference, Module/Scope, Status, Effective
From, Effective To, Default Flag, and Aliases.
7. The user provides required values and optional metadata, sets parent or order if applicable, and
clicks Save.
8. The system validates required fields, uniqueness of Code/ID within the table, and hierarchy (no
cycles), then persists the new/updated entry and creates a new version.
9. The system logs the change in the audit trail and refreshes the list view to show the updated entry.
10. If the user uploads an import file, the system validates file format, previews conflicts, queues the
import job, performs validation and import, and notifies the user on completion with an import
report.
11. If the user attempts to delete or disable an entry in use, the system detects dependencies and
either prevents deletion with an explanatory message or marks the entry Inactive (soft delete)
after confirmation.
12. The system displays a confirmation prompt indicating successful submission.

1.5 Business Rules with Alternative Paths

Business Rule / Alternative Path & System
Field Label Field Type Mandatory
Comments Response
User must enter a unique
If duplicate name entered, system
Reference system name for the
Text Input Yes displays validation error and
Table Name reference table; used
prevents save.
internally to map lookups.
If non-unique or invalid format,
Reference Must be alphanumeric and
Text Input Yes system prompts error and requests
Code / ID unique within the table.
correction.
User-facing label; supports If left blank, system displays
Display Name Text Input Yes localization; displayed in required field warning and prevents
dropdowns. save.
Optional detailed
If left empty, field remains blank
Description Text Area No description; shown as
without affecting processing.
tooltip or help text.
Controls sorting of list
Number If left empty, system defaults to
Display Order No items; lower numbers
Input alphabetical ordering.
appear first.
Allows linking an entry as a
Parent If no parent selected, entry is
Lookup No child of another entry in the
Reference treated as a top-level item.
same table.
Specifies the module(s) If not selected, system prompts user
Module /
Dropdown Yes where the reference list will to choose at least one module
Scope
be available. before saving.
Defines availability: If set to Inactive/Deprecated, entry
Status Dropdown Yes Active, Inactive, or is hidden from standard user
Deprecated. lookups.
If left empty, value becomes
Effective Sets start date of value
Date Picker No effective immediately upon
From validity.
creation.
Sets end date of value If left empty, value remains valid
Effective To Date Picker No
validity. indefinitely.
 Business Rule / Alternative Path & System
Field Label Field Type Mandatory
Comments Response
If checked for multiple entries,
Default Value Allows setting a single
Checkbox No system prompts error and prevents
Flag default entry per table.
save.
Alias / Allows entering comma-
If left empty, system uses only the
Alternate Text List No separated or multi-line
primary Reference Code.
Codes alternate identifiers.
Allows language-specific If missing for a language, system
Localization Structured
No display names keyed by falls back to the primary display
Labels Input
language codes. name.
Supports uploading
If file has invalid or duplicate data,
CSV/Excel to bulk
Import File File Upload No system highlights errors for
create/update entries with
correction before import.
validation.
Allows exporting current If export is large, system queues the
Action
Export Button No reference list to CSV or export and notifies user when
Button
Excel. ready.
Display Auto-populated with
Created By Yes Read-only; no alternative path.
Field creator’s system user ID.
Auto-populated with
Display
Created On Yes system timestamp at Read-only; no alternative path.
Field
creation.
Auto-populated with user
Last Updated Display
Yes who last modified the Read-only; no alternative path.
By Field
record.
Last Updated Display Auto-populated with last
Yes Read-only; no alternative path.
On Field modification timestamp.
Auto-generated version
Display
Version Yes number incremented with Read-only; no alternative path.
Field
each change.
Opens complete change
Audit Trail Link / If user lacks permission, system
No history for the record
Link Action hides the link.
(visible to admins).
If valid, shows “Record saved
Validates and stores the
Action successfully” and updates list; if
Save No entered data in the
Button invalid, displays error and stays on
database.
screen.
Discards unsaved changes Prompts “Discard changes?” If Yes,
Action
Cancel No and returns to previous returns without saving; if No, stays
Button
screen. on current screen.
1.6 Mockup
1.7 Field-Level Specification + Buttons, Links, and Icons
Label / Default /
Type Mandatory Data Type Value Set / Action Comments
Element Function
System-
Free text; pick Unique system
assigned
Reference from system list name; used in
Text Input Yes String (50) internal id;
Table Name when creating configuration to
displayed as
table metadata map lookups.
table title
Free text or pattern Short identifier
Reference (alphanumeric); No default; user used internally
Text Input Yes String (20)
Code / ID must be unique must provide and in data
within table relationships.
User-facing label
Display Free text; localized No default;
Text Input Yes String (200) shown in
Name labels supported required
dropdowns.
Shown as tooltip
Description Text Area No Text (500) Free text Default = empty or detail for
clarity.
Numeric order;
Display Number Default = null Lower number
No Integer system uses this to
Order Input (alphabetical) appears first.
order list
Supports
Select existing
Parent hierarchical lists
Lookup No String / ID reference entry in Default = none
Reference (e.g., provinces
same table
under country).
Default =
Select system Required to limit
Module / selected module
Dropdown Yes String module(s) where where list is
Scope during table
values are used available.
creation
Only Active
Active, Inactive, Default = values shown in
Status Dropdown Yes Enum
Deprecated Active standard
lookups.
Effective Date Controls start of
No Date Calendar selector Default = none
From Picker validity.
Date Controls end of
Effective To No Date Calendar selector Default = none
Picker validity.
Only one entry
Default Single-select per
Checkbox No Boolean Default = false per table can be
Value Flag table
default.
Alias / Comma-separated
Useful for legacy
Alternate Text List No String[] or multi-row Default = empty
mappings.
Codes aliases
Fallback to
Default =
Localization Structured JSON / Keyed by language primary
No primary
Labels Input Key-Value code (e.g., en, ur) language if
language label
missing.
Import File File No CSV / Upload and No default Validates codes,
 Label / Default /
Type Mandatory Data Type Value Set / Action Comments
Element Function
duplicates, and
validate; preview
Upload Excel mapping before
conflicts
import.
Export Action Export current list Large exports
No Action Default = CSV
Button Button as CSV/Excel queued.
Display Read-only;
Created By Yes String System populated System user
Field shows creator.
Display System
Created On Yes Timestamp System populated Read-only.
Field timestamp
Last Updated Display
Yes String System populated System user Read-only.
By Field
Last Updated Display System
Yes Timestamp System populated Read-only.
On Field timestamp
Display Integer / System-generated Default = 1 on Incremented on
Version Yes
Field String version number create each change.
Shows change
Default =
Audit Trail Link / Opens audit log for history, user,
No Action visible to
Link Action the entry timestamp,
admins
old/new values.
Displays
On click, validates
Enabled when confirmation
Action all mandatory
Save No Action mandatory message upon
Button fields and saves
fields are valid success; error if
record to database
validation fails
On click, prompts Returns to Prevents loss of
Action
Cancel No Action user to confirm previous screen data without
Button
discarding changes if confirmed warning