To support the creation of NRL pointers.

References

Create

Provider interaction to support the creation of NRL pointers. The create interaction is a FHIR RESTful create interaction.

Prerequisites

In addition to the requirements on this page, the general guidance and requirements detailed on the Development Overview page MUST be followed when using this interaction.

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, if set, this must be either application/fhir+json or application/fhir+xml. OPTIONAL
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see the JSON Web Token Guidance page for details. REQUIRED
fromASID Client System ASID. REQUIRED
toASID The Spine ASID. REQUIRED

Create Operation

Provider systems MUST:

  • construct and send a new pointer (DocumentReference) resource that conforms to the NRL-DocumentReference-1 profile and submit this to the NRL using the FHIR RESTful create interaction.
  • include all of the mandatory data-elements contained in the NRL-DocumentReference-1 profile when constructing a DocumentReference. The mandatory data-elements are detailed on the Developer FHIR Resource page.
  • follow all population guidance as outlined on the Developer FHIR Resource page when constructing a DocumentReference.
  • only create pointers for records where they are the pointer owner (custodian).

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

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" />
    </coding>
  </type>
  <class>
    <coding>
      <system value="http://snomed.info/sct" />
      <code value="734163000" />
      <display value="Care plan" />
    </coding>
  </class>
  <subject>
    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210" />
  </subject>
  <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://p1.nhs.uk/MentalhealthCrisisPlanReport.pdf" />
      <creation value="2016-03-08T15:26:00+01:00" />
    </attachment>
    <format>
      <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1" />
      <code value="urn:nhs-ic:unstructured" />
      <display value="Unstructured Document" />
    </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="708168004" />
        <display value="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"
      }
    ]
  },
  "class": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "734163000",
        "display": "Care plan"
      }
    ]
  },
  "subject": {
    "reference": "https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"
  },
  "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://p1.nhs.uk/MentalhealthCrisisPlanReport.pdf",
        "creation": "2016-03-08T15:26:00+01:00"
      },
      "format": {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1",
        "code": "urn:nhs-ic:unstructured",
        "display": "Unstructured Document"
      },
      "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": "708168004",
          "display": "Mental health service"
        }
      ]
    }
  }
}

Create Response

Success

A successful execution of the create interaction will return:

  • a 201 CREATED HTTP status code confirming the entry has been successfully created in the NRL.
  • a response body containing an OperationOutcome resource (see below for full details).
  • 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 will 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.

OperationOutcome

The OperationOutcome resource in the response body will conform to the ‘Spine-OperationOutcome-1’ FHIR resource:

Element Content
id A UUID for this OperationOutcome.
meta.profile Fixed value: https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1
issue.severity Fixed value: information
issue.code Fixed value: informational
issue.details.coding.system Fixed value: https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1
issue.details.coding.code Fixed value: RESOURCE_CREATED
issue.details.coding.display Fixed value: New resource created
issue.details.text A Spine internal message UUID which can be used to identify the client’s create transaction within Spine. A client system SHOULD reference this UUID in any related incidents raised with the National Service Desk. The UUID will be used to retrieve log entries that relate to a specific client transaction.
issue.diagnostics Fixed value: Successfully created resource DocumentReference

Example success response body (XML)

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="ca613912-e0fe-4ad3-a5b2-378a2f2824c3-00000000000000000000" />
  <meta>
    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1" />
  </meta>
  <issue>
    <severity value="information" />
    <code value="informational" />
    <details>
      <coding>
        <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1" />
        <code value="RESOURCE_CREATED" />
        <display value="New resource created" />
      </coding>
      <text value="3de126fa-b5f5-4783-b67f-30c02b865016" />
    </details>
    <diagnostics value="Successfully created resource DocumentReference" />
  </issue>
</OperationOutcome>

Example success response body (JSON)

{
  "resourceType": "OperationOutcome",
  "id": "ca613912-e0fe-4ad3-a5b2-378a2f2824c3-00000000000000000000",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1"
    ]
  },
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1",
            "code": "RESOURCE_CREATED",
            "display": "New resource created"
          }
        ],
        "text": "3de126fa-b5f5-4783-b67f-30c02b865016"
      },
      "diagnostics": "Successfully created resource DocumentReference"
    }
  ]
}

Failure

The following errors can be triggered when performing this operation:

Explore the NRL

You can explore and test the create interaction using Swagger in the NRL API Reference Implementation.