EPIC INTEGRATION GUIDE FOR

DEVELOPERS

Atiq Tahir
COGNITIVE HEALTH INTERNATIONAL Islamabad
Table of Contents

EXECUTIVE SUMMARY ................................................................................................................... 1

1. INTRODUCTION....................................................................................................................... 2

2. APPLICATIONS ON EPIC APP MARKET...................................................................................... 2

3. SYSTEM ARCHITECTURE .......................................................................................................... 3

4. EPIC TELECONSULT SERVER (ETS) ............................................................................................ 4

4.1 EPIC LAUNCHES & OAUTH 2.0 SIMPLIFIED...................................................................................... 5

4.2 ETS CODE STRUCTURE................................................................................................................ 6
4.3 PATIENT LAUNCH WORKFLOW ..................................................................................................... 8
4.4 PROVIDER LAUNCH WORKFLOW ................................................................................................... 9
4.5 DIRECT LAUNCH WORKFLOW ......................................................................................................10

5. TESTING USING EPIC SIMULATOR ...........................................................................................11

5.1 TESTING PROVIDER LAUNCH .......................................................................................................11

5.2 TESTING PATIENT LAUNCH..........................................................................................................12

6. TESTING USING EPIC MYCHART WEB APPLICATION ................................................................13

6.1 SCHEDULING NEW APPOINTMENT................................................................................................13

6.2 JOINING A SCHEDULED VIDEO VISIT ..............................................................................................13

7. EPIC API REFERENCE ...............................................................................................................17

7.1 CONNECT (2021) .....................................................................................................................17

7.2 DISCONNECT (2020) .................................................................................................................19
7.3 STOREAUDIOVIDEOTESTRESULT (2021) .......................................................................................20
7.4 GETTELEHEALTHDIRECTLAUNCHTOKEN ........................................................................................23
7.5 TELEMEDICINECONFIGURATION (2021) ........................................................................................24
Executive Summary
This document presents all the workflows, code and other related logic to integrate CHI
Teleconsult with Epic Video Visit. All the integration logic is wrapped around different
endpoints of the underlaying web server.
Target audience of this document could be any developer with good understanding of:
• Python
• Tornado Web Server
• CHI Web Server Architecture
This document explains the code and logic of the Epic Teleconsult Server (ETS) on frozen code
tag v2.0-stable. Changes to the ETS code will be reflected in other versions of this
document.

December 18, 2022 1

1. Introduction
Epic integration can be simply Video Visit Integration or it can be a more complex integration
where we can schedule new appointments for the patients, push patient vitals, physician
orders to Epic etc. This document focuses only on Video Visit Integration.
All the workflows, code references etc. given in this document are taken from the frozen code
with tag v2.0-stable of the git repository.

2. Applications on Epic App Market

Applications on Epic App Market serve three purposes:
1. Appear in Epic Apps listing and act as a marketing tool
2. Provide Epic API and usage details to concerned customers
3. Provide an Epic-App-ID for the App which is used by our backend services for different
API calls to Epic
For complete Video Visit workflow integration with Epic, we need to submit one primary app
and three sub-apps to Epic App Market. Only the primary app appears in the listing and the
three sub-apps are used just to qualify for the Epic API usages and Epic-App-ID. Following four
apps have been submitted to Epic App Market (of which first one is the primary app)
1. CHI Teleconsult
Primary app on Epic App Market, provides Provider API access and Epic-App-ID to
handle provider side launches.
2. CHI Teleconsult – Backend
Provides API access for backend services, including OAuth for backend.
3. CHI Teleconsult – Patient
Provides API access for patients and Epic-App-ID to handle patient side launches
4. CHI Teleconsult – Patient Contact
Provides API access and Epic-App-ID for direct launches including patient launches
without MyChart account and patient contact launches.

December 18, 2022 2

3. System Architecture
Figure 1 explains the entire system architecture. CHI Teleconsult consists of two major system
components:
1. Epic Teleconsult Server (ETS)
2. Media Servers
Patients access the Teleconsult Application (TA) on their mobiles or desktop browsers from
ETS. Doctors/Providers access the Teleconsult Application via EHR from ETS. Media Server
relays the live audio and video streams to the call participants. ETS is the only system
component which interacts with Epic deployment.
The platform can be deployed in a variety of ways like:
• Everything on premises
• Everything in the cloud
• Mixed mode with some components on the premises while others in the cloud.

