Notice
- Important: This guidance is under active development by NHS England and content may be added or updated on a regular basis.
- This Implementation Guide is currently in Draft and SHOULD NOT be used for development or active implementation without express direction from the NHS England Genomics Unit.
Composition document
As a consequence of supporting RESTful update operations on resources within the central broker, some information, such as patient history may change over time. This poses a problem when interrogating past 'documents', or resources such as ServiceRequests or DiagnosticReports, as the information contained within them, or the references to other resources, may change after a test request has been closed.
To maintain the accuracy of historic information, such as the observations a genomic report was based on, it may be necessary to create an immutable snapshot of the resources related to a ServiceRequest or DiagnosticReport after closure of a request.
To support this, the central broker can create Document Bundles using the $document operation on Composition. The Compositions would need to be generated on closure of a ServiceRequest (e.g. a ServiceRequest being marked as 'completed' or 'revoked', or a DiagnosticReport marked as 'final', 'amended', 'corrected' or 'appended') to capture the final IDs for the ServiceRequest and DiagnosticReport.
Upon generation of the Composition, the central broker can call the $document operation on the Composition resource, using the appropriate GraphDefinitions to follow the required resource references and generate a Bundle of type 'document' containing all the resources forming the order or result:
GET [base]/Composition/[id]/$document?persist=true&graph=genomics-test-result
This Bundle could then be stored/accessible via the Bundle endpoint as an immutable snapshot of the order/result at that point in time, regardless of whether any changes were made to those resources after generation:
GET [base]/Bundle/[id]
or searched via:
GET [base]/Bundle?composition.entry:DiagnosticReport=[id]
GET [base]/Bundle?composition.entry:ServiceRequest=[id]
The sequence diagram for the proposed process is given below:
$document for UGR
The Unified Genomic Record will also use Composition resources to structure the UGR. It is expected that additional information added to a UGR will be reflected in new versions of the Composition resource.
To retrieve the UGR, clients can either retrive the composition alone, and follow references to resources they want to retrieve, or they can use the $document operation to generate the full UGR, importing all the referenced resources into a Document Bundle.
It is expected that Document bundles will not be persisted (parameter persist=false), to ensure the latest version of a UGR is retrieved. The amount of recursion when generating the document bundle is still under discussion, e.g. will resources referenced from DiagnosticReports, which are referenced from the Composition, also be included in the Document Bundle by default? This may require generation of additional GraphDefinitions to ensure the resulting Bundle does not become too large or difficult to assemble.
The expected sequence for retrieval of a UGR Document is represented below:
