2. Configure the Epic integration

This section contains information to help you configure the Epic integration.

• Prerequisites
• Epic CAL feature compatibility with Vidyo versions
• Super Admin: Enable Epic integration (on-premise only)
• Tenant Admin: Configure Epic with VidyoConnect CAL
• Automatic join via browser
• Automatic Epic CAL link expiration
• Automatic Epic CAL link expiration for ad-hoc rooms
• Configure auto-provisioned providers
• Configure auto-invite of participants
• Play audio or video content in a waiting room
• Configure Epic Save Media integration
• Configure an auto-moderator PIN
• Deploy the Vidyo Epic Service

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.

Prerequisites

If you want to use an on-premises Epic integration, you must first enable it in the Super Admin. 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. For information about how to configure it via the REST APIs, see EPIC Integration REST Services under VidyoPlatform.

Note 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 log in with your credentials.

Follow the applicable below prerequisites 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.

1. 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.
1. 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.
2. 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:
1. VidyoConnect Desktop 19.4.1 or later (latest version) or 18.2.0 (minimum version)
2. VidyoConnect Mobile 19.4.0 or later (latest version) or 18.1.0 (minimum version).
3. VidyoConnect Room SE 21.1.0 or later

Note 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 VidyoPortal configuration, and when selected, it will download the VidyoConnect desktop application rather than the VidyoConnect Room application.

3. Enable Scheduled Rooms (in the Super Admin and/or Tenant Admin) by following the instructions in the Setting Global Features > Configuring Scheduled and Public Room Settings section of the VidyoPortal and VidyoRouter Administrator Guide.
4. Enable Guest Access (Super Admin) by following the instructions in the Adding a Default Tenant or Adding a New Tenant section of the VidyoPortal and VidyoRouter Administrator Guide. Make sure the Enable Guests login checkbox is enabled.
5. Enable Mobile Access for VidyoConnect (Super Admin) by following the instructions in the Setting Global Features > Enabling Mobile Access section of the VidyoPortal and VidyoRouter Administrator Guide.
6. Upload the appropriate VidyoConnect installers to Manage Endpoint Software (Tenant Admin) by following the instructions in the Managing Endpoint Software section of the VidyoPortal and VidyoRouter Administrator Guide.

Epic CAL feature compatibility with Vidyo versions

The following table lists the Vidyo and Epic App Market App versions required for each Epic CAL feature.

Epic CAL feature	Vidyo infrastructure (Portal and Router)	Vidyo Epic Service	Desktop	WebRTC	Android	iOS	Epic App Market (Vidyo CAL app)
Automatic join via browser	22.2.0 or later	22.2.0 or later	22.1.0 or later	21.5.1 or later	Not supported	Not supported	2.0 or later
Automatic Epic CAL link expiration	22.2.0 or later	22.2.0 or later	22.1.0 or later	21.5.1 or later	Not supported	Not supported	2.0 or later
Automatic Epic CAL link expiration for ad-hoc rooms	22.3.1 or later	22.2.0 or later	22.1.0 or later	21.5.1 or later	Not supported	Not supported	2.0 or later
Auto-provisioned providers	21.2.0 or later	22.2.0 or later	22.1.0 or later	21.5.1 or later	Not supported	Not supported	2.0 or later
Auto-invite of participants	22.2.0 or later	22.2.0 or later	22.1.0 or later	21.5.1 or later	Not supported	Not supported	2.0 or later
Play audio or video content in a waiting room	21.4.0 or later	22.2.0 or later	21.5.0 or later	21.4.0 or later	21.6.0 or later	21.6.0 or later	2.0 or later
Epic Save Media integration	22.2.0 or later	22.2.0 or later	22.1.0 or later	21.5.1 or later	Not supported	Not supported	2.0 or later
Auto-moderator PIN	22.2.0 or later	22.2.0 or later	22.2.0 or later	22.2.0 or later	Not supported	Not supported	2.0 or later

Super Admin: Enable Epic integration (On-premises only)

Note 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 enable Epic integration:

1. Log in to the Admin portal using your Super Admin account.
2. On the top menu, click Settings.
3. On the left panel, expand Feature Settings and click Epic Integration. The Epic Integration page displays.
4. Select the Enable Epic Integration check box.
   
5. Click Save.

Tenant Admin: Configure Epic with VidyoConnect CAL

• Configure Epic Integration (and enter the Crypt Key)
• Configure the Epic Interconnect Server
• Generate an Epic CAL URL Link
• Change Epic Mode
• Download an API Usage Report

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 Super Admin: Enable Epic integration.