Figure 1: System Components of the Teleconsult Workflow

December 18, 2022 3

4. Epic Teleconsult Server (ETS)
Epic Teleconsult Server acts as the main controller providing public/private interfaces and
APIs. It consists of different interconnected components, some of the important components
are:
• Patient/Provider Launch Points
• Patient/Provider API End Points
• Admin Portal & API End Points
• Different backend services & Integrations
For interconnection details please refer to Figure 2. ETS components can run as service on
bare-metal and virtualised servers. We prefer running the components in containers using
docker. Each component is described in detail under forthcoming subsections.

Figure 2: Epic Teleconsult Server

December 18, 2022 4

4.1 Epic Launches & OAuth 2.0 Simplified
All Epic endpoints use Single Sign On (SSO) using OAuth 2.0, for reference please see OAuth
2.0 Tutorial under Epic documentation. Everything starts from Epic, Table 1 lists all the
launches currently supported by ETS.
Table 1: ETS Supported Launches

Launch Teleconsult Platform

Provider launching from Hyper Drive Web App
Patient launching from MyChart Web App Web App
Patient launching from MyChart Mobile App Mobile SDK
Patient directly launching Call URL from SMS or text message on
Web App
mobile or desktop
Patient Contact directly launching Call URL on mobile or desktop Web App

For any of the above launches, the user needs to be authenticated and the conference Id
needs to be validated to ensure it exists and is linked to the launching user.
The ultimate target of the SSO OAuth process is to get the Access Token from Epic for the
launching user. This token is then used in all Epic API calls.
For end user, OAuth is a two-step process, in the first step the user comes to one of the above
launch points with parameters listed in Table 2. The backend determines Epic SSO URL and
redirects the user to it after saving launch state. If SSO is successful on Epic side, the user
returns back to the same launch point with parameters listed in Table 3. This is step two, here
we fetch Access Token from Epic using the code and then create our own Auth Token.

Table 2: Launch step parameters

Parameter Details Is Optional?

launch Simulator/Hyperspace launch parameter Yes if djt is present
djt Epic Telehealth Token Yes if launch is present
iss No

Table 3: Authorize phase parameters

Parameter Details Is Optional?

state Launch state saved in step-1 No
Authorization code used to fetch Access
code Yes, if error else No
Token
error True if Auth error on Epic side Yes
error_description Error message from Epic Yes

December 18, 2022 5

4.2 ETS Code Structure
Figure 3 presents the directory structure of the code. The main Tornado Web Application
(TWA) inherits from EpicBackendBase which contains Epic specific configuration attributes
and utility methods. Details of other classes is listed in Table 4.

Figure 3: ETS Code Structure

December 18, 2022 6

Table 4: ETS Code – Class Details

Class Details
Contains static methods for calling Epic APIs like Connect
EpicClient
(2021), Disconnect and Utility methods to process launch.
Contains static utility methods to transform Epic Ids and lower
EpicHelper
level calls to Epic API.
inherits BaseApiHandler and contains method like Connect,
EpicClientApiHandler
Disconnect, RecordingStarted etc.
inherits EpicClientApiHandler with methods like GetToken,
EpicPatientApiHandler Launch which are used for getting token from epic and
processing launch respectively.
More to be done

December 18, 2022 7

4.3 Patient Launch Workflow
Patient launch follows the steps described in OAuth (section 4.1). this workflow uses Epic-
Client-Id from CHI Teleconsult – Patient app. Once the call flow starts, ETS calls other Epic
APIs which are listed in a separate section.
Table 5 lists all the Epic APIs that are called. In current implementation, we don’t need to call
the Connect API because when the patient is authenticated Epic backend auto calls Connect
API and marks the patient status as connected. This behavior may change in production
deployments of Epic requiring us to make code changes in ETS.
Table 6 lists all the registered endpoints for patient (sandbox and production).

Figure 4: Patient Launch Workflow

Table 5: Epic APIs used for Patient Launch

Sr# Epic APIs

1 Connect (2021)
2 Disconnect (2020)
3 StoreAudioVideoTestResult (2021)
4

December 18, 2022 8

 TelemedicineConfiguration (2021)
