Skip to main content

ITK Payloads – HL7v3 and Clinical Document Architecture

The NHS Interoperability Toolkit (ITK) provides specifications for electronic messaging between systems, supported by an accreditation for suppliers who build solutions that adhere to these specifications. This page explains the two main areas; transport and payloads.

The NHS ITK provides specifications for electronic messaging between systems, supported by an accreditation for suppliers who build solutions that adhere to these specifications.

The specifications can be broken down into two main areas – transport (the “plumbing” to get information from A to B), and payloads (the actual clinical content). Many of the “payloads” that have been specified within ITK use the HL7v3 standards to hold structured clinical content. This comes in two main flavours – plain HL7v3, used for 111 and notifications for example, and HL7v3 Clinical Document Architecture (CDA). The latter provides a standard way of representing a clinical “document”, so that it can be processed consistently by any other system that understands CDA.

Documents in ITK

At the lowest level of maturity, ITK allows an arbitrary attachment (such as Word or PDF document) to be sent directly within an ITK distribution envelope. This does not typically provide any meta-data to identify the type of document, or the patient to which it relates (there are ways of adding meta-data in this case, but these are beyond the scope of this article).

Higher levels of maturity can be achieved using the CDA documents specified within the various ITK “domain message specifications” available on TRUD. These CDA specifications allow for differing maturity in the approach for representing clinical documents.

Note: HL7 have specific CDA maturity levels within their published documentation – this article will not discuss those, rather it will introduce maturity in terms of the ITK specifications published by NHS Digital.

A more mature approach, but still allowing flexibility for locally defined content, is to use the Non-Coded CDA specification. This allows the document to incorporate unstructured content (or content whose structure is locally defined), but also include enough structured content to allow for consistent processing by a recipient. There are two main ways that the Non-Coded CDA specification can be used:

  1. To send a binary attachment (or locally defined text/xml), with some standard structured information about the author, recipients, patient to whom it relates, for example. This is referred to in the specifications as a “NonXML Body”.
  2. To send a set of human readable sections that can be rendered to a user using the standard XSLT transforms provided by NHS Digital – again supported by structured information about author, recipients, patient, for example. This is referred to in the specifications as a “Structured Body”.

The highest maturity is to use a structured, coded CDA document (such as a Discharge Summary or End of Life Care document), which fully specifies the information and clinical coding to use, and allows that to be consistently interpreted by a receiving system. This will allow for much richer processing in a recipient system, as the system can interrogate the content, and where appropriate incorporate information into local records or use it for more intelligent display and processing (such as to drive decision support, alerts).

Creating ITK payloads

In order to make the creation of the HL7v3 and CDA payloads easier, we have created a Java library which simplifies the process of both creating and consuming ITK payloads within systems.

The java library is still evolving, and currently it supports four ITK payloads:

  1. End of Life Care Preferences Document (CDA)
  2. Non-Coded CDA Document
  3. Notifications
  4. Document Retrieval

This article will explain how to use the Java library to create a simple end of life care preferences document. Further details and instructions for creating the other payloads are included on the Wiki page for the library.

Creating an end of life care preferences document

The end of life care workstream within NHS England and NHS IQ have identified a core set of information about people’s preferences for end of life care. The electronic capture and sharing of this information has been identified as an important component in delivering safer, more effective and compassionate care for those in the last year of life. This core set of information has been defined as a national information standard (ISB1580), and the End of Life ITK specification allows these data items to be populated into a CDA document for transmission between systems.

In order to create this CDA document from a Java application, we first need to download the ITK-payloads library and put it into our classpath.

There are two ways that the ITK-payloads library can be used to create an end of life care document. The easiest way is to make use of a “helper” provided with the library. This is a simple class that takes a set of fields in the form of an EndOfLifeCareISBFields object, and uses them to create the various Java objects that represent the document:

import uk.nhs.interoperability.payloads.DateValue;

