Troubleshooting and call setup information for Epic telehealth integrations

This topic provides some guidance on troubleshooting installation and call launching issues with telehealth integrations with Pexip Infinity, and it also contains some detailed call setup information.

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

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.

Detailed call setup information

Pexip Infinity needs to access Epic at several points while setting up a telehealth call:

  1. During OAuth authentication before the call starts (after a user has proven their identity to Epic's satisfaction they get redirected back to Pexip Infinity with a one-time-use ID which Pexip needs to take and exchange for Epic OAuth2 tokens).
  2. When the call is connected and while it is ongoing, Pexip may need to periodically renew its OAuth2 tokens as they typically have a finite lifetime of approximately 1 hour.
  3. When the call ends, Pexip uses its OAuth2 token to make an API call to let Epic know that the call has ended.

The following sequence diagram shows the call flow when establishing and finishing a telehealth call via the Epic apps. It shows the touch points between the Epic app, the patient/provider, the Pexip proxying and transcoding nodes and the API calls to the Epic server.

This diagram shows the flow when a patient joins via an SMS or email notification (step 7 onwards in this flow is the same as step 4 onwards in the Epic apps flow above):

Note that:

  • The Epic API (at api.epic.hospital.com in our example) is publicly reachable.
  • All transcoding nodes (and proxying nodes) need to be able to reach out to api.epic.hospital.com. There are no inbound messages to transcoding nodes.
  • You can use a reverse proxy instead of a proxying node (the addresses are configured in the Epic telehealth profile).