feat(compliance): implement FRS S-01 Compliance Standards Administration by mherman22 · Pull Request #3500 · DIGI-UW/OpenELIS-Global-2

mherman22 · 2026-04-26T19:30:19Z

Pull Requests Requirements

The PR title includes a brief description of the work done, including the
Issue number if applicable.
The PR includes a video showing the changes for the work done.
The PR title follows conventional commit label standards.
The changes confirm to the OpenElis Global x3
Styleguide and Design
documentation.
The changes include tests or are validated by existing tests.
I have read and agree to the Contributing Guidelines of this project.

Summary

Implements FRS S-01 Compliance Standards Administration — a configurable regulatory-standards framework so non-clinical test results can be evaluated against externally published thresholds (Indonesia's PP No. 22/2021 / Baku Mutu, WHO drinking-water guidelines, etc.).

This PR is scoped to S-01 only (admin / data model / seed loader). The S-05 Compliance Evaluation Engine is a separate FRS and is not in this PR.

Two admin surfaces:

Compliance Standards admin (/MasterListsPage/ComplianceStandardsAdmin) — list / search / filter / archive / copy standards; manage parameter groups + linked tests inline.
Per-test compliance thresholds (Tab 2 of the same screen, plus embedded as a tab inside Modify Test per FR-3-001) — overview of tests that already have linked thresholds, drill-in editor with multi-limit numeric form (HIGH / LOW / RANGE / BORDERLINE / DESCRIPTIVE) or value-mapping table for select-list tests.

Data model

Four JPA entities form the standard → group → threshold → option-mapping hierarchy. All persist via Liquibase changesets 018 → 027 (no XML mappings, ORM annotations on the value holders).

`compliance_standard`

The top-level regulation. Natural key is (name, regulation_number, version).

Column	Type	Notes
`id`	INTEGER PK	Sequence-generated, surfaced as String to JPA
`fhir_uuid`	UUID, unique, NOT NULL	FHIR R4 reference
`name`, `display_name`	VARCHAR(500) / 500	name NOT NULL
`issuing_body`	VARCHAR(255), NOT NULL	E.g. "Indonesian Government"
`regulation_number`	VARCHAR(100), NOT NULL	E.g. "PP No. 22 Tahun 2021"
`version`	VARCHAR(50)	Suffixed `" - Copy"` on copy-clone
`effective_date`, `expiry_date`	DATE
`country_region`	VARCHAR(100)	Drives FR-1-007 typeahead
`status`	enum `DRAFT/ACTIVE/SUPERSEDED/ARCHIVED`	CHECK constraint, default DRAFT
`superseded_by_id`	INTEGER (FK self)	ON DELETE SET NULL; required when status=SUPERSEDED
`description`, `regulatory_context`	TEXT
`enforcement_authority`	VARCHAR(255)
`is_pre_seeded`	BOOLEAN, NOT NULL	Set by seed loader; blocks UI delete
Audit columns	`created_date`, `created_by`, `archived`, `archived_date`, `sys_user_id`, `last_updated`

Plus a compliance_standard_sample_type join table (FR-1-007a sample-type set).

`parameter_group`

Logical grouping of parameters within a standard. Per-standard uniqueness on (standard_id, name).

Column	Type	Notes
`id`	INTEGER PK
`standard_id`	INTEGER (FK → compliance_standard)	ON DELETE CASCADE
`name`, `description`, `sort_order`, `is_mandatory`		UI accordion order is `sort_order`

`compliance_threshold`

The actual numeric/categorical constraint. Per-(group, parameter, type) uniqueness so multi-limit saves (HIGH + BORDERLINE on the same parameter) don't collide.

Column	Type	Notes
`id`	INTEGER PK
`group_id`	INTEGER FK → parameter_group	NOT NULL, ON DELETE CASCADE
`test_id`	VARCHAR(100) FK → test (nullable)	When null, threshold is template-level
`parameter_code`, `display_name`	VARCHAR(255)	NOT NULL
`threshold_type`	enum `MINIMUM/MAXIMUM/RANGE/BORDERLINE/EXACT/DESCRIPTIVE/SELECT_MAP`	CHECK constraint
`min_value`, `max_value`, `target_value`	DECIMAL(15,6)	Type-specific (RANGE/BORDERLINE require both min+max)
`value_descriptive`	VARCHAR(1024)	DESCRIPTIVE thresholds only
`units`, `method_reference`	VARCHAR(255)
`detection_limit`	DECIMAL(15,6)
`is_mandatory`, `is_active`, `sort_order`		`is_active` is the FR-3-010 archive flag
`validation_rules`, `notes`	TEXT
Composite unique: `(test_id, group_id, threshold_type)`		Migration 027-4

`compliance_threshold_value_map`

Maps select-list result options to a ComplianceStatus. Required for FR-3-013 / FR-3-014.

Column	Type	Notes
`id`	INTEGER PK
`threshold_id`	INTEGER FK → compliance_threshold	ON DELETE CASCADE; cascade=ALL on parent
`option_value`	VARCHAR(255)	E.g. "Positive", "Negative"
`compliance_status`	enum `COMPLIANT/BORDERLINE/NON_COMPLIANT`

Liquibase migrations

File	Purpose
`018-compliance-standards-complete-feature.xml`	Sequences, core tables, FKs, indexes, check constraints, comments
`019-compliance-threshold-add-descriptive.xml`	Adds `DESCRIPTIVE` to threshold-type CHECK
`020-compliance-threshold-add-select-map.xml`	Adds `SELECT_MAP` to threshold-type CHECK
`023-compliance-threshold-test-fk.xml`	Promotes `test_id` from String → real FK
`024-compliance-standard-sample-types.xml`	Element-collection join table
`025-compliance-rename-lastupdated-column.xml`	`lastupdated` → `last_updated` to match BaseObject mapping
`026-compliance-threshold-value-map.xml`	Value-map table
`027-compliance-frs-data-model-alignment.xml`	FRS Section 5 alignment: column lengths, natural key `(name, regulationNumber, version)`, `is_active` on threshold, `(test_id, group_id, threshold_type)` uniqueness. Drop/add steps split + guarded by `<sqlCheck>` against `information_schema.table_constraints` so reruns on partly-migrated DBs are no-ops.

REST API

All endpoints under /rest/compliance/... and /rest/tests/{testId}/compliance-thresholds. View endpoints accept any authenticated lab role; mutations are GLOBAL_ADMIN-only.

# Standards
GET    /rest/compliance/standards            paginated list with parameterGroupCount
GET    /rest/compliance/standards/active     ACTIVE-only (drives S-02 dropdown when wired)
GET    /rest/compliance/standards/search     ?name&issuingBody&regulationNumber&status&countryRegion&sampleType
GET    /rest/compliance/standards/{id}
POST   /rest/compliance/standards
PUT    /rest/compliance/standards/{id}
DELETE /rest/compliance/standards/{id}       blocked when has thresholds OR pre-seeded
POST   /rest/compliance/standards/{id}/archive
POST   /rest/compliance/standards/{id}/copy   FR-7-004 deep clone → new DRAFT
GET    /rest/compliance/standards/{id}/parameter-groups
POST   /rest/compliance/standards/{id}/parameter-groups
PUT    /rest/compliance/standards/{id}/parameter-groups/{groupId}
DELETE /rest/compliance/standards/{id}/parameter-groups/{groupId}    blocked when has thresholds (BR-003)
GET    /rest/compliance/standards/{id}/linked-tests
GET    /rest/compliance/standards/country-regions

# Thresholds (group-scoped)
GET    /rest/compliance/thresholds?groupId=...
GET    /rest/compliance/thresholds/summary    Tab 2 overview: testId / count / standardCount
GET    /rest/compliance/thresholds/{id}
POST   /rest/compliance/thresholds
PUT    /rest/compliance/thresholds/{id}
DELETE /rest/compliance/thresholds/{id}

# Thresholds (test-scoped)
GET    /rest/tests/{testId}/compliance-thresholds
POST   /rest/tests/{testId}/compliance-thresholds
DELETE /rest/tests/{testId}/compliance-thresholds/{thresholdId}
GET    /rest/tests/{testId}/compliance-thresholds/standard/{standardId}

# Catalog (compliance UI helpers)
GET    /rest/compliance/test-catalog                   active tests + sample-types + result type + select options
GET    /rest/compliance/test-catalog/with-compliance   same + thresholdCount/standardCount
GET    /rest/compliance/sample-type-categories

Slim DTOs (ComplianceThresholdListItem, TestCatalogEntry, etc.) are built inside service-level transactions so the controllers stay thin and Jackson never traverses a lazy graph.

Frontend

frontend/src/components/admin/complianceStandards/:

ComplianceStandardsAdmin.jsx — list page with filters (status / region / sample-type / text), inline-row add+edit, archive flow with destructive modal, Copy Standard action (just landed), View Linked Tests panel, clickable linked-tests count, parameter-group accordion.
StandardForm.jsx — inline editor, ComboBox typeahead for Country/Region, applicable sample-types panel, Description TextArea, Save Standard.
ParameterGroupAccordionItem.jsx — per-group editor with Move Up / Move Down (individual PUTs), threshold child rows.
LinkTestForm.jsx — sample-type chip filters, typeahead capped at 12, excludes already-linked tests.
MultiLimitForm.jsx — single form rendering all 5 numeric limit types as checkable rows.
SelectMapForm.jsx — option × ComplianceStatus matrix with live row tinting + per-row a11y label.
TestComplianceThresholds.jsx — Tab 2: overview table → per-test editor with vertical sidebar, Limit Types Legend, Group-by toggle, superseded warning banner. Also runs in embedded mode (embeddedTestId prop) when mounted inside Modify Test → it suppresses its own header strip and placeholder sidebar so the parent Test Editor owns those affordances.

frontend/src/components/admin/testManagementConfigMenu/TestModifyEntry.jsx — when a test is selected for editing, the editor surface is now wrapped in Carbon Tabs: Tab 1 "Configuration" hosts the existing 7-step TestStepForm wizard (untouched); Tab 2 "Compliance Thresholds" hosts <TestComplianceThresholds embeddedTestId={...} />. Toasts from both tabs flow through the existing NotificationContext + AlertDialog already mounted on the page.

React Intl throughout — no hardcoded user-facing strings.

Seed loader (FR-6)

Four sibling DomainConfigurationHandlers under org.openelisglobal.compliance.service load CSVs from volume/configuration/backend/compliance-standards/ at app startup. Idempotent — each row is upserted by natural key.

File pattern	Handler	Order
`*-standards.csv`	ComplianceStandardConfigurationHandler	200
`*-parameter-groups.csv`	ComplianceParameterGroupConfigurationHandler	210
`*-thresholds.csv`	ComplianceThresholdConfigurationHandler	220
`*-threshold-value-maps.csv`	ComplianceThresholdValueMapConfigurationHandler	230

Ships with the Baku Mutu PP No. 22/2021 default seed. CSV authoring rules in volume/configuration/backend/compliance-standards/README.md.

Hardening done:

RFC 4180 escaped-quote handling in the CSV line parser ("" decodes to literal ").
Header read tolerates leading blank/# comment lines.
ThresholdType.fromImportToken accepts FRS-aliased tokens (HIGH, LOW, MAX, MIN, QUALITATIVE, select-map, etc.) instead of silently dropping rows that don't match the canonical enum constant.
ComplianceStatus.parse accepts NON_COMPLIANT, Non-Compliant, NON-COMPLIANT, etc.
Description column treats empty cell as null so re-imports can clear stale values.
testName column on threshold rows resolves to a real Test via TestService.getTestByName, populating compliance_threshold.test_id so seeded data shows up in the Tests column on the Standards list and inside Modify Test.

FRS Section 12 — Acceptance Criteria

AC	Status
1. View access from Admin → Test Management	✅
2. Create standard with success notification	✅
3. Edit via inline row expansion	✅
4. Add / edit / reorder / remove parameter groups	✅
5. Archive standard, status tag → "Archived"	✅
6. Archived excluded from registration dropdowns	⚠️ Backend ready (`/active`); S-02 caller wiring is cross-module
7. Copy Standard → new Draft with all groups + thresholds	✅ FR-7-004
8. Superseded banner with replacement link	✅ FR-3-011
9. Compliance tab in Test Editor (FR-3-001)	✅ Implemented as a peer Carbon Tab in Modify Test — see "Pragmatic deviations" #4
10. Sample-type chips before linking tests	✅
11. Add/remove sample-type chips above accordion	✅
12. LinkTest filter chips pre-filter typeahead	✅
13. Typeahead excludes already-linked	✅
14. Numeric: 5 limit types as checkable rows	✅
15. Select list: value-mapping table	✅
16. Per-option Compliant/Borderline/Non-Compliant + live row tint	✅
17. Linked tests table: one row per test, badge summary	✅
18. Edit icon expands correct form variant	✅
19. BORDERLINE warm-gray tag	✅ tag rendering; engine-side "doesn't mark non-compliant" is S-05 territory
20. View Linked Tests panel	✅
21. Standard auto-suggest in S-02 registration	❌ Cross-module deferral

Pragmatic deviations from the FRS literal text

FRS-named i18n namespaces. FRS Section 9 lists ~70 keys under label.complianceStandard.*, button.complianceStandard.*. The codebase mostly uses its own compliance.* namespace; the FRS-literal keys (button.complianceStandard.copy) are added where the spec is explicit. Functionally equivalent, doesn't match the literal key strings.
Permission keys. FRS Section 11 specifies compliance.standard.view/.add/.modify/.archive etc. This PR maps onto existing OpenELIS roles (GLOBAL_ADMIN/RECEPTION/RESULTS) — the FRS-named permission keys are deferred until the broader OpenELIS roles/permissions cleanup.
Sidebar tab placeholders are decorative. In Tab 2's vertical sidebar, only the Compliance tab is real; the other FRS-named tabs render disabled with a tooltip.
FR-3-001 sidebar shape. FRS describes a vertical-tab sidebar on the Test Editor with a Compliance section group placed after an Automation group, alongside 13 other named tabs (Basic Info / Sample & Results / Ranges / Sample Storage / Display Order / Panels / Labels / Terminology / Reagents / Analyzers / Methods / Alerts / Reflex & Calc). The existing OpenELIS Test Editor uses a 7-step linear wizard, not a sidebar — none of those FRS-named tabs exist. This PR adds Compliance as a peer horizontal Carbon Tab to the wizard ("Configuration" tab → existing wizard untouched, "Compliance Thresholds" tab → embedded threshold editor), the closest faithful mapping without rebuilding the whole Test Editor surface.

Deferred to follow-up PRs

Item	Why
FR-3-001 vertical-tab sidebar refactor	The 14-tab vertical sidebar described in the FRS (Basic Info / Sample & Results / Ranges / … / Automation / Compliance) is a multi-PR Test Editor refactor outside this branch's scope. The Compliance tab itself ships in this PR as a peer horizontal Tab.
FR-3-001 permission gating (`compliance.threshold.view`)	Tab 2 inside Modify Test is currently visible to anyone who can reach Modify Test (matches the existing Compliance Standards admin route, which is also un-role-gated). Real gating waits on the Section 11 permissions framework cleanup.
FR-4-001 Standard auto-suggest during S-02 registration (AC#21)	Cross-module integration outside compliance scope
S-05 Compliance Evaluation Engine	Separate FRS — would add `ComplianceEvaluation`, `EvaluationResult`, evaluation/bulk/reporting REST + service tier
Runtime CSV upload UI (Section 4.5 / 6)	Backend handlers + REST endpoint will return; the seed-loader pipeline (FR-6) covers the FRS-required import path today
`ComplianceImportLog`	Coupled to runtime CSV upload — returns when upload returns
Permissions framework (Section 11)	OpenELIS roles/permissions model needs broader cleanup before FRS-named keys land
`compliance.seed.directory` config wiring (FR-6-008)	Documentation key exists; the override resolver is deferred

Test plan

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Implements the FRS S-01 Compliance Standards Administration module, including backend domain model + APIs and frontend admin/editor UIs for managing compliance standards, parameter groups, and per-test thresholds (including select-list value mappings).

Changes:

Added compliance domain entities/enums, DAO/service layers, CSV seed/import logging, and operational utilities.
Implemented REST endpoints for standards/thresholds/test-threshold management and supporting DTO wrappers to avoid lazy-graph serialization issues.
Integrated compliance admin UI entry points and embedded per-test “Compliance Thresholds” tab into the Test Editor.

Reviewed changes

Copilot reviewed 75 out of 124 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
src/main/java/org/openelisglobal/compliance/valueholder/ComplianceThresholdValueMap.java	New entity for SELECT_MAP value→status mappings
src/main/java/org/openelisglobal/compliance/valueholder/ComplianceStatus.java	New enum for COMPLIANT/BORDERLINE/NON_COMPLIANT
src/main/java/org/openelisglobal/compliance/valueholder/ComplianceStandardStatus.java	New lifecycle enum for standards
src/main/java/org/openelisglobal/compliance/valueholder/ComplianceImportLog.java	New entity to persist CSV import/seed audit logs
src/main/java/org/openelisglobal/compliance/valueholder/BulkProcessResult.java	Helper model for bulk operation outcomes
src/main/java/org/openelisglobal/compliance/util/ComplianceConstants.java	Centralized constants + export cap config
src/main/java/org/openelisglobal/compliance/service/TestComplianceStandardServiceImpl.java	Service for linking tests↔standards
src/main/java/org/openelisglobal/compliance/service/TestComplianceStandardService.java	Interface for tests↔standards operations
src/main/java/org/openelisglobal/compliance/service/ParameterGroupServiceImpl.java	Parameter group CRUD + delete guard (BR-003)
src/main/java/org/openelisglobal/compliance/service/ParameterGroupService.java	Parameter group service API + bulk count
src/main/java/org/openelisglobal/compliance/service/EvaluationStatusServiceImpl.java	Status transition rules + lifecycle actions
src/main/java/org/openelisglobal/compliance/service/EvaluationStatusService.java	Status lifecycle service interface
src/main/java/org/openelisglobal/compliance/service/EvaluationServiceImpl.java	Core evaluation logic + manual review flags
src/main/java/org/openelisglobal/compliance/service/EvaluationService.java	Core evaluation service interface
src/main/java/org/openelisglobal/compliance/service/EvaluationResultServiceImpl.java	Result CRUD + validation + recalc support
src/main/java/org/openelisglobal/compliance/service/EvaluationResultService.java	Result service API
src/main/java/org/openelisglobal/compliance/service/ComplianceThresholdValueMapConfigurationHandler.java	CSV seed loader for SELECT_MAP mappings
src/main/java/org/openelisglobal/compliance/service/ComplianceThresholdServiceImpl.java	Threshold CRUD, validation, uniqueness, mapping sysUser propagation
src/main/java/org/openelisglobal/compliance/service/ComplianceThresholdService.java	Threshold service API
src/main/java/org/openelisglobal/compliance/service/ComplianceStandardService.java	Standards service API (search, lifecycle, copy, FHIR hooks)
src/main/java/org/openelisglobal/compliance/service/ComplianceReportingService.java	Reporting service interface for compliance reports/exports
src/main/java/org/openelisglobal/compliance/service/ComplianceParameterGroupConfigurationHandler.java	CSV seed loader for parameter groups
src/main/java/org/openelisglobal/compliance/service/ComplianceMessages.java	Centralized i18n-backed error messages
src/main/java/org/openelisglobal/compliance/service/ComplianceImportLogServiceImpl.java	Service to record/retrieve import logs
src/main/java/org/openelisglobal/compliance/service/ComplianceImportLogService.java	Import log service API
src/main/java/org/openelisglobal/compliance/service/ComplianceEvaluationService.java	Compliance evaluation service API (broad)
src/main/java/org/openelisglobal/compliance/service/ComplianceCsvUtil.java	Shared CSV parsing helpers
src/main/java/org/openelisglobal/compliance/service/CSVImportService.java	CSV import service interface (upload path)
src/main/java/org/openelisglobal/compliance/service/BulkEvaluationServiceImpl.java	Batch/bulk evaluation operations
src/main/java/org/openelisglobal/compliance/service/BulkEvaluationService.java	Bulk evaluation service API
src/main/java/org/openelisglobal/compliance/form/ComplianceStandardConfigMenuForm.java	MVC form for (legacy) compliance standard config menu
src/main/java/org/openelisglobal/compliance/daoimpl/TestComplianceStandardDAOImpl.java	DAO queries for tests↔standards associations
src/main/java/org/openelisglobal/compliance/daoimpl/ParameterGroupDAOImpl.java	DAO for groups + reorder + bulk counts
src/main/java/org/openelisglobal/compliance/daoimpl/EvaluationResultDAOImpl.java	DAO queries for evaluation results
src/main/java/org/openelisglobal/compliance/daoimpl/ComplianceThresholdDAOImpl.java	DAO queries for thresholds + summary aggregates
src/main/java/org/openelisglobal/compliance/daoimpl/ComplianceImportLogDAOImpl.java	DAO for import log listing
src/main/java/org/openelisglobal/compliance/dao/TestComplianceStandardDAO.java	DAO interface for tests↔standards data access
src/main/java/org/openelisglobal/compliance/dao/ParameterGroupDAO.java	DAO interface for parameter groups
src/main/java/org/openelisglobal/compliance/dao/EvaluationResultDAO.java	DAO interface for evaluation results
src/main/java/org/openelisglobal/compliance/dao/ComplianceThresholdDAO.java	DAO interface for thresholds
src/main/java/org/openelisglobal/compliance/dao/ComplianceStandardDAO.java	DAO interface for standards
src/main/java/org/openelisglobal/compliance/dao/ComplianceImportLogDAO.java	DAO interface for import logs
src/main/java/org/openelisglobal/compliance/dao/ComplianceEvaluationDAO.java	DAO interface for evaluations + bulk save/update
src/main/java/org/openelisglobal/compliance/controller/rest/TestComplianceThresholdRestController.java	Test-scoped threshold CRUD endpoints
src/main/java/org/openelisglobal/compliance/controller/rest/ParameterGroupListItem.java	DTO wrapper for parameter groups list
src/main/java/org/openelisglobal/compliance/controller/rest/ComplianceThresholdRestController.java	Group-scoped threshold CRUD + test summary endpoint
src/main/java/org/openelisglobal/compliance/controller/rest/ComplianceThresholdListItem.java	Slim DTO for threshold responses incl. flattened group/standard
src/main/java/org/openelisglobal/compliance/controller/rest/ComplianceTestCatalogRestController.java	Compliance-oriented test catalog endpoint (+ select options + counts)
src/main/java/org/openelisglobal/compliance/controller/rest/ComplianceStandardListItem.java	Standards list wrapper adding parameterGroupCount
src/main/java/org/openelisglobal/compliance/controller/rest/ComplianceReportingController.java	REST endpoints for compliance reporting/export
src/main/java/org/openelisglobal/compliance/controller/ComplianceStandardConfigMenuController.java	MVC controller for (legacy) compliance config menu
frontend/src/components/admin/testManagementConfigMenu/TestModifyEntry.jsx	Adds Compliance Thresholds tab into Test Editor
frontend/src/components/admin/testManagementConfigMenu/TestManagementConfigMenu.jsx	Adds admin tile linking to ComplianceStandardsAdmin
frontend/src/components/admin/complianceStandards/SelectMapForm.jsx	UI to map select-list options → compliance status
frontend/src/components/admin/Admin.jsx	Wires ComplianceStandardsAdmin route into Admin app

Copilot

Pull request overview

Copilot reviewed 74 out of 124 changed files in this pull request and generated 8 comments.

Copilot

Pull request overview

Copilot reviewed 65 out of 65 changed files in this pull request and generated 6 comments.

Copilot