Using the phiMail API to Send and Receive Patient Event Notifications

Direct is one method of sending and receiving patient event notifications. Implementers can follow the DirectTrust Event Notifications via the Direct Standard Implementation Guide along with the phiMail API's ADD CONTEXT command to send ADT notifications via Direct with a Context attachment using EMR Direct software. phiMail endpoints may also receive ADT notifications from other organizations as Direct messages with a Context attachment and/or an XDM Zip attachment; that content can be extracted from the included XDM Zip file or Context attachment using the phiMail API too. Refer to the phiMail API documentation for more details about the ADD CONTEXT command.

Event notifications require three payloads: a context attachment, an HL7 V2.3 or later version ADT message, and a human readable text attachment that contains the event notification information. Please refer to the Event Notifications via the Direct Standard IG for complete details and the required data in each payload part. To generate an Event Notification using phiMail, you will need to follow the procedure below to add these three required payloads to a Direct message.

Please refer to the phiMail API SDK example code for a sending example that includes the opening/closing of the connector and additional error handling information. After opening the connector, start a new message by adding a recipient using the TO command.

Then, call three methods in sequence to add: (1) the human readable part, (2) the HL7 ADT message part, and (3) the context part of the patient Event Notification to the Direct message.

1. For the human readable format, construct a string containing the required text and demographic information, with appropriate line breaks (CRLF) in the string as in section 4.2.2 of the Event Notifications via the Direct Standard IG. Then add the human-readable string to the outgoing message using the ADD TEXT command. For example, in C# this command is called using the AddText method of the PhiMailConnector class.

2. For the ADT data, construct an HL7 ADT message that meets the "Content" requirements in section 4.2.1 of the Event Notifications via the Direct Standard IG. The HL7 ADT message should be converted to a string. The string should then be Base64 encoded and then the encoded output split every 76 characters with a CRLF (i.e. "\r\n"). The HL7 ADT message is then attached to the message. At this time, the IG doesn't require a specific MIME type or file name/extension for the HL7 ADT attachment, but if this changes, a different method may be required to add the ADT data as an attachment in the future. For now, the ADD MIME command can be used to attach the this file to the message.

3. Finally, for the context data, construct a string containing the required parameters, with appropriate line breaks (CRLF) in the string, as in section 4.1 of the IG. This can be attached using the ADD CONTEXT command. For example, in C# this command is called using the AddContext method of the PhiMailConnector class.

After all three parts are added to the message successfully, call the SEND command to initiate transmission of the message, and then monitor for any status notifications returned later from the API, as usual, to determine whether or not the transmission was successfully received.

The phiMail API is also capable of extracting the payloads from incoming event notifications. Use the SHOW command to extract the human-readable part, the HL7 ADT message, and the context data or XDM Zip file. Please refer to the phiMail API documentation for more details on the SHOW command and CONTEXT.

To find out more about EMR Direct's Interoperability Engine FHIR and Direct Messaging services, register for a complimentary EMR Direct developer account.


Did this article answer your question? If not, please contact us.