Documentation/Direct_Messaging_README.txt

   1 Direct Messaging with OpenEMR and EMR Direct phiMail(R)
   2 Version 1.3, 19 Jul 2014
   3
   4 A. Purpose: To provide a secure method from within OpenEMR 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 OpenEMR
  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 OpenEMR
  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 OpenEMR users.
  18
  19 2. the current code only sends the CCR or CCD XML data that is already available in OpenEMR;
  20 these files as currently generated by existing OpenEMR 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 OpenEMR 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 OpenEMR user through the
  33 main interface.
  34
  35 4. Receive Direct messages from other sources.
  36
  37 D. How it Works:
  38 Once configured, OpenEMR 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 OpenEMR:
  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 OpenEMR.
  53
  54 F. How to enable the Direct Messaging Features in OpenEMR:
  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 OpenEMR user who will receive notification of new incoming Direct messages.
  66 Enter their OpenEMR 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 OpenEMR'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 OpenEMR 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 OpenEMR's connection.  Your Direct private
  88 key and certificate are managed by the phiMail Server and are not installed in OpenEMR.
  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 OpenEMR
  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 OpenEMR 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 OpenEMR:
 135 Administrators may view the status of the service by Selecting Reports::Services::Background
 136 Services from the main OpenEMR 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, OpenEMR probably won't ever receive a
 146 final delivery confirmation for that message.
 147
 148 J. How to use the Direct Messaging Features in OpenEMR:
 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 jonesclinic@direct.example.com. 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 OpenEMR 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 OpenEMR does not interoperate,
 168 please let us know at support@emrdirect.com.
 169
 170 OpenEMR 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, OpenEMR 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 OpenEMR 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