Versions Compared

Old Version 1

changes.mady.by.user Aryn Wiebe

Saved on

compared with

New Version 2

changes.mady.by.user Lianne So

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Need help? Contact us:

...

 

 

The Epic FHIR adapter is designed to provide a template for getting started with Epic FHIR integrations, including:

  1. Authenticating with the Epic FHIR Server via OAuth2.0 using the OAUTH Library. Generating FHIR Resources using the FHIR Library. (JWT)

  2. Performing various interactions against the Epic FHIR Server including create, read, search, and extended $operations.

...

Expand
titleSTEP 3: Configure the ClientId and PrivateKey custom fields and click Edit to open the Translator

Enter the ClientId and PrivateKey certificate path.

Using the information provided, the component will run through the authentication workflow and set the Key and KeyExpiry value of the obtained access token automatically.

Screen Shot 2024-02-21 at 1.04.33 PM.pngImage Removed

store the returned access token and expiry time in an encrypted file for use on subsequent API requests.

image-20240422-202132.pngImage Added

Expand
titleSTEP 4: If needed, use the FHIR Profiling Tool to generate and replace the FHIRresources.lua schema file

The FHIRresources.lua file included in the project contains the schema for a FHIR R4 Patient and Appointment resource. This file can be replaced with the schemas you require.

See FHIR Profiling Tool for how to generate the FHIRresources.lua file containing the FHIR resource schemas you need to create.

Expand
titleSTEP 5: Create and map your FHIR Resource

Using the FHIR Library, FHIRCreate generates an empty FHIR Resource for you to map.

Code Block
languagelua
local NewPatient = FHIRcreate{resource='Patient'}
-- then populate your FHIR resource with data
Expand
titleSTEP 6: View and modify the examples for creating and searching for a patient on the Epic FHIR Server View and modify the examples for creating and searching for a patient on the Epic FHIR Server

Use the provided SamplePatient.json to load a FHIR patient resource. Alternatively, you can explore the FHIR Profiling Tool to generate a template resource you can use to populate with data of your own.

Code Block
-- Load a sample patient
local F = io.open(iguana.projectRoot()..'SamplePatient.json','rb')
local RawPatient = F:read("*a")
F:close()
local NewPatient = json.parse{data=RawPatient}

Set live=true to invoke each the creation interaction.

Code Block
languagelua
-- Create the new patient
E:create{resource="Patient",parameters=NewPatient,live=true}
   
-- Search for our patient
local Search = {
   family = 'Lufhir',  
   given = 'Sakiko',
   birthdate = '1994-07-22'
   }
local Status, R = E:search{resource="Patient",parameters=Search,live=true}

View the resultant patient search in the Annotations:

Screen Shot 2024-02-20 at 4.38.22 PM.png

...

Expand
titleEPICFHIRclient - sets up the adapter framework

Sets up the EPIC FHIR adapter framework, adding the various method modules to a metatable and storing the configurations added to the custom fields.

Expand
titleEPICFHIRcustom - makes API requests and returns the response

EPICcustom takes in any API requests and parameters to make the API call and return the response.

  • First, the function checks if the token key exists or is still valid (based on the key_expiry). If not, it calls EPICFHIRauth to perform the OAuth2.0 authentication workflow to obtain the token to be used in subsequent requests.

  • Uses the passed configurations API request parameters - the method (ex. post), API (ex. Patient) and parameters for the call (ex. the patient resource to be created) - to build and carry out the appropriate HTTP request.

Expand
titleauth/EPICFHIRauth - authenticates with the Epic FHIR Server

The EPICFHIRauth function , builds and makes the HTTP POST token request to obtain the access token required for any resource requests against the FHIR Server.

A separate CreateJWT EPICFHIRcreateJWT function creates the JSON Header and Payload components of the JWT and calls the OAUTH Library EPICFHIRjwt to sign and return the JWT required for the token request.

If the token requests is successful (HTTP 200 response), the token and token expiry returned are set to the Key and KeyExpiry custom fields respectivelystored in the adapter object (key and key_expiry) and saved in an encrypted file via EPICFHIRencrypt.

EPICcustom takes in any API requests and parameters to make the API call and return the response.

  • First the function checks if the token Key exists and performs the OAuth2.0 authentication workflow to obtain the token to be used in subsequent requests.

  • Uses the passed configurations API request parameters - the method (ex. post), API (ex. Patient) and parameters for the call (ex. the patient resource to be created) - to build and carry out the appropriate HTTP request.

    • For resiliency, the Retry Library is used to retry any failed attempts and the response is handled and returned
    Expand
    titleEPICFHIRcustom - makes API requests and returns the response
    auth/EPICFHIRencrypt - stores and encrypts the API token and token expiry

    EPICFHIRencrypt provides localized https://interfaceware.atlassian.net/wiki/x/EQCeqg functionality via save and load functions that encrypt and decrypt the provided API token and expiry time in an external file. This allows the token to be reused for subsequent API calls.

    Expand
    titleauth/EPICFHIRjwt - takes the provided parameters and private key to generate and sign the JWT token

    EPICFHIRjwt provides localized OAUTH Library functionality. It takes the provided JWT header, JWT payload, signing algorithm, and private key to generate and sign the JWT token.

    Expand
    titlemethod/EPICFHIRcreate - prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Create request

    EPICFHIRcreate prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Create HTTP POST request.

    Expand
    titlemethod/EPICFHIRsearch - prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Search request

    EPICFHIRsearch prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Search HTTP GET request.

    Expand
    titlemethod/EPICFHIRreadResource - prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Read request

    EPICFHIRreadResource prepares the API endpoint and arguments to call EPICFHIRcustom for an FHIR Resource Read HTTP GET request.

    Expand
    titlemethod/EPICFHIRoperation - prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Extended Operation request

    EPICFHIRoperation prepares the arguments and calls EPICFHIRcustom for an FHIR Resource Create HTTP GET or POST request.

    A FHIR operation is extended functionality unique across FHIR Servers. Extended operations on a resource use a $ in front of the operation. For example, when calling EPICFHIRcustom, the passed api argument may be “Patient/$match“ to perform a more detailed patient matching search.