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 guide 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 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.

If that succeeds, 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 Implementation Guide. 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, the sending system constructs an HL7 ADT message that meets the "Content" requirements in section 4.2.1 of the Event Notifications via the Direct Standard Implementation Guide. The HL7 ADT message is then converted to a string. No other format conversion is needed; the HL7 ADT message is simply attached to the Direct message as an email attachment. At this time, the DirectTrust guide 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. Based on the current draft DirctTrust standard, you can use the ADD TEXT command to attach the ADT content to the message and specify a generic filename like "ADT.hl7".

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 DirectTrust standard. 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 successful.

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


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