Partners Blog Contact Us

Vidyo and Epic Integration with VidyoConnect Context-Aware Linking (CAL)

Follow

The Epic Context-Aware Linking integration for Vidyo enables healthcare providers to access VidyoConnect™ meetings from within their Epic EHR (Electronic Health Record) system.

This article consists of the following sections. Please proceed to the correct Epic version and configuration information.

Overview and Getting Started

Using Epic Version February 2019 and Later

Using Epic Version August 2018 and Earlier

Important Tips when Configuring Epic Integration (On-Premises)

Epic Demonstration of CAL

Vidyo Telehealth Epic Solution Brief

 


Overview and Getting Started


 

If you want to use an on-premises Epic integration, you must first enable it in the Super Admin portal. If you are a cloud customer, your Epic integration will already be enabled. Both on-premises and cloud customers need to configure Epic integration in the Tenant Admin for each tenant that's going to use this integration. Alternatively, you can enable it via REST APIs. This article describes how to configure it via the Super Admin and the Tenant Admin. For information about how to configure it via the REST APIs, refer to version 18.3.1 or later of the Vidyo Web Services API User Guide

If you need to enable context aware linking on Epic, select this link https://galaxy.epic.com/?#Browse/page=1!68!50!1621949,3769901,and then login with your credentials.

 

Prerequisites

