Building an Ambient Documentation Workflow Inside Epic Haiku
Technology Blogs

Building an Ambient Documentation Workflow Inside Epic Haiku

Sanket Nawghare
Full Stack Developer

Building an Ambient Documentation Workflow Inside Epic Haiku

Epic Haiku gives mobile clinicians a fast way to move through patient care, but ambient documentation adds a different level of complexity. The application is not simply launched from a browser tab. It runs inside Haiku, depends on Epic-managed session context, receives recording lifecycle events from Epic, and has to return note content in a form that fits directly into the clinician’s workflow.

This article explains what it takes to integrate an external application with Epic Haiku for ambient note generation. It focuses on the engineering flow: launch, authentication, context handling, recording retrieval, note generation and handoff back to Epic. Epic documents its ambient integration for participating vendors; this page describes the pattern, not Epic’s specification.

The Problem the Integration Solves

The goal is straightforward: let a clinician start an ambient recording session from Haiku, process the captured audio outside of Epic, and deliver generated note sections back into Epic for review and signing.

The implementation, however, spans multiple systems:

  • Haiku hosts the vendor UI in an embedded web view.
  • Epic creates and manages the ambient session.
  • The vendor backend receives callbacks and downloads recordings.
  • External processing services transcribe audio and generate note content.
  • Epic ultimately remains the system of record for the reviewed and signed note.

The result is less like embedding a simple app and more like wiring together a mobile launch surface, an OAuth-enabled frontend, a callback-driven backend, and an asynchronous audio-processing pipeline.

What the Architecture Looks Like

At a high level, the integration has four moving parts: the Haiku client, Epic backend services, the vendor integration backend, and the processing layer that turns audio into documentation.

What the Architecture Looks Like

Haiku is responsible for launching the vendor experience in an embedded mobile web view. Epic is responsible for establishing the ambient session, storing recordings, and notifying the vendor when chunks or completed recordings are ready. The vendor backend is responsible for everything orchestration-related: session state, callback handling, audio retrieval, retries, processing coordination, and note submission.

That split is important. The frontend embedded in Haiku and the backend receiving Epic callbacks solve different problems and should be designed independently even though they are part of the same integration.

Where the Workflow Begins

The flow starts when the clinician opens the Ambient activity in Haiku. At that point Epic creates an ambient session and sends the vendor backend a session-start call. That call anchors the whole session.

It contains the core session context:

  • user identifier
  • session identifier
  • patient identifiers
  • encounter identifiers
  • callback URL
  • optional care context
  • optional note type
  • optional allowed note sections

That payload should be treated as authoritative. It defines the session the vendor is expected to manage and provides the context needed for both backend processing and frontend launch reconciliation.

Launching the Embedded Experience

After the session is created, Haiku launches the vendor web view. The embedded page is typically opened with a vendor-defined route that includes the ambient session identifier and, when SMART on FHIR is enabled, the standard iss and launch parameters used in an EHR launch.

This is where teams often underestimate the mobile constraints. The vendor UI is not running in a full desktop browser. It is running inside an embedded mobile environment that can be backgrounded, interrupted, or terminated by the operating system. Any critical state that exists only in memory inside the web view is fragile by definition.

Why SMART on FHIR Still Matters

The ambient session itself is established through Epic’s callback model, but the embedded frontend may still need direct FHIR access. That is where SMART on FHIR comes in.

If the embedded app needs to show patient, encounter, or user context directly from Epic, it should use the EHR launch flow:

  1. Read iss and launch from the Haiku launch URL.
  2. Discover the SMART configuration from the Epic FHIR server.
  3. Perform the authorization code flow.
  4. Exchange the code for a token.
  5. Use the token for FHIR reads needed by the embedded experience.

Why SMART on FHIR Still Matters

A useful design principle here is to keep the responsibilities separate:

  • The frontend SMART token is for the embedded user-facing app.
  • The backend integration credentials are for callback handling and Epic API operations.

Mixing those models creates unnecessary coupling and usually makes failure handling harder.

Context Is More Than Just Patient and User

One of the more interesting parts of this integration is how much context Epic provides at session start. The session-start call can carry several identifier types each for the patient and the encounter. It can also include care context, note type, and the set of note sections that are eligible for generation.

That means a robust implementation should not flatten the context too early. Instead, it should preserve the original identifiers and treat the mapping layer as a first-class part of the integration.

In practice, that session store becomes the backbone of the entire integration. It is where the application keeps the callback URL, current recording version, processing status, allowed note sections, and overwrite protection state after Epic notifies the vendor about clinician edits.

How Recording Actually Moves Through the System

Once the recording starts, Epic stores the audio and notifies the vendor as chunks become available. The vendor then calls back to Epic to download those chunks.

This is a queue-driven workflow, not a synchronous request-response chain. Chunk processing, transcript aggregation, and final note generation should all be designed as asynchronous work with durable state and retries.

That asynchronous model matters for two reasons.

First, chunk retrieval can fail transiently. A retry strategy with exponential backoff is necessary. Second, note generation should not begin until the backend knows all required chunks for the current recording version have been processed successfully.

Building an Ambient or AI Documentation App on Epic?

Turning Recordings into Documentation

