Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Create Interaction

To support the creation of NRL pointers

References

Create

API to support the creation of NRL pointers. This functionality is only available for providers.

Create Request Headers

Provider API create requests support the following HTTP request headers:

Header Value Conformance
Accept The Accept header indicates the format of the response the client is able to understand, this will be one of the following application/fhir+json or application/fhir+xml. See the RESTful API Content types section. MAY
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens (JWT) for details. MUST
fromASID Client System ASID MUST
toASID The Spine ASID MUST

Create Operation

Provider system will construct a new Pointer (DocumentReference) and submit this to NRL using the FHIR RESTful create interaction.

Providers systems SHALL only create pointers for records where they are the pointer owner (custodian).

For all create requests the custodian ODS code in the DocumentReference resource SHALL be affiliated with the Client System ASID value in the fromASID HTTP request header sent to the NRL.

In addition to the base mandatory data-elements, the following data-elements are also mandatory:

  • The type data-element MUST be included in the payload request.

XML Example of a new DocumentReference resource (pointer)

<DocumentReference
    xmlns="http://hl7.org/fhir">
    <id value="c037a0cb-0c77-4976-83a1-a5d2703e6aa3-23325861873450086113"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
    </meta>
    <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>
    <content>
        <attachment>
            <contentType value="application/pdf"/>
            <url value="https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalHealthCrisisPlanReport.pdf"/>
            <title value="Mental health Crisis Plan Report"/>
            <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>
    <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>

JSON Example of a new DocumentReference resource (pointer)

{
  "resourceType": "DocumentReference",
  "id": "c037a0cb-0c77-4976-83a1-a5d2703e6aa3-23325861873450086113",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"
    ]
  },
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "736253002",
        "display": "Mental health crisis plan (record artifact)"
      }
    ]
  },
  "class": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "734163000",
        "display": "Care plan (record artifact)"
      }
    ]
  },
  "subject": {
    "reference": "https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"
  },
  "created": "2016-03-08T15:26:00+01:00",
  "indexed": "2016-03-08T15:26:01+01:00",
  "author": [
    {
      "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/RGD"
    }
  ],
  "custodian": {
    "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/RR8"
  },
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "url": "https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalhealthCrisisPlanReport.pdf",
        "title": "Mental health Crisis Plan Report",
        "creation": "2016-03-08T15:26:00+01:00"
      },
      "format": {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1",
        "code": "direct:https://www.iso.org/standard/63534.html",
        "display": "PDF (Publicly accessible)"
      },
      "extension": [
        {
          "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1",
                "code": "static",
                "display": "Static"
              }
            ]
          }
        }
      ]
    }
  ],
  "context": {
    "period": {
      "start": "2016-03-07T13:34:00+01:00"
    },
    "practiceSetting": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "892811000000109",
          "display": "Adult mental health service"
        }
      ]
    }
  }
}

Create Response

Success:

  • SHALL return a 201 CREATED HTTP status code on successful execution of the interaction and the entry has been successfully created in the NRL.
  • SHALL return a response body containing a payload with an OperationOutcome resource that conforms to the ‘Operation Outcome’ core FHIR resource. See table below.
  • SHALL return an HTTP Location response header containing the full resolvable URL to the newly created ‘single’ DocumentReference.
    • The URL will contain the ‘server’ assigned logical Id of the new DocumentReference resource.
    • The URL format MUST be: https://[host]/[path]/[id].
    • An example Location response header:
      • https://psis-sync.national.ncrs.nhs.uk/DocumentReference/297c3492-3b78-11e8-b333-6c3be5a609f5-54477876544511209789
  • When a resource has been created it will have a versionId of 1.

The table summarises the create interaction HTTP response code and the values expected to be conveyed in the successful response body OperationOutcome payload:

HTTP Code issue-severity issue-type Details.Code Details.Display Details.Text Diagnostics
201 information informational RESOURCE_CREATED New resource created Spine message UUID Successfully created resource DocumentReference

Failure:

The following errors can be triggered when performing this operation:

Ensuring that masterIdentifier is unique

The masterIdentifier should be unique within the NRL. For more information see the discussion on Pointer identifiers. The masterIdentifer is a FHIR identifier and for NRL the system and value properties are mandatory.

The system defines how the value is made unique. As the FHIR specification says this might be a recognised standard that describes how this uniqueness is generated.

The NRL recommends the use of either an OID or a UUID as an Identifier in keeping with the need for the masterIdentifier value to be unique. In this case then the system SHALL be “urn:ietf:rfc:3986” (see the FHIR identifier registry for details) and the value is of the form –

• OID - urn:oid:[oidValue]
• UUID - urn:uuid:[uuidValue]

See the example OID and UUID based Identifiers from the FHIR specification.

Code Examples

POST a Pointer with C#

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

First we generate a base pointer request model that includes the custodian and author details, and the specific care plan attachment details that are later used to build our pointer (DocumentReference). These pointer values are taken from the demo crisis plan that is created for the Demonstrator Provider system.

Then we call our DocumentReference service GenerateAndCreatePointer method which will generate our pointer (DocumentReference) using the values stored in the model, build a POST command request and then start the call to the NRL API.

Demonstrator/Demonstrator.Services/Service/Epr/CrisisPlanService.cs#L125-L128 view raw
var pointerRequest = NrlsPointerRequest.Create(crisisPlan.OrgCode, crisisPlan.OrgCode, crisisPlan.PatientNhsNumber, $"https://spine-proxy.national.ncrs.nhs.uk/{newCrisisPlan.Id}/mental-health-care-plan.pdf", "application/pdf", MentalHealthCrisisPlanTypeCode, MentalHealthCrisisPlanTypeDisplay, crisisPlan.Asid);

//Create new NRLS pointer
var newPointer = await _documentReferenceServices.GenerateAndCreatePointer(pointerRequest);


Within the DocumentReference service GenerateAndCreatePointer method we generate our pointer model and then serialise this generated model ready for posting:

Demonstrator/Demonstrator.NRLSAdapter/DocumentReferences/DocumentReferenceServices.cs#L53-L54 view raw
{
    var pointerJson = new FhirJsonSerializer().SerializeToString(pointer);


Calling the NRL
Using our POST command request model we create a connection to the NRL using HttpClient.

You can view the common connection code example here.

Explore the NRL
You can explore and test the NRL POST command using Swagger in our Reference implementation.


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