HL7v2 API

Introduction

This document specifies the technical details for accessing and using the Discovery Data Service HL7v2 API, for the use by interoperability system suppliers developing integrations against the service.

The Discovery Data Service (DDS) is an NHS owned service that provides low cost access to personal health and care data from combined primary, secondary, unscheduled and community health care data sets (https://discoverydataservice.org/Content/Overview.htm)

All data that is published or subscribed to and from DDS is governed by strict information governance rules and underpinned by Data Sharing Agreements, Sharing Flows and Subscriber Extract Projects (https://discoverydataservice.org/Content/Governance.htm)

DDS receives data from multiple source publishing systems in multiple formats and normalises the data into a common structure based on national care record standards.

DDS can receive HL7v2 structured ADT and ORU messages from Secondary Care systems, and transform them into the Discovery FHIR store, from where the data gets transformed into subscriber databases for reporting.

The Discovery HL7v2 API uses a secure authentication and authorisation service. This uses recommended standards for identity and access management, using OpenID Connect and OAuth 2.0 methods, and also includes an additional security layer, where DDS checks it’s internal User Management service to ensure that each user is authorised with the necessary role based access profiles to use each particular application. This allows for tokens and user access to be centrally managed and revoked within the DDS User Manager application.

Two API calls are used for the HL7v2 API:

• Authenticate
• Authorise/ProcessMessage

Authenticate

Authenticate the client identity by passing in client credentials to receive an access token for the API.

https://devauthentication.discoverydataservice.net/authenticate/$gettoken

Passing this JSON POST body (no header required)

{
  "grantType": "password",
  "clientId": "information-manager",
  "userName": "XXXXXXXXXXX",
  "password": "XXXXXXXXXXXX"
}

(userName and password can be requested by contacting the Learning Health Solutions Helpdesk at https://learning-health.co.uk/). This API call returns an authorisation access_token in this JSON reply, or a 404 HTTP Not Found response if the user is not recognised.

{
    "access_token": "xxxxxxxx",
    "refresh_token": "xxxxxxxxx",
    "refresh_expires_in": 1800,
    "not-before-policy": 1548863201,
    "scope": "profile email",
    "token_type": "bearer",
    "session_state": "79b125f5-f062-4a4c-a5a6-b2fa4519e8ad",
    "expires_in": 60
}

An access token can also be retrieved using the refresh_token value, once the user's identity has been authenticated using the above call. Passing this JSON POST body (no header required)

{
  "grantType": "refresh_token",
  "clientId": "information-manager",
  "userName": "",
  "password": "<refresh_token_value>"
}

Note: this will return as updated refresh token along with each new access token request, and retrieves the access token based on updated refresh token.

Authorise/ProcessMessage

Post HL7v2 messages to a REST API.

This call uses the access token from the authentication API to authorise the client's access to the API, which will then post the HL7v2 message to DDS if the client is recognised and authorised to use this service.

https://devhl7.discoverydataservice.net/hl7/$process-message

Passing this JSON POST body

{
  "meta": {
    "profile": [
      "https://hl7.org.uk/V2/OperationDefinition/ProcessMessage-Operation-1"
    ],
    "tag": [
        {
            "system": "https://hl7.nhs.uk/Id/ODS-Code",
            "code": "RYJ",
            "display": "IMPERIAL COLLEGE HEALTHCARE NHS TRUST"
        }
    ]
  },
  "resourceType": "HL7v2",
  "messageType": "LaboratoryResult",
  "id": "4847653a-7b39-4d7e-928f-a9fa6d833dd4",
  "identifier": [
	    {
	        "system": "https://hl7.org.uk/Id/dds",
	        "value": "1716"
	    }
	],
  "creationTime": "2012-10-23T00:00:00+00:00",
  "messageEventType": [
        {
            "valueCodeableConcept": {
                "coding": [
                    {
                        "system": "https://hl7.nhs.uk/V2/CodeSystem/EMS-MessageEventType-1",
                        "code": "new",
                        "display": "New event message"
                    }
                ]
            },
            "url": "https://hl7.nhs.uk/V2/StructureDefinition/Extension-EMS-MessageEventType-1"
        }
    ],
  "body": "MSH|^~\&|GHH LAB|ELAB-3|GHH OE|BLDG4|200202150930||ORU^R01|CNTRL-3456|P|2.4 PID|||07827717281||JANET^EVE^E^^^^L|JONES|19620320|F|||153 FERNWOOD DR.^
 ^TESTVILLE^EL4^35292||(01)33452232|(01)348439949||||AC555444444||67-A4335^LONDON^20030520 OBR|1|845439^GHH OE|1045813^GHH LAB|15545^GLUCOSE|||200202150730|||||||||
 0283829292^PRIMARY^PATRICIA P^^^^MD^^|||||||||F||||||02992888292^SMITH^HOWARD H^^^^MD OBX|1|SN|1554-5^GLUCOSE^POST 12H CFST:MCNC:PT:SER/PLAS:QN||^182|mg/dl|70_105|H|||F"
}

Note: The body elements contains the HL7v2 message. The rest of the JSON is the wrapper specification for the message.

Set the Authorization header in the REST POST call to the value of the access_token returned from the authentication API.

Note: Access tokens expire if they are not used within 60 seconds.

If this API fails to authorise the access token against the Discovery identity and access management service, then an Unauthorised return value will be sent with a 401 HTTP Status (Unauthorized).

Success will return a 200 OK HTTP status, after the message is filed into DDS.

Workflow

The Discovery Data Service is powered by Learning Health Solutions Ltd. https://learning-health.co.uk/