Posting HL7 Messages To a Web Service
Stage 2: Posting the HL7 message(s) to the web service
Stage 1 'pinged' the web service and retrieved a URL list with the URL to use to post HL7 messages from the client computer to the web service (the HL7POSTURL).
In Stage 2 the postmaster will iterate through each of the HL7 messages waiting in the Queue folder, encode them into an XML format for posting and then use the HL7POST URL to transmit that XML to the web service. The web service MUST respond with either an EXCEPTION (see EXCEPTION XML below) or an ACK (acknowledgement) XML structure containing the HL7 MESSAGEID (which was generated by the postmaster) posted with the HL7 message. An example of the XML used to post is shown below.
HL7 Message XML: The postmaster produces a simple XML structure for HL7 message data. In addition to the encoded HL7 message the XML structure will contain some additional information as shown below
Metadata generated by postmaster
ID=A unique (GUID) id generated by the postmaster for each message
LOGONID=The logon id in the web destination profile
PASSWORD=The password in the web destination profile
PMVERSION=The software version of the UltraPort HL7 Postmaster
COMPUTERNAME=The name of the client computer
Data elements from the HL7 message
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)
<HL7 ID="UniqueMessageID " LOGONID="YourLogonID" PASSWORD="YourPassword" SA="HermeTech" SF="FSPM Demo" RA="Your Company" RF="Your Application" MTYPE="ADT" MEVENT="A08" MCONTROLID="153681279959711" MVERSION="2.3" MTESTPROD="T" PMVERSION="18.104.22.168" COMPUTERNAME="SendingComputerName">
<MESSAGE ID="UniqueMessageID "> ...(hl7 message encoded as Base64)... </MESSAGE>
Processing the HL7 Message: On receipt of the HL7 message XML the web service must then decode the HL7 message stored in the <MESSAGE> XML node, evaluate it and then immediately write back an XML acknowledgement to the postmaster indicating whether it was accepted or rejected. See below:
An "Accepted" HL7 Acknowedgement
<ACK ID="UniqueMessageID " ACCEPTED="True" ERRORMESSAGE=""</ACK>
A "Rejected" HL7 Acknowedgement
<ACK ID="UniqueMessageID " ACCEPTED="False" RESEND="False" ERRORMESSAGE="Your Reason Why"</ACK>
**Rejected ACK: If the RESEND attribute is "True" then the Postmaster will continue to repost the HL7 message.
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.
<EXCEPTION METHOD="ImportHL7Message" ERRORCODE="86551" ERRORMESSAGE="database error" ADDITIONAL="StreamRequest"></EXCEPTION>