Patient Access Integration

JHE can pull a patient’s clinical data from any SMART on FHIR patient-access API (Epic, Cerner/Oracle Health, Athena, ...) using the SMART App Launch standalone patient launch. Epic’s sandbox is the seeded example, but nothing in the client is Epic-specific: a patient searches for their hospital, picks it, is sent to that hospital’s login, and their records are converted and stored in JHE.

This is the single onboarding doc for the Patient Access client: hospital branding, setup, configuration, and an end-to-end test. The flow is vendor-agnostic - only the FHIR endpoint (iss) and brand differ per provider.

Architecture¶

Unlike the OW integration (a server-side poller), the Patient Access flow runs client-side in the browser: a vanilla-JS page hosted on JHE redeems the invitation for a JHE token, lets the patient pick their hospital, runs the EHR’s PKCE OAuth, pulls the patient’s FHIR data, and writes it back into JHE. The backend serves the pages, holds the EHR config in JheClient.aux_data, searches the hospital-brand tables, converts each pulled R4 resource to R5, and stores it.

Patient browser ─▶ /clients/patient-access/?code=<invitation>   (connect.html)
   ├─ POST /api/v1/invitation/<token>          ─▶ redeem invitation
   ├─ POST /o/token/                           ─▶ JHE access token (PKCE)
   ├─ GET  /api/v1/patient-access/brands?q=    ─▶ hospital search (pick one -> its iss)
   └─ FHIR.oauth2.authorize(iss, clientId, scope, redirectUri)
          │
     EHR login ◀───── login + consent ─────────┘
          │
          ▼
   /clients/patient-access/callback   (callback.html)
       │  FHIR.oauth2.ready()  ─▶ EHR access token + patient id
       ├─ POST /api/v1/patient-access/identifier  ─▶ PatientIdentifier (EHR patient id)
       ├─ POST /api/v1/fhir_sources               ─▶ FhirSource id
       ├─ GET  <EHR>/{Patient,Condition,...}      ─▶ pull each USCDI type (R4)
       └─ POST /fhir-import/R4/{type}             ─▶ convert R4->R5, store as FhirAuxResource
              (header X-JHE-FHIR-Source-ID)          "Conditions: N", "Labs: N", ...

The EHR patient id is stored as a PatientIdentifier (system = the EHR iss, value = the EHR patient id). The client pulls the demo USCDI set (Patient demographics, Condition, MedicationRequest, AllergyIntolerance, lab Observations); each type is fetched and written independently so one failure does not abort the rest. Because the EHR serves R4 and JHE stores R5, each resource is POSTed to the /fhir-import/R4/ endpoint, which converts it via the HL7 cross-version maps and then runs the normal create - landing non-OMH resources in FhirAuxResource, linked to a FhirSource the patient registers on the fly.

Hospital branding / selection (SMART App Launch 2.2)¶

A JHE invitation doesn’t say which hospital the patient uses, so the connect page shows a search box first. This implements SMART 2.2 “user-access brands”.

• Data model (ehr_brand.py): EhrBrand (one per health system: name, vendor, unique fhir_base_url = the SMART iss, npi, logo_url) and EhrBrandLocation (one per facility: name, address_text, city, state, postal_code, FK to brand). Vendor-neutral by design - no Epic-only columns.

• Search API: GET /api/v1/patient-access/brands?q=&state=&postal= (authenticated). q matches facility name, city, or brand name. Returns facilities with the brand’s fhir_base_url.

• Selection: picking a facility calls FHIR.oauth2.authorize({ iss: <brand.fhir_base_url> }). fhir-client.js discovers the authorize/token endpoints from {iss}/.well-known/smart-configuration - so JHE routes purely on the iss, never on hardcoded endpoints.

Seeding + refreshing the brand list¶

manage.py seed loads a small curated sample (core/data/ehr_brands.sample.json) so the picker has data out of the box. For a full list, download a vendor’s user-access Brands Bundle and import it:

# Epic publishes ~94k organizations / ~800 endpoints:
curl -sSL -o epic_brands.json https://open.epic.com/MyApps/Endpoints
docker compose exec web python manage.py import_ehr_brands --file epic_brands.json

The importer is idempotent (brands keyed on fhir_base_url); re-run to refresh.

The full Epic file does not import yet. Epic’s bundle links its organizations to endpoints with urn:uuid references, which the importer does not resolve, so the command above completes with few or no locations. Use the shipped sample until that is fixed - see Out of scope.

Extending to other EHR vendors¶

The importer parses any SMART user-access Brands Bundle, so adding Cerner/Athena/etc. is importing that vendor’s bundle - no code change for search or selection. The one future code change for real multi-vendor auth is a per-vendor client_id (today the single EHR client_id lives in the Patient Access client’s aux_data). If CMS ships its planned national brands directory, point the importer at that instead.

Configuration¶

EHR config (JheClient.aux_data)¶

The seeded Patient Access client carries the EHR config in its aux_data JSON blob. The connect/callback views inject it into the page; fhir-client.js discovers the authorize/token endpoints from {iss}/.well-known/smart-configuration.

{
  "client_id": "<EHR non-production client id>",
  "scopes": "openid profile launch/patient patient/Patient.read patient/Observation.read patient/Condition.read patient/MedicationRequest.read patient/AllergyIntolerance.read"
}

There is no iss in aux_data. The hospital the patient picks supplies it (EhrBrand.fhir_base_url) at authorize time, and the callback reads it back from the authorized server. Only client_id and scopes are configured.

Register the EHR app (one-time, Epic example)¶

Each deploying institution registers its own app at fhir.epic.com; the redirect URI and APIs live on the EHR app, not in JHE.

1. Sign in at fhir.epic.com, Build Apps -> Create. Audience Patients, SMART on FHIR standalone launch, public client (PKCE, no secret).

2. Incoming APIs (R4): Patient.Read, Observation.Search/Read, Condition.Search/Read, MedicationRequest.Search/Read, AllergyIntolerance.Search/Read.

3. Redirect URIs: add, byte-for-byte, your callback URL per environment:

   • Local: http://localhost:8001/clients/patient-access/callback

   • Fly: https://jhe.fly.dev/clients/patient-access/callback

4. Save; copy the issued non-production client id into the JHE config below.

Epic can take ~1-12h to sync a new redirect URI. A redirect_uri mismatch right after editing usually just means it hasn’t propagated yet.

Point JHE at your EHR app¶

docker compose exec web python manage.py shell -c "
from oauth2_provider.models import get_application_model as G
c = G().objects.get(name='Patient Access').jhe_client
c.aux_data['client_id'] = '<your EHR non-production client id>'
c.save()
"

The EHR’s FHIR base URL is not configured here. It comes from the EhrBrand row the patient picks, so import that vendor’s brands bundle instead (see Seeding + refreshing the brand list).

Local setup (Docker)¶

The default Compose stack serves :8001 with SITE_URL=http://localhost:8001. The seed also creates the Patient Access API DataSource (every FhirSource needs one), seeds the sample hospital brands, and wires the Patient Access client to the example patient Peter (ll_patient_peter@example.com), so the flow is testable out of the box.

cd jupyterhealth-exchange
docker compose up --build -d
# wait for the web container's migrate to finish, then seed a clean DB:
docker compose exec web python manage.py seed --flush-db

Verify:

End-to-end test¶

Epic sandbox test patients: https://fhir.epic.com/Documentation?docId=testpatients.

Troubleshooting¶

Out of scope (follow-up)¶

• Full Epic brands import: Epic’s file uses urn:uuid references; the importer resolves the sample’s Organization/<id> style and needs a small tweak to resolve urn:uuid for the full 94k-entry file. Bulk insert for that volume is also a follow-up.

• Production (non-sandbox) EHR app and promotion.

• Per-vendor client_id for simultaneous multi-vendor auth; refresh-token handling.