Update

A large part of the interactions with the central service, over the course of order fulfilment, will be updates to Task resources, which constitute status updates. These events will be captured by the central broker through AuditEvent resources. Additionally, ServiceRequest and DiagnosticReport resources may be updated if tests need to be changed or new data added. Reasons for changed SHOULD be captured through Provenance resources. The impact these updates have on work-in-progress will be defined within Business Rules on the central broker (including how cancellations are managed).

Updates to Requests and Reports

The Genomic Order Management Service will support updates to requests and reports as well as resources referenced from the focal ServiceRequest and DiagnosticReport.

To support clear identification of superseded items, e.g. Observations, older resources SHALL have their status updated alongside an update to indicate either that they have been ammended/corrected since a prior version, or that the resource itself has been superseded or entered-in-error, if the resource itslef is no longer valid. If entered in error, a new resource MAY be created as a replacement. The new resource SHOULD reference the prior either using a dedicated relatesTo field or via a 'replaces' extension, where this has been defined in core R4, e.g. for DocumentReference use DocumentReference.relatesTo, for Observation use the observation-replaces extension.

Focal resources, which reference changed resources, such as the ServiceRequest and DiagnosticReport, SHALL also be updated with new references and new statuses, where applicable, to indicate underlying data has changed. To support updates to ServiceRequests where references to resources have not changed (and so there is no substantive update to the ServiceRequest resource itself), a ServiceRequest.note SHALL be added, detailing the change that has occurred, this will then trigger subsequent events notifying subscribers of the change. The NHS England Genomics Unit are currently investigating the types of changes to be allowed when updating requests, including at what point requests can no longer be ammended, and what the lab standard operating procedures are for when a change occurs for a test which is already in progress. This MAY mean in certain circumstances, updates to requests SHOULD be submitted as new requests replacing prior ones, rather than be allowed as updates to an in-flight request.

Provenance resources SHALL be submitted alongside changed DiagnosticReport and ServiceRequest resources to detail the context under which a change has been made, but MAY also be submitted alongside changes to lower level clinical resources, e.g. Observations, to align with Acknowledgement Framework Errors and Ammendments Guidance. Updates to orders in draft status do not require associated Provenance resources as these are expected to change frequently prior to being marked as active.

If using a Document based approach, i.e. using Composition alongside DiagnosticReport. The Composition SHALL be updated in response to resource changes: updating changed references; updating the composition status; and incrementing the Composition version number. Provenance resources MAY also be referenced from within the Composition to allow a single point of reference for changes to content.

Conditional Update

The conditional update interaction allows a client to update an existing resource based on some identification criteria, rather than by logical id. To accomplish this, the client issues a PUT with additional parameters to identify the resource to be updated, e.g. by identifier.

Within the Alpha for Order Management, conditional updates will not be supported, i.e. it is expected that all updates will be submitted against a logical id. However, support for conditional updates will be investigated post-Alpha based on demand and use cases from users.

Resource contention

To avoid 'Lost Updates', where two clients update the same resource, and the second overwrites the updates of the first, the If-Match header will be used. As per the FHIR HTTP pages, servers SHOULD return an ETag header, matching the version id assigned by the server for the resource, when returning a resource (though the version id can be used directly).

Clients then SHOULD request a version aware update, when submitting PUTs by including an If-Match header that quotes the version id from the server:

PUT /Patient/347 HTTP/1.1
If-Match: W/"23"

If the version id given in the If-Match header does not match, the server SHOULD return a 412 Precondition Failed status code instead of updating the resource.

Servers can require that clients provide an If-Match header by returning 400 Client Error status codes when no If-Match header is found. Implementation of version specific updates for Genomic Order Management is pending development within the Alpha

To support If-Match within Transaction Bundles, the Bundle.entry.request.ifMatch element SHOULD be used:

"request": {
  "method": "PUT",
  "url": "Patient/347",
  "ifMatch": "W/\"23\""
}

Patch

As an alternative to updating an entire resource, some FHIR servers allow clients to perform a patch operation. This is useful for cases where only small changes are required to resources such as adding local identifiers. The patch interaction is performed by an HTTP PATCH command as shown:

PATCH [base]/[type]/[id] {?_format=[mime-type]}

The body of a PATCH operation SHALL be either:

a JSON Patch document with a content type of application/json-patch+json an XML Patch document with a content type of application/xml-patch+xml a FHIRPath Patch parameters resource with FHIR Content Type

Implementation of the PATCH operation for Genomic Order Management will not be supported within the Alpha

Common Patterns