We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
ITK Spine Mini Services use synchronous Simple Object Access Protocol (SOAP) Interoperability Toolkit (ITK) web service calls, constrained to 5 specific operations:
Step 1 – functional requirements
The ITK Spine Mini Service functional specifications are available in the requirements pack and the first three that should be read are:
- The ‘PDS – Spine Mini Services Provider Requirements-v1.0.pdf‘ document contains the details of the information model shown above. It also explains the provider requirements, the request message descriptions, plus behaviours of wildcards and data type format. Note: NHS Digital have implemented the Spine Mini Service as a central solution.
- The ‘PDS – Spine Mini Services Client Requirements-v1.0.pdf‘, a document which the Client developer will need to read to ensure the application meets the requirements within.
- The ‘SMSP Response Code – v1.0.xls’ spreadsheet, which as the name suggests contains the general service message response codes and PDS specific ones. An example being a successful query would contain an SMSP-0000 Success code< value codeSystem=”2.16.840.1.1138126.96.36.199.188.8.131.525″ code=”SMSP-0000″/>
Further information about the 5 specific SOAP ITK web service call operations can also be found in the SMSP-PDS requirements pack and target operating model template.
Step 2 – message specification
The ‘PDS Mini Services Domain Message specification’ is also in the requirements pack.
The message specification contains all the details of the SOAP message requests and responses. It also includes the wsdl file (PDSMiniServices-v1-0.wsdl under \schema\wsdl), and some specific message examples under the ‘Payload’ column. It should be noted that the wsdl file has not been created for importing into frameworks capable of automatically building proxy classes.
ITK SOAP Messages contain a number of layers, as shown in the diagram below.
The ‘Payload’ detailed within the message specification refers to the Payload shown within the diagram above, which is a child element within the distribution envelope.
So what does the diagram actually look like in XML? The extract below (click to zoom) shows the SOAP Envelope, the SOAP Head, SOAP Body, and within the body (under the itk namespace) the ITK Distribution Envelope. The distribution envelope is used within all ITK SOAP Web Service calls, containing a header with the audit identity (the accredited system identifier provided during the endpoint registration process, linked to the calling organisations’ ODS code).
Step 3 – quick test
Firstly we convert the NHS Digital provided PKCS#12 file (for a specific environment) into a PEM, for use with
curl: openssl pkcs12 -in pkcs_filename.p12 -out pem_filename.pem -nodes -clcerts
Using this file getNHSNumber.xml which contains a test patient example from the opentest environment, execute the following curl command, substituting the certificate name and message endpoint (Opentest url shown in example). Note: the patient search details may need to be altered depending on the environment being accessed.
$ curl -i -X POST -H “SOAPAction: urn:nhs-itk:services:201005:getNHSNumber-v1-0” -H “content-type: text/xml” –E pem_filename.pem -d @getNHSNumber.xml -k https://192.168.128.11/smsp/pds
Note: there are some variations in curl 7.43.0 on OS X, this is a working command line:
$ curl -X POST -H SOAPAction:urn:nhs-itk:services:201005:getNHSNumber-v1-0 -H content-type:text/xml -E p12_filename.p12:Password -d @getNHSNumber.xml -k https://192.168.54.6/smsp/pds
This will return:
The returned NHS number is 9473480032.
Step 4 – transport connection
The ITK Spine Mini Service uses TLS MA (mutual authentication) to secure the connection between the client and central provider. When an endpoint is registered to the Path To Live Integration environment you will be provided with a PKCS#12 file containing the endpoint certificate, sub CA, and CA certs. This certificate is used to create the mutually authenticate connection with the service endpoint.
Describes the required approval of usage and settings mainly relating to the end user.
The NHS Digital Spine Mini Service Provider (SMSP) lets health and social care providers access important information held on Spine. It aims to reduce the complexities around integration with the Spine.