If you are a cloud customer, you must complete the Tenant Admin steps below to configure your Epic integration. You can then perform the additional optional procedures on the Epic Integration page.

Configure Epic integration

To configure the Epic integration:

1. Log in to the Tenant Admin portal.
2. On the top menu, click Settings.
3. On the left panel, expand Feature Settings and click Epic Integration. The Epic Integration page displays.
   
4. Select the Enable EPIC Integration checkbox to enable Epic Integration and to enable the rest of the page options. (This checkbox will already be selected if you have an existing Epic integration).
5. In Crypt Key, configure the Epic integration for the tenant by entering a 16-digit alphanumeric Crypt Key. (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.
• 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.
• You must enter the same Crypt Key in your Epic configuration. This key will be used for encrypting and decrypting the URL strings.
• 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.
6. Go to the Configure the Epic Interconnect Server procedure to troubleshoot any issues. Then, you can do one of the following:
• Click Save. Proceed to any of the following procedures:
• Generate an Epic CAL URL Link
• Change Epic Mode
• Download an API Usage Report

Generate a sample 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.

1. In SessionID, enter any unique shared context ID identifier which is shared across users joining a single Vidyo session.
2. In ConferenceID, enter the Epic Video Visit Conference ID (Encounter CSN).
3. In ExternalID, enter the ID for the user.
4. In ExternalIDType, select 1 for EMP, Provider or 2 for WPR, Patient. 5. In FirstName, enter the first name of the person joining the conference
5. In FirstName, enter the first name of the person joining the conference.
6. In LastName, enter the last name of the person joining the conference.
7. In AppointmentTime (Optional), enter or select the scheduled time for the video visit in hours or minutes for your test conference (ex. HH:MM/AM/PM).
8. Use Timestamp (Optional) to test Automatic Epic CAL link expiration for ad-hoc rooms.
9. In orgid (Optional), if you are using multiple Epic Interconnect Servers, enter the Epic Interconnect/SetExternalConnectionStatus orgid. If you are only using one Epic Interconnect Server, leave blank.
10. Use LinkValidityPeriod to test Automatic Epic CAL link expiration.
11. Use AP to test Configure auto-provisioned providers.
12. Use AllowMod to test Configure an auto-moderator PIN.
13. Use EBM to test Configure auto-provisioned providers.
14. Use InviteID to test Configure auto-invite of participants.
15. Click Generate to generate the Epic CAL URL link. The test call link is generated in the Sample URL text box. You can copy this link to compare the generated extData from Epic's system to look for discrepancies. Alternatively, you can join this link in a browser to simulate a doctor or patient test call.
16. Click Save.

Change the Epic mode

The default mode is Test.

1. Under Epic Mode, 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.
• 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.
• 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.

Configure 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 sign next to the Notification button.
   
2. In the URL field, enter the URL provided by your Epic Technical Support.
3. In the Username field enter the Epic Interconnect/SetExternalConnectionStatus user name. For example, "emp$" is a required prefix for username (e.g., emp$12345).
4. In the Password field, enter the Epic Interconnect/SetExternalConnectionStatus password.
5. If you are using multiple Epic Interconnect Servers, in the orgid field, enter the Epic Interconnect/SetExternalConnectionStatus orgid. in the orgid (Optional) field. If you are only using one Epic Interconnect Server, leave blank.
6. Click Connection test. If there is an issue with connecting to the server, an Error dialog displays with an HTTP status notification/code and message such as in the example below.
   
7. Click Save.

Download 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.
   
2. Click Export. The system generates a spreadsheet in the lower left-hard corner of the screen for you to download.
3. Click Save.

Automatic join via browser

• Terminology
• Prerequisites
• Use the jvw parameter

Terminology

Before configuring advanced workflows, 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. Note: 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	This is the number of minutes that a CAL link is valid from the start of the period 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	This optional parameter, which can be included in the encrypted parameter CRYPTSTRING, can be used to override the Default CAL link validity period for an individual CAL link.
Timezone of Epic	This is the time zone that your Epic system resides in. That is, it is the time Integration Server.
Default CAL link	This is the number of minutes that a CAL link is valid from the start of the validity period AppointmentTime if the LinkValidityPeriod parameter is not specified or is invalid.
Timestamp	This is a field in the encrypted CRYPTSTRING of an Epic CAL link that indicates the current time in the UNIX time format (in seconds).

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

This feature requires:

• VidyoConnect WebRTC enabled on your Tenant
• Native WebRTC deployment for mobile WebRTC workflows If a participant does not meet the WebRTC or VidyoPortal requirements, 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:
  
• VidyoConnect mobile application (iOS and Android):
  

Use the jvw parameter

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 browser" window.

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

Note 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. 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

• Prerequisites
• Configure your tenant
• Add the LinkValidityPeriod parameter to the CRYPTSTRING
• Test

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.

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

Configure your tenant

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

1. Log in to the Admin portal using your Admin account.
2. On the top menu, click Settings.
3. On the left panel, expand Feature Settings and click Epic Integration. The Epic Integration page displays.
4. Select the Enable EPIC Integration checkbox if it’s not already selected.
5. In Default CAL link validity period (minutes), 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.
6. In Timezone of Epic Integration Server, select the time zone where the Epic server is located.
7. Click Save.

Add the LinkValidityPeriod parameter to the CRYPTSTRING

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

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 CRYPTSTRING with the LinkValidityPeriod parameter set for a 60 minute expiration period (with added line breaks for legibility):

Note 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.

Test

Use the Context Aware Sample Link Generator in the Admin portal to generate a sample Epic CAL URL link with the LinkValidityPeriod parameter.

Automatic Epic CAL link expiration for ad-hoc rooms

• Prerequisites
• Configure your tenant and add the LinkValidityPeriod parameter
• Add the Timestamp parameter to the CRYPTSTRING

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

Configure your tenant and add the LinkValidityPeriod parameter

Follow the instructions in Automatic Epic CAL link expiration to:

• Configure the default CAL link validity period and time zone of the Epic Integration Server in the Tenant Admin.
• Add the LinkValidityPeriod parameter to the CRYPTSTRING.

Add the Timestamp parameter to the CRYPTSTRING

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

Parameter	Value
Timestamp	Unix timestamp in seconds.

The Timestamp 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 CRYPTSTRING with the LinkValidityPeriod parameter set for a 60minute expiration period (with added line breaks for legibility):

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link with the Timestamp parameter.

Configure auto-provisioned providers

• Prerequisites
• Terminology
• Configure your tenant
• Add endpoint behaviors
• Add the parameters to the CRYPTSTRING
• Test

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

Note Each auto-provisioned provider consumes a Seat license.

Configure your tenant

To configure your tenant:

1. Log in to the Tenant Admin using your Admin account.
2. On the top menu, click Settings.
3. On the left panel, expand Feature Settings and click Epic Integration. The Epic Integration page displays.
   
4. Select the Allow Auto-Provisioning of Providers checkbox.

Add endpoint behaviors

For information about how to add Endpoint Behaviors via Vidyo's REST APIs, see the Endpoint Behavior Mode API.

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.

Add the parameters to the 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 Note: Values must be included inside the encrypted CRYPTSTRING.
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).

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link with the AP and EBM parameters.

Configure the auto-invite of participants

• Prerequisites
• Add the InviteID parameter to the CRYPTSTRING
• Test

Using Vidyo’s Epic Context-Aware Linking (CAL) integration, providers can now invite other participants automatically by invoking a link using a new parameter. By including the parameter inviteID=<entityID> into the Epic CAL CRYPTSTRING, the VidyoPortal will automatically invite that participant into the Epic CAL conference.

Invitees can be:

1. VidyoConnect registered users
2. VidyoRoom registered users
3. Custom endpoints based on VidyoClient

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

Add the InviteID parameter to the CRYPTSTRING

The InviteID is an optional CAL link parameter that allows Epic integrations to invite a user into a conference using their entityID.

Parameter	Value
InviteID	Numeric entityID (obtained via SOAP API request on VidyoPortal).

The InviteID parameter 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 CRYPTSTRING with the InviteID parameter (with added line breaks for legibility):

Invitees must be online and not in a conference—just as one would need to be to receive a call invite.

directDial versus InviteID parameters

There are some similarities between the directDial and InviteID parameters, but there are some key differences that are important to note.

	DirectDial Parameter	InviteID Parameter
Parameter location	Outside of CRYPTSTRING	Inside of CRYPTSTRING
User type	Registered user only	Guest or registered user
Room	Uses ad-hoc Room	Uses Epic CAL-generated room (CSN based)
Epic notification	No Epic notification	Triggers Epic SetExternalConnectionStatus API
Disconnection	Auto-disconnect of invitee when call hangs up (standard P2P flow)	Does not auto-disconnect invitee when call hangs up

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link with the InviteID parameter.

Play audio or video content in a waiting room

• Prerequisites
• Media files
• Parameters
• Configure your tenant
• Add the parameters to your Epic CAL working link
• Test

Healthcare customers using Epic CAL can now play music, display a background, or show a video to patients who are waiting for their healthcare providers to join their VidyoConnect call. You can customize this feature so that the patients in the waiting room can:

