Wires a contact-center phone system into Epic Hyperspace so inbound calls screen-pop the right chart, agents click-to-dial from the workspace, and every call is logged against the patient record. MuleSoft brokers real-time CTI events, resolves callers to Epic patients, and reconciles call outcomes back to the chart.
Tags: healthcare, epic, interoperability, event-driven, api-led, system-api, process-api, fhir
Computer Telephony Integration (CTI)
Objective: Contact-center and clinic staff answer patient calls blind: they hear a voice, then hand-search Epic for the caller while the patient waits and re-verifies identity. Manual chart lookup wastes 20-40 seconds per call, misroutes callers, and leaves call activity undocumented. Done looks like: an inbound call triggers a caller-to-patient match, pops the correct Hyperspace chart (or a chooser when ambiguous) before the agent says hello, lets the agent click-to-dial from the record, and logs call metadata back to the chart. The happy path needs no manual patient search, and every call leaves a documented telephony trail whether or not it matched. This accelerator packages the Computer Telephony Integration (CTI) Epic Data Sharing Playbook as a MuleSoft-anchored solution plan.
What's Getting Built
- CTI System API (System API) — wraps the telephony vendor's agent-desktop events and click-to-dial into one canonical schema ·
POST /events/call (signed webhook), POST /originate (click-to-dial command)
- Epic Interconnect System API (System API) — searches FHIR Patient for caller matching and writes the call back to the chart ·
GET /Patient?telecom={ani}, GET /Patient?identifier={mrn}, POST /Communication
- Screen Pop Process API (Process API) — resolves the caller to a patient, sets Hyperdrive context, and reconciles the call log on disconnect ·
CONSUME call.answered, PUT Hyperdrive patient context (CCOW), POST Communication writeback via Epic System API
- Call Events (Anypoint MQ queue) — decouples low-latency screen-pop from asynchronous call logging so slow chart writes never delay the pop ·
PUBLISH call.answered, CONSUME call.answered, CONSUME call.disconnected
- active-call state (Object Store) — Object Store v2 holding call, agent, matched patient, and cached ANI resolutions keyed by vendor call ID ·
GET /{vendorCallId}, PUT /{vendorCallId}, GET /ani/{e164}
- Dead Letter Queue (target) — captures un-writable call-log events for scheduled reconciliation of dropped disconnects ·
PUBLISH failed-writeback, SCHEDULER reconcile
Prerequisites
- Telephony platform exposing a CTI/agent-desktop API or event stream (e.g. Genesys, Amazon Connect, Cisco Finesse) with softphone/agent-state webhooks and click-to-dial endpoints
- Epic Interconnect environment with FHIR R4 read access to Patient plus web-service credentials for creating Telephony/communication documentation
- Epic client-side integration surface enabled: Hyperdrive screen-pop via context (HL7 CCOW or Epic-Hyperdrive URL/telephony hooks) configured with Epic technical services
- OAuth 2.0 client registered on open.epic.com with scopes for Patient.read and the telephony write service; backend client credentials for server-to-server calls
- Anypoint Platform with CloudHub or RTF, Anypoint MQ for the call-event queue and DLQ, and Object Store v2 for active-call and match-token state
- Agreed caller-match policy signed off by clinical/compliance: which demographics (ANI phone, DOB, MRN via IVR) may auto-open a chart versus require agent confirmation
1. Epic interfaces and standards
This accelerator implements the Computer Telephony Integration (CTI) Epic Data Sharing Playbook. Register the connecting app on Epic on FHIR and confirm the customer has the relevant Epic modules licensed before building.
- Hyperspace/Hyperdrive (clinician desktop screen-pop and click-to-dial target)
- Epic Interconnect FHIR R4 Patient resource (search by phone/identifier for caller matching)
- FHIR R4 Communication resource (call logged against the chart with sender/recipient and sent time)
- Epic Telephony/Real-Time web services for CTI screen-pop context and click-to-dial
- SMART on FHIR EHR launch with launch/patient context for the embedded agent panel
- HL7 CCOW patient-context vault for synchronizing the popped chart with the agent's active call
Architecture
2. Business requirements
- Pop the matched patient chart in the agent's active Hyperspace before greeting, targeting sub-second latency from call-ring to context set.
- Resolve the caller from ANI (calling number) first, then IVR-collected MRN or DOB, and never auto-open a chart on a low-confidence match.
- When the match is ambiguous or absent, present a candidate chooser rather than the wrong chart or a blank search.
- Let agents click-to-dial any phone number on the chart, originating the outbound call through the telephony platform without keying digits.
- Log every call as a documented event on the chart with direction, start/end time, disposition, and a reference to the recording.
3. Ingestion and event modeling
- Wrap the telephony vendor's agent-desktop API in a CTI System API that normalizes ringing, answered, held, transferred, and disconnected events into one canonical DataWeave schema.
- Stamp every event with the vendor call ID and a Mule correlation ID so screen-pop and writeback share one trace across the call lifecycle.
- Publish normalized events to Anypoint MQ so screen-pop and post-call logging consume independently and slow chart writes never delay the pop.
- Hold active-call state (call ID, agent, matched patient, disposition) in Object Store v2 keyed by vendor call ID for the duration of the call.
- Treat click-to-dial as a command into the CTI System API, not an event out of it, and keep the two directions in separate flows.
4. Caller matching and normalization
- Normalize the ANI to E.164 in DataWeave before any lookup so vendor-formatted numbers match Epic's stored phone values.
- Search FHIR R4 Patient by telecom phone first; fall back to identifier (MRN) or family name plus birthdate when the IVR captured them.
- Score candidates and gate auto-pop behind a confidence threshold: exactly one active patient on the ANI auto-pops, everything else routes to the chooser.
- Cache recent ANI-to-patient resolutions in Object Store with a short TTL to cut repeat lookups from callback storms, but expire aggressively to avoid stale identity.
- Return a candidate list, never a guess, when the phone is shared across a household or maps to multiple active patients.
5. Orchestration and Hyperspace delivery
- The Screen Pop Process API consumes the answered/ringing event, calls the Epic System API for the match, and sets patient context into Hyperdrive via the configured telephony/CCOW channel.
- Correlate the popped chart to the live call through CCOW so a transfer re-pops the receiving agent and clears context on disconnect.
- Drive click-to-dial from a SMART on FHIR EHR-launch panel that carries launch/patient context, so the dialed number and the originating agent are known without re-lookup.
- On disconnect, enrich the cached call state with disposition and duration, then write a FHIR Communication (or Epic Telephony documentation service call) referencing the patient and encounter.
- Keep screen-pop on the low-latency synchronous path and push call-logging writeback onto the asynchronous queue path.
6. Error handling and operations
- Route un-writable call-log events to a DLQ and reconcile on a schedule; a dropped disconnect event is the failure mode that silently loses call documentation.
- Alert on the absence of an expected disconnect event for an answered call, since a call that never closes leaves stale context and an unlogged encounter.
- Degrade gracefully: if the Epic Patient search times out, still pop an empty-search context so the agent is not blocked, and flag the call for manual documentation.
- Never retry a click-to-dial command blindly on ambiguous failure, because a naive retry can originate a duplicate outbound call to the patient.
- Emit per-call latency (ring-to-pop) and match-rate metrics with the correlation ID so a slow pop can be traced to telephony, Mule, or Epic.
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.
- Scope the telephony webhook to mutual TLS and validate the vendor's event signature before the CTI System API accepts a call event, since a spoofed event could pop an arbitrary chart.
- Redact recording URLs and DTMF-captured MRNs from logs and traces; store the recording reference, not the audio, on the chart.
- Bind the SMART launch and click-to-dial command to the authenticated agent so an agent can only originate calls and pop charts within their own session.
- Expire cached ANI-to-patient resolutions quickly and never persist caller identity in the queue payload beyond the active call.
Sample payload — Normalized inbound call event published to Anypoint MQ
{
"eventType": "call.answered",
"vendorCallId": "gen-8842-20260820-1030",
"correlationId": "a7f3c1e0-9b2d-4c11-8e6a-2f9d0c4b7a10",
"direction": "inbound",
"agent": { "epicUserId": "CTIAGENT42", "extension": "5120" },
"ani": "+15125550143",
"dnis": "+15125559000",
"ivr": { "capturedMrn": null, "menuPath": "clinic>appointments" },
"ringTime": "2026-08-20T10:30:02Z",
"answerTime": "2026-08-20T10:30:09Z",
"match": {
"status": "single",
"confidence": 0.94,
"patient": { "fhirId": "eXbY3k9...", "mrn": "203118" }
},
"recordingRef": "tel-rec://gen-8842-20260820-1030"
}
Testing and validation
- Unit-test DataWeave ANI normalization against vendor formats: national, E.164, extensions, blocked/anonymous, and international callers.
- Test the match gate: single active patient auto-pops, multiple candidates route to the chooser, no match yields empty context and a manual-documentation flag.
- Simulate a full call lifecycle (ring, answer, hold, transfer, disconnect) and assert CCOW context sets on the receiving agent and clears on disconnect.
- Verify click-to-dial originates exactly one outbound call and does not duplicate under a simulated ambiguous timeout.
- Confirm a suppressed or dropped disconnect event lands in the DLQ and the reconciliation job writes the missing Communication.
- Load-test ring-to-pop latency at peak concurrent-call volume and assert the synchronous pop path stays within the sub-second target.
Phased rollout
Phase 1 — Connect
- Register the OAuth client on open.epic.com and stand up the Epic Interconnect System API with FHIR Patient.read in a non-production environment.
- Wrap the telephony vendor API in the CTI System API and confirm signed call-event webhooks flow into Anypoint MQ.
Phase 2 — Map and test
- Build and unit-test DataWeave for ANI normalization, Patient search, candidate scoring, and Communication writeback.
- Validate screen-pop into a Hyperspace test environment with Epic technical services, including CCOW context on transfer and disconnect.
Phase 3 — Production
- Pilot with one contact-center queue and a small agent cohort, monitoring match-rate and ring-to-pop latency before widening.
- Enable click-to-dial and automated call-logging writeback after the read-only screen-pop path is proven stable.
Success metrics
- Ring-to-pop latency (p95) from call answer to Hyperspace context set
- Caller auto-match rate versus chooser versus no-match
- Percent of answered calls with a documented call-log written to the chart
- Manual patient searches per agent per shift (target trending to near zero on matched calls)
- DLQ depth and mean time to reconcile dropped call events
Troubleshooting
- Chart pops for the wrong patient on inbound calls from a family's shared landline. — Likely cause: The ANI resolves to multiple active patients but the match gate auto-popped the first candidate instead of offering a chooser. Fix: Lower the auto-pop threshold to require a single active patient on the ANI and route all multi-candidate results to the agent chooser.
- Screen-pop fires but the agent's Hyperspace never changes charts. — Likely cause: CCOW patient-context is not joined to the agent's session, so the context set has no active vault to update. Fix: Verify the agent is joined to the CCOW context vault at login and that the telephony context channel targets the agent's workstation identity.
- Calls are answered and handled but no call-log appears on the chart. — Likely cause: The disconnect event was dropped or arrived without matched-call state, so the Communication writeback never fired. Fix: Consume disconnects with correlation-ID lookup against Object Store, DLQ any writeback failures, and run the reconciliation job to backfill missing Communications.
- Click-to-dial occasionally places two outbound calls to the same patient. — Likely cause: The Process API retried an ambiguous originate-call failure that had actually succeeded. Fix: Make the originate command idempotent with the correlation ID and stop blind retries on ambiguous responses; confirm call state before re-issuing.
Deliverable: A deployable Anypoint blueprint: a CTI System API wrapping the telephony vendor's events plus an Epic Interconnect FHIR/SOAP System API, a Process API that resolves callers to patients and emits screen-pop payloads to Hyperspace, click-to-dial and call-logging flows writing back to the chart, and DLQ-backed reconciliation for dropped call events.