Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Retrieval Formats

Support formats for record and document retrieval

Retrieval Formats

The NRL may support retrieval of records and documents in a range of formats, this could include both unstructured documents and structured data.

The format of the referenced record is detailed in two meta-data fields:

  • Record format - describes the technical structure and the rules of the document/record and its retrieval route
  • Record mime type - describes the data type of the document/record

See FHIR Resources & References for further detail on the data model.

The combination of these two meta-data fields describes to a Consumer system the type and structure of the content that will be returned. This gives the Consumer system the information it needs to know to render the referenced record. For example, whether the referenced content is a publicly accessible web page, an unstructured PDF document or specific FHIR profile. See Retrieval Formats for further detail and the list of currently supported formats.

Supported Formats

The table below describes the formats that are currently supported:

Format Description
HTML Web Page (Publicly accessible) A publicly accessible HTML web page detailing contact details for retrieving a record.
PDF (Publicly accessible) A publicly accessible PDF detailing contact details for retrieving a record.
PDF A PDF document. For guidance see the CareConnect GET Binary specification.

Please see the format code value set for the list of codes to use.

Consumers and Providers SHOULD support PDF as a minimum.

The prefix of direct in a Format code MUST be used for publicly accessible contact details only.

Note that the NRL supports referencing multiple formats of a record document on a single pointer.

Multiple Formats

Multiple formats of a record or document can be made available through a single pointer on the NRL. For example a pointer can contain a reference to retrieve a record in PDF format and as a structured FHIR resource. Each format must be detailed in a separate content element on the DocumentReference (pointer).

Multiple Format Example

The example below shows a pointer for a Mental Health Crisis Plan that can be retrieved over the phone (using the contact details listed on the referenced HTML web page) and directly as a PDF document.

<DocumentReference>
    <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
    </meta>
    <masterIdentifier>
        <system value="urn:ietf:rfc:3986"/>
        <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.7"/>
    </masterIdentifier>
    <status value="current"/>
    <type>
        <coding>
            <system value="http://snomed.info/sct"/>
            <code value="736253002"/>
            <display value="Mental health crisis plan (record artifact)"/>
        </coding>
    </type>
    <class>
        <coding>
            <system value="http://snomed.info/sct"/>
            <code value="734163000"/>
            <display value="Care plan (record artifact)"/>
        </coding>
    </class>
    <subject>
        <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"/>
    </subject>
    <created value="2016-03-08T15:26:00+01:00"/>
    <indexed value="2016-03-08T15:26:01+01:00"/>
    <author>
        <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RGD"/>
    </author>
    <custodian>
        <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RR8"/>
    </custodian>
    <relatesTo>
        <code value="replaces"/>
        <target>
            <identifier>
                <system value="urn:ietf:rfc:3986"/>
                <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.6"/>
            </identifier>
        </target>
    </relatesTo>
    <content>
        <attachment>
            <contentType value="application/pdf"/>
            <url value="https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalhealthCrisisPlanReportRGD.pdf"/>
            <creation value="2016-03-08T15:26:00+01:00"/>
        </attachment>
        <format>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
            <code value="direct:https://www.iso.org/standard/63534.html"/>
            <display value="PDF (Publicly accessible)"/>
        </format>
        <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1">
            <valueCodeableConcept>
                <coding>
                    <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1"/>
                    <code value="static"/>
                    <display value="Static"/>
                </coding>
            </valueCodeableConcept>
        </extension>
    </content>
    <content>
        <attachment>
            <contentType value="text/html"/>
            <url value="https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalhealthCrisisTeam"/>
            <creation value="2016-03-08T15:26:00+01:00"/>
        </attachment>
        <format>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
            <code value="direct:https://www.w3.org/TR/html"/>
            <display value="HTML Web Page (Publicly Accessible)"/>
        </format>
        <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1">
            <valueCodeableConcept>
                <coding>
                    <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1"/>
                    <code value="static"/>
                    <display value="Static"/>
                </coding>
            </valueCodeableConcept>
        </extension>
    </content>
    <context>
        <period>
            <start value="2016-03-07T13:34:00+01:00"/>
        </period>
        <practiceSetting>
            <coding>
                <system value="http://snomed.info/sct"/>
                <code value="892811000000109"/>
                <display value="Adult mental health service"/>
            </coding>
        </practiceSetting>
    </context>
</DocumentReference>

Direct vs Proxy

The record format code also indicates whether the record should be retrieved directly (for publicly accessible URLs) or is secured via the SSP. Where a record is to be secured via the SSP, in a response to a search or read interaction the NRL will pre-fix the Pointer URL property with the proxy server URL as follows:

https://[proxy_server]/[record_url]

Interaction ID

The SSP requires an interaction ID for retrieval of records, which Consumers are required to include in the SSP-InteractionID HTTP header as part of the HTTP request.

The interaction ID is specific to the format of the record. The association between format codes and interaction IDs are detailed in the table below:

Format code Interaction ID
direct:https://www.w3.org/TR/html/ Not applicable (direct retrieval)
direct:https://www.iso.org/standard/63534.html Not applicable (direct retrieval)
proxy:https://www.iso.org/standard/63534.html urn:nhs:names:services:nrls:binary.read

Endpoints for retrieval will need to be registered under the associated interaction ID on Spine Directory Services (SDS). For further details on registering endpoints, see Provider Retrieval Guidance.


All content is available under the Open Government Licence v3.0, except where otherwise stated