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

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

  • Already performed a basic installation and configuration of Pexip Infinity. Any of Pexip Infinity's deployment models may be used (on-premises, cloud-hosted etc). Note that if you are using Pexip Smart Scale (PSS), then you need to deploy and configure a web proxy in order to use PSS with Epic telehealth.
  • Confirmed that (non-telehealth) call connectivity is working correctly e.g. by calling two people into a test VMR via the Infinity Connect web app.

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 Infinity 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:

Option Description
Name

The name of the telehealth profile. This name appears in the web app participant list (roster) and in the Pexip Infinity administrator interface as part of the service name, so we recommend setting it to the name of the hospital or healthcare organization.

Example: Healthcare Org

Description A description of the telehealth profile.
Unique uuid identifier for this telehealth profile

A unique identifier for the telehealth profile. A value is automatically assigned and there is normally no need to modify it.

Example: 12daaebc-ea75-43c1-a6c7-c044be66a36e

The corresponding Launch URL (CRYPTURL) in the Epic FDI record should include this uuid, for example:

https://yourpexipinfinityserver.example.com/api/telehealth/v1/patient/oauth2smartlaunch/12daaebc-ea75-43c1-a6c7-c044be66a36e?<parameters>

with the <parameters> replaced with appropriate parameters for your deployment as per Epic's own Pexip integration guide documentation. Note that the CRYPTURL configured in the Epic FDI record determines which telehealth profile is used for a particular call.

Domain name The name of the domain to use for telehealth aliases associated with this telehealth profile location.
Base URL of the Epic server

The base HTTPS URL of the Epic server.

Example: https://epic.example.com/

Epic OAuth2 base URL

The base HTTPS URL of the Epic server's OAuth2 APIs.

Example: https://epic.example.com/interconnect-aocurprd-oauth

Patient OAuth2 redirect URL

The OAuth2 redirect URL for the patient telehealth application.

Format: https://[infinity deployment]/api/telehealth/v1/patient/oauth2authorized/[uuid]

where:

  • [infinity deployment] is the address of your public Conferencing Node, Proxying Edge Node, reverse proxy or load balancer.
  • [uuid] is a unique uuid identifier for this telehealth profile (typically this should be the same as the uuid identifier entered above for this profile).

Example: https://yourinfinitydeployment.example.com/api/telehealth/v1/patient/oauth2authorized/12daaebc-ea75-43c1-a6c7-c044be66a36e

Provider OAuth2 redirect URL

The OAuth2 redirect URL for the provider telehealth application.

Format: https://[infinity deployment]/api/telehealth/v1/provider/oauth2authorized/[uuid]

where:

  • [infinity deployment] is the address of your public Conferencing Node, Proxying Edge Node, reverse proxy or load balancer.
  • [uuid] is a unique uuid identifier for this telehealth profile (typically this should be the same as the uuid identifier entered above for this profile).

Example: https://yourinfinitydeployment.example.com/api/telehealth/v1/provider/oauth2authorized/12daaebc-ea75-43c1-a6c7-c044be66a36e

Infinity web application base URL

The public base URL for the Pexip Infinity web app.

Example: https://[infinity deployment]/

where:

  • [infinity deployment] is the address of your public Conferencing Node, Proxying Edge Node, reverse proxy or load balancer.

Example: https://yourinfinitydeployment.example.com/

Patient application Client ID The unique OAuth2 application Client ID assigned by Epic for the Pexip telehealth patient application to use when contacting clients.
Provider application Client ID The unique OAuth2 application Client ID assigned by Epic for the Pexip telehealth provider application to use when contacting clients.
Template for provider aliases

The jinja2 template used for generating provider aliases used by providers (e.g. doctors) when joining a telehealth conference. This must include the value of {{base_telehealth_alias}} somewhere in the alias, although you can use your own choice of prefix and/or suffix.

Default: telehealth.{{base_telehealth_alias}}@{{telehealth_integration.telehealth_call_domain}}

See Supported jinja2 template variables for the full set of template variables that can be used in provider alias templates.

Template for patient aliases

The jinja2 template used for generating patient aliases used by patients when joining a telehealth conference. This must include the value of {{base_telehealth_alias}} somewhere in the alias, although you can use your own choice of prefix and/or suffix.

Default: telehealth.{{base_telehealth_alias}}@{{telehealth_integration.telehealth_call_domain}}

Provider WebRTC join link template

The jinja2 template used for generating HTTPS web join links used by providers (e.g. doctors) when joining a telehealth conference. It must include:

  • {{telehealth_alias}} variable somewhere in the link (usually as a conference=parameter)
  • pin parameter (so that the provider automatically opens the conference when they join)

and you may customize other aspects of the URI if required.

Default: {{telehealth_integration.infinity_webapp_server_base_url}}/webapp/#/?conference={{telehealth_alias}}&pin={{pin}}&name={{display_name}}

See Supported jinja2 template variables for the full set of template variables that can be used in join link templates.

Patient WebRTC join link template

The jinja2 template used for generating HTTPS web join links used by patients when joining a telehealth conference. It must include:

  • {{telehealth_alias}} variable somewhere in the link (usually as a conference=parameter)

and you may customize other aspects of the URI if required, although you should not include the pin parameter.

Default: {{telehealth_integration.infinity_webapp_server_base_url}}/webapp/#/?conference={{telehealth_alias}}&name={{display_name}}&role=guest

Service name template

The jinja2 template used for generating the telehealth conference/appointment name. It must include:

  • {{unique_encounter_id}} variable somewhere in the generated name; however you may add your own prefix or suffix to the ID if required.

