Browse and search developer information

National Record Locator Service


The purpose of this article is to provide a brief introduction to the National Record Locator Service (NRLS) and describe the NRLS interactions that we’re assessing in more detail as part of the initial technical Proof of Concept platform that has been developed.

The article will provide reference to some of the key reference artefacts, in particular a pointer to the current draft DMS, and a set of test interactions.

The National Record Locator Service

The NIB Roadmap  introduced the concept of the creation of a National Record Locator Service that would:

“act as a national index to be able to find out what records exist for a patient across local and national care record solutions (such as SCR).”

What this proposes is a strategic direction, for the creation of a fundamental data sharing component within the health and care architecture to support the delivery of a paperless NHS.

As part of the assessment as to how this may best be achieved (and maintained), NHS Digital have been commissioned to create a technical Proof of Concept platform that would enable stakeholders, including the Code4Health community, to test and assess the opportunities and approach for how such a service could best deliver real value, including how it would integrate with local and regional services for that aim.

In terms of the technology, we’re basing the design on the FHIR DSTU2 standard. In particular, we’re aiming to use a profiled version of the DocumentReference resource (a draft DMS for this is now available here on this site), accessed using FHIR’s RESTful API.

The overall architectural implementation is expected to draw heavily on the IHE XDS standard although is not currently expected to fully implement this standard or the ebXML serialisation of the messages utilised by XDS. The national Record Locator Service (at least for the PoC) will provide a simplification of the XDS pattern thought to be appropriate to a national scale implementation.

We recognise that there is debate on the best approach but at this stage we are not in a position to define strict requirements which might limit the capability. Further:

  • The XDS standard is based on the concept of an Affinity Domain; in effect you draw a circle around the systems playing a part, and apply a set of rules to those systems. Apart from “The whole Health and Social Care system” NHS Digital does not have a defined scope which we can control in this way.
  • The XDS standard is substantial – being designed to support relatively detailed, relatively complex scenarios. For the NRLS, NHS Digital is required to simplify the interfaces so as to provide a lower barrier to entry for systems.
    • For example, the support offered by XDS (folders etc.) isn’t something we’ve seen a need for (yet).

Some basic assumptions

As a discreet service the NRLS is not designed to solve all of the challenges of moving clinical documents between parties.  Under the current design proposed queries to the NRLS will be supported by appropriate IG controls, based on currently existing or planned NHS Digital standards.

Once a document has been identified governing and securing retrieval of the data may also be controlled by national standards but there may be capacity for separate point to point implementations to utilise their own secured transport mechanisms (for example it may prove possible to use an XDS Retrieve Document Set (ITI-43) to retrieve a document).

The IG and security model for document retrieval across health and social care services is being considered and designed alongside this piece of work, in the pilot we’ll make some simplistic assumptions, but before this service could be used in production, these two pieces of work need to come together.

A further assumption is that all systems are working with verified patient identities. The NRLS will rely on document consumers having a validated NHS Number with which to identify the patient.

The NRLS is expected to point to a number of categories of document:

  1. Null pointers which indicate the existence of a (probably paper) record and merely provide contact details of the owning organisation;
  2. Pointers to immutable documents which are correct at a point in time (such as a discharge) and may be relied up to be accurate at that point in time;
  3. Pointers to mutable interfaces which will provide the latest record of a certain type, for example a pointer to the GP System interface to retrieve the whole patient record.

It is recognised that the types of document references which can be stored at the national level is a particularly important piece of meta data and may require a separate governance process through which NHS organisations and programmes can request the addition of new record types to the national service.

For the proof of concept, our current working assumption (that will be assessed) is that the ‘types’ of records being indexed by the NRLS will have been defined following stakeholder engagement and published prior to adoption, and therefore the consuming systems can be confident in knowing exactly what a record ‘is’.

The actual process

To describe the process, we’ll define three ‘actors’:

  • Contributing system
  • NRLS
  • Consuming system

Working to the Registry Repository pattern as described here, the mapping of components from that page to the above ‘actors’ is as follows:

Document Repository                    Contributing System

Document Source                            Not required by this design, in reality it will usually be the same as the Document Repository

Document Registry                         National Record Locator Service (NRLS)

Document Consumer                     Consuming System

Store a reference

The first operation to consider is that a Contributing system has a record for a patient which it is willing to make available to other clinical systems. In the POC, we’re limiting the scope to EPaCCS systems, but this could be any system holding patient records.

The contributing system creates a FHIR DocumentReference resource object, this contains amongst other things, the following data items:

  • Subject (our patient)
  • Type (the type of record)
  • Created (when the record was created)
  • Indexed (when it was indexed)
  • Security Label (one of a set of values e.g. restricted, very restricted etc.)
  • Content (The URL of the Document, it’s size and mime type)
  • Custodian (the organisation owning the record)

The contributing EPaCCS system now sends the resource object to the NRLS using a http POST interaction to create a DocumentReference in the NRLS.  The NRLS validates the data, and all being well stores the DocumentReference.

Find references

At some later point in time, a consuming system wants to know what records are available for our patient.  For example, a user in an unscheduled care service, using their local clinical system, begins to deal with the same patient where access to further information would help their clinical decision making (that information being stored in the Contributing EPaCCS system).

The consuming system makes a GET request to the NRLS FHIR server, which describes a search for records matching specific criteria (i.e. DocumentReferences of which the subject is our patient).

The NRLS performs the query, and returns a FHIR Bundle resource containing any matching DocumentReference resources.

In our scenario described here, there would be one DocumentReference contained, which has a pointer (the specification requires a URI, but we expect a URL) to the original EPaCCS record which was made available by the contributing system.

Having got the DocumentReference, the consuming system can now display some of the data (see bullet points above) from it as a list (assuming there could be more than one) to the user in the unscheduled care service, and on demand from the user request the original EPaCCS record.

Retrieve record

As mentioned above, fetching the actual record is not a feature that is included within the current NRLS PoC.  This requirement needs to be solved, but isn’t something we’re addressing directly at this stage (for the purposes of the PoC we plan to use a simple and direct http GET request).

Supporting artefacts

Once the POC has been built and is up and running, we are planning to make the service available to suppliers via OpenTest, but in the meantime as we’re building to the FHIR standard, it can be tried against a FHIR service.

In order to bring this process to life, the entire sequence has been created as a POSTMan collection available here.

There have been a few assumptions made during the creation of these interactions, for example:

HSCIC owned URLS:  the examples contain a few URLS, for FHIR profiles, and for locations of other FHIR resources, these aren’t intended to be valid at this stage, nor are they an indication of what the URLs might be. We’re aware we would need to host FHIR profiles and resources, and these are just placeholder values for the purposes only of these tests.

Coding systems used:  A number of items in the tests have coding systems assigned, for example the types of documents. We’ve worked on the assumption these will be SNOMED CT, given the strategic direction this is likely to be right but it’s yet to be the result of a specific and explicit decision here.

Server implementation:  Because we’ve based the sequence on a HAPI FHIR implementation, (see below), we need to do some additional set-up work.

Note: The HAPI FHIR server assigns an incrementing integer ‘identity’ value to each resource created. In addition to this, it verifies that any referenced resources exist on the server, both when resources are being created, but also when they’re being deleted.  In other words, if we try to create a DocumentReference which is authored by a resource identified as Practitioner/123, then unless that Practitioner resource already exists, the creation will fail.  Similarly, if we later try to delete the Practitioner, while the DocumentReference still exists, the delete request will fail to prevent the DocumentReference object having a non-existent author.

Single user:  The tests are not ‘thread safe’, in other words if two people run the test set at the same time, there’s a good chance that one will get indeterminate results. This is simply a result of some oversimplifications made during the build.

The process

This sequence of interactions uses POSTMan environment variables as parameters to chain together the entire sequence as follows, those in Bold are equivalent to the NRLS calls, whereas all of the others are only there to support the test sequence.

  • Create a Practitioner
  • Select the Practitioner to find the server assigned Logical ID
  • Create an Organisation
  • Select the Organisation to find the server assigned Logical ID
  • Create a Patient
  • Find the Patient to get the server assigned Logical ID
  • Create a DocumentReference for our Patient, with the custodian of our Organisation, and the Author as our Practitioner.
  • Create a second DocumentReference.
  • Search for DocumentReferences for the Patient
  • Get the first DocumentReference we found
  • Get the second DocumentReference we found
  • Delete the DocumentReferences
  • Delete the Patient
  • Delete the Organisation
  • Delete the Practitioner

To make this sequence able to be pointed at any arbitrary FHIR server, it uses an environment variable for the base URL. In order to run this set of interactions, you therefore need to create an Environment in POSTMan. To do this, click Manage Environments at the Top Right corner:


You need to create a new Environment (call it anything you like) and add an Environment variable Key Value pair with a Key of ‘BaseURL’ and a Value of the Base of a FHIR server (for testing, you can use


You can therefore create multiple Environments, pointing to different FHIR servers, and flick between them at will.

Outstanding questions

There are still a number of questions which the NRLS proposal raises that we are still to address, these include:

The lifecycle of the DocumentReference and underlying record

Certain ‘records’ will be permanent, for example a Discharge summary is created on the discharge of a patient, and is a point in time record.  It is highly unlikely that the record will be updated or even checked ever again. Whereas other ‘records’ may only exist (or be relevant) for a short period, and can be expected to be deleted or at least updated frequently.

If we make the wrong assumptions for the NRLS, we risk it filling up over time with orphaned records (as systems move, and links break down).  If we opt to set an expiry date for records, then more permanent documents will not exist in the index (when they should be available).

What constitutes a record?

At the moment, the assumption is that each ‘record’ will effectively be (the equivalent of) a discreet document relating to a patient. It could be that a ‘record’ would need to be registered which represents a system’s ability to provide one or more records for the selected patient.  An example could be that a FHIR search URL could be registered for example:

http://contributing_server/DocumentReference?subject=Patient/[Patient ID Here]

This might reduce the number of items needing to be registered (one entry could represent multiple records), but reduce the amount of information visible, and add complexity onto the maintenance of the references to those records.

Types of record

We are pretty sure that we’ll need to only allow known ‘types’ of record to be registered, in order to ensure that consumers know how to interpret them. This hasn’t been properly tested yet but is certainly our starting assumption.