<< Click here to display Table of Contents >> Navigation: Creating Postmasters > Data Sources > Web Service > Technical Overview:

#3 Retrieve HL7 Messages

Contents

Stage 3: Retrieve HL7 Messages in the Mailbox

Stage 1 'pinged' the web service and received a URL list with 3 URLS to use to retrieve HL7 messages from your web service. The MAILBOXURL, the HL7GETURL and the HL7ACKURL.

Stage 2 used the MAILBOXURL to retrieve the HL7 Mailbox XML from the web service..

In Stage 3 the postmaster will iterate through each of the HL7 message "ID"s in the Mailbox XML and post a request for each HL7 message individually using the HL7GETURL. The web service will respond with either an EXCEPTION (see EXCEPTION XML below) or an XML structure containing the HL7 message. If no EXCEPTION the postmaster will write the HL7 message into the Distribution Folder for further processing and then immediately post an acknowledgement XML structure to the web service using the HL7ACKURL to which the web service merely has to respond with an EMPTY EXCEPTION (see below).

The HL7MAILBOX XML Structure which the postmaster will send contains 5 pieces of information as XML Attributes on the root XML node:

1.ID - Will be the unique HL7 message ID passed in the HL7 Mailbox XML retrieved in Stage 2.

2.LOGONID - Will be the Logon ID from your postmaster profile.

3.PASSWORD - Will be the Password from your postmaster profile.

4.PMVERSION - Will be the software version of the UltraPort HL7 Postmaster posting the XML.

5.COMPUTERNAME = Will be the name of the client computer running the postmaster.

The web service must respond with either an HL7 Message XML structure which includes the HL7 message or with a properly formatted EXCEPTION (see EXCEPTION XML below).

EXCEPTION XML: An EXCEPTION response can be returned at any time during the process to indicate that an error or condition exists whereby you want the postmaster to abandon it's current operation and "reset". It might mean that for whatever reason you did not like the Login ID and/or Password provided OR your HL7 delivery system is down etc. etc.). Whenever the postmaster receives an EXCEPTION XML response from the web service it will 'Reset' all the way back to Stage 1 and start again. In the Exception XML structure the xml root node name MUST be 'EXCEPTION' and all other attributes are optional. The 4 attributes shown below are the only XML attributes actually looked at by the postmaster and the values are logged on the local computer.

HL7 Message XML: If there is no exception in your web service then it must return a properly formatted HL7 Message XML structure (see below). In the HL7 Message XML the root node name MUST be HL7 and it must contain the LOGONID and ID attributes. The LOGONID and ID attributes MUST be the same as the LOGONID and ID values passed in the message request XML. The HL7 Message XML root node MUST have 1 (and only 1) Childe Node. The Child Node MUST be named MESSAGE and the InnerText MUST be a standard HL7 version 2.xx HL7 message in an ASCII string which has been Base64 Encoded. The HL7 Message XML looks like this:

<MESSAGE ID="YourUniqueMessageID "> ...(hl7 message encoded as Base64)... </MESSAGE>

</HL7>

HL7 Message XML (Optional): The web service may also include some OPTIONAL attributes which (if included) the postmaster will use to validate against the contents of the HL7 message.

<MESSAGE ID="YourUniqueMessageID "> ...(hl7 message encoded as Base64)... </MESSAGE>

</HL7>

The optional attributes are as shown below:

*SA=Sending Application (MSH 3.1)

*SF=Sending Facility (MSH 4.1)

*RA=Receiving Application (MSH 5.1)

*RF=Receiving Facility (MSH 6.1)

*MTYPE=Message Type (MSH 9.1)

*MEVENT=Message Event (MSH 9.2)

*MCONTROLID=Message Control ID (MSH 10.1)

*MTESTPROD=The Test/Production Flag (MSH 11.1)

*MVERSION=HL7 Version (MSH 12.1)

Processing the HL7 Message: The postmaster will then decode the HL7 message stored in the <MESSAGE> XML node and write that message to the Distribution Folder defined in your UltraPort HL7 Postmaster for further processing and then immediately post back an XML acknowledgement to the web service using the HL7ACKURL. On receipt of the successful acknowledgement your web service should then REMOVE the HL7 message so that it will not be listed in future HL7 Mailboxes retrieved in Stage 2. The HL7 Message ACK XML looks like this:

If the postmaster encounters an ERROR processing the HL7 message (such as being unable to write the message to the Distribution Folder or if the HL7 message is invalidly formatted) it will post a NAK (negative acknowledgement) to the web service, then reset itself all the way back to Stage 1 as if the web service had responded to the HL7 message request with an exception. It is up to the Web Service Provider whether the message for which the NAK is received is removed from future MAILBOX retrievals (see Stage 2). The NAK XML Post will look like this:

Your web service MUST respond to the ACK to close out the process with an EMPTY EXCEPTION XML any other response to an ACK is treated as a regular EXCEPTION and postmaster will 'reset' all the way back to Stage 1. When a NAK is sent for a message the postmaster will autmatically reset all the way back to Stage 1.

EMPTY EXCEPTION XML: An EMPTY EXCEPTION is only returned to close out a message retrieval process. In the EMPTY EXCEPTION XML the METHOD attribute must have a value of ACK and the ERRORCODE attribute MUST be 0. Any other values or response is treated as a regular exception or web service error. An empty exception XML looks like this:

OR this: