Admit Discharge Transfer (ADT) Query Patient (XML)

Overview

In this scenario a client application queries a remote Master Patient Index (MPI) asynchronously using an XML version of an ADT HL7v2 message. From a business perspective this is typically used by a departmental system to retrieve demographics from the hospital PAS.

The following describes the logic required to invoke the ITK urn:nhs-itk:services:201005:getPatientDetailsByNHSNumber-v1-0 service.

From a black-box perspective this asynchronous interaction is still fairly straightforward, though obviously more complicated than the synchronous interactions. The service requestor sends the appropriate ITK request message and receives a synchronous acknowledgement. Any exceptions encountered in accepting the request will be returned as synchronous Simple Object Access Protocol (SOAP) Faults.Sometime later, the query response is returned by the service provider (PAS) asynchronously to a callback handler specified by the service requestor. Any exceptions encountered in processing the request will be returned as asynchronous SOAP Faults.

Sender view

The Sender builds a SimpleMessage using a String containing the XML ADT message. Configuration of the service tells the R.I. that this message is XML and does not requires base64 encoding.

Receiver view

The Receiver consumers the SOAP message. This validates the SOAP headers and then extracts the payload. The SOAP payload is then split further into Distribution Envelope and business payload. The Distribution Envelope is validated and extracted into MessageProperties. The R.I. then looks up the service properties from the configuration and – in this case – as the payload is simple XML it is passed onto the Application Message Handler.

The sending application builds a SimpleMessage and populates the business payload with the ADT message. The application then sets a number of message properties before creating a message sender and sending the message.

In this case the application uses the sendAsync call of the ITK API because the call is to be asynchronous. Normally this will be known at design time, but as the example shows this decision can be made at run-time provided the application is sophisticated enough to handle the two paradigms.

See the full source code for the sample ADT Servlet.

The first layer of the ITK Reference Implementation (R.I.) is the sendAsync method of the ITKMessageSenderImpl. This component is responsible for checking service properties, establishing the physical transport route and adding the ITK Distribution Envelope, as described in earlier scenarios.

For a simple asynchronous message the service configuration is of particular interest. ADT messages can be sent synchronously or asynchronously, but in the later case the return endpoint needs to be defined. The R.I. does this through the directory.properties configuration file, which manages all configurable aspects of message routing.

The config on the right is taken from the Samples Project and shows where callback calls are routed to.

See the full source code for the ITKMessageSenderImpl.

The next layer of the ITK Reference Implementation (R.I.) is the sendAsync method of the ITKSenderWSImpl.

This component is responsible for managing the WebServices layer – building the SOAP wrappers, physically sending the message, then interpreting the response.

The sendAsync code tells the SOAP handler (WSSOAPMessageImpl) that the message is an Async request which, together with the configuration properties, enables the R.I. to build the correct SOAP Headers.

See the full source code for the ITKSenderWSImpl.

The Reference Implementation provides the AbstractSimpleMessageServlet as an abstract implementation of an ITK receiving application. This is realised by an application provider producing an extension of this class providing concete implementations of the abstract methods.

This abstract class extracts the incoming transport properties from the SOAP headers and attaches them to the ITKMessage which is built to represent the inbound message, providing a mechanism for the reply to parameters to live with the message.

Importantly the replyTo parameter is used by the R.I. to determine whether to invoke the application handler synchronously or asynchronously.

See the full source code for the AbstractSimpleMessageServlet.

In the Async ADT Query in the Samples project the SimpleApplicationEmulator is used to illustrate this. This emulator creates the response message using the message properties from the request, thereby telling the R.I. that this is a response to that message.

In this scenario the onMessage method of the application handler wass called which provides no response. Once control is received from the handler the R.I. will simply return an HTTP 202 acknowledgement on the open channel.

See the full source code for the SimpleApplicationEmulator.

The response message is sent through the normal send API. However. because the ITKMessage was built from the incoming message properties (including the ReplyTo), the message already knows the route back to the callback endpoint and therefore skips the routing lookup.

The ITKMessageSenderImpl allows for this pre-determination of route.

See the full source code for the ITKMessageSenderImpl.

The Reference Implementation provides the AbstractCallbackListenerServlet as an abstract implementation of an ITK callback application. This is realised by an application provider producing an extension of this class which acts as a factory providing an instance of the callback handler ITKCallbackHandler.

The abstract class extracts the incoming transport properties from the SOAP headers and attaches them to the ITKMessage which is built to represent the inbound message. The message is passed to the processITKMessage layer which hands off processing to the appropriate application handler.

See the full source code for the AbstractCallbackListenerServlet.

Finally, the application call handler processes the message as per the local requirements of the system

The sample callback hander simply prints a message.