Table 6: Patient Launch Registered End Points

URL Production
https://teleconsult.cognitivehealthintl.com/ep/patient/Launch No
https://teleconsult.cognitivehealthintl.com/ep/patient/HardwareTest No
https://teleconsult.cognitivehealthintl.com/ep/patient/DirectLaunch No
https://teleconsult-prod.cognitivehealthintl.com/ep/patient/Launch Yes
https://teleconsult-prod.cognitivehealthintl.com/ep/patient/HardwareTest Yes
https://teleconsult-prod.cognitivehealthintl.com/ep/patient/DirectLaunch Yes

4.4 Provider Launch Workflow

Provider launch workflow is same as for patient with just one change that is, in this launch
Epic-Client-Id is taken from CHI-Teleconsult app.
Table 7 lists all the Epic APIs called during different stages of provider launch and provider call
state workflow. This uses one additional Epic API (SaveMedia), which is called with the call
recording media (if there has been one or more recording for the call).
Table 7: Epic APIs used for Provider Launch

Sr# Epic APIs

1 Connect (2021)
2 Disconnect (2020)
3 StoreAudioVideoTestResult (2021)

4
TelemedicineConfiguration (2021)
5 SaveMedia

Table 8: Provider Launch Registered End Points

URL Production
https://teleconsult.cognitivehealthintl.com/ep/provider/Launch No
https://teleconsult.cognitivehealthintl.com/ep/provider/DirectLaunch No
https://teleconsult-prod.cognitivehealthintl.com/ep/provider/Launch Yes
https://teleconsult-prod.cognitivehealthintl.com/ep/provider/DirectLaunch Yes

December 18, 2022 9

4.5 Direct Launch Workflow
Direct Launch option is available for all the three types of users (Provider, Patient and Patient
Contact). In Figure 5 Direct Launch EP and Launch EP represent respective user launch
endpoints. The major difference in this workflow is fetching the Direct Launch Token from
Epic which needs Backend Token.

Figure 5: Direct Launch Workflow

December 18, 2022 10

5. Testing using Epic Simulator
Patient and provider launches can be tested using Epic Simulator. Before running any test
make sure you have selected:
1. Correct Epic Version
2. Patient and its appointment
5.1 Testing Provider Launch
To test provider launch, follow the steps below:
1. Create new Simulator
2. Select CHI Teleconsult App
3. Set the development launch endpoint. This is usually
https://teleconsult.cognitivehealthintl.com/ep/provider/Launch
4. Set the context parameters as listed in Table 9.
5. Save the Simulator

Figure 6: Provider Launch Test in Epic Simulator

Table 9: Provider Launch Parameters

Name Value Details

patient_id %PATID%
employee_id %USERPROVFHIRID%
csn %CSN%
conference_id %CONFERENCEID%
Note: Parameters names and values are case sensitive.

December 18, 2022 11

5.2 Testing Patient Launch
To test patient launch, follow the steps below:
1. Create new Simulator
2. Select CHI Teleconsult – Patient App
3. Set the development launch endpoint. This is usually
https://teleconsult.cognitivehealthintl.com/ep/patient/Launch
4. Set the context parameters as listed in Table 10
5. Save the Simulator

Figure 7: Patient Launch Test in Epic Simulator

Table 10: Patient Launch Parameters

Name Value Details

patient_id %PATID%
csn %CSN%
conference_id %CONFERENCEID%
Note: Parameters names and values are case sensitive.

December 18, 2022 12

6. Testing using Epic MyChart Web Application
MyChart Web Application can be accessed on following URL:
https://appmarket.epic.com/mychart-amcurprd/
Get MyChart username and password from your manager. Once logged in, go to Visits (see
Figure 8 and Figure 9).

Figure 8: MyChart Appointments and Visits – No Upcoming Visit

6.1 Scheduling New Appointment

To schedule a new appointment, click on Schedule an appointment button (see Figure 8),
new screen will appear to schedule the appointment (see Figure 10). Press the Schedule
button under CHI Video Visit with Video Visit Physician section. On the next screen select
time of the appointment. On the next Screen for State or territory field select Wisconsin (see
Figure 11) and press Confirm button. On the next screen enter your comments and press the
Schedule it button (See Figure 12).
6.2 Joining a Scheduled Video Visit
To join the video visit, select the target appointment from Visits screen (see Figure 9), video
visit details screen will appear (see Figure 13). Here press the Join video visit button, this will
open new window (or browser tab) taking you to the CHI Video Visit page.