• Listen to audio (with or without a background image)
• See a background image (with or without audio)
• View a video

Providers can specify the audio, background image, or video content to be played in the waiting room. They can also select different content for different calls.

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

Media files

To play audio or video files or display a background for your VidyoConnect users, you must use the following media formats:

• Audio content: .ogg or .mp3 format
• Background content: .png or .jpg format
• Video content: .mp4 or .webm (vp8) format

Audio and video content

For audio and video content, the media files for each format must have the same name and be stored in the same location.

For example, if you have an audio file called waiting that you want to play to VidyoConnect users on both Windows and Mac, you must save the file as both waiting.mp3 and waiting.ogg and store both files in the same location, such as:

• https://cv-workshop.herokuapp.com/test/waiting.mp3
• https://cv-workshop.herokuapp.com/test/waiting.ogg

Despite having to store both file types for audio and video content, Tenant Admins only have to specify one file type in the Value field on the Settings > Feature Settings > Custom Parameters page. Provided both the .mp3 and the .ogg file types are in the same location, both Windows and Mac users will be able to hear the audio file.

Background content

For background content, only one format needs to be stored. For example, if you store a waiting .png file, you don't also have to store a waiting .jpg file. Both Windows and Mac users will be able to access .png files as well as .jpg files.

Parameters

The following parameters control whether VidyoConnect users hear audio, view a background, or see a video while in a waiting room.

Parameter	Value
wrac	Controls whether audio content is played in the waiting room while users wait for the physician to join the VidyoConnect call.
wrbc	Controls whether background content is displayed in the waiting room while users wait for the physician to join the VidyoConnect call.
wrvc	Controls whether video content is played in the waiting room while users wait for the physician to join the VidyoConnect call.

The Tenant Admin must add and configure these custom parameters as described below.

Configure your tenant

To configure your tenant:

1. Log in to the Tenant Admin using your Admin account.
2. On the top menu, click Settings.
3. On the left panel, expand Feature Settings and click Custom Parameters.
4. Select the Enable Custom Parameters checkbox and click Save.
   
5. At the bottom of the page, click Add Custom Parameters. The Add Custom Parameters dialog displays.
   
6. In Auth type, select whether registered or unregistered (guest) users will be able to use the URL. If you want both types of users to have access, you can add a custom parameter for each type.
7. In Key, type wrac# to play audio in the waiting room, type wrbc# to display a background in the waiting room, or type wrvc# to play a video in the waiting room.

Note The # can be any number; however, it must match the configuration parameter entered in the Epic CAL working link. For example, if you enter wrac7 in the Key field, your Epic link must include wrac=7.

8. In Value, type the path of the audio, background, or video content.
9. Click Save. The Auth Type, Key, and Value you configured appear on the Custom Parameters list.

Add the parameters to your Epic CAL working link

Add the parameters as described in Invoke VidyoConnect with parameters.

Note The wrac, wrbc, and wrvc parameters must be outside the Epic CAL CRYPTSTRING.

The value used for the parameter must match the parameter entered in the Key field on the Tenant Admin Settings > Feature Settings > Custom Parameters page. For example, if wrac7 is entered in the Key field, you must use wrac=7 in your Epic CAL working link.

Here is an example (with added line breaks for legibility):

This link would invoke VidyoConnect with the following custom invocation parameters (with added line breaks for legibility):

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link.

Configure Epic Save Media integration

• Prerequisites
• App Market requirements
• Configure your Epic environment
• Configure your tenant
• Update your FDI record for LaunchToken
• Test

Vidyo supports a direct integration with Epic whereby providers using VidyoConnect can take a snapshot of what a patient is showing to the camera and have that snapshot automatically saved into that patient’s chart.

To enable this functionality, Vidyo has added support for the SMART of FHIR integration with Epic. This requires deploying the Vidyo Epic Service.

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

This integration requires the Vidyo Epic Service:

• If you are a VidyoCloud customer, this will be set up for you automatically.
• l If you are an On-Premise customer, you need to deploy and configure this component by following the instructions in Deploy Vidyo Epic Service. You must also enable the Auto-Provisioned Provider feature on your tenant. For more information, see Configure auto-provisioned providers.

Note We highly recommend that you configure this integration on a test tenant before you update your production tenant.

App Market requirements

If you are currently using the Vidyo Context-Aware Linking version 1.0 in Epic App Market, to use the client-IDs that support SMART on FHIR and Save Media, you need to request access to the updated Vidyo Context Aware Linking version 2.0 App via Epic App Market.

1. Log into https://appmarket.epic.com.
2. Search for the Vidyo Context-Aware Linking app.
3. Click Request Download.
4. Vidyo will get a notification of this request and usually withing 24-48 hours it will be approved. If it is not approved, please create a ticket with Vidyo Support.

