Partners Blog Contact Us

Interacting with Epic Context Aware Linking and VidyoConnector

Follow

The Epic Context-Aware Linking integration with Vidyo enables healthcare providers to conduct video visits with patients through Epic. On-premises and cloud Epic customers can now create a custom mobile application using the VidyoConnector API which interacts with VidyoPortal and Epic Context-Aware Linking mechanism.

This article consists of the following sections: 

Definitions

VidyoConnector API Definitions

Term Description
VidyoConnector

The VidyoConnector is the main class object used with the VidyoClient APIs.

%ENCRYPTED_DATA% The %ENCRYPTED_DATA% is the Epic encrypted session information associated with the video call. This data is AES encrypted by the Epic application as a 16-digit alphanumeric Crypt Key in the Shared Secret field as described in the Vidyo and Epic Integration with VidyoConnect Context-Aware Linking (CAL) article and outlined in the Epic App Orchard documentation. 
Epic Data Json Object   The Epic Data Json Object is the information passed to the VidyoConnector object to link the call to the Epic session before connecting to the call.

Assumptions and Prerequisites

Before using the VidyoConnector APIs, be sure to understand the following assumptions and prerequisites listed below.

Assumptions:

  • The VidyoConnector API knows the Epic integration information including the session id and display name.
  • To understand more about the %ENCRYPTED_DATA%, refer back to the Definitions section.

Prerequisites:

General Application Flow

The below Epic integration process describes how the mobile application avoids having to call the browser directly. 

  1. The application makes an HTTPs request with the information below:

    https://epicintegration.vidyocloud.com/join/?extDataType=1&extData=%ENCRYPTED_DATA%

    (This link is an example URL and not intended as a clickable link).

    • The %ENCRYPTED_DATA% is the Epic session information provided to the Epic Context Aware Linking service.
  2. The application receives a response with a web page with a protocol handler link embedded within it. 
    Join: 
    vidyo://join?portal=https%3a%2f%2fepic.vidyo.com&f=RzpJUENPOklQQk6W9kOlRMUzpMQjpXQjpQQzpQdWJDOkNEUjpFUDpSUEk6QkE6TkRDOkNQUjpPQToyMjA6VEM6UFI6U1IyOlNSOlRQ&roomKey=1qNRgZzH&extDataType=1&extData=%ENCRYPTED_DATA%&dispName=Some%20User


    NOTE:  If the web services misunderstand the user agent, a 302 response displays. You can remedy this issue by specifying a Chrome user agent header. For example, you can specify the header as follows: “User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36”.


  3. Then, the application finds the vidyo:// link in the page.
  4. Next, the application parses the link and looks for the roomKey.
  5. Once the vidyo:// URL is found and parses the roomKey, the application then constructs the following JSON document into a string variable named: epicintegrationdata.

    • { “extDataType”: “1”, “extData”: “%SESSIONID%” }

      • The %SESSIONID% is the same data sent to the server in #1.
      • The server returns the %ENCRYPTED_DATA% as extData in the vidyo:// URI.
  6. After the VidyoConnector object is created, the user can then call the following API:

    VidyoConnectorSetAdvancedOptions(connector, epicintegrationdata);

    • The epicintegrationdata is the JSON document stored in the variable in the previous step.
  7. After setting the advanced options successfully, the application connects to the room:

    Example:

    • VidyoConnectorConnectToRoomAsGuest(connector, serviceHost, displayName, roomKeyFromURI, null , onSuccess, onFailure, onDisconnected)

      • ServiceHost - In this example, the serviceHost is https://epicintegration.vidyocloud.com.
      • DisplayName - This is the Epic application user name. 
      • RoomKeyFromURL - This is the roomKey provided and parsed from the vidyo:// URL.
      • null - This means no pin.
      • onSuccess, onFailure, onDisconnect - These are standard API callbacks.

Resetting Epic Data

If reusing the VidyoConnector object, the Epic session data must be reset to the next Epic session or set to empty. To set to empty use the following call: VidyoConnectorSetAdvancedOptions(connector, “{ “extDataType”: “”, “extData”: “” }” ); 

NOTE: This is not necessary if a new VidyoConnector object is created and used.

 

Implementation Notes

  • If the HTTP request for the Epic link does not return a web page successfully, the HTTP request may need a different user agent header. For example, the following user agent will return a correct web page source:  “Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36".
  • To test this use can use the following command with your data: 

    wget --user-agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36"  "https://epic.cloud.vidyo.com/join/?extData=pjpj8P7O0lqB5ZeXufY7FhICpNZiDF2JYXwc7HzK3QgMYfmcHLDpRMgcPKckK3O5gJYgaPm0UhFxnDQAhP8BYxpyNniue+JMm+Ma33bjFzWrKhyau21dEYbwu/Ya09Txxxs7WinbgV4p1iB+UCoE3A==&extDataType=1"
Was this article helpful?
0 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.