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

 

Stage 1: Pinging Your Web Service

 

The postmaster will 'ping' the starting URL at predefined intervals with the Logon ID supplied in an XML format (http POST) which will look something like this:

 

<PING LOGONID="YourLogonID" PMVERSION="1.0.0.0" FREQUENCY="20 Seconds" REPING="True"></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

*Since it contains a minimum of data (and no private data) it can be either secure or unsecure

 

 

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 a URL Listing with three (3) different URLs which the postmaster will use to execute stages 2 and 3 will be returned. Since stages 2 and 3 will contain private data these URLs should definitely be secure (https). The URL list xml looks like this:

 

<PING MAILBOXURL="https://www.yourcompany.com/Webservices/HL7Interface.aspx?Action=HL7Mailbox" HL7GETURL="https://www.yourcompany.com/Webservices/HL7Interface.aspx?Action=GetHL7" HL7ACKURL=""https://www.yourcompany.com/Webservices/HL7Interface.aspx?Action=HL7Ack" LOGON="YourLogonID"></PING>

 

 

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

 

*It allows you to dynamically "throttle" and distribute your HL7 processing. The URLs provided in your response ping can be on entirely different servers, or can be different for each client 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 URLs.

*It provides better security and allows you to control the timing and flow of data. For instance, if the Postmaster has been configured to query your service for HL7 messages every 10 seconds BUT you only want the particular client to retrieve messages every hour you can just return an exception for the next hour after that client retrieves their HL7 messages.