Integration Use Cases (INT)¶
UC-INT-001: Receive HL7 ADT¶
Purpose: Handle admissions/discharges.
| Property | Value |
|---|---|
| Actor | EMR System |
| Trigger | ADT^A01 message |
| Priority | P0 |
Main Success Scenario:
1. Receive ADT message
2. Extract PID (Demographics) and PV1 (Visit)
3. Create/Update Patient record
4. Create "Admission" event in Timeline
5. Send ACK
Acceptance Criteria: 1. [ ] Updates patient location (Ward/Bed) 2. [ ] Creates new patient if not exists
UC-INT-002: Ingest FHIR Bundle¶
Purpose: Accept external FHIR data.
| Property | Value |
|---|---|
| Actor | External Lab |
| Trigger | POST /api/ingest/fhir |
| Priority | P1 |
Main Success Scenario:
1. Receive Bundle resource
2. Validate FHIR structure
3. Iterate resources (Observation, DiagnosticReport)
4. Map to Canonical Schema
5. Update Patient Bundle
Acceptance Criteria: 1. [ ] Rejects invalid FHIR resources 2. [ ] Preserves external identifiers
UC-INT-003: Push Radiology Results¶
Purpose: Send enriched imaging interpretations back to the hospital EMR as FHIR DiagnosticReport.
| Property | Value |
|---|---|
| Actor | Integration Service |
| Trigger | Imaging study marked finalized |
| Priority | P1 |
Main Success Scenario:
1. Listen to `imaging.finalized` Kafka topic
2. Build FHIR `DiagnosticReport` with references to Observation + ImagingStudy resources
3. Call EMR endpoint `POST /fhir/DiagnosticReport`
4. Handle 201 Created, capture response ID
5. Update local bundle with `externalReportId`
6. Log success and emit metric `radiology_push_success_total`
Acceptance Criteria: 1. [ ] Retries with exponential backoff on 5xx 2. [ ] Signs payload using shared mTLS certs 3. [ ] Stores request/response pair for auditing (30 days)
UC-INT-004: Receive LIS CSV¶
Purpose: Support labs that results as CSV attachments via SFTP.
| Property | Value |
|---|---|
| Actor | Integration Service |
| Trigger | SFTP upload detected |
| Priority | P1 |
Main Success Scenario:
1. Detect new CSV using UC-ING-012
2. After validation, call partner-specific transformer (mapping file)
3. Convert rows into FHIR Observations using canonical schema
4. Store transformed bundle in `ingestion_staging`
5. Trigger downstream pipeline (UC-ING-014) automatically
Acceptance Criteria: 1. [ ] Partner-specific transforms managed via configuration repo 2. [ ] Supports encrypted ZIP payloads (AES256) 3. [ ] Generates receipt email/SMS to partner upon success
UC-INT-005: Send Status Webhook¶
Purpose: Notify partner systems when ingestion jobs succeed or fail.
| Property | Value |
|---|---|
| Actor | Webhook Dispatcher |
| Trigger | Job status changes |
| Priority | P2 |
Main Success Scenario:
1. Subscribe to `job.status` topic
2. For configured partners, build JSON payload (jobId, status, patientId)
3. Sign payload using HMAC SHA256 secret per partner
4. POST to partner webhook URL with retries (max 5)
5. Persist delivery attempts/outcomes
6. Surface webhook failures in Ops dashboard
Acceptance Criteria:
1. [ ] Supports exponential backoff with jitter
2. [ ] Partners can query /api/webhooks/deliveries for history
3. [ ] Automatic disable after 10 consecutive failures
UC-INT-006: Sync Provider Directory¶
Purpose: Keep provider mappings (NPI, specialty) in sync with external master data.
| Property | Value |
|---|---|
| Actor | Provider Sync Service |
| Trigger | Nightly schedule 02:00 IST |
| Priority | P2 |
Main Success Scenario:
1. Fetch delta file via REST `GET /providers?updatedSince={timestamp}`
2. Validate signature + checksum
3. Upsert provider records into `provider_mapping` table
4. Invalidate cache entries for affected providers
5. Emit event `provider.directory.updated`
6. Notify Ops on completion with summary counts
Acceptance Criteria: 1. [ ] Handles >50k provider updates within 10 minutes 2. [ ] Maintains audit log of attribute changes 3. [ ] Supports manual re-run for a given date window