Epic Tips & Tricks

[mikix]

Hello 👋! Are you an Epic customer using Cumulus (or just doing bulk exports on your own)? Hopefully this collection of tips will help.

This post is aiming to be a living document - please reply with new suggestions or edits. 🙏

Frequent Bulk Exporting

You may encounter this error:

Error processing Bulk Data Kickoff request: Request not allowed: The Client requested this Group too recently..

If so, you will want to update the FHIR_BULK_CLIENT_REQUEST_WINDOW_TBL to a longer time. The default is 24 hours.

Long IDs

In rare cases, Epic's bulk FHIR export can generate IDs that are longer than the mandated 64-character limit. Cumulus ETL itself will not mind this, but if you use another bulk export client, you may find that it complains. If so, you have to reach out to Epic to cap it at 64 characters (there is a toggle for this when you register your API client).

Condition API Errors

Epic's bulk export for Conditions will give errors even for API types you haven't been given access to. For example, even if you do not have access to the Dental Finding Condition API, Epic's export will attempt to access those records behind the scenes and give you errors.

That's fine and expected - just ignore the errors.

Batch Updates

Epic has not yet implemented the _since parameter for bulk exports, but it has implemented _typeFilter! It's recommended to use it to specify a date range, to reduce the size of the export, since Epic can be very slow.

Something like:

https://host/path/$export?_type=Encounter&_typeFilter=Encounter?date=ge2020-01-01T00:00:00Z&date=lt2021-01-01T00:00:00Z

Initial Import

For performance reasons, you don't want to try to export your whole history in one go.

Instead, you should add a date range to your registry and start at the earliest date possible. Run Cumulus ETL and once you confirm it works, slide your registry range (or your _typeFilter window) forward. Rinse and repeat until you have imported all your data.

Incremental Updates

When running Cumulus on a regular ongoing basis, make sure you update your registry to slide your date range forward (or slide your _typeFilter date window forward) before running Cumulus ETL.

Versioning of Updates

Epic does not provide metadata about when each record was last updated (i.e. does not populate the meta.lastUpdated FHIR field).

Which means that Cumulus ETL has no way of knowing when one batch of data is more up-to-date than another. This is fine, it just means that you should run the ETL on the results of exports in the order that you exported them.

That is, if you exported patients both last week and today, you should run the ETL first on last week's batch, and then on today's. Otherwise, the ETL will accidentally overwrite today's patient data with last week's patient data (for any patients in both exports).

API Access

Epic will ask you for a list of APIs / resources to enable. Here is the currently recommended list to request. If you have suggestions for edits, please send them in.

• AllergyIntolerance.Search (R4)
• Binary.Read (Clinical Notes) (R4)
• Bulk Data Delete Request
• Bulk Data File Request
• Bulk Data Kickoff
• Bulk Data Status Request
• Condition.Search (Encounter Diagnosis) (R4)
• Condition.Search (Health Concern) (R4)
• Condition.Search (Infection) (R4)
• Condition.Search (Medical History) (R4)
• Condition.Search (Problems) (R4)
• Condition.Search (Reason for Visit) (R4)
• Device.Search (External Devices) (R4)
• Device.Search (Implants) (R4)
• DiagnosticReport.Search (Results) (R4)
• DocumentReference.Search (Clinical Notes) (R4)
• Encounter.Search (Patient Chart) (R4)
• Immunization.Search (R4)
• Medication.Read (R4)
• MedicationRequest.Search (Signed Medication Order) (R4)
• Observation.Search (Labs) (R4)
• Observation.Search (Social History) (R4)
• Observation.Search (Vitals) (R4)
• Procedure.Search (Orders) (R4)
• Procedure.Search (Surgeries) (R4)
• Procedure.Search (Surgical History) (R4)
• ServiceRequest.Search (Dental Procedure)
• ServiceRequest.Search (Order Procedure) (R4)
• ServiceRequest.Search (Pregnancy Plans) (R4)
• Patient.Search (R4)

[wfclark5]

Do you have the command that would be needed to run the bulk export on an EPIC FHIR server?

[mikix]

I haven't done an Epic export myself yet, but this is what I use for a Cerner export (using Cumulus ETL), with redacted values:

docker run
  --rm \
  -v $HOME/export-testing/:/inside/
  smartonfhir/cumulus-etl \
  export \
  https://fhir-ehr-code.cerner.com/r4/xxx/Group/xxx \
  /inside/results/ \
  --smart-client-id xxx \
  --smart-jwks /inside/cerner.jwks \
  --task patient

I believe Epic likes to pull the jwks file from a public URL though, so you can probably drop that argument?

[wfclark5]

Okay got it, thank you! EPIC works best with OAUTH2 authentication with a bearer token. Is that a possibility?

[mikix]

Ah yeah, there's a --bearer-token PATH argument you can use in that case. (See --help for all the options)

[mikix]

The example above uses --task patient which is a short hand for exporting Patient resources, but you can also specify all the normal bulk export args like:

docker run
  --rm \
  -v $HOME/export-testing/:/inside/
  smartonfhir/cumulus-etl \
  export \
  https://fhir-ehr-code.cerner.com/r4/xxx/Group/xxx/$export?_type=Patient \
  /inside/results/ \
  --bearer-token /inside/epic-bearer.txt