Follow the applicable below prerequisites in order to ensure a smooth transition with your Epic integration:

  • Verify versions, compatibility and ensure that you have the proper Epic security updates installed on your epic environment prior to upgrading to Vidyo. 
    •  Starting with the Epic February 2019 release, Epic requires the inclusion of an Epic-Client-ID for all third-party integrations that use their APIs.
      • Only VidyoPortal version 19.3.0 and later supports the Epic CAL integration through Epic's App Orchard marketplace and will send this Epic-Client-ID whenever the SetExternalConnectionStatus API is called.
      • To learn more version and compatibility details, please refer to the Epic Compatibility with Vidyo Infrastructure article.
    • Ensure that you've applied Security Update 21 to both the VidyoPortal™ and VidyoRouter™ running version 18.4.0 or later. Only use this integration with:
      • VidyoConnect Desktop 19.4.1 or later (latest version) or 18.2.0 (minimum version)
      • VidyoConnect Mobile 19.4.0 or later (latest version) or 18.1.0 (minimum version).
      • VidyoConnect Room SE 21.1.0 or later

      IMPORTANT: To use Epic CAL integration with VidyoConnect Room SE, ensure that the VidyoConnect desktop application is NOT installed on the same machine.

      If the VidyoConnect desktop application and the VidyoConnect Room application are installed on the same machine, when the Epic CAL URL is opened, the Download button will display based on the Portal configuration, and when selected, it will download the VidyoConnect desktop application rather than the VidyoConnect Room application.


       
    • Enable Scheduled Rooms (In the Super Admin and/or Tenant Admin)
      • Super Admin: Please refer to the Configuring Scheduled and Public Room Settings information under the section Setting Global Features in the Setting Global Features article.   
      • Tenant Admin: Please refer to the Configuring Scheduled and Public Room Settings information under the section Configuring Feature Settings in the Tenant Admin: Configuring Settings article.  
    • Enable Guest Access (Super Admin)
      • Super Admin: Please refer to the Adding a Default Tenant or Adding a New Tenant section in the Super Admin: Managing Tenants article. Make sure the Enable Guests login checkbox is enabled.    
    • Enable Mobile Access for VidyoConnect (Super Admin)
      • Super Admin: Please refer to the Enabling Mobile Access information under the section Setting Global Features in the Setting Global Features article. 
    • Upload the appropriate VidyoConnect installers to Manage Endpoint Software (Tenant Admin). Please refer to the Managing Endpoint Software article. 

     


    Using Epic Version February 2019 and Later 


     

    Configuring Epic Version February 2019 with VidyoConnect Context-Aware Linking (CAL) as the Super Admin Portal (On-Premises)

    In order for this configuration to work, the "Scheduled Room" feature must be enabled on the VidyoPortal. If you do not have this feature enabled; you will receive a 404 error message stating, "This is not a valid room link".

    To configure Epic integration in the VidyoPortal (On-Premises):

    1. Log in to the Super Admin portal using your Super Admin account.
      For more information, see Logging in to the Super Admin Portal.
      The Components page displays by default.
    2. Click the Settings tab.
      The Upload System License page displays by default.
    3. Click  to the left of Feature Settings on the left menu.
    4. Click Epic Integration from the submenu.
      The Epic Integration page displays.

      Epic_screen_Main.png

    5. Select the Enable Epic Integration check box.
    6. Click Save.

    Configuring Epic Version February 2019 with VidyoConnect Context-Aware Linking (CAL) as the Tenant Admin

    In order to use Epic integration as an on-premises customer, you must first ensure that the Super Admin has enabled it on the system level as described in the Enabling the EPIC Integration Feature with VidyoConnect Context-Aware Linking (CAL) for On-Premises section above.

    If you are a cloud customer, you must complete the Tenant Admin steps below to configure your Epic integration.  

    You can perform these additional optional procedures in the Epic Integration page: 

    Configuring Epic Integration

    To configure Epic integration in the Tenant Admin:

    1. Log in to the Admin portal using your Admin account.
      For more information, see Logging in to the Tenant Admin Portal.
      The Users page displays by default.
    2. Click the Settings tab.
      The License page displays by default.
    3. Click  to the left of Feature Settings on the left menu.
    4. Click Epic Integration from the submenu.
      The Epic Integration page displays.

      Epic_screen_Main.png
    5. Select the Enable EPIC Integration check box to enable Epic Integration and to enable the rest of the page options. (This check box will already be checked if you have an existing Epic integration). 
    6. Configure the Epic integration for the tenant by entering a 16-digit alphanumeric Crypt Key in the Crypt Key field. (Previously, this was known as the "Shared Secret" key). The Crypt Key is the shared encryption key used to encrypt the query string in PATIENTOPENURL. The 16-digit  crypt key can be manually created or you can use a key generator.
      • NOTE: Vidyo supports EPIC set external connection status through a web service which allows Hyperspace to properly reflect the video visit status of the Vidyo system in the provider schedule and connect visit navigator sections.
      • NOTE: You must enter the same Crypt Key in your Epic configuration. This key will be used for encrypting and decrypting the URL strings.
      • NOTE: The CryptAlgorithm: AES notation in the screen indicates that you must select AES as your encryption algorithm when configuring your Epic FDI record for CAL.
    7. Next, go to the Configuring the Epic Interconnect Server procedure to troubleshoot any issues. Then, you can do one of the following: 
      a.) Click Save -or- 
      b.) Proceed to any of the following below procedures:

    Generating an Epic CAL URL Link

    Input data in this next section to generate a sample Epic CAL URL link. For example, you can generate a link for a provider and patient to join a test conference call. To troubleshoot issues, compare the sample URL extData with the extData generated from Epic and the test call.

    Epic_General_URL_link.png

    1. Enter the Session ID in the SessionID field. For example, you can enter any unique shared context ID identifier which is shared across users joining a single Vidyo session. 
    2. Enter the ConferenceID in the ConferenceID field which is the Epic Video Visit Conference ID (Encounter CSN). 
    3. Enter the ExternalID in the ExternalID field which is the ID for the user.
    4. Select the ExternalIDType of the user from the drop down box: 

      1 for EMP, Provider or
      2 for WPR, Patient. 
    5. Enter the first name of the person joining the conference in FirstName field. 
    6. Enter the last name of the person joining the conference in the LastName field.
    7. Enter or select the scheduled time for the video visit in hours or minutes for your test conference (ex. HH:MM/AM/PM) in the Appointment Time drop down.
    8. Enter an orgid (Optional field) if you are using multiple Epic Interconnect Servers. If you are only using one Epic Interconnect  Server, this field should be left blank.  
    9. Click the Generate button to generate the Epic CAL URL link. The test call link is generated in the Sample URL text box. You may:
      Copy this link to compare the generated extData from Epic's system to look for discrepancies.
      Join this link in a browser to simulate a doctor or patient test call. 
    10. When finished making changes in this section, proceed to another procedure, or click Save.

    Changing the Epic Mode

    To set your Epic integration to Production, Test, or Legacy mode:

    1. To set your Epic integration to Production, Test, or Legacy mode, select one of the following modes. The system will automatically default to Test

      Epic_mode.png

      • Select Production when configuring and deploying in production. The Production Epic-Client-ID is sent for all API requests and is counted and billed by Epic.
      • Accept the system default option Test, when configuring a lab environment which sends a Non-Production Epic-Client-ID for testing purposes only. Epic will NOT count these requests for billing purposes.
      • Select Legacy when debugging and using systems running Epic version February 2019 and earlier. (In legacy mode, no Epic-Client-ID is sent so the system behaves exactly like VidyoPortal version 19.2.0 or earlier).
    2. Click Save.

    Configuring the Epic Interconnect Server

    To troubleshoot any issues, the Tenant Admin must configure a connection test through the Epic Interconnect Server. The connection test generates helpful HTTP status notifications/codes such as 408 - Request Timeout, 404 - Not Found, 401 - Bad Credentials, etc. 

    The connection test will send a "400: Bad Request" message which is actually a "successful" connection test since the server expects a CONFERENCE-ID parameter that is intentionally missing.  

    To configure the Epic Interconnect Server:

    1. Click the  plus next to Notification button to open this section. 
      Fields display in the Notification pop-up window. 

      epic_1.png

    2. Enter a URL in the URL field such as https://test.example.com.
      NOTE: Your Epic Technical Support will provide this URL information. 
    3. Enter the Epic Interconnect/SetExternalConnectionStatus user name in the Username field.
      For example, "emp$" is a required prefix for username (e.g., emp$12345).
    4. Enter the Epic Interconnect/SetExternalConnectionStatus password in the Password field. 
    5. Enter the Epic Interconnect/SetExternalConnectionStatus orgid in the orgid (Optional) field. 
      NOTE: Enter an orgid only if you are configuring multiple Epic Interconnect Servers. If you only have one server, this should be left blank. 
    6. Click the Connection test button.
      If there is an issue with connecting to the server, an Error pop up will display with an HTTP status notification/code and message such as in the example below. 

      Epic_Interconnect_Serv_er_pop_up_error_message.png 

    7. Click Save.

    Downloading an API Usage Report

    To download an API Usage Report, select a start and end date and then download the APIUSageLog.csv file which includes the following columns/data: ExternalUrl, Details, IsDelivered, CreateTime, UpdateTime, and EpicMode.

    To download an API Usage Report:

    1. Select or enter start and end dates (YYYY/MM/DD) in the calendar to indicate how often API requests are made.

      Epic_reporting.png

    2. Click Export
      The system generates a spreadsheet in the lower left-hard corner of the screen for you to download. 
    3. Click Save.

     

    Configuring Advanced Workflows

    This section describes how to configure advanced workflows, such as enabling conference participants to automatically join calls via the browser and setting expiration periods for CAL links.

    Automatic Join via Browser

    Vidyo supports an optional URL parameter that, when added to the URL of a CAL link, enables you to bypass the screen that asks participants to either “Join via the app” or “Join via the browser”; instead, the parameter automatically invokes the “Join via the browser” workflow.

    In order for participants to be able to automatically join via the browser, the following prerequisites must be met:

    • VidyoConnect WebRTC enabled on your Tenant
    • VidyoPortal 20.2.0 or later
    • Native WebRTC deployment for mobile WebRTC workflows

    If a participant does not meet the WebRTC or VidyoPortal requirements listed above, the standard splash screen that enables participants to “Join via the app” or “Join via the browser” displays. The desktop and mobile versions of this screen are shown below:

    VidyoConnect desktop application:

    JoinviaBrowserorApp.png

     

    VidyoConnect mobile application (iOS and Android):

    JoinviaApporBrowseriOS.png JoinviaApporBrowserAndroid.png

     

    The URL parameter that invokes the workflow where participants automatically join via the browser is the jvw parameter. As shown in the following table, values for this parameter include 0, which invokes the standard workflow that displays the “Join via the app” and “Join via the browser” splash screen, or 1, which automatically invokes the “Join via the browser” workflow.

     

    Parameter Value
    jvw

    0 — Default, which displays the standard splash screen. Using 0 is equivalent to not specifying the parameter in the URL.

    1 — Automatically invokes the “Join via the browser” workflow.

     

    Here is an example of a link in an FDI record that uses the jvw parameter:

    https://epic.alpha.vidyo.com/join/?extDataType=1&extData=%CRYPTSTR%&jvw=1

     

    IMPORTANT NOTES:

    You cannot force WebRTC on a system where WebRTC use is not supported. If a browser or device does not support WebRTC, the splash screen that displays “Join via the app” and “Join via the browser” will be displayed.

    The jvw parameter must be outside of the CRYPTSTRING and not contained within the encrypted extData.

     

    Recommendations

    • Vidyo recommends only using the jvw parameter for patient CAL links. For healthcare providers, we recommend preserving the option for joining via the VidyoConnect application because doing so provides additional functionality.
    • Your Epic integration gives you the ability to be selective about which links use the jvw parameter and which do not. You may have multiple FDI records that are based on use cases where some use cases add this parameter and others do not (such as for inpatient workflows).
    • Consult your Epic TS for more information about how to configure multiple FDI records.

     

    Automatic Epic CAL Link Expiration

    Vidyo offers extra security for your generated Epic CAL links by allowing integrators to set expiration periods for the links. This is an optional configuration that is disabled by default and should be configured in conjunction with your Epic FDI record.

    In order to use automatic Epic CAL link expiration, the following prerequisite must be met:

    • VidyoPortal version 20.2.0 or later

    Before configuring this feature, ensure you are familiar with the terms in the following table:

    Term Description
    AppointmentTime

    This is a field in the encrypted CRYPTSTRING of an Epic CAL link that indicates the date and time of an appointment. It is important to note that the time zone is not sent to Vidyo in this field and therefore needs to be configured at the Tenant Admin level.

    CAL link validity period

    This is the number of minutes that a CAL link is valid from the start of the AppointmentTime.

    Note there is a hard-coded 30-minute grace period BEFORE an AppointmentTime starts, but the link expires immediately after the validity period ends.

    LinkValidityPeriod parameter

    This optional parameter, which can be included in the encrypted CRYPTSTRING, can be used to override the Default CAL link validity period for an individual CAL link.

    Timezone of Epic Integration Server

    This is the time zone that your Epic system resides in. That is, it is the time zone your system schedules appointments in.

    Default CAL link validity period

    This is the number of minutes that a CAL link is valid from the start of the AppointmentTime if the LinkValidityPeriod parameter is not specified or is invalid.

     

    Tenant Admin Configuration

    To configure default CAL link validity period and time zone of Epic Integration Server on the Tenant Admin Portal: 

    1. Log in to the Admin portal using your Admin account.
      For more information, see Logging in to the Tenant Admin Portal.
      The Users page displays by default.
    2. Click the Settings tab.
      The License page displays by default.
    3. Click  to the left of Feature Settings on the left menu.
    4. Click Epic Integration from the submenu.
      The Epic Integration page displays.

      Epic_AutoProvisioningProvider.png

    5. Select the Enable EPIC Integration checkbox if it’s not already selected.
    6. In the Default CAL link validity period (minutes) field, enter the duration in minutes that your Epic CAL links will be valid. Once that time period has passed, the links will expire. For example, if you enter 15 minutes, your CAL links will be valid for only 15 minutes after the AppointmentTime.
    7. In the Timezone of Epic Integration Server field, select the time zone where the Epic server is located.
    8. Click Save.

    Using the LinkValidityPeriod Parameter

    The LinkValidityPeriod is an optional CAL link parameter that allows Epic integrations specify a link validity period on a per link basis.

     

    Parameter Value
    LinkValidityPeriod

    0 – indicates no expiration

    1 to 43,200 — Number of minutes after AppointmentTime that the Epic CAL link is valid

     

    Important Notes:

    • The LinkValidityPeriod must be included inside the CRYPTSTRING as part the encrypted extData that is passed to Vidyo from the Epic FDI record.
    • Here is an example of a decrypted CRYPSTRING with the LinkValidityPeriod parameter set for a 60-minute expiration period: SessionID=10007057852&ConferenceID=10007057852&ExternalID
      =+165790&ExternalIDType=1&FirstName=Krishnan&LastName=
      Ram&AppointmentTime=08/11/2020 02:00 PM&LinkValidityPeriod=60

     

    Recommendation

    • Your Epic integration gives you the ability to be selective about which links use the LinkValidityPeriod parameter and which do not. You may have multiple FDI records that are based on use cases where some use cases add this parameter and others do not and rely on your configured default.
    • Different types of appointments may last longer than others and Vidyo accommodates for this. Each individual CAL link can be customized to have its own validity period. Different FDI records can be built for each use case.
    • Consult your Epic TS for more information about how to configure multiple FDI records. 

    Auto-Provisioned Providers

    Using Vidyo’s Epic Context-Aware Linking (CAL) integration, providers can now be automatically provisioned into their Tenant as registered users. This allows these users to automatically inherit ownership of their Epic CAL conferences and thereby receive moderation rights which enables them to:

    • Mute and unmute participants
    • Disconnect participants
    • Invite other users via links
    • Invite other registered users to the conference
    • Dial out to SIP or H.323 devices

    IMPORTANT: Each auto-provisioned provider consumes a Seat license.

    In order to enable auto-provisioned providers, the following prerequisites must be met:

    • VidyoPortal version 21.2.0 or later
    • VidyoConnect for Desktop version 21.1.0 or later
    • Available Seat licenses on your Tenant

    Before configuring this feature, ensure you are familiar with the terms in the following table:

    Term Description
    ExternalID

    This is a mandatory field in the encrypted CRYPTSTRING of an Epic CAL link that denotes the ID for the user (EMP ID, Provider or WPR ID, Patient). This field is used to uniquely identify a provider and gets provisioned into your Tenant. This field is populated by Epic and must be alphanumeric.

    Auto-Provisioning Parameter

    This is a field in the encrypted CRYPTSTRING of an Epic CAL link that denotes whether Auto-Provisioning (AP) is to be performed for this user. When set to 0 (default), auto-provisioning is disabled; when set to 1 auto-provisioning is enabled. It will only be honored for providers and if Auto-Provisioning is enabled at the Tenant level.

    Endpoint Behavior Mode

    This is an optional parameter in the encrypted CRYPSTRING of an Epic CAL link that denotes an Endpoint Behavior Mode profile. This field can be used to customize the behavior of an endpoint when using this feature. For example, it can be used to specify if a provider will be logged out automatically after their Epic CAL conference.

     

    Tenant Admin Configuration

    To enable Auto-Provisioned Providers at the Tenant level: 

    1. Log in to the Admin portal using your Admin account.
      For more information, see Logging in to the Tenant Admin Portal.
      The Users page displays by default.
    2. Click the Settings tab.
      The License page displays by default.
    3. Click  to the left of Feature Settings on the left menu.
    4. Click Epic Integration from the submenu.
      The Epic Integration page displays.

      Epic_AutoProvisioningProvider.png

    5. Select the Allow Auto-Provisioning of Providers checkbox.

    Adding Endpoint Behaviors

    For information about how to add Endpoint Behaviors via Vidyo's REST APIs, refer to the Web Services User Guide.

    In order to support Endpoint Behavior Mode, you must have Custom Roles enabled on your Tenant. For on-premises customers, refer to the "Configuring Custom Roles" section of the VidyoConferencing Administrator Guide for information about how to enable custom roles.

    For VidyoCloud customers, this can be enabled on demand. To do so, open a ticket with VidyoCloud Support.

     

    Adding Parameters to Epic CRYPTSTRING

    The following parameters are used by the Auto-Provisioned Provider feature:

    Parameter Value
    AP (string)

    0 – indicates auto-provisioning is disabled (default)

    1 – indicates auto-provisioning is enabled

    EBM (string)

    Specifies the Endpoint Behavior Mode label to be used for the Epic CAL link (must be set up prior to being used via the REST API).

    For your Epic FDI record, you need to add the parameters listed in the table above. Note that EBM is optional. Here is an example of a decrypted CRYPTSTRING:

    SessionID=10007057852&ConferenceID=10007057852&ExternalID=165790&ExternalIDType=1&FirstName=John&LastName=Smith&AppointmentTime=08/11/2020 02:00 PM&LinkValidityPeriod=60&AP=1&EBM=ap

     


    Using Epic Version August 2018 and Earlier


     

    Configuring Epic CAL Integration (August 2018) as the Super Admin Portal (On-Premises Only)

    In order for this configuration to work, the "Scheduled Room" feature must be enabled on the VidyoPortal. If you do not have this feature enabled; you will receive a 404 error message stating, "This is not a valid room link".

    To configure Epic integration in the VidyoPortal (On-Premises):

    1. Log in to the Super Admin portal using your Super Admin account.
      For more information, see Logging in to the Super Admin Portal.
      The Components page displays by default.
    2. Click the Settings tab.
      The Upload System License page displays by default.
    3. Click  to the left of Feature Settings on the left menu.
    4. Click Epic Integration from the submenu.
      The Epic Integration page displays.

      EpicIntegrationTab.png
    5. Select the Enable Epic Integration check box.
    6. Click Save.

    Configuring Epic CAL Integration (August 2018) as the Tenant Admin (On-Premises and Cloud)

    In order to use Epic integration as an on-premises customer, you must first ensure that the Super Admin has enabled it on the system level as described in the Enabling the EPIC Integration Feature with VidyoConnect Context-Aware Linking (CAL) for On-Premises section above. If you are a cloud customer, you can follow the Tenant Admin steps below to configure your Epic integration. 

    To configure Epic integration in the Tenant Admin (On-Premises):

    1. Log in to the Admin portal using your Admin account.
      For more information, see Logging in to the Tenant Admin Portal.
      The Users page displays by default.
    2. Click the Settings tab.
      The License page displays by default.
    3. Click  to the left of Feature Settings on the left menu.
    4. Click Epic Integration from the submenu.
      The Epic Integration page displays.

      EPIC_1.png
    5. Select the Enable the Enable EPIC Integration check box.
    6. Configure the Epic integration for the tenant by entering the following information. (Vidyo supports EPIC set external connection status through a web service which allows Hyperspace to properly reflect the video visit status of the Vidyo system in the provider schedule and connect visit navigator sections):  
      • Enter a 16-digit alphanumeric Crypt Key in the Shared Secret field.
        The 16-digit  crypt/shared secret key can be manually created, or you can use a key generator.
        Please note that you must enter the same Shared Secret in your Epic database. This secret will be used for encrypting and decrypting the URL strings.

        EPIC_2.png
      • Enter the Epic Interconnect/SetExternalConnectionStatus URL in the Notification URL field.
      • Enter the Epic Interconnect/SetExternalConnectionStatus user name in the Notification user field.
      • Enter the Epic Interconnect/SetExternalConnectionStatuspassword in the Notification password field.
    7. Click Save

    Important Tips when Configuring Epic Integration 

    The following information will assist you in your configuration of Epic.

    • Vidyo supports the AES encryption for the crypt algorithm.
    • The format for the crypturl which is configured on the Epic system should have the following format: For example, the format should be: https://epicintegration.vidyocloud.com/join/?extDataType=1&extData=%ENCRYPTED_DATA%. (This link is an example URL and not intended as a clickable link).
    • The Crypt Key is the same as the Shared Secret and is a 16 digit alphanumeric number. 

    Epic Demonstration of CAL

    To view a demonstration of CAL in action hosted on Epic's galaxy site, select this link: https://eventarchive.epic.com/telehealth/Vidyo%20CAL%20Demo.mp4. You may need to obtain special login permissions to view this demo.

    Vidyo Telehealth Epic Solution Brief

    Please select the attached PDF to learn more about the Vidyo Telehealth Epic Solution Brief. 

Attachments:

Was this article helpful?
2 out of 3 found this helpful

Comments

2 comments

Please sign in to leave a comment.