updates to documentation, improved logging

Documentation/Direct_Messaging_README.txt

@@ -1,85 +1,153 @@
-Direct Messaging with OpenEMR and EMR Direct phiMail(TM)
-Version 1.2, 29 Jul 2013
+Direct Messaging with OpenEMR and EMR Direct phiMail(R)
+Version 1.3, 19 Jul 2014
 
-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 
+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)
 
-IMPORTANT:
-Please be aware of the following limitations when using the OpenEMR Direct Messaging 
-features with PHI in a production environment:
-a. the current code only supports a single shared "group" Direct Address for each OpenEMR 
-installation. Note that this trust model is fully compliant with the Direct Project 
-requirements for Direct messaging, but we may add additional trust models in the future 
+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.
-b. the current code only sends the CCR or CCD XML data that is already available in OpenEMR; 
+
+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.
 
-Problems Solved:
-1. Patient-initiated transmission of CCDA data from the Report section of the Patient Portal 
-interface.
-2. Provider-initiated transmission of CCDA data from the Report section of the Patient pane
-in the main OpenEMR interface.
-3. Log all CCDA data transmissions including date/time, patient, and whether transmission 
+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.
 
-How it Works:
+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.
 
-What you need before enabling Direct Messaging in OpenEMR:
-1. Test Mode: Developers may contact EMR Direct to request complimentary test address and 
-digital certificate provisioning, as well as API documentation, at support@emrdirect.com.  
-Access to a sandbox server is available for preliminary testing.
-2. Production Mode: Healthcare provider users should begin by signing up for a Direct message 
-account with EMR Direct. 
+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. Applicants may visit https://www.emrdirect.com/subscribe.html to begin the
-process. 
+configure OpenEMR.  
 
-How to enable the Direct Messaging Features in OpenEMR:
-Setup of phimail Direct messaging Service is done in the Administration::Globals::Connectors 
+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.
-3. Specify the interval for automatic message checking; we suggest 5 or 10 minutes as a
+
+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. By setting the interval to 0 (zero), automatic message checking through 
-OpenEMR's background service manager will be suppressed. (This would be appropriate if message 
-checking is managed through another mechanism, such as a system cron job.)
-4. Specify the OpenEMR user who will receive notification of new incoming Direct messages. 
-Enter the username in the field.
+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.
+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.
 
-Checking the status and history of the Direct Messaging Service in OpenEMR:
+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). 
+or Failed).
 
-Note of message status messages: Receiving message status updates requires that Direct message
+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.
 
-How to use the Direct Messaging Features in OpenEMR:
-Sending:
+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 
@@ -104,7 +172,19 @@ success or failure of the message transmission, or an error message. If the mess
 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.
 
-Receiving:
+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 
@@ -131,7 +211,7 @@ appropriate, assign the document to a specific patient using the "Move to Patien
 Documents interface.
 
 
-Trademark Notice: phiMail is a trademark of EMR Direct.
+Trademark Notice: phiMail is a registered trademark of EMR Direct.
 
-Copyright (c) 2013 EMR Direct.
+Copyright (c) 2013-2014 EMR Direct.
 

library/direct_message_check.inc

@@ -106,7 +106,10 @@ function phimail_check() {
    $phimail_password = $GLOBALS['phimail_password'];
 
    $ret = phimail_write_expect_OK($fp,"AUTH $phimail_username $phimail_password\n");
-   if($ret!==TRUE) return; //authentication error
+   if($ret!==TRUE) {
+      phimail_logit(0, "authentication error " . $ret);
+      return;
+   }
 
    if(!($notifyUsername = $GLOBALS['phimail_notify'])) $notifyUsername='admin'; //fallback
 
@@ -333,6 +336,7 @@ function phimail_check() {
 
       }
       else { //unrecognized or FAIL response
+          phimail_logit(0, "problem checking messages " . $ret);
           phimail_close($fp);
           return;
       }