import uk.nhs.interoperability.payloads.endoflifecarev1.*;

import uk.nhs.interoperability.payloads.exceptions.MissingMandatoryFieldException;

import uk.nhs.interoperability.payloads.vocabularies.generated.*

import uk.nhs.interoperability.payloads.vocabularies.internal.*;

import uk.nhs.interoperability.payloads.helpers.DocumentRenderer;

import uk.nhs.interoperability.payloads.helpers.EndOfLifeCareDocumentCreationHelper;

public class EndOfLifeCareDocumentTest {

   public static void main(String[] args) {

       EndOfLifeCareISBFields fields = new EndOfLifeCareISBFields();

And set some values:


Date values can be set using the DateValue class (find more details on the ITK-payloads wiki page).

fields.setEpaccsRecordCreationDate(new DateValue("20130101"));
fields.setPatientBirthDate(new DateValue("19800101"));

And fields that contain clinical codes can be set using the provided Java enumerations which provide the various values for each field vocabulary.


Some fields will themselves be a class – for example the “PatientAddress” field. To add these fields, first create the relevant object and then add it to the EndOfLifeCareISBFields object (note – all getters and setters return this to allow the builder pattern to be used as shown below):

fields.setPatientAddress(new Address()

        .addAddressLine("123 The Street")

        .addAddressLine("The Town")

        .setPostcode("AB1 2CD"));

If the class is a simple one, you may find it more convenient to use the constructor to initialise the values (refer to the javadocs for details of constructor arguments):

fields.setUsualGPName(new PersonName("Dr", "Simon", "Jones"));

Once you have set all the relevant values in the EndOfLifeCareISBFields object, you can use the EndOfLifeCareDocumentCreationHelper class to generate the more complex set of objects that represent the CDA document contents:

ClinicalDocument doc = EndOfLifeCareDocumentCreationHelper

The ClinicalDocument object that is returned contains many other objects representing the various coded and text sections within the CDA document. If necessary you can use these objects to add any additional information that might be required that has not been done by the helper.

Now we can simply call the serialise method on this document to generate a full CDA document that can be sent over ITK (or via other channels if required):

String xml = doc.serialise();

As a convenience, the standard renderer provided by the messaging team is also provided with the library, and can easily be used to generate a rendered HTML version of the document using the DocumentRenderer class:

String html = DocumentRenderer.generateHTMLDocument(xml);

Note: The helper makes a number of assumptions in order to simplify the process of creating an End of Life Care document. For example it assumes that all patients will be identified using an NHS number, and that all staff will be identified using an SDS ID. These assumptions may not fit the specific needs of teams implementing this library in their solution. Developers are encouraged to use the helper as a starting point to build on/tweak as required.

Consuming an end of life care document

The ITK-payloads library can also parse a CDA document and turn it back into Java objects which you can then use directly in your application.

To parse a payload, first create the overall ClinicalDocument object that you want to populate with data from the XML:

import uk.nhs.interoperability.payloads.endoflifecarev1.*;

public class EndOfLifeCareParseTest {

    public static void main(String[] args) {

        ClinicalDocument doc = new ClinicalDocument();

Then call the parse method, passing in your xml document:


You can now retrieve the information from the Java objects directly:

String documentID = document.getDocumentId();
Date dateOfBirth = document.getPatient().getBirthTime().getDate();

Or, you can use the EndOfLifeCareDocumentParsingHelper to retrieve the values into a EndOfLifeCareISBFields object:

EndOfLifeCareISBFields output = EndOfLifeCareDocumentParsingHelper.getISBFields(doc)

Which will give simpler access to the main ISB fields in a flat object:

Date dateOfBirth = output.getPatientBirthDate().getDate();

Further information

For more information about how to use the itk-payloads library, take a look through the documentation on the project’s bitbucket site.

Once you have a payload and want to know how to send it using ITK, take a look at the ITK Reference implementation also on this site.

Last edited: 12 August 2021 11:57 am