You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
217 lines
13 KiB
217 lines
13 KiB
Direct Messaging with OpenEMR and EMR Direct phiMail(R) |
|
Version 1.3, 19 Jul 2014 |
|
|
|
A. Purpose: To provide a secure method from within OpenEMR for sending/receiving |
|
protected health information to/from another Direct address using the Direct Project |
|
messaging standard, as a step toward the goal of satisfying the three MU2 criteria |
|
requiring the use of Direct messaging. (For general information about Direct messaging, |
|
see http://www.emrdirect.com/about-directed-exchange-and-secure-direct-messaging.html) |
|
|
|
B. IMPORTANT: Please be aware of the following limitations when using the OpenEMR |
|
Direct Messaging features with PHI in a production environment: |
|
|
|
1. the current code only supports a single shared "group" Direct Address for each OpenEMR |
|
installation. Note that this model is fully compliant with the Direct Project |
|
requirements for Direct messaging, but we may add additional models in the future |
|
should we determine that doing so would provide a higher degree of interoperability for |
|
OpenEMR users. |
|
|
|
2. the current code only sends the CCR or CCD XML data that is already available in OpenEMR; |
|
these files as currently generated by existing OpenEMR code do not meet the requirements |
|
of the MU2 criteria, and the current CCD files do not pass strict CDA validation tests. |
|
|
|
C. Problems Solved: |
|
|
|
1. Patient-initiated transmission of clinical data from the Report section of the Patient |
|
Portal interface. |
|
|
|
2. Provider-initiated transmission of clinical data from the Report section of the Patient |
|
pane in the main OpenEMR interface. |
|
|
|
3. Log all data transmissions including date/time, patient, and whether transmission |
|
was initiated by the patient through the Patient Portal or by an OpenEMR user through the |
|
main interface. |
|
|
|
4. Receive Direct messages from other sources. |
|
|
|
D. How it Works: |
|
Once configured, OpenEMR will interface with a phiMail Direct messaging server to complete the |
|
required message transactions. The phiMail platform is described on the EMR Direct website, |
|
http://www.emrdirect.com and http://www.emrdirect.com/phimail-faq.html. |
|
|
|
E. 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. |
|
|
|
F. How to enable the Direct Messaging Features 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. |
|
|
|
8. Install the EMR Direct trust anchor certificate. |
|
|
|
Note: This is *not* your Direct certificate; it is the trust anchor for the SSL |
|
certificate issued to our servers, and is used only to validate the SSL certificate |
|
presented by the phiMail server on the other side of OpenEMR's connection. Your Direct private |
|
key and certificate are managed by the phiMail Server and are not installed in OpenEMR. |
|
Your Direct certificate is made availabe for your review by EMR Direct, but you will not |
|
need to install it anywhere. |
|
|
|
For added security, the trust anchor for the phiMail Server should be installed in the OpenEMR |
|
installation tree at: |
|
|
|
[installation_root]/sites/[site_id]/documents/phimail_server_pem/phimail_server.pem |
|
|
|
This phimail_server_pem directory and its contents should be readable by the the |
|
webserver process, but only writable by trusted local users. The certificate file |
|
itself must be PEM encoded. You can identify a PEM encoded certificate file because |
|
it begins with the text "-----BEGIN CERTIFICATE-----". Although OpenEMR will connect |
|
to phiMail servers without installing this certificate, this is a required configuration |
|
step for all production accounts to ensure that you are connecting to the correct |
|
server. You can obtain the correct certificate at the following URLs: |
|
|
|
a. Test accounts: http://certs.emrdirect.com/EMRDirectTestCA.crt |
|
Important: Don't forget to rename the file to phimail_server.pem and install it |
|
in the correct directory. |
|
|
|
b. Production accounts: https://www.phicert.com/certs/phiCertDirectRootCA.crt |
|
Important: The production root must be converted to PEM format as follows: |
|
$ openssl x509 -in phiCertDirectRootCA.crt -inform DER -out phimail_server.pem |
|
Don't forget to install phimail_server.pem in the correct directory. As an added |
|
security measure, please call us to confirm the thumbprint on this certificate. |
|
|
|
G. 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 succesfully 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 (See F.4 above). If you see "could not connect to server" |
|
entries, each entry will also contain an error code: |
|
|
|
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. |
|
|
|
H. 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). |
|
|
|
I. 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. |
|
|
|
J. How to use the Direct Messaging Features in OpenEMR: |
|
|
|
1. Sending: |
|
When the phiMail Direct Messaging service is enabled, an additional "Transmit" button will |
|
appear in the Continuity of Care Record (CCR) and/or Continuity of Care Document (CCD) block |
|
of the Reports section in both the Patient Portal and the Patient pane of the main provider |
|
interface. |
|
|
|
To transmit a CCR or CCD, first click the "Transmit" button. This will open a small dialog |
|
immediately below the button with a form field to enter the intended recipient's Direct Address. |
|
Clicking "Transmit" again will hide the dialog. |
|
|
|
A Direct Address should have the same form as a regular email address, e.g. |
|
jonesclinic@direct.example.com. Enter the address in the field and click the "Send" button |
|
immediately to the right of the field. Only a single recipient may be specified in the field. |
|
The Send button will be temporarily disabled while OpenEMR is communicating with the phiMail |
|
server. This will only work for properly-configured Direct addresses. Attempts to send to a |
|
regular email address or Direct address outside of our test mode "trust sandbox" will fail |
|
during testing. Production accounts have wide interoperability with other Direct service |
|
providers. Should you encounter a trust community with which OpenEMR does not interoperate, |
|
please let us know at support@emrdirect.com. |
|
|
|
OpenEMR will then display a status message immediately below the Address field, the |
|
success or failure of the message transmission, or an error message. If the message is |
|
successfully submitted to the server, the Address field will be cleared to prevent accidental |
|
re-transmission. If multiple recipients are required, the next recipient can now be entered. |
|
|
|
If you receive an error message, it will be followed by an error code. For a discussion |
|
of error codes beginning with the letter "C" please see section G above. Error codes |
|
beginning with "EC" are listed here: |
|
|
|
EC 1: phiMail disabled in global configuration. Fix: enable. |
|
EC 4: authentication failure. Fix: The Username and Password entered in the |
|
global configuration must be corrected. |
|
EC 5: request to add text failed. Fix: Confirm total message length < 5MB. |
|
EC 6: problem sending the text. Fix: Confirm your local network connectivity is stable. |
|
EC 7: request to add clinical document failed. Fix: see EC 5. |
|
EC 8: problem sending the clinical document. Fix: see EC 6. |
|
|
|
2. Receiving: |
|
When the phiMail Direct Messaging service is enabled, and message checking is enabled either |
|
through the background services manager of another mechanism, OpenEMR will automatically process |
|
message status updates and new messages. Status updates will be reflected immediately in the |
|
Direct Messaging log. Additionally, if a "Failed" notification is received for a previously sent |
|
message, a regular email message will be generated to the Notification Email Address specified |
|
in the Notifications tab of the Global Settings panel (accessed by selecting Administration:: |
|
Globals from the main left navigation menu). |
|
|
|
New Direct messages will be processed as follows. A new "Patient Note" will be generated and |
|
sent to the phiMail notification user specified in the Connectors tab of the Global settings. |
|
The patient note will contain information about the message, including any text at the beginning |
|
of the message from the sender. Any attachments (and any non-text content) will be automatically |
|
converted to separate OpenEMR Documents, which will be referenced in the new Patient Note. |
|
The Documents and the Patient Note are initially created without an assigned patient. |
|
|
|
At this time, the envisioned workflow is that the notification user will review the message text |
|
and any included Documents to determine which patient the content belongs to and will then set the |
|
patient using the existing Patient Note interface for choosing a patient. Once the patient is sent, |
|
the Patient Note can be forwarded to another provider or staff member as appropriate using the |
|
existing forwarding mechanism for Patient Notes. The unassigned Documents can be viewed by Selecting |
|
Miscellaneous::New Documents from the main left navigation menu, which opens a Documents list. Once |
|
the specified document is opened, the user can optionally categorize the document and, when |
|
appropriate, assign the document to a specific patient using the "Move to Patient #" feature in the |
|
Documents interface. |
|
|
|
|
|
Trademark Notice: phiMail is a registered trademark of EMR Direct. |
|
|
|
Copyright (c) 2013-2014 EMR Direct. |
|
|
|
|