Streams near real-time physiologic waveforms (ECG, SpO2 pleth, respiration, arterial pressure) from Epic monitoring feeds through MuleSoft to a web or mobile visualization app, preserving sample cadence and gap markers so clinicians see a faithful trace, not a smoothed lie.
Tags: healthcare, epic, connected-devices, streaming, event-driven, fhir, system-api
Waveform Visualization
Objective: Clinicians reviewing a patient away from the bedside monitor need the same waveforms — ECG lead II, SpO2 pleth, respiration, arterial pressure — in a web or mobile app at near real-time cadence. The feed is high-frequency (125-500 Hz), bursty, and lossy over cellular, so the hard problem is not fetching data but delivering an honest trace: correct sample spacing, explicit gap markers where data was lost, and latency low enough to be clinically useful. Done looks like a sub-two-second glass-to-glass trace that renders continuously, marks dropouts instead of interpolating over them, and never drifts off the true sample clock. This accelerator packages the Waveform Visualization Epic Data Sharing Playbook as a MuleSoft-anchored solution plan.
What's Getting Built
- Waveform Poll/Subscribe (System API) — subscribes to or polls the Epic waveform channel for sampledData frames using cached backend-services token ·
SUBSCRIBE waveform-channel, GET /Observation?since={cursor}
- Anypoint MQ Buffer (target) — buffers correlation-ID-stamped inbound frames between ingestion and framing ·
PUBLISH waveform-frames, CONSUME waveform-frames
- Normalize/Frame (Process API) — decodes sampledData to per-channel amplitude arrays, emits fixed-window frames, and inserts explicit gap tokens ·
CONSUME queue, EMIT frame, DECIMATE min/max
- WebSocket Stream (Experience API) — terminates the client WebSocket per patient encounter, fans out per-channel frames, and serves a rolling replay buffer ·
WSS CONNECT /stream/{encounter}, SEND frame, SEND heartbeat
- Dead Letter Queue (target) — holds malformed or undecodable frames with correlation ID and raw payload for replay ·
PUBLISH dlq, CONSUME dlq
Prerequisites
- Epic App Orchard/Vendor Services registration with FHIR R4 Observation and the sampledData datatype enabled, plus access to the waveform/device-data channel for your monitoring integration
- SMART on FHIR backend-services (client-credentials) OAuth 2.0 with an asymmetric JWT signing key registered in Epic for unattended API access
- Anypoint Platform with a CloudHub 2.0 or RTF deployment that supports persistent WebSocket connections and Anypoint MQ for buffering
- A defined device-to-Epic ingestion path (bedside monitor via a middleware gateway or Epic Bridges) so waveform samples actually reach Epic before you consume them
- Patient-context launch or explicit patient-scope authorization so the app only opens waveforms for the encounter the clinician is viewing
- Reference sample rates and units per channel (Hz, mV, %, mmHg) agreed with the biomedical/clinical engineering team
1. Epic interfaces and standards
This accelerator implements the Waveform Visualization Epic Data Sharing Playbook. Register the connecting app on Epic on FHIR and confirm the customer has the relevant Epic modules licensed before building.
- FHIR R4 Observation with sampledData (period, factor, lowerLimit, upperLimit, dimensions, data)
- FHIR R4 Device and DeviceMetric for channel identity and units
- Bridges HL7v2 ORU-R01 for device-sourced numerics that accompany the waveform
- SMART on FHIR backend-services OAuth 2.0
- LOINC waveform codes (MDC/IEEE 11073 mapped) for channel typing
- Hyperspace/Hyperdrive embedded launch for clinician context
Architecture
2. Business requirements
- Deliver ECG, SpO2 pleth, respiration, and arterial pressure channels at their native sample rates with glass-to-glass latency under two seconds on a normal network.
- Render an honest trace: mark data loss with an explicit gap indicator rather than interpolating a smooth line the patient never produced.
- Preserve sample cadence exactly using the Observation.sampledData period; a trace that drifts off the sample clock is clinically misleading.
- Scope every session to a single patient encounter and tear down the stream when the clinician closes the view.
- Label the app as review-and-visualization, not primary alarm-grade monitoring, so it is not mistaken for the bedside device.
3. Ingestion from Epic
- Authenticate with SMART backend-services client-credentials and cache the bearer token; refresh before expiry so the stream never stalls on a 401.
- Consume waveform frames as FHIR Observation resources carrying sampledData, reading period, factor, and dimensions to reconstruct real amplitudes.
- Correlate the accompanying Bridges ORU-R01 numerics (heart rate, SpO2 value) with the waveform channel using Device and DeviceMetric references.
- Stamp every inbound frame with a correlation ID and the source sample timestamp before it enters Anypoint MQ.
- Prefer a subscription or channel push where Epic supports it; fall back to tight interval polling with a since-cursor, never a full re-read.
4. Normalization and framing
- Decode sampledData: multiply each integer sample by factor, apply lowerLimit/upperLimit clamps, and split multi-dimensional data into per-lead arrays.
- Map channel identity from LOINC/MDC codes to a stable channel key the renderer understands, carrying units (mV, %, mmHg) explicitly.
- Emit fixed-size time-windowed frames on the WebSocket with an absolute start timestamp and the period, so the client places samples on the true clock.
- Insert an explicit gap token when the source timestamp jumps more than one period; never backfill with zeros or interpolation.
- Downsample for mobile with min/max decimation, which preserves clinically important peaks that naive averaging erases.
5. Streaming orchestration
- Terminate the client on an Experience API WebSocket; fan out per-channel frames from a single Process API so the app opens one connection per patient.
- Maintain a short rolling replay buffer (about 30 seconds) per channel so a reconnecting client can catch up without a full re-fetch.
- Apply backpressure: if the client falls behind, drop older frames for that client and send a gap marker rather than growing an unbounded queue.
- Send periodic heartbeat frames so the client can detect a dead connection faster than TCP timeout and trigger reconnect.
- Key streams by encounter and enforce that a token scoped to one patient cannot subscribe to another patient channel.
6. Error handling and operations
- Route malformed or undecodable frames to a dead-letter queue with the correlation ID and raw payload; never drop them silently.
- Alert on the absence of expected frames per channel, which is the failure mode a throughput dashboard misses when a monitor unplugs.
- Track glass-to-glass latency as a first-class SLI and page when the p95 exceeds the clinical threshold, not just on hard errors.
- Emit a distinct metric for gap-marker rate per channel; a rising gap rate signals network or source degradation before users complain.
- Make token-refresh failures loud and self-healing: retry with jitter, and if refresh fails, close streams cleanly with a reason code the app can display.
7. Security and compliance
- Encrypt PHI in transit and at rest.
- Audit-log every access to and modification of patient data, and carry a correlation ID end to end.
- Enforce minimum-necessary access for integration operators and support users.
- Bind each WebSocket session to the patient scope in the presented token and reject cross-patient channel subscriptions server-side, not just in the UI.
- Do not persist waveform sample data beyond the short replay buffer; treat the buffer as ephemeral PHI and clear it on disconnect.
- Pin the SMART backend-services JWT signing key in a secure vault and rotate it on a schedule; a leaked key exposes every patient channel.
- Enforce TLS 1.2+ with WSS for all WebSocket traffic and reject downgrade to plain WS even on internal networks.
Sample payload — FHIR R4 Observation with ECG Lead II sampledData
{
"resourceType": "Observation",
"id": "wf-ecg-ii-20260820T134501",
"status": "final",
"category": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "procedure"
}]
}],
"code": {
"coding": [{
"system": "http://loinc.org",
"code": "11524-6",
"display": "EKG study"
}]
},
"subject": { "reference": "Patient/eXY12abcQZ" },
"encounter": { "reference": "Encounter/eENC998" },
"device": { "reference": "Device/monitor-bay4" },
"effectiveDateTime": "2026-08-20T13:45:01.000Z",
"valueSampledData": {
"origin": { "value": 0, "unit": "mV" },
"period": 4,
"factor": 0.0025,
"lowerLimit": -5,
"upperLimit": 5,
"dimensions": 1,
"data": "12 18 25 34 48 71 120 210 88 -14 -22 -9 4 10 15 19"
}
}
Testing and validation
- Replay a captured Observation stream at native rate and assert the rendered trace matches the source sample-for-sample within the factor tolerance.
- Inject a timestamp discontinuity and verify a gap marker appears where interpolation would otherwise hide the loss.
- Kill and restore the WebSocket mid-stream and confirm the replay buffer catches the client up without duplicate or reordered samples.
- Present a token scoped to patient A and attempt to subscribe to patient B; assert the subscription is rejected server-side.
- Measure glass-to-glass latency under simulated 4G loss and packet delay; confirm p95 stays under the clinical threshold.
- Feed a malformed sampledData payload (bad dimensions/data length mismatch) and confirm it lands in the DLQ with its correlation ID.
Phased rollout
Phase 1 — Connect
- Register the SMART backend-services client and validate token issuance against Epic's non-production waveform endpoint.
- Establish the System API subscription/poll and confirm Observation sampledData frames arrive with correct period and factor.
Phase 2 — Map and test
- Build the DataWeave decode from sampledData to per-channel amplitude arrays and validate against a known reference trace.
- Stand up the Experience API WebSocket and replay a captured session end-to-end into the renderer, verifying cadence and gap markers.
Phase 3 — Production
- Enable for a single unit with clinical sign-off that the app is labeled review-only, monitoring latency and gap-rate SLIs.
- Scale channels and encounters after validating backpressure and token-refresh behavior under real network loss.
Success metrics
- Glass-to-glass latency p50/p95 per channel
- Gap-marker rate per channel per minute
- Expected-frame-absence alerts fired vs. real outages
- WebSocket reconnect success rate and catch-up time
- DLQ frame count and root-cause categories
Troubleshooting
- The trace looks right but drifts slowly out of sync with the bedside monitor. — Likely cause: The client is spacing samples by wall-clock arrival time instead of the Observation.sampledData period. Fix: Render off the absolute frame start timestamp plus period per sample, and resync each frame to its declared start time rather than accumulating client-side time.
- Waveform amplitudes are wildly wrong or clipped flat. — Likely cause: The decoder ignored factor and lowerLimit/upperLimit when converting integer samples to physical units. Fix: Apply amplitude = sample * factor with origin offset, then clamp to lower/upper limits, and confirm units match the DeviceMetric before rendering.
- Clinicians report the line goes smooth during network hiccups and hides dropouts. — Likely cause: The pipeline backfills missing samples with interpolation instead of emitting an explicit gap. Fix: Detect timestamp jumps greater than one period in the Process API and emit a gap token; render it as a visible break, never a connecting line.
- Streams stall for all users at the same time every hour. — Likely cause: The cached backend-services bearer token expires and refresh is not firing ahead of expiry. Fix: Refresh the token proactively before expiry with retry-and-jitter, and monitor token age as an SLI so refresh failures page before streams drop.
Deliverable: A deployable Anypoint project that subscribes to Epic waveform channels, streams normalized samples over WebSocket to a browser/mobile renderer, and replays gaps from a short buffer — with correlation IDs, a dead-letter queue for malformed frames, and a Grafana operations dashboard.