Note Not all App Market users have permissions to request an updated or new app. Please reach out to your Epic TS for information on who in your organization has the appropriate permissions.

Configure your Epic environment

1. To set up Save Media, you need to set up Context-Aware Linking (OAuth2 approach) in your Epic environment.
2. Obtain your SMART on FHIR URL from the Epic Interconnect configuration. This is needed to setup your Vidyo tenant. Confirm that this URL is on the allowlist for your environments.
3. Confirm with your Epic team that the SMART on FHIR URL is enabled for both read and write access.
4. Configure your TXT Record Configuration to Define Which Web Services Are Available to Third-Party Video Clients (Vidyo).
5. Configure your TXT Record Configuration to Enable Additional Video Visit Features Using the TelemedicineConfiguration Web Service

Note For additional guidance on the above steps, reach out to your Epic TS.

Configure your tenant

Note You must make sure that you have enabled the updated Client-IDs via App Orchard before changing the App version. This change will update all requests to use the new Epic Client ID – including the SetExternalConnectionStatus API.

Note You must make sure that you have enabled the updated Client-IDs via App Orchard before changing the App version. This change will update all requests to use the new Epic Client ID – including the SetExternalConnectionStatus API.

To configure SMART on FHIR in the Tenant Admin:

1. Log in to the Tenant Admin using your Admin account.
2. On the top menu, click Settings.
3. On the left panel, expand Feature Settings and click Epic Integration. The Epic Integration page displays.
4. In the Epic Mode section:
1. Select the appropriate Mode. This is usually based on the environment on which you are enabling this feature. We recommend that you always start with TEST for initial build and testing. Only select PRODUCTION after all your testing has been completed and is successful.
2. Expand the App version list and select v2.
   
5. In the SMART on FHIR section:
1. Select the Enable SMART on FHIR checkbox.
2. Enter the URL provided by Epic in FHIR Server Endpoint URL.
   
6. Click Save.

Update your FDI record for LaunchToken

To provide your Providers with links that can invoke the Save Media integration, an additional dynamic parameter, launchToken, must be added to the generated Epic CAL link. To do this, the FDI build needs to be updated.

Note The launchToken parameter should ONLY be added to Provider links. It should not be added to patient links. For this link to work, the Provider must be using VidyoConnect for Desktop 22.1.0 or later.

1. In Client ID, add the Vidyo Context-Aware Linking Client ID (as defined in App Market for the Vidyo Context-Aware Linking App – version 2.0).
2. In OAuth2 Type, add 81454-TELEHEALTH - NO CONNECTION OAUTH TOKEN TYPE
3. Add the &launchToken=%OAUTHLAUNCHID% to the CRYPTURL mnemonic:

https://[tenant-url]/join/?extDataType&extData=%CRYPTSTR%&launchToken=%OAUTHLAUNCHID%

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link.

Configure an auto-moderator PIN

• Prerequisites
• Add the allowMod parameter to the CRYPTSTRING
• Test

Using Vidyo’s Epic Context-Aware Linking (CAL) integration, multiple providers can now be given moderation privileges explicitly by a parameter in the CRYPTSTRING.

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

Add the allowMod parameter to the CRYPTSTRING

allowMod is an optional CAL link parameter that allows Epic integrations to automatically give providers the ability to moderate a conference. This parameter must be used together with the AP=1 parameter (Auto-provisioned provider).

Parameter	Value
allowMod	0 - indicates moderation is not allowed for the given provider (default). 1 - indicates moderation is enabled for the given provider (values must be included inside the encrypted CRYPTSTRING)

The allowMod parameter must be included inside the CRYPTSTRING as part of the encrypted extData that is passed to Vidyo from the Epic FDI record.

Here is an example of a decrypted CRYPTSTRING with the allowMod parameter (with added line breaks for legibility):

When allowMod is used for a conference, only the providers that have the allowMod=1 parameter invocation will receive moderation privileges.

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link with the allowMod parameter.

Deploy the Vidyo Epic Service

To deploy the Vidyo Epic Service:

1. Deploy the VidyoEpicServices OVA file.
2. Set up a custom SSL certificate.
3. Set up the VidyoPortal Service.
4. Configure the Vidyo Discovery Service.

Prerequisites

• Network information
• Certificates
• Firewall
• Machine provisioning
• Access
• Files

The following are the items you require before you can begin the setup:

Network information

• IP Address
• Subnet Mask
• Default Gateway
• DNS Server(s)
• Public FQDN - should already be added to DNS

Certificates

