API Create Interaction

To support the creation of NRL pointers

Important: This site is under active development by NHS Digital and is intended to provide all the technical resources you need to successfully develop APIs. This project is being developed using an agile methodology, so iterative updates to content will be added on a regular basis.

Warning: This site is provided for information only and is intended for those engaged with NHS Digital on the development of APIs. It is advised not to develop against these specifications until a formal announcement has been made.

References

NHS Digital Profile:
DocumentReference

HL7 FHIR STU3 Resource:
DocumentReference

User Stories:
-

Create

Provider interaction to support the creation of NRL pointers.

Pre-requisites

In addition to the requirements on this page the general guidance and requirements detailed on the Development Guidance 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, this will be one of the following `application/fhir+json` or `application/fhir+xml`. See the RESTful API Content types section.	OPTIONAL
`Authorization`	The `Authorization` header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens (JWT) for details.	REQUIRED
`fromASID`	Client System ASID	REQUIRED
`toASID`	The Spine ASID	REQUIRED

Create Operation

POST [baseUrl]/DocumentReference

Provider systems:

MUST construct and send a new Pointer (DocumentReference) resource that conforms to the NRL-DocumentReference-1 profile and submit this to NRL using the FHIR RESTful create interaction.
MUST include the URI of the NRL-DocumentReference-1 profile StructureDefinition in the DocumentReference.meta.profile element of the DocumentReference resource.
MUST 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.
MUST supply subject, custodian and author attributes as absolute literal references, the formats of which can be found on the Developer FHIR Resource page.
MUST only create pointers for records where they are the pointer owner (custodian).

For all create requests the custodian ODS code in the DocumentReference resource 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://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.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://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.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:

MUST return a 201 CREATED HTTP status code on successful execution of the interaction and the entry has been successfully created in the NRL.
MUST return a response body containing a payload with an OperationOutcome resource that conforms to the ‘Operation Outcome’ core FHIR resource. See the following table.
MUST 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.

Note: The versionId is an integer that is assigned and maintained by the NRL server. When a new DocumentReference is created the server assigns it a versionId of 1. The versionId will be incremeted during an update or supersede transaction. See API Interaction - Update and API Interaction - Supersede for more details on these transactions.

The NRL server will ignore any versionId value sent by a client in a create interaction. Instead the server will ensure that the newly assigned verionId adheres to the rules laid out above.

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

Note: Upon successful creation of a pointer the NRL Service returns in the reponse payload an OperationOutcome resource with the OperationOutcome.issue.details.text element populated with a Spine internal message UUID. This UUID is used to identify the client’s Create transaction within Spine. A client system SHOULD reference the UUID in any calls raised with the Deployment Issues Resolution Team. The UUID will be used to retrieve log entries that relate to a specific client transaction.

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 MUST 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.

This Github Sample is by nhsconnect

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:

This Github Sample is by nhsconnect

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 the NRL API Reference Implementation.

Note: The code in these examples is standard C# v7.2 taken directly from the NRL Demonstrator code.

The official .NET FHIR Library is utilised to construct, test, parse, and serialize FHIR models with ease.

Tags:

API Hub

Explore and Make use of Nationally Defined Messaging APIs