Validation Evidence
Vorian Connect produces structured validation evidence from live analyzer traffic — enabled rule inventories, message throughput by source, destination delivery status, and per-instrument trace evidence — composited into a single exportable validation summary. Interface engineers use this evidence to document cutover readiness for CAP/CLIA validation requirements.
How It Works
- The validation summary API (
GET /api/validation/summary) aggregates evidence from multiple database-backed sources: enabled rules (lifecycle state, action, priority), message counts by source and verification status, destination status (enabled/disabled counts per delivery mode), and trace evidence (per-source delivery and mapping configuration) - All queries are tenant-scoped with RLS enforcement. The summary supports optional date-range filtering (
fromandtoparameters) and per-instrument filtering (sourceIdparameter) for targeted validation of a single analyzer interface - The export API (
POST /api/validation/export) generates a PHI-safe Markdown document from the summary data, suitable for inclusion in validation binders. The export writes a required audit event before returning evidence — if the audit write fails, the export is blocked to maintain the chain of custody - Source-scoped users see only evidence from instruments they are authorized to access. Requests for unauthorized source IDs return clean permission-denied responses with specific error codes
- The
/validationdashboard page renders the summary in a stat-card layout: enabled rule count, message throughput, destination readiness, and trace evidence coverage. The page supports date range and source filter controls
What's Included
- Rule inventory: A table of every enabled rule with its name, action (auto_verify, flag, reject), priority (high/medium/low), and creation timestamp. This provides a complete catalog of what validation conditions are actively running against each instrument's traffic
- Message throughput: Counts of processed messages by source instrument and verification status (passed, flagged, rejected, pending) for the requested date range. This shows the volume of traffic each rule acted upon
- Destination status: A count of enabled and disabled delivery destinations categorized by mode — webhook, FHIR R4, and HL7 MLLP. This confirms which outbound paths are active and which are held in test configuration
- Trace evidence: Per-source inventory of delivery destinations with their type, hostname, and enabled status, plus test-code mapping counts. This documents the wiring between each instrument and its downstream destinations
- Export format: The Markdown export includes a header with the generating tenant, date range, and source filter, followed by sections for rules, messages, destinations, and trace evidence. Each section is formatted as human-readable tables with timestamps, counts, and status labels
- Audit trail: Every export generates an immutable
validation_exportaudit event recording the initiator, source filter, and date range. The export fails closed — if the audit write cannot be completed, no evidence is returned. The response is a downloadable.mdfile with a filename that includes the date range
Where It Fits
Validation evidence bridges the gap between running analyzer traffic in shadow mode and proving to a lab director that the interface is production-ready. Instead of manually screenshotting dashboards and pasting counts into a Word document, an interface engineer selects a date range and source filter, clicks Export, and receives a timestamped, audited Markdown document that can go directly into the validation binder.
The evidence is PHI-safe by design — message counts and rule summaries never include patient identifiers, raw HL7 payloads, or decrypted PHI. The export is a summary of what the system did, not what it saw. This means the document can be shared with CAP/CLIA inspectors and procurement teams without redaction.
Technical Details (for evaluators)
The validation evidence system is built on two primary API endpoints. The summary endpoint (GET /api/validation/summary) accepts sourceId, from, and to query parameters and returns a JSON structure with rules (enabled rule list with names, actions, priorities, and timestamps), messages (source-by-source counts with status breakdowns), destinations (counts by mode and enabled/disabled status), and traces (per-source delivery destinations with hostnames, types, and mapping counts). The summary requires validation:view permission.
The export endpoint (POST /api/validation/export) accepts the same filter parameters as a JSON body, generates the summary, renders it to markdown via a dedicated renderer (renderValidationEvidenceMarkdown), writes a validation_export audit event using logRequiredAdminAction (failing closed with a 503 if the audit write fails), and returns the markdown as a downloadable attachment. The markdown renderer formats all values as plain text — no raw HL7, no patient identifiers, no encrypted PHI blobs.
Date parameters must be valid ISO timestamps with from before to, and sourceId must be a valid UUID when provided. Invalid parameters return clean 400 errors with operator-readable messages. Source-scope denials return structured error responses with the missing permission scope.