• PFX file for certificate that covers the Public FQDN

Firewall

• Inbound TCP Port 443 open to the public (where your WebRTC endpoints will be coming from).
• Inbound TCP Port 22 open ONLY from the Administrative network (for configuration only).

Machine provisioning

• Minimum of 8 vCPUs for Production with 18 GHz Reserved; 4 vCPU for Lab use
• Minimum of 8 GB RAM for Production with 8 GB Reserved; 4 GB for Lab use
• 50 GB Disk

Access

• SSH access to the deployed OVA for System Console access
• Platform API user configured with appropriate SSH key

Files

• VidyoEpicService-21.1.0.050.01.ova

Deploy the VidyoEpicServices OVA file

Use the following procedure to deploy the Vidyo Epic Services OVA file.

1. In your VMWare environment, ensure that your machine provisioning meets the requirements in the Prerequisites section.
2. Deploy the VidyoEpicServices OVA file in your VMWare environment.
3. Power on the machine.
4. Log in to the VMWare console with your default username and password: admin/password.
5. Configure the following:
1. IP Address
2. Subnet Mask
3. Default Gateway
4. DNS Server (s)
5. Server name and domain (Server FQDN)
6. Reboot.

Set up a custom SSL certificate

You need the following to successfully set up a custom SSL certificate:

• The Platform APIs
• A PBX file with the certificate
• An SSH private/public key pair

Note How to generate an SSH key is outside the scope of this document.

To set up the custom SSL certificate:

1. In the Vidyo Console, set up a VidyoPlatform API user.
2. Use the SSL_InstallPFX API to install the PFX on the server. SSL_InstallPFX is used to install password protected .pfx files. This install is done in two steps:
1. Use the VidyoUpload Platform API to upload the .pfx file to the VidyoEvent Service server.
   
2. Run the SSL_InstallPFX Platform API to install the .pfx file:
   
3. Reboot your server to apply the configurations.

Set up the VidyoPortal Service

• Obtain the JWT Authentication Secret
• Generate a Server Token
• Configure the VidyoPortal Token Level Event Service

Obtain the JWT Authentication Secret

You can obtain a JWT Authentication Secret by either one of these methods:

• Generate a JWT Authentication Secret
• Set a JWT Authentication Secret

Caution If you have already configured the Vidyo Event Service with a JWT Authentication Secret, you must use the same Secret here. Do not generate a new one; instead, skip this procedure and enter the Secret in the Vidyo Service Console.

Generate a JWT Authentication Secret

The VidyoPortal can generate its own random Authentication Secret and return that back as part of a REST API response.

URL: /admin/api/v1/system/tenants/jwtAuthenticationSecret

Method: PUT

Authentication: Super credentials

Response Body

Field	Data type	Mandatory	Description
version	String	Y	Defines the version of the API.
status	String	Y	Defines the response status. For a successful response, the value will be success.
data	Object	Y	This is the element which encapsulates the API response. For this API, the value is null.
Secret	String	Y	This is the new authentication secret generated on the change of signing algorithm.

HTTP status codes, error codes, and messages

HTTP response code	Error code	Error message	Scenario
400	101017	Invalid request.	If signing algorithm name is valid. Any other request body is a validation failure.
404	101018	Signing algorithm is not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
404	101019	Authentication secret was not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
403	N/A	N/A	Unauthorized user. If anybody other than the Super Admin tries to access. Invalid tenant ID/FQDN.
500	1010120	Internal server error.	Internal server error.

Configure an auto-moderator PIN

• Prerequisites
• Add the allowMod parameter to the CRYPTSTRING
• Test

Using Vidyo’s Epic Context-Aware Linking (CAL) integration, multiple providers can now be given moderation privileges explicitly by a parameter in the CRYPTSTRING.

Prerequisites

For the required component versions for this feature, see Epic CAL feature compatibility with Vidyo versions.

Add the allowMod parameter to the CRYPTSTRING

allowMod is an optional CAL link parameter that allows Epic integrations to automatically give providers the ability to moderate a conference. This parameter must be used together with the AP=1 parameter (Auto-provisioned provider).

Parameter	Value
allowMod	0 - indicates moderation is not allowed for the given provider (default). 1 - indicates moderation is enabled for the given provider (values must be included inside the encrypted CRYPTSTRING)

The allowMod parameter must be included inside the CRYPTSTRING as part of the encrypted extData that is passed to Vidyo from the Epic FDI record.

Here is an example of a decrypted CRYPTSTRING with the allowMod parameter (with added line breaks for legibility):

When allowMod is used for a conference, only the providers that have the allowMod=1 parameter invocation will receive moderation privileges.

