Supported CRUD capability

Create

The main create operations will be creation of the initial test request and associated clinical information; creation of interim data (either binary files or structured FHIR resources attached to Task.output; and creation of the resulting DiagnosticReport resources. Creation of ServiceRequest and DiagnosticReport resources will trigger the associated processes to kick-off or close down a test order fulfilment workflow.

On create/POST, clients are allowed to not supply an 'id' within the resource, as per the FHIR spec. Any ids provided will be replaced by the central broker.

Common Interaction Patterns

Read

From initial design work, it is expected the main use case will be labs and requesting systems polling the central service for test orders and reports, including associated clinical information, as well as polling the system for the current state of Tasks and Task update history, through associated AuditEvents and Provenance resources.

Retrieval of sets of resources using GraphDefinitions are also planned. The complete set of resources/operations supported are listed within the Instance page. All resources are expected to be compliant with UK Core FHIR R4.

Search

Supported Functionality

• The search parameters to be supported by the Genomic Order Management system are defined within the Instance page. Custom search parameters defined within SearchParameters will also be supported, such as a search parameter for supporting retrieval of supporting-info on ServiceRequests.

• Multiple _include/_revinclude parameters will be supported within a single URL search string. The :iterate modifier will also be supported to enable traversal of multiple levels of references in searches e.g. GET [base]/MedicationDispense?_include=Medication:prescription&_include:iterate=MedicationRequest:requester&criteria....

• The _history and _lastUpdated parameters will be supported as part of history and audit provenance needs. The _history parameter will only be supported on instance level reads, i.e. history will not be retrievable at the resource type or base levels.

• Token type searching for coded values based on system and/or code e.g. http://snomed.info/sct%7C3738000 will be supported, to enable unambiguous searching of codes.

• Date and number based prefixes, such as eq, gr, lt will be supported, to enable retrieval of resources based on date/time and quantity ranges.

• Chaining, e.g. ServiceRequest?subject:Patient.name will be supported to aid building of complex search criteria.

• Search result modifiers such as _count, _total and _sort will be supported to allow clients to tailor search results.

• The :not operator will be supported to allow organizations visibility of tests outside their region, e.g. for home GLHs which want to see tests from within their patch routed to labs outside their region. An example of the query to support this would be:

GET [base]/ServiceRequest?requester:PractitionerRole.organization={ODS_codes_in_my_patch}&performer:not={my_GLH_code}

• The :identifier modifier will be supported on SearchParameters of type reference, where identifiers are used within the referencing resource, in preference over inclusion of full resources, e.g. references using practitioner or organization identifiers, as the resources containing the relevant information logically sit within other NHS England services, e.g. SPINE SDS or ODS respectively.

• The _has parameter, used for Reverse Chaining MAY be supported to retrieve resources based on the properties of resources that refer to them, e.g. GET [base]/Patient?_has:Observation:patient:code={SNOMED_Code}, though this is pending investigation of the functionality supported by the Genomic Order Management core broker.

Unsupported Functionality

• Inclusion of external references (resources not hosted on the server) through the _include parameter will not be supported as there will be no guarantee they resolve or that they will return valid FHIR. While this may mean clients will need to perform multiple calls to construct a complete set of data, this ensures consistency of the responses from the broker. Within this Implementation Guide we expect a test requester to submit all relevant information for a test order to the broker so there should be very few instances where an external reference is used.

• No use cases requiring use of _query or $operation type searches have been elaborated so these are not planned to be supported as of the time of publication. Equally, usage of tags to encode data, and use of the _tag parameter will not be supported until use cases detailing their need are elaborated.

• Search modifiers such as :contains, :missing, :not-in, etc. will not be supported as there are currently no use cases for supporting text-based/fuzzy searching.

Common Patterns

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

Delete

It is not expected that delete operations will be supported by the central service for workflow based resources, e.g. if a service request or task was created in error. Cancellations or marking resources as entered in error SHOULD be represented using the associated status on the resources rather than deleting them from the central service to ensure changes to data are auditable. However, if a clinical resource is no longer relevant, this may require a delete. Though additional logic will need to be added to the central service to ensure referential integrity and notifications if deletes constitute material changes affecting the processing of a test request. The Information Governance implications of limiting deletion of resources will be investigated within the Alpha phase of the project.