Epic – Setup

Introduction

This guide explains how to setup Epic for use with Cyclr, as well as how to install an Epic Connector.

Note: Some details of this process in relation to working with production data are currently unclear, but we hope to improve this soon with help from Epic.

Setup & Authentication

Overview

The Cyclr Epic Connector supports 2 types of authentication:

• Standalone Launch (OAuth2): User-facing authentication where the user logs in through Epic (e.g. MyChart) to authorize access to their own health data. It uses the OAuth 2.0 Authorization Code flow and is typically used by patient or provider apps.
• JWT Backend Service: System-level authentication used by backend services or server applications. It uses a signed JWT (JSON Web Token) to authenticate without user interaction and allows access to multiple patients’ data based on the app’s registered scopes.

Cyclr Partner setup:

• Create and setup an Epic app.
• Store that app’s Client ID and Secret in your Cyclr Partner Console.

Your customer’s setup:

• Perform further setup within their Epic instance as appropriate.

Remote Setup in Epic – performed by Cyclr Partner

Create and setup an Epic app

• Login or sign up to Epic’s portal.
• Create a new app within Epic’s “Build Apps” area and use the following settings:
  • Application Name: provide a suitable name for your Epic app.
  • Make a note of your app’s Client ID if you plan to use the Epic Connector against a production environment, or the Non-Production Client ID when using the Epic sandbox.
  • Application Audience:
    Set this according to the type of Authentication to be used by the Cyclr Epic Connector:
    • Standalone Launch (OAuth2): Select Clinicians or Administrative Users.
    • JWT Backend Service: Select Backend Systems.
  • Incoming APIs: (see Epic’s documentation for more on this)
    • When working with a Backend System and the Epic PhoneSystem Web Service – e.g. to pause and resume external call recording – you will require the “PhoneSystem” API to be added to your app. That can only be performed by Epic Support by emailing them directly, as described in their documentation where you see the line ”submit an email request to have these web services added to your app”.
    • When working with the following Epic Connector Methods, select the following APIs:

Name of Connector Method	Incoming API
Get Patient	Patient.Read (R4)
Search Patients	Patient.Search (R4)

Depending on the type of Authentication being used, follow the appropriate section below:

Steps for “Standalone Launch (OAuth2)” only (Clinicians or Administrative Users)

• Redirect URI: set this as your Cyclr Partner Console’s Callback URL.
• Ensure the following options are all enabled:
  (these options appear one-by-one as the previous option is enabled)
  • “Is Confidential Client”
  • “Requires Persistent Access”
  • “Uses Rolling Refresh Tokens”
  • “Can Have Indefinite Access”
• Sandbox Client Secret: Generate a secret, record it, then store the hash.
• Smart on FHIR Version: selectR4.

Steps for “JWT Backend Service” only (Backend Systems)

• Create a Public Private Key Pair: for more info about this process go to Epic’s documentation page.
• Upload the public key under the Sandbox JWT Signing Public Key heading.
  Once uploaded the KID value appears in a text box there.

Once the above steps have been performed, read the terms and decide whether to accept them.

Mark the app as ready for production if you will be using the Epic Connector in a production environment, otherwise mark it as ready for sandbox.

Partner Setup in Cyclr Console

We would suggest leaving the Client ID and Client Secret fields on the Epic Connector entry within your Cyclr Console blank so that they are provided each time the Connector is installed.

Cyclr Connector Installation

When installing an Epic Connector, the following values are used:

Property	Description
Client ID	Obtained when creating your Epic app.
Client Secret	Depends on Authentication Type: * Standalone Launch (OAuth2): enter the Client Secret relating to your app’s Client ID. * JWT Backend Service: any value can be entered.
Endpoint	The organization API endpoint to be used. A list of R4 endpoints can be found here. If present, remove the api/FHIR/R4 substring from the end of the URL to be used. For Sandbox mode, the endpoint provided must be: https://fhir.epic.com/interconnect-fhir-oauth/
KID	Only required when using JWT Backend Service auth type. Key ID: A unique identifier for the public key used to verify the JWT signature. It allows the receiving system to quickly find the correct key from a set of keys (JWK Set).
Private Key	Only required when using the JWT Backend Service auth type. A PEM-formatted RSA key used to sign JWTs for secure authentication.

After providing the above values, the user will be taken to Epic to provide their consent.

Sandbox Mode

When authenticating an Epic Connector for use against sandbox data, the username and password provided must be as follows – Production credentials will not work in sandbox mode:

Sandbox Credentials
Username	FHIR
Password	EpicFhir11!

For more details on Epic’s sandbox mode along with a selection of the available test data please refer to Epic’s documentation.