Test

Use the Context Aware Sample Link Generator in the Tenant Admin to generate a sample Epic CAL URL link with the allowMod parameter.

Deploy Vidyo Epic Service

• Prerequisites

To deploy the Vidyo Epic Service:

1. Deploy the VidyoEpicServices OVA file.
2. Set up a custom SSL certificate.
3. Set up the VidyoPortal Service.
4. Configure the Vidyo Discovery Service.

Prerequisites

• Network information
• Certificates
• Firewall
• Machine provisioning
• Access
• Files

The following are the items you require before you can begin the setup:

• Network information
• IP Address
• Subnet Mask
• Default Gateway
• DNS Server(s)
• Certificates
• PFX file for certificate that covers the Public FQDN
• Firewall
• Inbound TCP Port 443 open to the public (where your WebRTC endpoints will be coming from).
• Inbound TCP Port 22 open ONLY from the Administrative network (for configuration only).
• Machine provisioning
• Minimum of 8 vCPUs for Production with 18 GHz Reserved; 4 vCPU for Lab use
• Minimum of 8 GB RAM for Production with 8 GB Reserved; 4 GB for Lab use
• 50 GB Disk
• Access
• SSH access to the deployed OVA for System Console access
• Platform API user configured with appropriate SSH key
• Files
• VidyoEpicService-21.1.0.050.01.ova

Deploy the VidyoEpicServices OVA file

Use the following procedure to deploy the Vidyo Epic Services OVA file.

1. In your VMWare environment, ensure that your machine provisioning meets the requirements in the Prerequisites section.
2. Deploy the VidyoEpicServices OVA file in your VMWare environment.
3. Power on the machine.
4. Log in to the VMWare console with your default username and password: admin/password.
5. Configure the following:
1. IP Address
2. Subnet Mask
3. Default Gateway
4. DNS Server (s)
5. Server name and domain (Server FQDN)
6. Reboot.

Set up a custom SSL certificate

• The Platform APIs
• A PBX file with the certificate
• An SSH private/public key pair

Note How to generate an SSH key is outside the scope of this document.

To set up the custom SSL certificate:

1. In the Vidyo Console, set up a VidyoPlatform API user.
2. Use the SSL_InstallPFX API to install the PFX on the server. SSL_InstallPFX is used to install password protected .pfx files. This install is done in two steps:
1. Use the VidyoUpload Platform API to upload the .pfx file to the VidyoEvent Service server.
   
2. Run the SSL_InstallPFX Platform API to install the .pfx file:
   
3. Reboot your server to apply the configurations.

Set up the VidyoPortal Service

• Obtain the JWT Authentication Secret
• Generate a Server Token
• Configure the VidyoPortal Token Level Event Service

Obtain the JWT Authentication Secret

You can obtain a JWT Authentication Secret by either one of these methods:

• Generate a JWT Authentication Secret
• Set a JWT Authentication Secret

Caution If you have already configured the Vidyo Event Service with a JWT Authentication Secret, you must use the same Secret here. Do not generate a new one; instead, skip this procedure and enter the Secret in the Vidyo Service Console.

Generate a JWT Authentication Secret

The VidyoPortal can generate its own random Authentication Secret and return that back as part of a REST API response.

URL: /admin/api/v1/system/tenants/jwtAuthenticationSecret

Method: PUT

Authentication: Super credentials

Response Body

Field	Data type	Mandatory	Description
version	String	Y	Defines the version of the API.
status	String	Y	Defines the response status. For a successful response, the value will be success.
data	Object	Y	This is the element which encapsulates the API response. For this API, the value is null.
Secret	String	Y	This is the new authentication secret generated on the change of signing algorithm.

HTTP status codes, error codes, and messages

HTTP response code	Error code	Error message	Scenario
400	101017	Invalid request.	If signing algorithm name is valid. Any other request body is a validation failure.
404	101018	Signing algorithm is not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
404	101019	Authentication secret was not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
403	N/A	N/A	Unauthorized user. If anybody other than the Super Admin tries to access. Invalid tenant ID/FQDN.
500	1010120	Internal server error.	Internal server error.

Set a JWT Authentication Secret

URL: /admin/api/v1/system/tenants/jwtAuthenticationSecret

Method: PUT

Authentication: Super credentials

Request Body

Field	Data type	Mandatory	Description	Validations
N/A	String	N	The authentication secret. For example: deC;p<V:3#p85?S3T#,4SqpJ6&7R(C"rET(<HPr3	Validation of authentication secret. It must contain at least one: Capital letter Special character Number The length of the authentication secret is dependent upon the JWT signing algorithm. For HS384, the size minimum is 48 characters. Should be encoded in Base64.
3gb5Zi3sDzs8oNAUiHlvd2SjBRZnnoAlQ3l1eIbEFlbsciNCglGuFw8sNNLyAEZb (BASE 64)

