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. This must include the:

  • {{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. This must include the:

  • {{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

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 and client secrets 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 and client secrets 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.

Supported jinja2 template variables

The following variables are available in the provider and patient alias templates:

Variable name Description
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.

telehealth_integration.telehealth_call_domain The Domain name from the telehealth profile.
telehealth_integration.name The Name from the telehealth profile.
telehealth_integration.description The Description from the telehealth profile.
telehealth_integration.integration_uuid The uuid identifier from the telehealth profile.
telehealth_integration.infinity_webapp_server_base_url The Infinity web application base URL from the telehealth profile.

The following variables are available in the provider and patient WebRTC join link templates:

Variable name Description
telehealth_alias The provider/patient alias (generated from the provider and patient alias templates).
pin A randomly-generated 8-digit Host PIN.
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.
telehealth_integration.telehealth_call_domain The Domain name from the telehealth profile.
telehealth_integration.name The Name from the telehealth profile.
telehealth_integration.description The Description from the telehealth profile.
telehealth_integration.integration_uuid The uuid identifier from the telehealth profile.
telehealth_integration.infinity_webapp_server_base_url The Infinity web application base URL from the telehealth profile.

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

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 Profile.
    Telehealth Profile Select as required from your configured telehealth profiles. Note that this field is only for your own information; the CRYPTURL configured in the Epic FDI record determines which telehealth profile is used for a particular call.
  3. Select Save.

Troubleshooting installation and call launching issues

During initial integration it is possible that various misconfigurations may cause authentication with Epic to fail when trying to make any telehealth calls. If authentication fails, the system will usually display a screen containing a short textual error message, and the telehealth call will not attempt to launch. As the failures here are potentially security related, this error page intentionally does not give too much away, but there is usually a short error reason presented, as described below.

"TelehealthIntegrationNotFoundException Error"

If this occurs, check that the Epic server is configured to use a launch URL that is correctly formatted and that contains the exact same (unique to your deployment) uuid as configured in the telehealth profile's Unique uuid identifier for this telehealth profile field.

"MetadataFetchError"

This error generally indicates some sort of network related problem (such as connectivity or DNS resolution issues). It occurs when Pexip Infinity was unable to access an unauthenticated (open) API exposed by the Epic server that provides Pexip Infinity with metadata pertaining to the Epic deploiyment.

Verify that the Epic server configured in the telehealth profile's Base URL of the Epic server and Epic OAUTH2 base URL fields is operational, reachable, and that it can be resolved using the DNS settings configured in all system locations (including both edge and transcoding locations as appropriate), and is not being blocked by a firewall.

If a web proxy is configured in any location, verify that it too is reachable (and, if applicable, its DNS name is resolvable using the DNS server in the relevant location).

"Oauth2 Launch Error"

If this error occurs, check that:

  • The Epic server is passing non-blank "launch=" and "iss=" parameters as part of the initial launch URL.
  • The Epic encryption key was entered correctly in the telehealth profile, and that Encryption key type and Epic encryption algorithm are both configured appropriately to match what is configured on the Epic side.
  • The Patient application Client ID and Provider application Client ID are appropriately configured in the telehealth profile for this deployment, and that you are using the production or non-production values as appropriate to match what is configured on the Epic side.
  • The Patient application Client Secret and Provider application Client Secret were both entered correctly in the telehealth profile for this deployment, and that you are using the production or non-production values as appropriate.
  • Pexip Infinity's access to the Epic server is not being blocked by a firewall.

"Epic OAuth2 Error"

This Epic-generated message can occur if the OAuth2 redirect URIs are not configured within Epic or there is a mismatch between what is configured on the Epic and Pexip sides.

Further investigation

If none of the above steps helps solve your initial launch integration problems, your Pexip authorized support representative may ask you to enable extra debug tracing, reproduce the failing call scenario and then afterwards to download a diagnostic snapshot.

See Monitoring, maintenance and reference information for Epic telehealth integrations for more information.

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.