Epic

Description

Epic is an electronic health record (EHR) system that hospitals and health systems use to run clinical care and operations.

Setup guide

1Ask your Epic team to set up the Improvado app in the Epic environment you want to connect. The app reads appointments, encounters, locations and practitioners, read-only and with no user sign-in. Your Epic team:

• downloads the app by its client ID, d5bd36bb-23a2-428f-a092-2c64e3cd90c4 in a production environment or b9f5873a-69d7-4687-a30b-d41696bf2ce8 in a non-production (test) environment, and allows the read-only APIs listed on it;
• maps the client ID to a background user, the Epic user account under which Epic audits the app's requests;
• configures Improvado's JWK Set URL, where Epic reads the public keys that verify the app. For the non-production client ID it is https://improvado.io/.well-known/jwks/epic-fhir-nonprod.json; for the production client ID, ask Improvado support for it;
• builds the Bulk Data groups of patients Improvado may export and gives you their FHIR IDs. Epic recommends groups of 1,000 patients or fewer.

Epic issues the app no access token until this setup is complete. Epic describes the setup in Implementing Apps at Epic Customers.

2Get the FHIR R4 base URL of the environment from your Epic team. It ends in /api/FHIR/R4, and production and test environments have different base URLs. Epic lists the production base URLs that organizations publish in its endpoint directory.

3In the authorization form, paste the base URL into the FHIR R4 Base URL field, enter the group IDs separated by commas into the Bulk Data Group IDs field and click Connect. A connection reads one environment: connect production and test environments separately. The connection is named after your FHIR server, with (non-production) added for a test environment.

4When the connection status is Active, each Bulk Data group is an account, named Group <group ID> on <connection name>. To add a group later, edit the connection and add its ID to Bulk Data Group IDs.

5For each group, set up the Bulk Data Resources report type first, following the instructions on how to set up data extraction, and keep its Resource (JSON) field selected: the other report types read it. Bulk Data Resources is the only report type that requests data from Epic. Once a day it exports the group's appointments and visits dated from the start of the date range on, future ones included, with the locations and practitioners they refer to.

6When Bulk Data Resources has loaded a group, set up Appointments, Encounters, Locations and Practitioners for the same group. They read the export Bulk Data Resources loaded and send no request to Epic. Until Bulk Data Resources has loaded the group, they stop with a message asking for it or return no rows.

Schema information

The schema information shows all report types you can use to extract data from Epic.

Limits

Patient data. Patients appear only by their Epic FHIR ID, and visits by Epic's contact serial number (CSN), which links an appointment to its encounter. In Appointments and Encounters, Patient ID and Contact Serial Number are marked as personal data and not selected by default. Bulk Data Resources keeps both inside Resource (JSON), which is marked as personal data too. Names and other identifiers of patients and relatives, narratives, comments, notes, patient instructions, visit reasons and diagnoses are not extracted. See how to work with PII fields.

Practitioner details. In Practitioners, gender, birth date, photo links, contact points, addresses and the full list of identifiers are marked as personal data and not selected by default.

One export per group a day. By default, Epic allows one Bulk Data export of a group in 24 hours, so it can refuse a second run of Bulk Data Resources for the same group within that time, such as a manual run or a historical load next to the scheduled run. Your Epic team can configure more frequent exports. None of the report types shows a data preview: for Bulk Data Resources, a preview would use the group's export of the day.

Export time. An export takes 30 minutes or more: Improvado checks its status every 30 minutes, as Epic recommends for groups of more than 100 patients.

Dates and times. Bulk Data Resources selects appointments and visits by date, from the start of the date range on, with no end date, so a new booking arrives with the next export. By default, scheduled extractions start 14 days back: a change Epic records to an older appointment or visit reaches your data when an extraction covers its date again, such as a historical load. A visit that started before the date range, such as an outpatient visit Epic still shows as open, may not be exported until a date range reaches its start. Times are in UTC.

Reading the export. Appointments, Encounters, Locations and Practitioners return everything Bulk Data Resources has loaded for the group, so its date range decides which appointments and visits you get. Each of their runs reads the latest load: today's export reaches them with their next run after it.

Coverage. Epic has no API that lists all appointments of a hospital, so the data covers the patients of the groups your Epic team builds. Locations and Practitioners include only the locations and practitioners that the group's appointments and visits refer to, and for locations the locations they sit under, not every location or practitioner of the hospital. A location or practitioner keeps its last loaded row when a later export no longer includes it.

Release notes

Epic lists the non-backwards-compatible changes to its certified APIs from the past year in its API Change Log.

Troubleshooting

Having trouble with your setup? Find solutions to common issues →