Ada’s Epic integration

1. Overview of the integration

Ada currently offers the integration of two different modules with the EPIC EHR provider. Those are:

The patient-facing Ada symptom assessment module, which is in addition offered as a mobile and web application, and can be integrated with Epic’s MyChart patient portal
The clinician-facing assessment report module, which can be launched within Epic’s Hyperspace/Hyperdrive

2. Integration of the symptom assessment module

The protocol followed for the symptom assessment module integration (single sign-on) is SMART on FHIR with OpenID Connect. An overview of the integration can be seen in the following diagram:

Click to see the token response in detail

Sample obtained by launching with SMART Health IT - https://launch.smarthealthit.org

{
  "accessToken": {
    "tokenValue": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZWVkX3BhdGllbnRfYmFubmVyIjpmYWxzZSwic21hcnRfc3R5bGVfdXJsIjoiaHR0cHM6Ly9sYXVuY2guc21hcnRoZWFsdGhpdC5vcmcvc21hcnQtc3R5bGUuanNvbiIsInBhdGllbnQiOiI4N2EzMzlkMC04Y2FlLTQxOGUtODljNy04NjUxZTZhYWIzYzYiLCJlbmNvdW50ZXIiOiI0MThlMzhjZi05ZGE2LTQxNTUtYjIwNS0wYmUyNDAyNGIxZGIiLCJ0b2tlbl90eXBlIjoiYmVhcmVyIiwic2NvcGUiOiJsYXVuY2ggb3BlbmlkIGZoaXJVc2VyIFBhdGllbnQuUmVhZCBDb25kaXRpb24uU2VhcmNoIE9ic2VydmF0aW9uLlNlYXJjaCIsImNsaWVudF9pZCI6IkFueSIsImV4cGlyZXNfaW4iOjM2MDAsImlkX3Rva2VuIjoiZXlKaGJHY2lPaUpTVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SndjbTltYVd4bElqb2lVR0YwYVdWdWRDODROMkV6TXpsa01DMDRZMkZsTFRReE9HVXRPRGxqTnkwNE5qVXhaVFpoWVdJell6WWlMQ0ptYUdseVZYTmxjaUk2SWxCaGRHbGxiblF2T0RkaE16TTVaREF0T0dOaFpTMDBNVGhsTFRnNVl6Y3RPRFkxTVdVMllXRmlNMk0ySWl3aVlYVmtJam9pUVc1NUlpd2ljM1ZpSWpvaVpqVmhaV1F3WlRneVptTTBZMlprT1Raa01ESTNObUl3WmpGaU1qaGlZVFF4Wm1OaFlqUmhPRFUzTURZMk9EaGxPRFl6TlRObFl6QmhNakUwTnpNd05TSXNJbWx6Y3lJNkltaDBkSEJ6T2k4dmJHRjFibU5vTG5OdFlYSjBhR1ZoYkhSb2FYUXViM0puTDNZdmNqUXZabWhwY2lJc0ltbGhkQ0k2TVRZek5ESTVNVGsyTlN3aVpYaHdJam94TmpNME1qazFOVFkxZlEuTDlDMG0zNE5WT21nRUZwT3N6M1BHTzNuenpaeWdCT3ZDcm9QMkpPdm5NTFU4OEtnSjk5eTVFdXZEN0FacnFqd3pXRzItNE5wRjhDSi05RkM4YkJJdzQwbzUtVVJ5SWs0WHBZejhyNUZOQ2Y4RFA4T2g5V1VXSFlqb0poWWtJeHBsVmREWm5UY0NaQzZrOS1KaTJEaDdTdl9TSi1say1kNUMyNFY2WXNnUVQ2dkFKNWN3d3ZPaVNYbGgyRDB4a0ZPR2Myc1lEd2IzU1dmTEQ3MDRSeFdCSHpMXzN3aGtkZjdFVExla3dZOEl0QjI2c1p6Q0tTZDFLODZrYmNJVzhfNGsxeFgwakxXZDZzVFQ3Wmd2bzFhOEFXYXlnM1IyakpGZnhKM1M0RjZJenh2UmhFMzhfbjdqeXgyMURPb1cxandSd3VORGtWaUdlN2JSWHBNVWxBZ1dRIiwiaWF0IjoxNjM0MjkxOTY1LCJleHAiOjE2MzQyOTU1NjV9.PilsOmKa2S-rCGv2lG0MpJRkpZUeyZIIckNwGe8bWno",
    "issuedAt": "2021-10-15T09:59:25.599887Z",
    "expiresAt": "2021-10-15T10:59:25.599887Z",
    "tokenType": {
      "value": "Bearer"
    },
    "scopes": [
      "openid",
      "Patient.Read",
      "Condition.Search",
      "launch",
      "fhirUser",
      "Observation.Search"
    ]
  },
  "refreshToken": null,
  "additionalParameters": {
    "patient": "87a339d0-8cae-418e-89c7-8651e6aab3c6",
    "need_patient_banner": "false",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlIjoiUGF0aWVudC84N2EzMzlkMC04Y2FlLTQxOGUtODljNy04NjUxZTZhYWIzYzYiLCJmaGlyVXNlciI6IlBhdGllbnQvODdhMzM5ZDAtOGNhZS00MThlLTg5YzctODY1MWU2YWFiM2M2IiwiYXVkIjoiQW55Iiwic3ViIjoiZjVhZWQwZTgyZmM0Y2ZkOTZkMDI3NmIwZjFiMjhiYTQxZmNhYjRhODU3MDY2ODhlODYzNTNlYzBhMjE0NzMwNSIsImlzcyI6Imh0dHBzOi8vbGF1bmNoLnNtYXJ0aGVhbHRoaXQub3JnL3YvcjQvZmhpciIsImlhdCI6MTYzNDI5MTk2NSwiZXhwIjoxNjM0Mjk1NTY1fQ.L9C0m34NVOmgEFpOsz3PGO3nzzZygBOvCroP2JOvnMLU88KgJ99y5EuvD7AZrqjwzWG2-4NpF8CJ-9FC8bBIw40o5-URyIk4XpYz8r5FNCf8DP8Oh9WUWHYjoJhYkIxplVdDZnTcCZC6k9-Ji2Dh7Sv_SJ-lk-d5C24V6YsgQT6vAJ5cwwvOiSXlh2D0xkFOGc2sYDwb3SWfLD704RxWBHzL_3whkdf7ETLekwY8ItB26sZzCKSd1K86kbcIW8_4k1xX0jLWd6sTT7Zgvo1a8AWayg3R2jJFfxJ3S4F6IzxvRhE38_n7jyx21DOoW1jwRwuNDkViGe7bRXpMUlAgWQ",
    "smart_style_url": "https://launch.smarthealthit.org/smart-style.json",
    "encounter": "418e38cf-9da6-4155-b205-0be24024b1db",
    "client_id": "Any"
  }
}

Steps 1 and 2: The module is launched from the MyRecord section of the menu in MyChart, or the partner’s custom patient portal.
Step 3: The Ada-ID service initiates an exchange of the launch ID for an authorization code.
Steps 4 to 6: The Tesseract API Gateway redirects to the Authz server, which in turn redirects with the code and state parameters to the assessment module.
Steps 7 to 14: The assessment module sends the parameters to the Ada-ID service and the Ada-ID service returns an internal JWS token
Steps 8 to 11: The internal token is created based on the token response Ada-ID retrieves from the Tesseract API.
Steps 9 and 10: The API Gateway obtains the token response from the Authz server.
Steps 12 and 13: The Ada-ID service performs additional checks on the token response that is retrieved, which involves inspecting the user database.
Steps 15 to 20: During the patient onboarding phase of the symptom assessment, the assessment module uses the internal token to obtain information about the patient’s demographics and associated risk factors from the Ada-ID service.
Steps 16 to 19: The Ada-ID service retrieves the data from the Epic FHIR server through the API gateway.

2.1. FHIR resources

The resources pulled from the FHIR server include the following:

Patient: for obtaining the patient name, date of birth and gender
Observation: for obtaining the birth sex and smoking status
Condition: for obtaining active hypertension or diabetes diagnoses.

Biological sex is populated with the birth sex observation - in case it’s missing, the gender value is used.

The user gets asked about any of the data missing from the Patient resource. If active hypertension or diabetes diagnoses cannot be found, the user will be asked if they exist.

2.2. Returning users

Step 9 ensures that returning users are recognized. The assessment flow for returning users can be distinguished from the one for new users in that the returning users will not be asked to agree to the Terms and Conditions and Privacy Policy again.

3. Integration of the assessment report module for healthcare professionals

The protocol followed for the assessment report module integration (single sign-on) is SMART on FHIR. An overview of the integration can be seen in the following diagram:

Steps 1 and 2: The assessment report module is triggered inside the Hyperspace/Hyperdrive platform.
Step 3: The Ada-ID service initiates an exchange of the launch ID for an authorization code.
Step 4: The request for an authorization code is directed towards the Tesseract API Gateway which redirects to the Epic Authz server.
Steps 5 and 6: The Authz server redirects with the code and state parameters to the report service.
Steps 7 to 12: The report service sends the code and state parameters to the Ada-ID service in order to obtain an internal JWS token.
Steps 8 to 11: The Ada-ID service constructs the internal token based on the token response it gets from Epic.
Steps 9 and 10: The Tesseract API obtains the token response from the Authz server.
Steps 14 and 15: The internal token contents include the patient ID from the launch context and the expiration time and these fields get validated in a request to the Ada-ID service.
Step 16: If the token is valid, the assessment report service displays reports for a particular patient, based on the token’s patient ID field.

3.1. Dashboard view

When a health-care professional launches the report module in Hyperspace/Hyperdrive from within the healthcare record context of a particular patient, the first screen they’re shown is the dashboard view - a full list of assessments the patient has carried out, along with the patient demographics, name and the patient ID. The list is ordered by the date and time of the assessments, with the latest one being first. Incomplete assessments and those the user did not explicitly share with their physician are neither shown nor saved in the system. A sample dashboard view can be seen here:

3.2. Report view

Clicking on one of the items in the report list leads to a view of the full assessment report, with the patient demographics, relevant risk factors, primary complaints, present and absent findings, suggested conditions and a transcript of the dialogue with Ada. The following image shows a sample report:

3.3. Customization

The dashboard and report interfaces currently support only the English language (locale en-GB).

If you have any feedback or just want to get in touch, reach us at partnerships@ada.com.