<< Click to Display Table of Contents >> Navigation:  Creating Postmasters > Destinations > Web Service > Technical Overview > #1 Ping Your Service

Stage 1: Pinging Your Service

 

Before it starts posting HL7 messages the postmaster will 'ping' the starting URL at predefined intervals with the Login ID and Password supplied (from the Web Service Destination profile) in an XML format (http POST) which will look like this:

 

<PING LOGONID="YourLogonID" PASSWORD="YourLogonID" PMVERSION="1.0.0.0" COMPUTERNAME="ClientComputerName"></PING>

 

This 'ping' request is quite short and serves several purposes.

 

•It determines quickly whether there is an internet connection on the client machine.

•It determines whether your web server and your web service are up and running to receive HL7.

•Since it contains private data (Password) it is highly recommended that it be a secure URL

 

Your web service will respond to the Ping request by returning 1 of 2 predefined XML responses which will be either an EXCEPTION XML indicating that something is wrong and that the postmaster should not continue with Stage 2 or a URL LIST XML containing the URLs to use when performing Stage 2 and Stage 3 of the HL7 Message retrieval process.

 

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.). The Exception XML structure looks like this:

 

<EXCEPTION METHOD="PingAcknowledgement" ERRORCODE="3267" ERRORMESSAGE="Invalid logon id" ADDITIONAL="StreamRequest"></EXCEPTION>

URL LIST XML: If there is no exception in your web service then it will return a properly formatted 'Ping' response which is an XML URL Listing with the actual URL to use when posting HL7 messages to the service. The Ping response XML should look like this:

 

<PING HL7POSTURL="https://www.yourcompany.com/Webservices/HL7Interface.aspx?Action=HL7Post" LOGONID="YourLogonID" REPING="False"></PING>

 

Programming Note for Web Service Developers: Observe the following rules which must be followed to produce a valid 'Ping' response XML:

 

•The root node of the XML must be named PING.

• The root node of the XML must contain an attribute named HL7POSTURL which must contain a validly formatted URL value.

•The root node must contain an attribute named LOGONID which must contain the same value which was posted in the PING XML post.

•(Optional) the root node MAY contain an attribute named REPING which (if present) must contain either the word True or False, if not present it is assumed to be False. The REPING attribute (which can also be used in the HL7 Acknowedegment in Stage 2) tells the Postmaster to execute Stage 1 every time it sends an HL7 message. If False, the Postmaster will only execute Stage 1 until it successfully retrieves a valid HL7POSTURL.

 

 

Benefits of this method for you the web service designer are:

 

•It allows you to dynamically "throttle" and distribute your HL7 processing. The URL provided in your response ping can be on entirely different servers based on  the client LOGON ID or can be rotated for load-balancing, etc. There are many possibilites.

•It provides a very narrow, low cost (in resources) "front door" for your web service. You can do as much or as little as you wish in terms of actually "processing" the 'Ping' request. For instance, you don't have to validate the login ID passed in the ping request, you can just return the URL.

•It provides better security and allows you to control the timing and flow of data.