Aller au contenu principal

Epic FHIR

Category: EHR & Practice Mgmt
Node id: epic-fhir

Standards: HIPAA, GDPR, SOC2

Integrates with Epic EHR via FHIR R4 and SMART on FHIR authentication for patient data retrieval

What it does​

  • SMART on FHIR OAuth2 client credentials authentication
  • FHIR R4 search with configurable parameters and pagination
  • Patient-specific search by name, birthdate, MRN, or identifier
  • $everything operation for complete patient data retrieval
  • Resource categorization by type from Bundle responses
  • Epic-specific MRN system identifier support

Use cases​

  • Sync patient demographics from Epic to a data warehouse
  • Retrieve complete patient records via $everything for analytics
  • Search Epic for patients by MRN in clinical integration pipelines
  • Feed Epic clinical data into FHIR-to-OMOP transformation nodes

Runtime​

  • Performance tier: variable

Input ports​

NameTypeRequiredDescription
search_paramsjsonNoFHIR search parameters
resource_idtextNoFHIR resource ID for read operation
patient_idtextNoPatient ID for patient_everything operation
family_nametextNoPatient family name (for patient_search)
given_nametextNoPatient given name (for patient_search)
birthdatetextNoPatient birthdate in YYYY-MM-DD format
identifiertextNoPatient identifier
mrntextNoMedical Record Number

Output ports​

NameTypeRequiredDescription
resultjsonNoMain result data from the Epic FHIR operation
metadatajsonNoResponse metadata including resource type, counts, and operation details
successbooleanNoWhether the operation succeeded

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Epic Base URLepic_base_urlstringYesEpic base URL (e.g., https://fhir.epic.com/interconnect-fhir-oauth)
OperationoperationenumNosearchsearch, read, patient_search, patient_everything, interactFHIR operation to perform
Resource Typeresource_typestringNoPatientFHIR resource type
InteractioninteractionenumNosearchread, search, history, operation, create, update, patch, deleteFHIR interaction for the 'interact' operation
FHIR Versionfhir_versionenumNoR4R4FHIR version path segment

Auth​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Client IDclient_idsecretNoEpic OAuth2 client ID
Client Secretclient_secretsecretNoEpic OAuth2 client secret
Auth Modeauth_modeenumNoclient_secretbackend_jwt, client_secret, injected_token, external_authHow to authenticate the 'interact' operation
External Auth Connection IDconnection_idstringNoUUID of the stored Epic connection in External Auth; the node mints the token from your stored cert (auth_mode=external_auth)
Bearer Tokenbearer_tokensecretNoPre-obtained access token for auth_mode=injected_token (or pass via the bearer_token input)
RS384 Private Key (PEM)private_key_pemsecretNoBackend Services signing key; delivered via secret reference, never logged
Key ID (kid)kidstringNoJWKS key id for the signing key
JWT Algorithmjwt_algenumNoRS384RS384, ES384Client-assertion signing algorithm
Token URLtoken_urlstringNoExplicit token endpoint (else discovered from iss/.well-known)
Issuer / BaseissstringNoIssuer base for .well-known endpoint discovery (defaults to epic_base_url)
SMARTv2 Scopesscope_v2booleanNofalseEmit granular SMARTv2 scopes (rs/cruds) instead of v1 (read/write)

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Resource IDresource_idstringNoFHIR resource ID (for read operation)
Patient IDpatient_idstringNoPatient ID (for patient_everything operation)
Search Parameterssearch_paramsjsonNoFHIR search parameters
CountcountnumberNoNumber of results to return
OffsetoffsetnumberNoOffset for pagination
MRN Systemmrn_systemstringNourn:oid:1.2.840.114350.1.13.0.1.7.5.737384.0Epic MRN system identifier
Start Datestart_datestringNoStart date for $everything operation (YYYY-MM-DD)
End Dateend_datestringNoEnd date for $everything operation (YYYY-MM-DD)
Resource IDinteraction_resource_idstringNoTarget id for read/history/operation interactions
Operation Nameoperation_namestringNosummary$operation name for interaction=operation. Epic R4 supports summary and match (NOT everything); use a Group $export for bulk
Max Pagesmax_pagesnumberNo1Max pages to follow for interaction=search
Dry Rundry_runbooleanNofalseFor write interactions: build the request but do not send it
Resource Bodyresource_bodyjsonNoFHIR resource payload for write interactions (preview only in this version)

Errors​

CodeDescription
EPIC_AUTH_FAILEDFailed to obtain OAuth2 token from Epic
EPIC_SEARCH_FAILEDEpic FHIR search returned an error
EPIC_READ_FAILEDEpic FHIR read returned an error
PATIENT_ID_REQUIREDpatient_id is required for patient_everything operation
RESOURCE_ID_REQUIREDresource_id is required for read operation
EPIC_WRITE_REQUIRES_APPROVALWrite interaction blocked: enable dry_run to preview; real writes require the clinical-safety gate
EPIC_UNSUPPORTED_OPERATIONThe requested interaction is not supported

Runtime notes​

  • Output has BOTH result and metadata as separate top-level keys — metadata is NOT inside result. Wire metadata for counts, result for data.
  • patient_search returns result.patients (extracted Patient resources array) in addition to result.bundle for convenience.
  • patient_everything returns result.resources categorized by resourceType, with a _counts key summarizing each type. Access like result.resources.Condition.
  • OAuth2 token is obtained automatically via client credentials flow on every execution — no manual token management needed.

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.