Spine Mini-Services Client

Overview

In this scenario a client application is indirectly querying Spine PDS to obtain demographic information held for the provided NHSNumber. From a business perspective this is typically used to check (and/or potentially update) the locally held demographic details about the patient from the national Patient Demographic Service.

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

From a black-box perspective the invocation of a Spine Mini-Service Provider web service interface is fairly trivial. The service requestor simply sends the appropriate ITK request message and receives the response synchronously. Likewise any exceptions will be returned as synchronous SOAP Faults.

SMS client

As the SMS client already has the pertinent patient’s NHSNumber in their local data store the query to get the latest demographics via the SMS Provider is relatively straightforward. The SMS Client builds the Get Patient Details By NHSNumber Request query message providing the patient’s NHSNumber and Date of Birth.

SMS provider

The SMS Provider is a unique component in ITK – providing a bridge between the Spine PDS interfaces and Spine Mini Service Clients. In a real deployment, the SMSP would receive the ITK Get Patient Details By NHSNumber Request, make one or more queries to Spine services the results of which are used construct the appropriate ITK Get Patient Details By NHSNumber Response.

In the samples application the SMSP is emulated via a simple XSLT that creates a response from the request.

Request

Get Patient Details By NHS Number Request

The following diagram shows how the sample application uk.nhs.interoperability.client.samples.smsp.SpineMiniServicesClient from the samples project uses the reference implementation to make a call to a Spine Mini-Service Provider.

In order to invoke the Spine mini-service the application layer first needs to collect and populate the query parameters. The sample application does this from a simple web form. However, how real world applications obtain the query parameters is outside the scope of the API and reference implementation.

Once the application has constructed the appropriate query object it needs to be handed over to the transport layers for the actual technical invocation of the service.

The actual specific on-the-wire format of the query message is not the responsibility of the transport layers to determine or manage. The request.serialise() method at line 6 populates the payload for the ITK invocation – in this case a getPatientDetailsByNHSNumber-v1-0 XML message with the appropriate parameters set.

It is an application layer responsibility to set the audit identity, to and from address details, profileId and business payload id (line 10). Many of these details are omitted here for clarity – for reference the ITKMessageProperties provides getters and setters to allow the message meta-data and addressing information to be passed between the application and transport layers.

Once the properties have been associated with the payload (line 14) the distribution and transport layers are invoked via the ITKMessageSender sendSync API call.

See the full source code for the Get Patient Details by NHS Number method.

Note - this step and the majority of the subsequent steps are common to all synchronous invocations via the Reference Implementation.

The application request payload is passed into the framework via the ITKMessage. In order to successfully call the service provider we need to resolve the service properties, obtain the route appropriate to the service provider, add the necessary wrappers and call the appropriate transport specific implementation classes.

The resolution of the route (line 9) is shown in more detail in Step 3 (listing 3a below). Having obtained the route we then get a reference to the transport specific ITKSender (line 12). Note the 0.1 release of the reference implementation only contains an implementaiton for HTTP/SOAP Web services. The reference implementation could be be extended in the future to support DTS, TMS and other transports as specified by ITK.

The details of building the ITK Distribution Envelope and on-the-wire encoding (line 15) are shown in detail in listing 3b below. Once the appropriate ITK message has been created the transport specific ITKSender is used to actual send the message (line 18). For this scenario the HTTP/WS invocation is shown in detail in Step 4 below

Once the transport layers have returned with the synchronous response this is unwrapped / deserialised via the buildResponse(response) method (line 21).

Listing 3a shows the logic for resolving the ITKTransportRoute, whilst Listing 3b shows the simple logic used to determine whether or not the payload should be wrapped in an ITK Distribution Envelope and base64 encoded.

The ITKTransportRoute may have already been pre-resolved from the application layer (listing 3, line 9) in which case we do not need to look it up. The pre-resolved route may have been determined via application layer configuration or because the application has maintained the transport return address details from a corresponding request in an asynchronous invocation.

In this synchronous invocation scenario the logical destination address provided by the application layer will need to be resolved to an HTTP URL for the web service invocation. This is achieved via the call to the DirectoryOfService on line 15. In the reference implementation the directory is a simple properties file wrapped by some simple logic – see ITKSimpleDOS.

The DirectoryOfService is responsible for returning a fully populated ITKTransportRoute which contains details of the under lying transport type, the physical destination address and whether or not a distribution envelope is required.

Listing 3b shows the logic for building the transport independent ITK message.

Line 4 determines whether a distribution envelope is required. If the message needs to be wrapped by a Distribution Envelope a new ITKMessage including the DistributionEnvelope is built via the DEWrappedMessage constructor (line 12).

Prior to building the complete Distribution Envelope wrapped message is may be that the business payload needs to be base64 encoded. Logically this is a property of the ITKService (determined via configuration), however in terms of the current ITK Specifications this is only required for HL7v2 messages exchanged in pipe and hat (|^) format. In this getPatientDetailsByNHSNumber scenario the business payload message is XML based and no base64 encoding is required.Listing 3a resolving the transport via the directory of services.

Listing 4 shows the code within the ITKSenderWSImpl which is responsible for adding the SOAP and WS-Addressing wrappers, for invoking the appropriate web-service endpoint as determined by the ITKTransportRoute and managing HTTP and SOAPFaults or other exceptions arising from the invocation.

In Step 3 we created a transport independent ITK message. The logic of this class is specific to ITK Web services and requires that we add SOAP Wrappers including the appropriate ws-addressing elements as per the ITK Specifications (line 4).

The call on line 7 to obtain the full payload invokes an XSLT transform that creates the complete on-the-wire SOAP message with the ITK Distribution Envelope wrapped getPatientDetailsByNHSNumber within the SOAP body.

The web service is actually invoked via the transportSend(destination, soapPayload) method call.

As this is a synchronous call there is no information in the response message SOAP header pertinent to the client so we directly extract the response payload (line 14) which is then passed back up the call stack via the returned SimpleMessage (line 18).