A clean way to build this is a queue per event:

  • The session-start event persists session metadata.
  • Each chunk-available event queues chunk retrieval and transcription.
  • The recording-complete event waits for every chunk, then either acknowledges a partial recording set or generates note content and submits it back to Epic.

This stage is where operational discipline matters most. Version tracking has to be exact. The note content you submit must match the latest recording version being processed. Once Epic accepts that content, earlier recordings up to that version are no longer available for download.

The Note Is Not Finished When the Vendor Sends It

A useful mental model is that the vendor generates documentation, but Epic owns the clinical workflow. The generated sections appear in Epic for clinician review. The clinician may modify the text before signing.

That creates a second lifecycle after note generation:

The edit notification matters most here. Once Epic signals that a clinician changed a note section, the vendor must stop overwriting that section with later generated content. If this rule is ignored, the system risks wiping out user edits, which is both a clinical and trust problem.

From Structured Output to a Written-Back Note

The deliverable in this integration isn’t free text. It’s structured, versioned, and tied back to Epic’s own session model. The session-start call sets which note sections are eligible. When the vendor submits, the generated sections are written back into Epic against the current recording version, and once Epic accepts them, earlier versions can no longer be downloaded. The write-back is version-locked.

The edit notification closes the loop: once a clinician changes a generated section, the vendor stops overwriting it. Write to the wrong version or overwrite a clinician’s edit, and the integration fails quietly.

Mobile Constraints Change the Design

Teams that are comfortable with web applications often discover that the hardest problems in this integration are not in transcription or FHIR. They are in mobile lifecycle handling.

The embedded Haiku web view can be backgrounded, interrupted, or killed by the operating system. Recording can pause and resume. Navigation away from the activity may need to be blocked while the recorder is active.

This is why session state must live on the backend, not only in the browser context. It is also why the embedded app should be built around rehydration rather than assuming that once the page loads, it will remain alive for the rest of the workflow.

Where Reliability Work Shows Up

From an engineering perspective, the most reliable implementations tend to share a few characteristics:

  • every Epic callback is idempotent
  • session state is durable and versioned
  • chunk processing is queue-backed
  • retryable failures are clearly separated from validation failures
  • user-edited note sections are protected from overwrite
  • frontend and backend auth models are intentionally separated

The backend also needs enough observability to debug cross-system issues. A single ambient session touches Haiku launch, SMART authorization, Epic callbacks, chunk retrieval, transcription jobs, note generation, and note submission. Without correlation IDs and structured state transitions, production debugging becomes slow and error-prone.

Lessons from the Implementation

A few lessons are easy to miss early in design.

The first is that the session-start call is the real session contract. It is not just a notification. It is the authoritative handoff of context and control data from Epic to the vendor.

The second is that mobile web views are an unreliable place to keep critical state. They are a rendering surface, not a source of truth.

The third is that generated documentation is only one step in the workflow. The full implementation must account for what happens after content is submitted, including clinician edits, note signing, and session completion.

Finally, a general backend lesson: reusable integration packages need careful dependency boundaries. Duplicate framework instances, especially in NestJS-based packages, can cause subtle exception-handling bugs that only appear when SDK code is consumed by another application. For a callback-heavy integration, those issues are more than cosmetic because they directly affect whether Epic receives the correct HTTP behavior on failure.

Conclusion

An Epic Haiku ambient integration is best understood as a coordination problem across launch context, authentication, mobile runtime behavior, callback orchestration, asynchronous processing, and clinical workflow handoff.

When it is designed well, the clinician experience feels simple: open Haiku, record, review, sign. Under the surface, however, that simplicity depends on a disciplined integration architecture that treats session context as authoritative, processing as asynchronous, note submission as versioned, and mobile state as disposable.

That combination is what turns an embedded app into a reliable ambient documentation workflow.

Where to go next

Frequently Asked Questions

It writes back. The vendor submits the generated sections into Epic, matched to the recording version that produced them, and the clinician reviews and signs.

Epic notifies the vendor of the edit, and the vendor must not overwrite that section with newer generated content.

Section-aware. The session-start call sets the eligible note sections up front.

Sanket Nawghare

Sanket Nawghare

Full Stack Developer

Connect Now

Sanket Nawghare is a Full Stack Developer with 4+ years of experience building scalable and high-performance web applications. He has hands-on expertise in React, Node.js, Java, and MySQL, with a strong focus on developing clean, maintainable, and efficient solutions across both frontend and backend systems. He has worked extensively on US healthcare projects, contributing to secure, reliable, and user-friendly applications in compliance-driven environments. His interests include system architecture, performance optimization, API development, and building robust enterprise-grade applications.

Share This Blog

Read More Similar Blogs

Let’s #Transform Healthcare,# Together.

Partner with us to design, build, and scale digital solutions that drive better outcomes.

Location

Global Tech Teams LLC, 525 Washington Blvd, Industrious at Newport Tower, Jersey City, NJ 07310, United States.

Contact

+1 408 786 5974
contact@mindbowser.com
BOOK A QUICK CONSULTATION

Have a Healthcare Project in Mind?

Let’s discuss your goals, workflows, and next steps in a focused consultation call.

Calendar icon Schedule a Call

Contact form