Configuring Pexip Infinity to integrate with Epic telehealth

This topic describes the mandatory configuration and administrative steps that are required to integrate Pexip Infinity with an Epic telehealth system. This topic covers:

• Prerequisites and integration basics
• Platform routing and firewall requirements
• Ensuring a telehealth integration license is installed
• Creating an Epic telehealth profile
• Creating a Call Routing Rule for incoming calls
• Configuring Pexip Infinity to integrate with Epic telehealth
• Optional features

Prerequisites and integration basics

Before you perform the telehealth integration steps described here, you should:

• Perform a basic installation and configuration of Pexip Infinity. Any of Pexip Infinity's deployment models may be used (on-premises, cloud-hosted etc).
• Confirm that (non-telehealth) call connectivity is working correctly e.g. by calling two people into a test VMR via the Connect web app.
• Ensure that you are running Pexip Infinity version 28 or later if you are using Epic August 2022 or later.

Summary of Pexip Infinity configuration steps

After you have completed your standard implementation of the Pexip Infinity platform, these are the specific Epic telehealth integration configuration steps that you must perform within Pexip Infinity:

1. Install a telehealth integration license (Platform > Licenses).
2. Create an Epic telehealth profile (Call control > Epic Telehealth Profile).
3. Create a Call Routing Rule to manage and route the incoming telehealth calls from providers and patients (Services > Call routing).

All of these steps are described in detail below.

You can also perform some optional configuration to customize the integration or use additional features.

Recommended Epic crypto algorithms and compatibility

The recommended crypto algorithms for different Epic versions are:

• AES-256-CBC is recommended for Epic versions from August 2019 onwards
• AES-128-CBC may be used for older Epic versions (August 2018 onwards)

The oldest Epic version that works with Pexip Infinity is August 2018.

Epic configuration requirements

As well as the Pexip Infinity configuration guidelines contained within this documentation, you must also refer to Epic's Pexip Implementation Guide.

The configuration of the Epic and the Pexip Infinity installations need to align precisely (with certain shared secret configuration values) for the integration to work correctly. Please note the following important configuration requirements that must be implemented within Epic:

• FDI records must be created in Epic to integrate Epic with the Pexip Infinity installation. These ensure that both Epic and Pexip Infinity use the same algorithm and key to pass information between themselves.
• The uuid identifier of the Epic telehealth profile on Pexip Infinity must be included in the corresponding Launch URL (CRYPTURL) in the Epic FDI record.
• The OAuth2 redirect URLs defined in the Epic telehealth profile on Pexip Infinity must be registered within the Epic configuration.
• Refer to Epic/Citrix support if there is a need to launch a browser in a Hyperspace/Citrix environment to ensure that Chrome is used for the video call instead of Internet Explorer.

Platform routing and firewall requirements

Each Epic customer requires a self-hosted Pexip Infinity platform with the following routing/firewall requirements:

• At least one Conferencing Node (which could be a Proxying Edge Node) must be accessible from the computers/devices running the Epic apps, which typically means that the node needs to be publicly reachable. Alternatively, access could be routed via a reverse proxy. If required, the jinja templates can be used to load balance traffic across multiple Conferencing Nodes or to split provider traffic and patient traffic between different pools of Conferencing Nodes. For large environments (100+ concurrent video calls) we recommend that you contact your Pexip authorized support representative to discuss your architectural design.

• Firewall and DNS requirements are as for a standard Pexip Infinity public deployment. However, note that:

  • All inbound calls are placed via the Connect web app (WebRTC), so no SIP or H.323 ports are required for incoming calls.
  • All Conferencing Nodes that may be involved in handling telehealth calls, including all "internal" transcoding nodes that are processing conference media, must be able to connect out to port 443/TCP (HTTPS) on the Epic provider and patient systems.
  • If device pairing is used, or you want the ability to call out from the VMR to invite other participants into the meeting, then you need to ensure that you allow SIP or H.323 call signaling and media from your Conferencing Nodes to those video endpoints.
• There is nothing from the Epic/public side of the integration that needs to access the Pexip Infinity Management Node.