The same service name is used for all participants who join the conference. Therefore if this integration is used for group appointments, the template must not include {{launch_information.fname}} or {{launch_information.lname}} as these will differ from patient to patient — and in which case you must modify the default template content.

Default: Appointment for {{launch_information.fname}} {{launch_information.lname}} {{telehealth_integration.name}}:{{unique_encounter_id}}{% if launch_information.encfacnpiname %} in {{launch_information.encfacnpiname}}{% endif %}

This default template generates a name of "Appointment for <first name> <last name> <profile name>:<Epic appointment ID" and also adds "in <encounter department>" if the department information has been provided by Epic.

See Supported jinja2 template variables for the full set of template variables that can be used in the service name template.

Error page template for launch failures

The jinja2 template used for generating the error page shown to users if the telehealth call launch fails. You may adapt the template styles and text as appropriate for your environment.

See Error page template for launch failures for more information.

Epic encryption key

The encryption key used to encrypt and decrypt telehealth parameters passed from Epic to Pexip Infinity when launching calls associated with this telehealth Integration.

  • If the encryption algorithm is AES-256-CBC then the key type must be base64-encoded key (not password), and the key itself must be a base64-encoded 32 byte random value.
  • If the encryption algorithm is AES-128-CBC then the key type may be base64-encoded key or password. If a base 64 key is used the key itself must be a base64-encoded 16 byte random value. A password may be any length.

Both Epic and Pexip Infinity must be configured to use exactly the same algorithm and key in order for information to be passed correctly.

See Epic encryption keys, client secrets and OAuth2 keypairs for more information.

Encryption key type

The type of the encryption key. It may be a simple text password from which a key will be derived, or it may be a predefined base64-encoded key. If AES-256-CBC is the encryption algorithm used, a base64-encoded key is mandated. Options are:

  • Simple password
  • Base 64 encoded key

Default: Simple password

Epic encryption algorithm

The encryption algorithm used by Epic when encrypting telehealth call parameters during telehealth call launch. For Epic releases from August 2019 onwards AES-256-CBC is recommended. Options are:

  • AES-128-CBC
  • AES-256-CBC

Default: AES-128-CBC

Patient application Client Secret

The unique OAuth2 application Client ID assigned by Epic for the Pexip telehealth patient application.

Currently, the same value is used for both the Patient and Provider secrets on a single telehealth profile.

See Epic encryption keys, client secrets and OAuth2 keypairs for more information.

Provider application Client Secret The unique OAuth2 application Client ID assigned by Epic for the Pexip telehealth provider application. This should be set to the same value as the Patient application Client Secret.
Email and SMS helper application
Backend OAuth2 application Client ID

The unique OAuth2 application Client ID assigned by Epic for the Pexip backend application to use when contacting the Epic server.

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

Epic OAuth2 token URL for the backend application

The HTTPS URL of the Epic server's OAuth2 token URL.

Example: https://epic.example.com/interconnect-aocurprd-oauth/oauth2/token

Backend OAuth2 private key

The private key for the Pexip backend OAuth2 application to use when authenticating to Epic.

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

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 indicates that the variable must be present in the template.

    Allowed in template?
Variable name Description Alias Join link Service name Error page
base_telehealth_alias

A unique one-time alias for this join attempt, that must be included in the alias templates. It forms part of the overall conference alias that is specified in the WebRTC join link.

This is the element that the associated Call Routing Rule should extract from the dialed conference alias when routing the incoming call.

     

detailed_debug_information

Contains debug information about the failure to launch a call that can be used to help diagnose the problem.      

display_name

The name of the provider/patient displayed in the VMR:

  • Providers: the telehealth_integration.name (e.g. "Healthcare Org") as the name of the practitioner may not be available to Pexip Infinity.
  • Patients: the display name supplied by Epic during launch.
 

   
error_name

The error name (returned from Epic) that can be used to decide which messages to display to the user on the error page:

  • An error_name of "BorvoGetTelehealthDirectLaunchTokenError" is returned if the launch link was not valid. This error could be expected to occur in a working environment. It might be because the user has selected a link for an old appointment, or for an appointment that isn't ready to start yet.
  • Any other error names that might be returned are the result of an unexpected error, and we recommend that these are all treated in the same manner.
     

launch_information

This variable contains appointment information provided by Epic.

It may only be used in the service name template. It contains the following fields:

  • fname: patient first name
  • lname: patient last name
  • encfacnpiname: encounter department

Example: "Appointment for {{launch_information.fname}} {{launch_information.lname}} in {{launch_information.encfacnpiname}}"

   

 
pin

A randomly-generated 8-digit Host PIN.

This is mandatory for provider join links, and optional for patient join links.

 

   
telehealth_alias The provider/patient alias (generated from the provider and patient alias templates).  

   
telehealth_integration

This variable contains various properties of the telehealth profile configured in Pexip Infinity. It contains the following fields:

  • telehealth_call_domain: the profile's Domain name
  • name: the profile's Name
  • description: the profile's Description
  • integration_uuid: the profile's uuid identifier
  • infinity_webapp_server_base_url: The profile's Infinity web application base URL

Example: "telehealth.{{base_telehealth_alias}}@{{telehealth_integration.telehealth_call_domain}}"

 
telehealth_request_id The telehealth call identifier. This is unique for every attempt to join an appointment.

 

unique_encounter_id A unique appointment ID provided by Epic. This is the same for all participants (providers and patients) joining a given appointment (or "encounter" in Epic terminology). It must be referenced in the service name template.

 
utc_time The current time in UTC, used to indicate when a call launch error occurred.      

* Mandatory.

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:

Copy to clipboard
<!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).

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

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