Response Body

Field	Data type	Mandatory	Description
version	String	Y	Defines the version of the API.
status	String	Y	Defines the response status. For a successful response, the value will be success.
data	Object	Y	This is the element which encapsulates the API response. For this API, the value is null.
Secret	String	Y	This is the new authentication secret generated on the change of signing algorithm.

HTTP status codes, error codes, and messages

HTTP response code	Error code	Error message	Scenario
400	101017	Invalid request.	If signing algorithm name is valid. Any other request body is a validation failure.
404	101018	Signing algorithm is not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
404	101019	Authentication secret was not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
403	N/A	N/A	Unauthorized user. If anybody other than the Super Admin tries to access. Invalid tenant ID/FQDN.
500	1010120	Internal server error.	Internal server error.

Generate a Server Token

To generate a server token:

1. Log into the System Console.
2. Go to Advanced > VidyoEpic > Security Management > Portal Token: <generate>.
   
3. Select OK. The Confirm page displays.
   
4. Select Yes. The Portal Token is generated and appears on the Message page.
   
5. Take note of the generated Token (you will need it in the next procedure) and then click OK.

Configure the VidyoPortal Token Level Event Service

To complete the setup, you need the following:

• ServerToken: This is the Portal Token generated in the Generate a server token section.
• Super Admin credentials.

Set the Portal Token on the VidyoPortal (REST API)

URL: https://{tenantFQDN}/admin/api/v1/serverTokens

Method: POST

Authentication: Super credentials

Request Body

Field	Data type	Mandatory	Description	Validations
serverToken	String	Y	Token is in GUID format.	It is validated by GUID 8-3-3-3-12 characters (alphanumeric).

Response Body

Field	Data type	Mandatory	Description
version	String	Y	Defines the version of the API.
status	String	Y	Defines the response status. For a successful response, the value will be success.
data	Object	Y	This is the element which encapsulates the API response. For this API, the value is null.

HTTP status codes, error codes, and messages

HTTP response code	Error code	Error message	Scenario
400	101017	Invalid request.	If signing algorithm name is valid. Any other request body is a validation failure.
401	101018	Signing algorithm is not configured.	If signing algorithm is fetched while it is not configured at the tenant level.
403	N/A	N/A	Unauthorized user. If anybody other than the Super Admin tries to access. Invalid tenant ID/FQDN.
500	1010120	Internal server error.	Internal server error.

Configure the Vidyo Discovery Service

The Vidyo Discovery Service is an optional component that can be configured on the same deployment of the Vidyo Epic Service. The Vidyo Discovery Service serves as a location to point endpoints to where they can discover where certain services are hosted; in this case, the Vidyo Epic Service. You can optionally choose to host this JSON file in another location instead of on the Vidyo Epic Service. If you choose to do so, just upload the JSON file to that location and skip to Apply the custom parameters to your tenant.

This section provides the information you require to configure the Vidyo Discovery Service:

• Setup prerequisites
• Create the services file
• Upload the services file
• Apply the custom parameters to your tenant

Setup prerequisites

1. Vidyo Epic Service Public FQDN: This is the URL (public) that clients will use to interact with the Vidyo Epic Service.
2. VidyoPlatform API credentials: These are the VidyoPlatform API credentials to the Vidyo Epic Service. These will be used to invoke certain commands.

Create the services file

Note Replace https://vidyoepicservice.example.com/epic/api/v1 with the Public FQDN of your deployed Vidyo Epic Service.

Upload the services file

1. Log into the System Console.
2. Set up a VidyoPlatform API user.

Note To continue, you must have an SSH private/public key pair generated. How to do this is outside the scope of this document.

3. Use the VidyoUpload Platform API to upload the services.json file to the Vidyo Epic Service server.
   
4. Run the VidyoDiscovery Platform API to update the file.
   
5. After the service file is updated, restart the service to apply the changes.
   
6. Verify the service.json file is available by going to the following path:
7. You should see the content of the service.json file that you uploaded.

Apply the custom parameters to your tenant

For information about how to configure the Tenant Admin for this feature, refer to the Configuring Custom Parameters section in the VidyoPortal and VidyoRouter Administrator Guide.

Using the Custom Parameters menu, add the following entry (replacing vidyoepicservice.example.com with your service URL).

Auth type	Key	Value
Registered	VidyoCloudServicesURL	https://vidyoepicservice.example.com/discovery/api/v1/services