References

Search

API to support parameterised search of the NRLS. This functionality is available for both consumer and provider systems.

Search Request Headers

Provider API search requests support the following HTTP request headers:

Search DocumentReference

Though the NRLS does not keep a version history of each DocumentReference each one does hold a versionId.

In responding to a search request the NRLS server will populate the versionId of each matching DocumentReference.

Search Parameters

This implementation guide outlines the search parameters for the DocumentReference resource in the table below.

When the _id search parameter is used by a client it SHALL only be used as a single search parameter and SHALL not be used in conjunction with any other search parameter to form part of a combination search query with the exception of ‘_format’ parameter.

When the subject parameter is used by a client it MAY be used in conjunction with the custodian and type search parameters to form a combination search query. The custodian and type search parameters SHALL only be used to form combination search queries.

_id

The search parameter _id refers to the logical id of the DocumentReference resource and can be used when the search context specifies the DocumentReference resource type.

Functionally this search is the equivalent to a simple pointer read operation.

See _id for details on this parameter. The _id parameter can be used as follows:

When the _id search parameter is used by a client, this search parameter SHALL only be used as a single search parameter and SHALL not be used in conjunction with any other parameter to form part of a combination search query with the exception of ‘_format’ parameter.

subject

See reference for details on this parameter. The subject parameter can be used as follows:

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210

Return all DocumentReference resources for a patient with a NHS Number of 9876543210

subject and custodian

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&custodian.identifier=https://fhir.nhs.uk/Id/ods-organization-code%7CRR8

Return all DocumentReference resources for a patient with a NHS Number of 9876543210 and a pointer provider ODS code of RR8.

subject and type

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&type.coding=http://snomed.info/sct%7C736253002

Return all DocumentReference records for a patient with NHS Number of 9876543210 and a pointer type of Mental Health Crisis plan.

_summary

The search parameter _summary allows the client to retrieve the number of DocumentReferences that match a given search.

See _summary for details on this parameter. The _summary parameter can be used as follows:

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&_summary=count

Return a count of resources for a patient with a NHS Number of 9876543210

The _summary search parameter must be set to the value ‘count’ to retrieve the number of matching results. Other FHIR values for this search parameter are not supported.

Search Response

Success:

• SHALL return a 200 OK HTTP status code on successful execution of the interaction.
• SHALL return a Bundle of type searchset, containing either:
  • One or more documentReference resource that conforms to the NRLS-DocumentReference-1 profile; or

  • A ‘0’ (zero) total value indicating no record was matched i.e. an empty ‘Bundle’.

    Note: The returned searchset bundle does NOT currently support:
    
    (1) the self link, which carries the encoded parameters that were actually used to process the search.
    
    (2) the identity of resources in the entry using the fullUrl element.
    
    (3) resources matched in a successful search using the search.mode element.
    
    NB: The NRLS Service will ONLY return an empty bundle if a Spine Clincals record exists and there is no DocumentReference for that specific Clinicals record.

• Where a documentReference is returned, it SHALL include the versionId of the current version of the documentReference resource

• When a Consumer retrieves a DocumentReference if the masterIdentifier is set then it should be included in the returned DocumentReference

• When a Consumer retrieves a DocumentReference if the relatesTo is set then it should be included in the returned DocumentReference

Failure:

The following errors can be triggered when performing this operation:

• Invalid NHS number
• Invalid parameter
• No record found

Example Scenario

An authorised NRLS Consumer searches for a patient’s relevant health record using the NRLS to discover potentially vital information to support a patient’s emergency crisis care.

Request Query

Return all DocumentReference resources (pointers) for a patient with a NHS Number of 9876543210. The format of the response body will be XML.

cURL

curl -H 'Accept: application/fhir+xml' -H 'Authorization: BEARER [token]' -X GET  '[baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&_format=xml'

Query Response Http Headers

Query Response

Single Pointer (DocumentReference) Returned:

• HTTP 200-Request was successfully executed
• Bundle resource of type searchset containing a total value ‘1’ DocumentReference resource that conforms to the nrls-documentReference-1 profile.

Multiple Pointers (DocumentReference) Returned:

• HTTP 200-Request was successfully executed
• Bundle resource of type searchset containing a total value ‘2’ DocumentReference resources that conform to the nrls-documentReference-1 profile

No Record (pointer) Matched:

• HTTP 200-Request was successfully executed
• Empty bundle resource of type searchset containing a ‘0’ (zero) total value indicating no record was matched

Error Response (OperationOutcome) Returned:

• HTTP 400-Bad Request. Invalid Parameter.
• OperationOutcome resource that conforms to the ‘Spine-OperationOutcome-1’ profile if the search cannot be executed (not that there is no match)

See Consumer Search section for all HTTP Error response codes supported by Consumer Search API.

_summary=count response:

• Response body SHALL return a valid XML or JSON formatted Bundle of type searchset, containing a bundle that reports the total number of resources that match in Bundle.total, but with no entries, and no prev/next/last links. Note that the Bundle.total only include the total number of matching DocumentReferences.

Examples

• 3 DocumentReferences exist for patient with NHS number passed into the search

• 0 DocumentReferences exist for patient with NHS number passed into the search

Code Examples

GET Pointers with C#

The following code samples are taken from the NRLS Demonstrator application which has both Consumer and Provider client implementations built in. More information about the design solution can be found on the NRLS Demonstrator Wiki

First we generate a base pointer request model that includes the patients NHS Number used for the subject parameter. The NHS Number is obtained through a stub PDS Trace performed within the Demonstrator Consumer system.

Then we call our DocumentReference service GetPointersBundle method which will build a GET command request and then start the call to the NRLS API.

var pointerRequest = NrlsPointerRequest.Search(request.OrgCode, request.Id, null, request.Asid, null);

var pointerResponse = await _docRefService.GetPointersBundle(pointerRequest);

Once we have received pointers from the NRLS when then look up the custodian (and author) organisation details using the ODS Code’s held within each pointer via a stub ODS lookup. We can then present actual organisation details to the end users.

Calling the NRLS
Using our GET command request model we create a connection to the NRLS using HttpClient.

You can view the common connection code example here.

Explore the NRLS
You can explore and test the NRLS GET command using Swagger in our Reference implementation.