Epic - Troubleshooting

Most Epic issues come from the setup of the Improvado app in your Epic environment or from the values of the connection. Your Epic team manages the app and gives you the FHIR R4 base URL and the Bulk Data group IDs. The setup guide lists what your Epic team sets up.

The FHIR R4 Base URL or the Bulk Data Group IDs are not accepted

The authorization form accepts an https address that ends in /api/FHIR/R4, such as https://fhir.example.org/api/FHIR/R4, and group IDs made of letters, digits, periods and hyphens, separated by commas. Use the base URL and the group IDs your Epic team gave you.

The address is not the FHIR R4 base URL of an Epic environment

The base URL has the right form, but no Epic FHIR server answers at it, for example because of a typo or a missing part of the path. Check the base URL with your Epic team and connect again.

Epic did not issue Improvado an access token

The Improvado app is not set up in this Epic environment, or its setup is not complete. Epic issues a token only after your Epic team has downloaded the app by the client ID of this environment, mapped it to a background user and configured Improvado's JWK Set URL. A production environment uses the production client ID and a test environment the non-production one. When the setup is complete, connect again, or run the extraction again if the message came from one.

Epic rejects freshly issued access tokens

During an extraction, Epic issued Improvado a new token but did not accept it, for example because the Improvado app is no longer active in this Epic environment. Ask your Epic team to check that the app is still active, then run the extraction again.

Epic refused the Bulk Data export of a group

The message names the group and gives Epic's reason. "Group ID is invalid" means that the ID is not a Bulk Data group of this environment. Check the group IDs with your Epic team and edit the connection.

By default, Epic allows one export of a group in 24 hours. If Bulk Data Resources already exported the group within the last 24 hours, for example in a manual run, that limit can also cause this message or the one about denied access below. Exports of the group work again once 24 hours have passed since the last one.

Epic found no Bulk Data export for a group, or could not find the requested resource

Epic did not find what Improvado asked for at this FHIR server. Check the FHIR R4 base URL and the group IDs of the connection with your Epic team.

Epic denied Improvado's app access

Your Epic team has not authorized the Improvado app for the group or for one of the APIs the app uses. Ask your Epic team to authorize the app for the groups of the connection and for the Bulk Data APIs: kick-off, status, file and delete requests.

Epic left a resource type out of the export, or does not support it

When the Improvado app is not authorized for a resource type, Epic leaves it out of the export, and the extraction stops instead of loading an incomplete export. Ask your Epic team to authorize the app for the search API (R4) of each resource type the message names: Appointment, Encounter, Location or Practitioner.

When the message says that Epic does not support a resource type in Bulk Data exports in this environment, Epic cannot export it there, and the extraction stops for the same reason. Share the message with your Epic team.

Epic could not complete the Bulk Data export

The export failed on Epic's side, and the message gives Epic's reason. The next scheduled run starts a new export. If the error repeats, share the message with your Epic team.

The Bulk Data Resources report has no data in this workspace yet

Appointments, Encounters, Locations and Practitioners read the export that Bulk Data Resources loads, and this workspace has none yet. Set up Bulk Data Resources for the same group, wait until its first load is complete, which takes 30 minutes or more, then run the report type again.

A report type returns no rows

Appointments, Encounters, Locations and Practitioners return no rows for a group that Bulk Data Resources has not loaded yet: they get its data with their next run after that load. Bulk Data Resources returns no rows when the patients of the group have no appointments or visits from the start of the date range on, which is not an error.

Epic stayed unavailable or kept asking Improvado to slow down

Improvado retries when Epic is unavailable or asks it to slow down. When Epic still does not answer after several retries, the extraction stops, and the next scheduled run tries again.