|
| 1 | +Direct Messaging with LibreEHR and EMR Direct phiMail(R) |
| 2 | +Version 1.3, 19 Jul 2014 |
| 3 | + |
| 4 | +A. Purpose: To provide a secure method from within LibreEHR for sending/receiving |
| 5 | +protected health information to/from another Direct address using the Direct Project |
| 6 | +messaging standard, as a step toward the goal of satisfying the three MU2 criteria |
| 7 | +requiring the use of Direct messaging. (For general information about Direct messaging, |
| 8 | +see http://www.emrdirect.com/about-directed-exchange-and-secure-direct-messaging.html) |
| 9 | + |
| 10 | +B. IMPORTANT: Please be aware of the following limitations when using the LibreEHR |
| 11 | +Direct Messaging features with PHI in a production environment: |
| 12 | + |
| 13 | +1. the current code only supports a single shared "group" Direct Address for each LibreEHR |
| 14 | +installation. Note that this model is fully compliant with the Direct Project |
| 15 | +requirements for Direct messaging, but we may add additional models in the future |
| 16 | +should we determine that doing so would provide a higher degree of interoperability for |
| 17 | +LibreEHR users. |
| 18 | + |
| 19 | +2. the current code only sends the CCR or CCD XML data that is already available in LibreEHR; |
| 20 | +these files as currently generated by existing LibreEHR code do not meet the requirements |
| 21 | +of the MU2 criteria, and the current CCD files do not pass strict CDA validation tests. |
| 22 | + |
| 23 | +C. Problems Solved: |
| 24 | + |
| 25 | +1. Patient-initiated transmission of clinical data from the Report section of the Patient |
| 26 | +Portal interface. |
| 27 | + |
| 28 | +2. Provider-initiated transmission of clinical data from the Report section of the Patient |
| 29 | +pane in the main LibreEHR interface. |
| 30 | + |
| 31 | +3. Log all data transmissions including date/time, patient, and whether transmission |
| 32 | +was initiated by the patient through the Patient Portal or by an LibreEHR user through the |
| 33 | +main interface. |
| 34 | + |
| 35 | +4. Receive Direct messages from other sources. |
| 36 | + |
| 37 | +D. How it Works: |
| 38 | +Once configured, LibreEHR will interface with a phiMail Direct messaging server to complete the |
| 39 | +required message transactions. The phiMail platform is described on the EMR Direct website, |
| 40 | +http://www.emrdirect.com and http://www.emrdirect.com/phimail-faq.html. |
| 41 | + |
| 42 | +E. What you need before enabling Direct Messaging in LibreEHR: |
| 43 | + |
| 44 | +1. Test Mode: Developers may request a complimentary test address at |
| 45 | +https://www.emrdirect.com/subscribe-developer |
| 46 | +Access to a sandbox server is available for testing and development purposes. |
| 47 | + |
| 48 | +2. Production Mode: Healthcare provider users should begin by signing up for a production |
| 49 | +Direct messaging account with EMR Direct by registering at https://www.emrdirect.com/subscribe |
| 50 | + |
| 51 | +Subscribers will receive the username, password, and server address information with which to |
| 52 | +configure LibreEHR. |
| 53 | + |
| 54 | +F. How to enable the Direct Messaging Features in LibreEHR: |
| 55 | +Setup of phiMail Direct messaging Service is done in the Administration::Globals::Connectors |
| 56 | +tab |
| 57 | + |
| 58 | +1. Check the "Enable phiMail Direct Messaging Service" checkbox. |
| 59 | + |
| 60 | +2. Enter the Server Address, Username, and Password provided to you. The server address |
| 61 | +will be of the form "ssl://servername.example.com:32541" - replace the hostname and port |
| 62 | +with the values provided to you by EMR Direct. The Username is your Direct Address. Do not |
| 63 | +enter the server URL into your browser address bar, as this will not work. |
| 64 | + |
| 65 | +3. Specify the LibreEHR user who will receive notification of new incoming Direct messages. |
| 66 | +Enter their LibreEHR username in the notification user field. |
| 67 | + |
| 68 | +4. Specify the interval for automatic message checking; we suggest 5 or 10 minutes as a |
| 69 | +starting point, but installations processing a large number of Direct messages may want a |
| 70 | +shorter interval. To disable automatic message checking through LibreEHR's background service |
| 71 | +manager, set the interval to 0 (zero). Disabling automatic checking would be appropriate |
| 72 | +if message checking is managed through another mechanism, such as a system cron job. |
| 73 | + |
| 74 | +5. Optionally check "phiMail Allow CCD Send" and/or "phiMail Allow CCR Send" to enable |
| 75 | +the Transmit feature for these data types. If you do not select at least one of these, |
| 76 | +LibreEHR will operate in a receive-only mode. |
| 77 | + |
| 78 | +6. Click the "Save" button. |
| 79 | + |
| 80 | +7. Confirm that a valid Notification Email Address is set in the Administration:: |
| 81 | +Globals::Notifications tab to receive error notifications from the Direct Messaging service. |
| 82 | + |
| 83 | +8. Install the EMR Direct trust anchor certificate. |
| 84 | + |
| 85 | +Note: This is *not* your Direct certificate; it is the trust anchor for the SSL |
| 86 | +certificate issued to our servers, and is used only to validate the SSL certificate |
| 87 | +presented by the phiMail server on the other side of LibreEHR's connection. Your Direct private |
| 88 | +key and certificate are managed by the phiMail Server and are not installed in LibreEHR. |
| 89 | +Your Direct certificate is made availabe for your review by EMR Direct, but you will not |
| 90 | +need to install it anywhere. |
| 91 | + |
| 92 | +For added security, the trust anchor for the phiMail Server should be installed in the LibreEHR |
| 93 | +installation tree at: |
| 94 | + |
| 95 | +[installation_root]/sites/[site_id]/documents/phimail_server_pem/phimail_server.pem |
| 96 | + |
| 97 | +This phimail_server_pem directory and its contents should be readable by the the |
| 98 | +webserver process, but only writable by trusted local users. The certificate file |
| 99 | +itself must be PEM encoded. You can identify a PEM encoded certificate file because |
| 100 | +it begins with the text "-----BEGIN CERTIFICATE-----". Although LibreEHR will connect |
| 101 | +to phiMail servers without installing this certificate, this is a required configuration |
| 102 | +step for all production accounts to ensure that you are connecting to the correct |
| 103 | +server. You can obtain the correct certificate at the following URLs: |
| 104 | + |
| 105 | + a. Test accounts: http://certs.emrdirect.com/EMRDirectTestCA.crt |
| 106 | + Important: Don't forget to rename the file to phimail_server.pem and install it |
| 107 | + in the correct directory. |
| 108 | + |
| 109 | + b. Production accounts: https://www.phicert.com/certs/phiCertDirectRootCA.crt |
| 110 | + Important: The production root must be converted to PEM format as follows: |
| 111 | + $ openssl x509 -in phiCertDirectRootCA.crt -inform DER -out phimail_server.pem |
| 112 | + Don't forget to install phimail_server.pem in the correct directory. As an added |
| 113 | + security measure, please call us to confirm the thumbprint on this certificate. |
| 114 | + |
| 115 | +G. Debugging background connections to the server. |
| 116 | + |
| 117 | +You may review the connection activity to the server by Selecting Administration::Other::Logs, |
| 118 | +selecting "direct-message" in the "Name of events:" drop-down menu, and clicking "[Refresh]". |
| 119 | +If the background service is succesfully connecting, you will see "message check completed" |
| 120 | +events in the log as well as any message related entries (see below for instructions to |
| 121 | +view more detailed message related status information). If you see no entries, make sure that |
| 122 | +the background service is enabled (See F.4 above). If you see "could not connect to server" |
| 123 | +entries, each entry will also contain an error code: |
| 124 | + |
| 125 | + C1: phiMail is disabled in the global configuration. Fix: enable. |
| 126 | + C2: the phiMail server URL entered in the global configuration is invalid. Fix: Confirm |
| 127 | + the URL has been entered correctly. It should be of the form |
| 128 | + "ssl://server.example.com:32541". |
| 129 | + C3: unable to create stream context. Fix: Usually this is because the server certificate |
| 130 | + file installed in F.8 above is not the correct certificate or is in the wrong format. |
| 131 | + C4: failed to open connection. Fix: Confirm you Internet service and local DNS servers are |
| 132 | + online and your firewall is not blocking connections to the phiMail Server. |
| 133 | + |
| 134 | +H. Checking the status and history of the Direct Messaging Service in LibreEHR: |
| 135 | +Administrators may view the status of the service by Selecting Reports::Services::Background |
| 136 | +Services from the main LibreEHR left navigation bar. The "View Log" link on this page or |
| 137 | +Reports::Services::Direct Message Log will open the messaging history log showing each message |
| 138 | +sent or received and the current status of that message (Received, Sent, Delivery Confirmed, |
| 139 | +or Failed). |
| 140 | + |
| 141 | +I. Note of message status messages: Receiving message status updates requires that Direct message |
| 142 | +checking be enabled. When receiving messages, the phiMail back-end is fully compliant with the |
| 143 | +Direct messaging protocols to notify the sender and provide final delivery confirmation, but |
| 144 | +please note that many other Direct providers do not yet support these features. If a message |
| 145 | +is sent to a recipient using one of these other systems, LibreEHR probably won't ever receive a |
| 146 | +final delivery confirmation for that message. |
| 147 | + |
| 148 | +J. How to use the Direct Messaging Features in LibreEHR: |
| 149 | + |
| 150 | +1. Sending: |
| 151 | +When the phiMail Direct Messaging service is enabled, an additional "Transmit" button will |
| 152 | +appear in the Continuity of Care Record (CCR) and/or Continuity of Care Document (CCD) block |
| 153 | +of the Reports section in both the Patient Portal and the Patient pane of the main provider |
| 154 | +interface. |
| 155 | + |
| 156 | +To transmit a CCR or CCD, first click the "Transmit" button. This will open a small dialog |
| 157 | +immediately below the button with a form field to enter the intended recipient's Direct Address. |
| 158 | +Clicking "Transmit" again will hide the dialog. |
| 159 | + |
| 160 | +A Direct Address should have the same form as a regular email address, e.g. |
| 161 | +[email protected]. Enter the address in the field and click the "Send" button |
| 162 | +immediately to the right of the field. Only a single recipient may be specified in the field. |
| 163 | +The Send button will be temporarily disabled while LibreEHR is communicating with the phiMail |
| 164 | +server. This will only work for properly-configured Direct addresses. Attempts to send to a |
| 165 | +regular email address or Direct address outside of our test mode "trust sandbox" will fail |
| 166 | +during testing. Production accounts have wide interoperability with other Direct service |
| 167 | +providers. Should you encounter a trust community with which LibreEHR does not interoperate, |
| 168 | +please let us know at [email protected]. |
| 169 | + |
| 170 | +LibreEHR will then display a status message immediately below the Address field, the |
| 171 | +success or failure of the message transmission, or an error message. If the message is |
| 172 | +successfully submitted to the server, the Address field will be cleared to prevent accidental |
| 173 | +re-transmission. If multiple recipients are required, the next recipient can now be entered. |
| 174 | + |
| 175 | +If you receive an error message, it will be followed by an error code. For a discussion |
| 176 | +of error codes beginning with the letter "C" please see section G above. Error codes |
| 177 | +beginning with "EC" are listed here: |
| 178 | + |
| 179 | + EC 1: phiMail disabled in global configuration. Fix: enable. |
| 180 | + EC 4: authentication failure. Fix: The Username and Password entered in the |
| 181 | + global configuration must be corrected. |
| 182 | + EC 5: request to add text failed. Fix: Confirm total message length < 5MB. |
| 183 | + EC 6: problem sending the text. Fix: Confirm your local network connectivity is stable. |
| 184 | + EC 7: request to add clinical document failed. Fix: see EC 5. |
| 185 | + EC 8: problem sending the clinical document. Fix: see EC 6. |
| 186 | + |
| 187 | +2. Receiving: |
| 188 | +When the phiMail Direct Messaging service is enabled, and message checking is enabled either |
| 189 | +through the background services manager of another mechanism, LibreEHR will automatically process |
| 190 | +message status updates and new messages. Status updates will be reflected immediately in the |
| 191 | +Direct Messaging log. Additionally, if a "Failed" notification is received for a previously sent |
| 192 | +message, a regular email message will be generated to the Notification Email Address specified |
| 193 | +in the Notifications tab of the Global Settings panel (accessed by selecting Administration:: |
| 194 | +Globals from the main left navigation menu). |
| 195 | + |
| 196 | +New Direct messages will be processed as follows. A new "Patient Note" will be generated and |
| 197 | +sent to the phiMail notification user specified in the Connectors tab of the Global settings. |
| 198 | +The patient note will contain information about the message, including any text at the beginning |
| 199 | +of the message from the sender. Any attachments (and any non-text content) will be automatically |
| 200 | +converted to separate LibreEHR Documents, which will be referenced in the new Patient Note. |
| 201 | +The Documents and the Patient Note are initially created without an assigned patient. |
| 202 | + |
| 203 | +At this time, the envisioned workflow is that the notification user will review the message text |
| 204 | +and any included Documents to determine which patient the content belongs to and will then set the |
| 205 | +patient using the existing Patient Note interface for choosing a patient. Once the patient is sent, |
| 206 | +the Patient Note can be forwarded to another provider or staff member as appropriate using the |
| 207 | +existing forwarding mechanism for Patient Notes. The unassigned Documents can be viewed by Selecting |
| 208 | +Miscellaneous::New Documents from the main left navigation menu, which opens a Documents list. Once |
| 209 | +the specified document is opened, the user can optionally categorize the document and, when |
| 210 | +appropriate, assign the document to a specific patient using the "Move to Patient #" feature in the |
| 211 | +Documents interface. |
| 212 | + |
| 213 | + |
| 214 | +Trademark Notice: phiMail is a registered trademark of EMR Direct. |
| 215 | + |
| 216 | +Copyright (c) 2013-2014 EMR Direct. |
| 217 | + |
0 commit comments