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.

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

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.