Difference between revisions of "Direct"

From OpenEMR Project Wiki
Line 72: Line 72:


You can see a log of Direct messages interactions by going to Report -> Services -> Direct Message Log
You can see a log of Direct messages interactions by going to Report -> Services -> Direct Message Log
A more detailed error log is found by going to the Administration -> System -> Logs and searching for logs where the '''Name of the event''' is '''direct-message'''.


For services to run the Background Service must be running.  Learn more at the [[Background Service Manager]] page.
For services to run the Background Service must be running.  Learn more at the [[Background Service Manager]] page.
Line 80: Line 78:


Since Direct's testing environment uses self signed certificates we suppress the errors from the php function stream_socket_client which can masks some of these problems.  Removing the @ suppression sign can display these errors (currently this is in the ''library/direct_message_check.inc::phimail_connect()'' function).
Since Direct's testing environment uses self signed certificates we suppress the errors from the php function stream_socket_client which can masks some of these problems.  Removing the @ suppression sign can display these errors (currently this is in the ''library/direct_message_check.inc::phimail_connect()'' function).
=== Debugging background connections to the server. ===
You may review the connection activity to the server by Selecting Administration::Other::Logs, selecting "direct-message" in the "Name of events:" drop-down menu, and clicking "[Refresh]". If the background service is successfully connecting, you will see "message check completed" events in the log as well as any message related entries (see below for instructions to view more detailed message related status information). If you see no entries, make sure that the background service is enabled. If you see "could not connect to server" entries, each entry will also contain an error code:
; Direct Message Log Error Codes
; C1: phiMail is disabled in the global configuration. Fix: enable.
; C2: the phiMail server URL entered in the global configuration is invalid. Fix: Confirm the URL has been entered correctly. It should be of the form "ssl://server.example.com:32541".
; C3: unable to create stream context. Fix: Usually this is because the server certificate file installed in F.8 above is not the correct certificate or is in the wrong format.
; C4: failed to open connection. Fix: Confirm you Internet service and local DNS servers are online and your firewall is not blocking connections to the phiMail Server.  Check to make sure your local server time is synced with an NTP server as out of sync server times can cause the SSL handshake to fail.
===Checking the status and history of the Direct Messaging Service in OpenEMR===
Administrators may view the status of the service by Selecting Reports::Services::Background
Services from the main OpenEMR left navigation bar. The "View Log" link on this page or
Reports::Services::Direct Message Log will open the messaging history log showing each message
sent or received and the current status of that message (Received, Sent, Delivery Confirmed,
or Failed).
===Note of message status messages===
Receiving message status updates requires that Direct message checking be enabled. When receiving messages, the phiMail back-end is fully compliant with the Direct messaging protocols to notify the sender and provide final delivery confirmation, but please note that  many other Direct providers do not yet support these features. If a message is sent to a recipient using one of these other systems, OpenEMR probably won't ever receive a final delivery confirmation for that message.

Revision as of 19:34, 17 February 2022

Direct

Overview

The Direct Project is a simple, secure, scalable, standards-based way for participants to send authenticated, encrypted health information directly to known, trusted recipients over the Internet. More information on Direct can be found here: https://www.healthit.gov/sites/default/files/pdf/fact-sheets/the-direct-project.pdf

Available Options

EMR Direct phiMail

This service enables Direct messaging functionality that's integrated directly into OpenEMR. Users can send clinical data in CCR or CCD format. Users can also receive Direct messages, with or without attachments. OpenEMR users connect to the EMR Direct HISP (Health Information Service Provider) via the secure OpenEMR-to-phiMail edge-client channel to complete these transactions.
EMR Direct phiMail Direct Messaging is used by over 100 EHR vendors and thousands of healthcare organizations, and has been integrated into OpenEMR since February, 2013. EMR Direct is an ONC 2014 Edition and ONC 2015 Edition certified HISP and its HISP, CA, and RA services have been EHNAC and DirectTrust accredited since 2014. Production accounts allow OpenEMR users to exchange Direct Messages on the DirectTrust network which includes over 1.6 million trusted addresses, or with other trust communities of their choice. If you are interested in using these Direct messaging features, your administrator can register for service at https://www.emrdirect.com/subscribe (if you use a modified version of OpenEMR provided by another party, you'll register for Direct through that vendor instead).
The screenshots below show the basic Direct functionality added in Version 4.1.2 and as updated in version 5.0.1. Other OpenEMR contributors may have modified or extended this functionality in the version you are using, if a whitelabeled or modified version of OpenEMR is used.
Sending: When enabled, a Transmit button will appear in the Continuity of Care Document section after selecting the Report link on the main patient information pane. Clicking the Transmit button will reveal the Recipient field. After first configuring a test or production phiMail address into an OpenEMR instance using the documentation linked at the end of this page, enter a valid Direct Address in the text box and click the Send button to transmit the message. The same interface will also appear in the Patient Portal. Note that if a separate Patient Portal is used (for example, to meet regulatory requirements), an additional Direct account may be needed for the Direct service within the separate Patient Portal.

