205 lines
8.8 KiB
Markdown
205 lines
8.8 KiB
Markdown
```markdown
|
|
# VigilCare Records — Digitization Workstation Guide
|
|
|
|
## Overview
|
|
|
|
This guide describes three primary clinical workflows supported by the VigilCare
|
|
Records digitization platform: historical backfill, live bedside capture, and
|
|
corrections. Each workflow maps to a real operational scenario in a paper-based
|
|
hospital or clinic.
|
|
|
|
---
|
|
|
|
## Workflow 1: Historical Backfill (Track A)
|
|
|
|
**Scenario:** District General Hospital has 200 active patients with paper charts.
|
|
The facility is deploying VigilCareClinical for real-time alerting. Before alerts
|
|
can fire, historical vital signs and lab results must be digitized into the system.
|
|
|
|
**Actors:** Intake Clerk, Data Entry Clerk, Verifier, Clinical Approver (for
|
|
high-stakes batch types)
|
|
|
|
**Steps:**
|
|
|
|
### 1. Intake (Intake Clerk)
|
|
|
|
The intake clerk receives a stack of patient charts from the ward. For each chart
|
|
section:
|
|
|
|
1. Scan the page(s) using a flatbed scanner or document camera
|
|
2. Log in to the workstation as `intake1`
|
|
3. Navigate to **Intake** view
|
|
4. Upload the scan (PDF, JPEG, or PNG; max 25 MB)
|
|
5. Select the batch type:
|
|
- **Vitals Sheet** — vital signs from nursing observation charts
|
|
- **Lab Results** — laboratory test result reports
|
|
- **Patient Registration** — face sheet with demographics
|
|
- **Encounter Summary** — admission/discharge summaries
|
|
- **Allergy Update** — allergy documentation
|
|
- **Medication List** — current medication records
|
|
6. Set track to **Backfill** (default)
|
|
7. Optionally link to an existing patient by searching MRN or name
|
|
8. Click **Upload and Create Batch**
|
|
|
|
The batch is created in `uploaded` status. The SHA-256 hash prevents duplicate
|
|
uploads of the same document for the same patient within 24 hours.
|
|
|
|
### 2. Data Entry (Data Entry Clerk)
|
|
|
|
The entry clerk opens the batch from their **Entry** queue:
|
|
|
|
1. Log in as `entry1`
|
|
2. Click the batch to open the split-pane workstation
|
|
3. **Left pane:** The scanned document is displayed with zoom, pan, and rotate
|
|
controls. The clerk reads the handwritten or printed values from the scan.
|
|
4. **Right pane:** Structured form fields for:
|
|
- Patient demographics (name, DOB, sex, blood type, emergency contact)
|
|
- Encounter context (admission date, department, room/bed, admission reason)
|
|
- Observations (one row per vital sign or lab result)
|
|
|
|
**Observation entry rules:**
|
|
- Each observation requires a code (e.g., `HEART_RATE`), numeric value, unit, and
|
|
`recordedAt` timestamp taken from the chart (not scan time)
|
|
- Plausibility validation fires on save:
|
|
- Heart rate: 20-300 bpm
|
|
- Temperature: 25-45 C
|
|
- SpO2: 0-100 %
|
|
- Potassium: 1.5-10.0 mEq/L
|
|
- Glucose: 20-800 mg/dL
|
|
- Out-of-range values return `422 OBSERVATION_OUT_OF_PLAUSIBLE_RANGE`
|
|
- This catches the most common digitization error: decimal misplacement (5.2 vs 52)
|
|
|
|
5. Click **Submit for Verification** when all fields are complete
|
|
6. The batch transitions to `pending_verification`
|
|
|
|
### 3. Verification (Verifier)
|
|
|
|
The verifier reviews the entry against the original scan:
|
|
|
|
1. Log in as `verifier1` (must be a different person than the entry clerk)
|
|
2. Open the batch from the **Verification** queue
|
|
3. **Left pane:** Same scan viewer
|
|
4. **Right pane:** Each field has a verification checkbox
|
|
- Compare each entered value against the scan
|
|
- Check the checkbox when the value matches
|
|
- Progress bar shows completion percentage
|
|
5. If all fields match: click **Approve - Verified**
|
|
6. If any field is wrong: click **Reject** with a mandatory reason
|
|
|
|
**Separation of duties:** The system enforces that `enteredByUserId !== verifiedByUserId`.
|
|
If the entry clerk tries to verify their own batch, the API returns `409
|
|
SEPARATION_OF_DUTIES_VIOLATION`.
|
|
|
|
**On rejection:** The batch returns to `rejected` status. The entry clerk sees the
|
|
rejection reason and can correct the draft, then resubmit for verification.
|
|
|
|
### 4. Approval and Promotion
|
|
|
|
Track A has **two human gates** before live records exist:
|
|
|
|
1. **Verifier** — scan comparison (`verify` / `reject` on `pending_verification`)
|
|
2. **Clinical approver** — promotion authorization (`approve` on `verified` or `awaiting_clinical_approval`)
|
|
|
|
After verification passes, site configuration routes the batch:
|
|
|
|
| batchType | Default: next status after verify |
|
|
|---|---|
|
|
| `patient_registration`, `allergy_update` | `verified` → clinical approver calls `approve` |
|
|
| `encounter_summary`, `vitals_sheet`, `lab_results`, `medication_list`, `mixed` | `awaiting_clinical_approval` → clinical approver reviews in **Clinical Approval** queue, then calls `approve` |
|
|
|
|
Log in as `approver1` for the approval step. Verifiers (`verifier1`) never call `approve`.
|
|
|
|
On approval:
|
|
1. The promotion service runs atomically:
|
|
- Create or update Patient in VigilCareClinical
|
|
- Create or match Encounter
|
|
- Insert each DraftObservation as a live Observation
|
|
- Write outbox events (alerting suppressed for backfill unless
|
|
`enableRetroactiveAlerts: true`)
|
|
2. Batch status transitions to `promoted`
|
|
3. All observations are now visible in VigilCareClinical's ward dashboard
|
|
|
|
**Alert suppression for backfill:** By default, backfilled observations do not
|
|
trigger real-time alerts. A historical potassium of 6.2 mEq/L from three days ago
|
|
should not page the on-call physician today. The facility can override this per
|
|
batch by setting `enableRetroactiveAlerts: true`.
|
|
|
|
---
|
|
|
|
## Workflow 2: Live Bedside Capture (Track B)
|
|
|
|
**Scenario:** A nurse or physician enters vital signs at the bedside using a tablet.
|
|
The observation needs to reach VigilCareClinical's alert pipeline immediately.
|
|
|
|
**Actor:** Clinician
|
|
|
|
**Steps:**
|
|
|
|
1. Log in as `clinician1`
|
|
2. Navigate to the live capture endpoint
|
|
3. Select or create the encounter
|
|
4. Enter observation values with `clinicianAttestation: true`
|
|
5. Confirm with password re-entry or PIN
|
|
|
|
**What happens:**
|
|
- A `DigitizationBatch` is created with `track: live_capture` and lands in `promoted` immediately (workflow states skipped, audit unit retained)
|
|
- `DraftObservation` rows and `DigitizationEvent` entries (`live_capture_attested`, `promoted`) are written in the same transaction as live observations
|
|
- No verification queue — the clinician's attestation replaces verify + approve for that batch only
|
|
- The batch is promoted synchronously
|
|
- If a critical value is entered (e.g., potassium 6.8 mEq/L), the synchronous
|
|
alert fires before the response returns
|
|
- The observation appears in VigilCareClinical's ward dashboard immediately
|
|
|
|
**When to use Track B vs Track A:**
|
|
- Track B: Current patient encounter, values just measured, clinician is at bedside
|
|
- Track A: Historical charts, bulk digitization, values from past encounters
|
|
|
|
---
|
|
|
|
## Workflow 3: Corrections
|
|
|
|
**Scenario:** After promotion, a reviewer discovers that the SpO2 value was entered
|
|
as 94% but the chart actually shows 95%. The promoted observation must be corrected.
|
|
|
|
**Rule:** Approved records are never silently edited. Corrections go through the
|
|
full pipeline.
|
|
|
|
**Steps:**
|
|
|
|
1. Create a new batch with `supersedesBatchId` pointing to the original batch
|
|
2. Re-enter the corrected values
|
|
3. Submit for verification (new entry, new verifier review)
|
|
4. On approval and promotion:
|
|
- The corrected observations are inserted as new live records
|
|
- The original observations are marked `superseded` (soft flag, not deleted)
|
|
- The audit trail shows: original values, correction request, new values,
|
|
who made each change and when
|
|
|
|
**Why not just edit the original?** Clinical audit integrity. A regulator must be
|
|
able to see what was originally entered, when it was corrected, and by whom. Silent
|
|
edits destroy this chain.
|
|
|
|
---
|
|
|
|
## Staffing Considerations
|
|
|
|
- In a small facility, one person may serve as both intake clerk and data entry clerk
|
|
- The system **never** allows one person to both enter and verify the same batch,
|
|
even if they hold both roles
|
|
- Minimum staff for full workflow: 2 people (one enters, one verifies)
|
|
- The system tracks clerk throughput via the work queue overview endpoint and
|
|
Prometheus metrics
|
|
|
|
---
|
|
|
|
## Common Issues and Resolution
|
|
|
|
| Issue | Cause | Resolution |
|
|
|---|---|---|
|
|
| `409 DUPLICATE_DOCUMENT` | Same PDF uploaded for same patient within 24h | Check if batch already exists; use a different scan if needed |
|
|
| `409 SEPARATION_OF_DUTIES_VIOLATION` | Entry clerk trying to verify own batch | Assign to a different verifier |
|
|
| `422 OBSERVATION_OUT_OF_PLAUSIBLE_RANGE` | Value outside allowed range | Check for decimal misplacement (52 vs 5.2) |
|
|
| `409 ILLEGAL_STATUS_TRANSITION` | Trying to skip a workflow step | Follow the status machine: uploaded -> in_entry -> pending_verification -> verified -> approved -> promoted |
|
|
| High rejection rate (>15%) | Scan quality or training issues | Review rejection reasons; improve scanner resolution or provide entry clerk training |
|
|
| Batch stuck in `approved` | VigilCareClinical unreachable | Promotion retry worker handles this automatically with exponential backoff |
|
|
``` |