December 18, 2022 13

Figure 9: MyChart Appointments and Visits – With Upcoming Visit

Figure 10: Schedule an appointment

December 18, 2022 14

Figure 11: Schedule an appointment – Select State

Figure 12: Schedule an appointment – Last Step

December 18, 2022 15

 Figure 13: Joint Video Visit

Testing using Epic MyChart Mobile Application

TBD

December 18, 2022 16

7. Epic API Reference
7.1 Connect (2021)
General Information
API Type: Epic Private Class C / Write
API Group: Connect (2021)
Namespace: Epic.Telemedicine.External
First Available Epic Version: May 2021
Http Method: GET
Url Template: /api/epic/2021/Telehealth/External/Connect?
AdditionalInfo={AdditionalInfo} &Browser={Browser}
&BrowserVersion={BrowserVersion} &OS={OS}
&OSVersion={OSVersion} &Device={Device}
Supported Web Service Types: REST
Supported OAuth 2.0 User Clinicians, Staff, or Administrative Users, Patient Contacts,
Types: Patients

Description
This web service is used to connect users to a video visit in Epic.
Vendors can specify a connect comment, user browser, user browser version, user operating
system, user operating system version, and user device to identify patterns in hardware
failures.
This web service can be used only with the OAuth2 telemedicine context-aware linking APIs.
It will require only an OAuth2 access token generated specifically for Telehealth and will not
have any additional properties.
This API requires a MyChart account.

Request:

/api/epic/2021/Telehealth/External/Connect?Browser=1&BrowserVersion=10.0.1
&OS=2&OSVersion=12.1&Device=iPhone%2011%20Pro%20Max

Request Elements
Is Is
Name Description
Optional Array
Any free text information to store
AdditionalInfo (String) true false
alongside the result of the test.
The browser being used for the hardware
Browser (Int32) test: true false

December 18, 2022 17

 Is Is
Name Description
Optional Array
• 1-Chrome
• 2-Edge
• 3-Safari
• 4-Firefox
• 5-Internet Explorer
• 6-Other

The version of the browser being used for

BrowserVersion (String) true false
the hardware test.
The device being used for the hardware
Device (String) true false
test.
The operating system being used for the
hardware test:

• 1-Windows
• 2-Mac
OS (Int32) true false
• 3-Linux
• 4-Android
• 5-iOS
• 6-Other

The version of the operating system being

OSVersion (String) true false
used for the hardware test.

Response:

{
AdditionalInfo: “could not detect webcam”,
Browser: [1],
BrowserVersion: “10.0.1”,
OS: [2],
OSVersion: “12.1”,
Device: “iPhone 11 Pro Max”
}

Faults:

Alias Description

INVALID-TOKEN The OAuth2 token was invalid for this web service.

INVALID-BROWSER An invalid value was passed for browser.

INVALID-OPERATING-SYSTEM An invalid value was passed for operating system.

December 18, 2022 18

7.2 Disconnect (2020)
General Information
API Type: Epic Private Class C / Write
API Group: TelemedicineDisconnect
Namespace: Epic.Telemedicine.External
First Available Epic Version: November 2020
Http Method: POST
Url Template: api/epic/2020/Telehealth/External/Disconnect?
DisconnectInstantUtc={DisconnectInstantUtc}&
DoNotEndAppointment={DoNotEndAppointment}
Supported Web Service Types: REST
Supported OAuth 2.0 User Clinicians, Staff, or Administrative Users, Patient Contacts,
Types: Patients

Description
This web service is used to disconnect users from a video visit in Epic. This service is similar to
the August 2018 version of Disconnect, but it allows the system to more accurately specify
when the user disconnected. This API requires a MyChart account.

Request:

https://apporchard.epic.com/interconnect-aocurprd-oauth/api/epic/2020/Tele
health/External/Disconnect?DisconnectInstantUtc=2020-05-22T17:31:06Z&DoNot
EndAppointment=true