Emr-direct-phimail.png

Receiving: When enabled, messages are processed and a new Patient Note is delivered to a specified user and appears in that user's Message and Reminder Center. These Patient notes are sent without an assigned patient.

Emr-direct-phimail-openemr-integration.png

When the new message is opened, the administrator can review the message content and any attachments, assign the message to the correct patient by clicking "Patient: Click to select", assign a Type and forward the message on to the correct clinician or staff member.

Phimail-openemr-integration-direct-message.png

Full Documentation on this feature, including troubleshooting information, can be found here:

Setup

Pre-Setup Requirements

What you need before enabling Direct Messaging in OpenEMR:

1. Test Mode: Developers may request a complimentary test address at https://www.emrdirect.com/subscribe-developer Access to a sandbox server is available for testing and development purposes.

2. Production Mode: Healthcare provider users should begin by signing up for a production Direct messaging account with EMR Direct by registering at https://www.emrdirect.com/subscribe

Subscribers will receive the username, password, and server address information with which to configure OpenEMR.

Enabling Direct Messaging in OpenEMR

Setup of phiMail Direct messaging Service is done in the Administration::Globals::Connectors tab

1. Check the "Enable phiMail Direct Messaging Service" checkbox.

2. Enter the Server Address, Username, and Password provided to you. The server address will be of the form "ssl://servername.example.com:32541" - replace the hostname and port with the values provided to you by EMR Direct. The Username is your Direct Address. Do not enter the server URL into your browser address bar, as this will not work.

3. Specify the OpenEMR user who will receive notification of new incoming Direct messages. Enter their OpenEMR username in the notification user field.

4. Specify the interval for automatic message checking; we suggest 5 or 10 minutes as a starting point, but installations processing a large number of Direct messages may want a shorter interval. To disable automatic message checking through OpenEMR's background service manager, set the interval to 0 (zero). Disabling automatic checking would be appropriate if message checking is managed through another mechanism, such as a system cron job.

5. Optionally check "phiMail Allow CCD Send" and/or "phiMail Allow CCR Send" to enable the Transmit feature for these data types. If you do not select at least one of these, OpenEMR will operate in a receive-only mode.

6. Click the "Save" button.

7. Confirm that a valid Notification Email Address is set in the Administration:: Globals::Notifications tab to receive error notifications from the Direct Messaging service.

Direct Debugging

You can find out if the Direct Polling Service (the process that checks for messages every X interval) is enabled by going to Report -> Services -> Background Services.

You can see a log of Direct messages interactions by going to Report -> Services -> Direct Message Log

For services to run the Background Service must be running. Learn more at the Background Service Manager page.

If you are receiving a C4 0 (connection error) response codes in the logs this could be an issue with a time synchronization during the SSL handshake of the machine. Synchronizing your server time with an NTP server can make this issue go away.

Since Direct's testing environment uses self signed certificates we suppress the errors from the php function stream_socket_client which can masks some of these problems. Removing the @ suppression sign can display these errors (currently this is in the library/direct_message_check.inc::phimail_connect() function).

Debugging background connections to the server.

You may review the connection activity to the server by Selecting Administration::Other::Logs, selecting "direct-message" in the "Name of events:" drop-down menu, and clicking "[Refresh]". If the background service is successfully connecting, you will see "message check completed" events in the log as well as any message related entries (see below for instructions to view more detailed message related status information). If you see no entries, make sure that the background service is enabled. If you see "could not connect to server" entries, each entry will also contain an error code:

Direct Message Log Error Codes
C1
phiMail is disabled in the global configuration. Fix: enable.
C2
the phiMail server URL entered in the global configuration is invalid. Fix: Confirm the URL has been entered correctly. It should be of the form "ssl://server.example.com:32541".
C3
unable to create stream context. Fix: Usually this is because the server certificate file installed in F.8 above is not the correct certificate or is in the wrong format.
C4
failed to open connection. Fix: Confirm you Internet service and local DNS servers are online and your firewall is not blocking connections to the phiMail Server. Check to make sure your local server time is synced with an NTP server as out of sync server times can cause the SSL handshake to fail.

Checking the status and history of the Direct Messaging Service in OpenEMR

Administrators may view the status of the service by Selecting Reports::Services::Background Services from the main OpenEMR left navigation bar. The "View Log" link on this page or Reports::Services::Direct Message Log will open the messaging history log showing each message sent or received and the current status of that message (Received, Sent, Delivery Confirmed, or Failed).

Note of message status messages

Receiving message status updates requires that Direct message checking be enabled. When receiving messages, the phiMail back-end is fully compliant with the Direct messaging protocols to notify the sender and provide final delivery confirmation, but please note that many other Direct providers do not yet support these features. If a message is sent to a recipient using one of these other systems, OpenEMR probably won't ever receive a final delivery confirmation for that message.