References
NHS Digital Profile: DocumentReference |
HL7 FHIR STU3 Resource: 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.
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.
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, 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 |
Supersede Operation
The NRL API does not allow a true update i.e. the HTTP PUT verb is not supported. A pointer can be replaced by superseding it with a newer pointer 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. In effect the POSTing of a new DocumentReference provides a means to specify an existing DocumentReference whose status should be moved to superseded. Concretely this is achieved as follows:
- Provider assembles a new DocumentReference resource
- 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 masterIdentifier of the existing DocumentReference
- the action code “replaces”
- Provider POSTs the DocumentReference resource
- NRL will transactionally -
- create the new DocumentReference marking it as current
- resolve the existing DocumentReference using the relatesTo.target
- mark that DocumentReference as superseded
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 supersede by master identifier.
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. The value should be a URL in the form of read by logical ID.
Example of a DocumentReference relatesTo property populated using a FHIR reference.
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 NRL.
Example of a DocumentReference relatesTo property populated using a FHIR identifier.
In both cases (use of reference or identifier values) the patient NHS Number on the new (to be created) DocumentReference and the DocumentReference being superseded must match. For more details, see Error Handling Guidance.
If both the target.reference property and the target.identifier property are populated then the NRL will use the target.reference property to resolve the DocumentReference. If a DocumentReference is found, then the MasterIdentifier of the returned DocumentReference must match the identifier in the relatesTo collection. For more details, see Error Handling Guidance.
The NRL will only accept one relatesTo element. Requests that contain multiple relatesTo elements will be rejected. For more details, see Error Handling Guidance.
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.
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.
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.
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.
Response
Success and Failure:
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.
Code Examples
When either Creating or Superseding a Pointer, the same HTTP POST verb is used.
See Create Interaction - Code Examples for an example of POSTing a pointer.