Request Elements
Is Is
Name Description
Optional Array
The instant the disconnection
occurred. If left blank, the disconnect
DisconnectInstantUtc is logged for the current instant. This
true false
(String) should be an ISO 8601 formatted UTC
instant string (YYYY-MM-
DDThh:mm:ssZ).
If set to true, Epic does not update the
DoNotEndAppointment
appointment status after true false
(Boolean)
disconnecting.

Response:

This web service has an empty response. The status of the request is determ
ined by the status code. 200 means success, anything else means failure.

December 18, 2022 19

Faults:

Code Description

INVALID-INSTANT The value provided for DisonnectInstantUtc was not a properly formatted
ISO-8601 UTC instant string.

7.3 StoreAudioVideoTestResult (2021)

General Information
API Type: Epic Private Class C / Write
API Group: StoreAudioVideoTestResult (2021)
Namespace: Epic.Telemedicine.External
First Available Epic Version: May 2021
Http Method: POST
Url Template: /api/epic/2021/Telehealth/External/StoreAudioVideoTestResult?
Success={Success}&
AdditionalFailureInfo={AdditionalFailureInfo}&
Browser={Browser}& BrowserVersion={BrowserVersion}&
OS={OS}& OSVersion={OSVersion}&Device={Device}
Supported Web Service REST
Types:
Supported OAuth 2.0 User Clinicians, Staff, or Administrative Users, Patient Contacts,
Types: Patients

Description
This web service allows a context-aware linking video vendor to send hardware test results
back to Epic for video visits. It can be used to send both successes and failures, as well as
details of why a test failed.
This web service can be used only with the OAuth2 telemedicine context aware linking APIs.
SetExternalConnectionStatus, a web service that many vendors use, will not work with this web
service.

Request:

/api/epic/2021/Telehealth/External/StoreAudioVideoTestResult?Success=false
&AdditionalFailureInfo=could%20not%20detect%20webcam&Browser=1&BrowserVers
ion=10.0.1&OS=2&OSVersion=12.1&Device=iPhone%2011%20Pro%20Max
{
Failures: [2],
}

December 18, 2022 20

Request Elements
Is Is
Name Description
Optional Array
AdditionalFailureInfo Any free text information to store alongside
true false
(String) the result of the test.
The browser being used for the hardware
test:

• 1-Chrome
• 2-Edge
Browser (Int32) true false
• 3-Safari
• 4-Firefox
• 5-Internet Explorer
• 6-Other

BrowserVersion The version of the browser being used for

true false
(String) the hardware test.
The device being used for the hardware
Device (String) true false
test.
Indicates all failures that occurred. The
failure values are:

• 0-Passed Hardware test

• 1-Failed Hardware Test - Generic
Failures (Int32) • 2-Failed Hardware Test - Camera true false
• 4-Failed Hardware Test -
Microphone
• 8-Failed Hardware Test - Speaker
• 16-Failed Hardware Test - Network

The operating system being used for the

hardware test:

• 1-Windows
• 2-Mac
OS (Int32) true false
• 3-Linux
• 4-Android
• 5-iOS
• 6-Other

The version of the operating system being

OSVersion (String) true false
used for the hardware test.
Success (Boolean) True if the test passed, false if it failed. false false

December 18, 2022 21

Response:

{
Success: false,
Failures: [2],
AdditionalFailureInfo: “could not detect webcam”,
Browser: [1],
BrowserVersion: “10.0.1”,
OS: [2],
OSVersion: “12.1”,
Device: “iPhone 11 Pro Max”
}

Faults:

Alias Description

INVALID-TOKEN The OAuth2 token was invalid for this web service

INVALID-USER-ID-TYPE The OAuth2 token was invalid for this web service

INVALID-USER-ID The OAuth2 token was invalid for this web service

INVALID-HARDWARE-TEST-STATUS An invalid value was passed for the list of failures

INVALID-BROWSER An invalid value was passed for browser

INVALID-OPERATING-SYSTEM An invalid value was passed for operating system

December 18, 2022 22

7.4 GetTelehealthDirectLaunchToken
General Information
API Type: Epic Private Class B / Read
API Group: GetTelehealthDirectLaunchToken
First Available Epic November 2020
Version:
Url Template: api/epic/2020/Telehealth/External/GetTelehealthDirectLaunchToken
Supported Web Service SOAP, REST, REST legacy
Types:
Supported OAuth 2.0 Backend Systems and Non-OAuth 2.0
User Types:

Description
This web service is used specifically for the direct link workflow to allow for patients to launch
into video visits from outside MyChart. It is used to generate a valid SMART on FHIR launch
token so that links being launched outside Epic can still perform the OAuth 2.0 workflow to
authenticate into the video visit. In this workflow the SMART on FHIR launch link will be set up
to add the TelehealthToken to the launch URL. This telehealth token will need to be exchanged
for a launch token in order to proceed with the SMART on FHIR launch. This web service
requires Backend OAuth 2.0 authentication. This API requires a MyChart account and may
contribute to your annual MyChart subscription count.

Request:

{
TelehealthToken: “6L2NW7L5YUP7V4MTHVAKEXJC6I”
}

Request Elements
Is Is
Name Description
Optional Array
TelehealthToken A code generate by Epic to exchange for a launch
false false
(String) token.

Response:

{
LaunchToken: “LSIRHT2K4I2LNAOR==”
}

December 18, 2022 23

Response Elements
Is Is
Name Description
Optional Array
A launch token to be used within a direct-
LaunchToken (String) false false
join telehealth context.

7.5 TelemedicineConfiguration (2021)

General Information
API Type: Epic Private Class A / Helper
API Group: TelemedicineConfiguration (2021)
First Available Epic Version: August 2021
Http Method: GET
Url Template: /api/epic/2021/Telehealth/External/TelemedicineConfiguration/
Supported Web Service REST
Types:
Supported OAuth 2.0 User Clinicians, Staff, or Administrative Users, Patient Contacts,
Types: Patients

Description
This web service loads configuration information about a video visit for third-party vendors
integrating using context-aware links. Compared to the previous version of this API, a new
parameter is returned as part of the AdditionalConfig array, “Epic_IsGroupVisit” which will be
true or false depending on if the visit is scheduled with multiple patients.
This version of the web service also provides additional response information to indicate which
additional web services the Epic organization has enabled for Telemedicine. In particular, it can
indicate which version, if any, is available for the following services:

• StoreAudioVideoTestResult,
• Disconnect,
• SaveMedia, and
• Connect.

Request:

https://apporchard.epic.com/interconnect-aocurprd-oauth/api/epic/2021/Tele
health/External/TelemedicineConfiguration

December 18, 2022 24

Response:

{
"DocumentTypes": [
{
"Id":"10",
"Abbreviation":"ADLW",
"Title":"Advance Directives and Living Will"
}
],
"Security": {"CaptureImageSecurity":true},
"AvailableServices": [
{
"Service":"StoreAudioVideoTestResult",
"Endpoint":"/api/epic/2021/Telehealth/External/StoreAudioVideoTestRes
ult"
},
{
"Service":"Disconnect",
"Endpoint":"/api/epic/2020/Telehealth/External/Disconnect"
},
{
"Service":"SaveMedia",
"Endpoint":"/api/epic/2018/Telehealth/External/SaveMedia"
},
{
"Service":"Connect",
"Endpoint":"/api/epic/2021/Telehealth/External/Connect"
}
],
"AdditionalConfig":[]
}

Response Elements
Is Is
Name Description
Optional Array
AdditionalConfig An array of KeyValue objects for
false true
(KeyValue) additional configuration.
An array of available services where
AvailableServices
each object in the array contains the false true
(WebService)
web service and the API endpoint
DocumentTypes List of document types a user can
false true
(DocumentType) save the file with
Security
Actions the user has security for false false
(TelemedicineSecurity)

December 18, 2022 25

Types:
DocumentType
Is Is
Name Description
Optional Array
Abbreviation (String) Category abbreviation false false
Id (String) Category ID of the document type false false
Title (String) Category title false false

TelemedicineSecurity
Is Is
Name Description
Optional Array
CaptureImageSecurity True if the user has security to capture
false false
(Boolean) an image

WebService
Is Is
Name Description
Optional Array
Endpoint (String) Endpoint that service is available at false false
Service (String) Web service parameter name false false

KeyValue
Is Is
Name Description
Optional Array
Key (String) Generic key for a parameter false false
Value (String) Value associated with a parameter key false false

December 18, 2022 26