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

#2 Retrieve the Mailbox

Contents

Stage 2: Check for HL7 Messages

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.

In Stage 2 the postmaster will post to the web service using the HL7 Mailbox URL (retrieved in stage 1) at predefined intervals with the Login ID and Password supplied in an XML format which will look something like this:

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

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

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

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

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

The web service must respond with either an HL7 Mailbox XML structure which lists the HL7 messages which are waiting on the server 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 Mailbox XML: If there is no exception in your web service then it must return an HL7 Mailbox XML structure (see below) listing the waiting HL7 messages to be retrieved. In the HL7 Mailbox XML the root node name MUST be HL7MAILBOX and it must contain the LOGONID and COUNT attributes. The LOGONID attribute MUST be the same as the LOGONID passed in the mailbox request XML. The COUNT attribute must be a number greater than or equal to 0 indicating how many HL7 Message Identifiers (XML Child Nodes) the Mailbox Contains. OPTIONALLY you can include a MORE attribute which (if included) MUST be either the word "True" or the word "False". If you include the MORE attribute AND the value is "True" then the postmaster will immediately "re-execute" Stage 2 (without waiting) after it successfully retrieves all of the HL7 messages in Stage 3. The Mailbox XML looks like this:

</HL7MAILBOX>

The XML child nodes in the Mailbox XML MUST be named HL7 and MUST have an attribute name ID which MUST contain whatever unique identifier your system will assign to the HL7 messages (if blank then the postmaster will not process ANY entries in the mailbox. In Stage 3 these unique ID values will be posted to the web service to retrieve the actual HL7 messages and they will be requested IN THE SAME ORDER in which they appear in the Mailbox XML so you should insure that when your web service constructs the Mailbox XML that you build the HL7 entries in the correct order.

Hints for creating the Mailbox XML: When running in a 'live' environment the postmaster will be using a 60 second timeout maximum. We highly recommend that you keep your Mailbox XML as short as possible. For instance, if you have 5000 HL7 messages to deliver to a client, rather than building a Mailbox XML with 5000 entries, build it with only the top 100, 200, or 500 HL7 IDs and set the MORE attribute to "True" until the postmaster has retrieved all messages.