The web entry point used for the OAuth2 redirect URLs (typically a Proxying Edge Node or reverse proxy) must be stable. Subsequent changes to DNS names will require hard-to-coordinate changes on Epic’s side. Ensure that you use a DNS name that is suitable over the long term.

A typical deployment environment may look like this:

Ensuring a telehealth integration license is installed

You must have a telehealth integration license enabled on your Pexip Infinity platform (Platform > Licenses).

The telehealth license enables you to configure an Epic telehealth profile, and is required in addition to the standard Pexip Infinity call licenses. If necessary, contact your Pexip authorized support representative to purchase the required license.

Creating an Epic telehealth profile

The Epic telehealth profile configured on Pexip Infinity defines how the join URLs for providers and patients are constructed, and includes the shared encryption settings and keys that allow Pexip Infinity and the Epic servers to communicate securely.

At the start of the integration process, your Pexip authorized support representative will have given you various configuration items, including customer-specific secret credentials. Be very careful about copying and pasting the Epic encryption key and Application client secrets into your Epic telehealth profile. If there are any extra (or missing) characters in these fields, telehealth calls will fail to launch. Furthermore, as these fields are stored encrypted and are not decryptable by Pexip support, this can make it difficult to discover any typos when troubleshooting.

Go to Call control > Epic Telehealth Profile, select Add Telehealth Profile and configure the profile as described:

Supported jinja2 template variables

The following table shows which variables may be used in which templates. A indicates that the variable may be included in the template, whereas Mandatory indicates that the variable must be present in the template.

See Jinja2 templates and filters for more information about using jinja templates.

Error page template for launch failures

An error page is displayed to users If a telehealth call fails to launch correctly.

The contents of the page is determined by the Error page template for launch failures field in the telehealth profile. This field is an HTML/jinja2 template that typically contains a mixture of HTML markup and styles, literal text and jinja2 variables. It can also contain jinja2 control structures that allow you to vary the content of the page based upon certain conditions.

The default template is shown below but you may adapt the content as appropriate for your environment:

<!DOCTYPE html>
<html lang="en">
  <head>
      <title>Something went wrong</title>
      <style>
        .pexip-cell {
        padding: 20px;
        }
        .main-title {
        font-size: 22px;
        color: #4a4a4a;
        }
        .pexip-heading {
        font-weight: bold;
        font-size: 14px;
        color: #4a4a4a;
        }
        .pexip-info {
        font-size: 12px;
        color: #4990e2;
        }
          </style>
  </head>
  <body>
    <br>
    <table style=
           "width: 100%; border-collapse: collapse; border: 1px solid #e9e9e9; font-family: Calibri, sans-serif, serif;">
      <tbody>
        <tr>
          <td colspan="2" class="pexip-cell" style="vertical-align: top;">
            {% if error_name == "BorvoGetTelehealthDirectLaunchTokenError" %}
            <p><span class="main-title">That link isn't working at the moment. It might be a link for an old appointment, or for an appointment that isn't ready to start yet.</span></p>
            <p><span class="pexip-heading">Please check that you are using the correct link for your appointment today.</span></p>
            <p>
              <span class="pexip-heading">Extra information:</span><br>
                <span class="pexip-info">telehealth_request_id: {{telehealth_request_id}}</span><br>
                {% if detailed_debug_information %}
                <span class="pexip-info">Detailed debugging information: {{detailed_debug_information}}</span>
                {% endif %}
            </p>
            {% else %}
            <p><span class="main-title">Something went wrong - looks like an error on our end or on the network.</span></p>
            <p><span class="pexip-heading">Please close this window and try reconnecting.</span></p>
            <p>
              <span class="pexip-heading">If the error persists, please share the information below with your provider for troubleshooting:</span><br>
                <span class="pexip-info">utc_time: {{utc_time}}</span><br>
                <span class="pexip-info">telehealth_request_id: {{telehealth_request_id}}</span><br>
                {% if detailed_debug_information %}
                <span class="pexip-info">Detailed debugging information: {{detailed_debug_information}}</span>
                {% endif %}
            </p>
            {% endif %}
          </td>
        </tr>
      </tbody>
    </table>
  </body>
</html>

The default template has the following logic:

• First, It defines some styles for use within the page.

• It tests if error_name == "BorvoGetTelehealthDirectLaunchTokenError":

  • If true, it displays a message that the user may have used a link that is out of date or is not ready yet.
  • Otherwise (error_name is not "BorvoGetTelehealthDirectLaunchTokenError") this means an unexpected error has occurred and an appropriate message is displayed ("Something went wrong - looks like an error on our end or on the network").
• In both cases, the telehealth_request_id is displayed, and if detailed_debug_information is available then that is also displayed on the page.

The following variables are available in the error page template for launch failures: detailed_debug_information, error_name, telehealth_request_id and utc_time (full details are included above).

Email and SMS helper application and "direct join links"

"Direct join links" allow invitees, including guests, to join video visits directly. The links can be shared with end users via, for example, email or SMS and so on, using the Epic "Send Video Visit Link" activity. To enable direct join links:

• The Email and SMS helper application section of the Telehealth Profile on Pexip Infinity must be populated.
• You must enable the Pexip Direct Launch Backend app (this is a hidden app, not publicly listed on the Epic Vendor Services).
• Work with your Epic technical support representative to create appropriate Integration Records for Guest and Provider Direct Join Links records in your Epic environment. The records created must align with the settings on the Pexip Infinity Telehealth Profile configuration.

See Backend OAuth2 client ID and private/public keypairs for more information.

Creating a Call Routing Rule for incoming calls

You must create a Call Routing Rule within Pexip Infinity to manage and route the incoming telehealth calls appropriately.

1. Go to Services > Call routing and select Add Call Routing Rule.

2. Configure the following fields (leave all other fields with default values or as required for your specific deployment):

   Option	Description
   Name	The name of this rule e.g. "Epic telehealth".
   Priority	Assign the priority for this rule. If you are creating multiple rules you need to ensure that any other rules with a higher priority (lower number) will not process your telehealth calls.
   Incoming gateway calls	Ensure this option is selected.
   Outgoing calls from a conference	Leave this option unselected.
   Calls being handled in location	Applies the rule only if the incoming call is being handled by a Conferencing Node in the selected location. To apply the rule regardless of the location, select Any Location.
   Match incoming calls from registered devices only	Leave this option unselected.
   Match Infinity Connect (WebRTC / RTMP) Match SIP Match Lync / Skype for Business (MS-SIP) Match H.323 Match Teams	Select Match Infinity Connect (WebRTC / RTMP). Do not select any of the other protocols.
   Match against full alias URI	Leave this option unselected.
   Destination alias regex match	The objective of the match/replace strings is to extract the base_telehealth_alias from the dialed alias in the incoming call received by Pexip Infinity from Epic. The match string should map to the provider/patient alias templates in the telehealth profile. The example regex match of telehealth\.(.*)@(.*) works perfectly with the default telehealth profile alias templates. Example: telehealth\.(.*)@(.*)
   Destination alias regex replace string	When used with the example Destination alias regex match shown above you would use: \1 which would extract the base_telehealth_alias from the dialed alias.
   Theme	If required, assign a customized theme to this rule. For example, the theme could use alternative labels on some of the splash screens that are displayed when connecting the call. See Optional features and customizations for Epic telehealth integrations for more information.
   Call target	Select Epic Telehealth meeting.

3. Select Save.

Optional features

In addition to the basic configuration requirements described here, there are extra optional features you may want to consider that require additional configuration, including:

• Device pairing: this allows a provider to pair the Connect web app or desktop client with an external SIP or H.323 device and use it to handle the audio/video aspects of the call.

• Branding and customization: you can apply a range of branding or customization options:

  • Create your own theme to customize the splash screens (such as the Waiting for the host screen).
  • Create a customized Connect web app to control the web app's appearance and behavior on call completion.
  • Use local policy to change the default layout and other properties of the VMR.
• Dial out (teleconsult): enable dialing out to another provider from within the conference.

See Optional features and customizations for Epic telehealth integrations for more information.