Troubleshooting and call setup information for Epic telehealth integrations
This topic provides some guidance on troubleshooting installation/integration and call launching/completing issues with telehealth integrations with Pexip Infinity, and it also contains some detailed call setup information.
Installation and integration 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.
| Symptom | Possible cause | Resolution |
|---|---|---|
|
"TelehealthIntegrationNotFoundException Error" |
The Epic server is configured with an incorrect launch URL. | 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" | This could be caused by a range of issues including misconfiguration or calls being blocked by a firewall. |
If this error occurs, check that:
|
| "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. | Check that the OAuth2 redirect URIs are the same on the Epic and Pexip sides. |
|
"BorvoGetTelehealthDirectJoinTokenError" |
Incorrect backend client id | Set Backend OAuth2 application Client ID on the relevant telehealth profile to the value appropriate for your environment (the correct value differs between production and non-production Epic environments) |
| Invalid private key | Ensure Backend OAuth2 private key is correctly configured on the relevant telehealth profile. | |
| Poorly synced NTP clock | Fix any NTP sync alarms raised on Pexip Infinity. | |
| "Malformed or missing state cookie" | The appointment launch URI is misconfigured on Epic. |
Ensure that the launch URI from MyChart or Hyperspace is pointing to the launch URI e.g. /api/telehealth/v1/patient/oauth2smartlaunch/11111111-2222-3333-4444-555555555555 and not the (similar, but different) redirect uri /api/telehealth/v1/patient/oauth2authorized/11111111-2222-3333-4444-555555555555 (where 11111111-2222-3333-4444-555555555555 is replaced by the "Unique uuid identifier for this telehealth profile" appropriate for your deployment's Epic integration). This correction needs to be applied to the FDI records for the Pexip integration within the Epic solution. |
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.
Call launching/completion issues
This section describes some of the occasional issues that can occur when launching or completing a telehealth call.
| Symptom | Possible cause | Resolution |
|---|---|---|
| The telehealth call launches, but provider or patient audio/video is not being sent to the other meeting participants | Healthcare and hospital networks often have multiple network segments that are independently and very tightly/securely locked down. If they are very locked down, that may prevent audio and video being transmitted to and from an end user on a particular network segment to the Pexip Infinity server. |
Verify that the network configuration allows audio and video to be sent to Pexip Infinity. Check that all the users can join a regular non-telehealth Virtual Meeting Room from their respective networks and that they can see and hear each other. Troubleshoot/fix the network configuration for simple VMRs by working with your video and networking teams, before re-testing telehealth calls. |
| Transient USB webcam driver issues preventing camera/microphone selection. | Disconnect and reconnect your USB webcam, then place the call again. | |
| Web browser issues preventing camera/microphone selection. | Close all tabs on all web browsers and restart the browser, then place the call again. | |
| Third party video applications such as MS Teams can prevent other applications (such as Pexip) from using the webcam. (See this Microsoft community article.) | Exit any third party application (such as MS Teams) which may be attempting to use your webcam. | |
| When a telehealth call terminates, including accidental termination or termination due to unexpected network stability issues, the appointment is automatically checked out within Epic | This is an Epic configuration issue. | This can be worked around on the Epic side from Epic May 2021 onwards. Please contact your Epic support representative and refer them to https://galaxy.epic.com/Redirect.aspx?DocumentID=100106247 |
Detailed call setup information
Pexip Infinity needs to access Epic at several points while setting up a telehealth call:
- 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).
- 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.
- 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.
- The api.epic.hospital.com entity in the sequence diagrams is sometimes referred to (in Epic terminology) as the "interconnect" server.
- You can use a reverse proxy instead of a proxying node (the addresses are configured in the Epic telehealth profile).