API Supersede Interaction

To support the superseding of NRL pointers.

References

NHS Digital Profile:
NRL-DocumentReference-1

HL7 FHIR STU3 Resource(s):
DocumentReference

User Stories:
-

Create (Supersede)

Provider interaction to support superseding NRL pointers. Create with Supersede (abbreviated to Supersede) is an extension of the Create Interaction. The Supersede functionality will be used in cases where a provider wishes to replace one DocumentReference with another, newer one.

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.

Supersede Request Headers

Provider API supersede 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

Supersede Operation

The NRL API does not allow a traditional Update operation (the HTTP PUT verb is not supported). Instead, a pointer can be replaced by superseding it with a newer version that contains the updated attributes.

A provider transitions an existing pointer’s status from current to superseded as part of the act of creating its replacement. The create action allows specifying an existing DocumentReference to be superseded. The process is as follows:

The provider assembles a new DocumentReference resource.
The provider populates the relatesTo property with a new target element which holds:
- A reference that is the logical identifier of the existing DocumentReference or an identifier that is the master identifier of the existing DocumentReference.
- The action code replaces.
The provider POSTs the DocumentReference resource.
The NRL will transactionally:
1. Create the new DocumentReference, marking it as current.
2. Resolve the existing DocumentReference using relatesTo.target.
3. Mark the original DocumentReference as superseded and increment its versionId by 1.
4. Set the version number of the newly-created DocumentReference to 1.

Provider systems MUST only supersede pointers for records where they are the pointer owner (custodian).

The target property within the relatesTo attribute must be either a reference or a FHIR identifier, depending on whether a provider chooses to supersede by logical ID or master identifier.

Note: NRL supports the ability to update a pointer’s status from "current" to "entered-in-error" using the HTTP PATCH verb. For more details, see the Update Interaction page.

Supersede by Logical ID

To supersede by logical ID, the relatesTo.target attribute on the DocumentReference should be a FHIR reference property i.e. an absolute literal reference to a DocumentReference held within NRL.

Example of a DocumentReference.relatesTo property populated using a FHIR reference.

{
  "relatesTo": [
    {
      "code": "replaces",
      "target": {
        "reference": "https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"
      }
    }
  ]
}

Supersede by Master Identifier

To supersede by master identifier, the relatesTo.target attribute on the DocumentReference should be a FHIR identifier. The identifier is interpreted as the masterIdentifier of a DocumentReference held within the NRL.

Example of a DocumentReference.relatesTo property populated using a FHIR identifier.

{
  "relatesTo": [
    {
      "code": "replaces",
      "target": {
        "identifier": {
          "system": "urn:ietf:rfc:3986",
          "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.6"
        }
      }
    }
  ]
}

In both cases, the patient NHS Number on the new (to be created) DocumentReference and the DocumentReference being superseded must match.

If both target.reference and target.identifier properties are populated then the NRL will use the target.reference property to resolve the DocumentReference. If a DocumentReference is found, then the master identifier of the returned DocumentReference must match the identifier in the relatesTo collection.

The NRL will only accept one relatesTo element. Requests that contain multiple relatesTo elements will be rejected.

Supersede by Logical ID XML Example

An XML example of a DocumentReference resource that supersedes an existing DocumentReference by logical ID.

Please note the addition of the relatesTo property within the DocumentReference example below:

<DocumentReference>
  <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>
  <relatesTo>
    <code value="replaces" />
    <target>
      <reference value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261" />
    </target>
  </relatesTo>
  <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>

Supersede by Logical ID JSON Example

A JSON example of a DocumentReference resource that supersedes an existing DocumentReference by logical ID.

Please note the addition of the relatesTo property within the DocumentReference example below:

{
  "resourceType": "DocumentReference",
  "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:00+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"
            }
          ]
        }
      }
    }
  ],
  "relatesTo": [
    {
      "code": "replaces",
      "target": {
        "reference": "https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"
      }
    }
  ],
  "context": {
    "period": {
      "start": "2016-03-07T13:34:00+01:00"
    },
    "practiceSetting": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "708168004",
          "display": "Mental health service"
        }
      ]
    }
  }
}

Supersede by Master Identifier XML Example

An XML example of a DocumentReference resource that supersedes an existing DocumentReference by master identifier.

Please note the addition of the relatesTo property within the DocumentReference example below:

<DocumentReference>
  <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" />
    </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>
  <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://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>

Supersede by Master Identifier JSON Example

A JSON example of a DocumentReference resource that supersedes an existing DocumentReference by master identifier.

Please note the addition of the relatesTo property within the DocumentReference example below:

{
  "resourceType": "DocumentReference",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"
    ]
  },
  "masterIdentifier": {
    "system": "urn:ietf:rfc:3986",
    "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.7"
  },
  "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:00+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"
            }
          ]
        }
      }
    }
  ],
  "relatesTo": [
    {
      "code": "replaces",
      "target": {
        "identifier": {
          "system": "urn:ietf:rfc:3986",
          "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.6"
        }
      }
    }
  ],
  "context": {
    "period": {
      "start": "2016-03-07T13:34:00+01:00"
    },
    "practiceSetting": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "708168004",
          "display": "Mental health service"
        }
      ]
    }
  }
}

Response

As an extension of the Create interaction, the success and failure responses are the same for Supersede as they are for Create. See Create Interaction - Responses for details of the expected response behaviours and codes.

Explore the NRL

You can explore and test the Create (Supersede) interaction using Swagger in the NRL API Reference Implementation.

Tags: