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.
DocumentReference generate
This operation is a customization of the R5 generate operation for DocumentReference.
It will take in a URL (either DRS or presigned URL) for a Genomic Data file, optionally pulls the file into a common data store, generates a DRS URL if this has not already been assigned, and creates a DocumentReference resource to hold the URL and associated metadata.
The selected input parameters as well as specific profiles for input or output parameters, e.g. for certain data file types, are pending further investigation by GEL, as such, this OperationDefinition SHOULD be considered for illustrative purposes only.
Invocations
URL: [base]/DocumentReference/$genomics-generate
This operation changes content
Parameters (In)
| Name | Cardinality | Type | Documentation |
| url | 1..1 | uri | The URL to the source document. This may be a general URL or a Binary or a Composition or a Bundle. For a Genomic Data File, MUST be either a DRS URL or a presigned URL. |
| persist | 0..1 | boolean | Whether to store the document at the document end-point (/Document) or not, once it is generated (default is for the server to decide). For a Genomic Data File, determines whether the data file will be pulled to a central data store, or will remain on the source server. In all cases, the DocumentReference will be generated and stored on the server at the /DocumentReference endpoint. |
| content-type | 1..1 | string | MIME type for the file. Used to determine how the reference should be processed and which context references are required. |
| context-reference | 0..* | Reference(UKCoreServiceRequest | UKCoreSpecimen) | Reference to FHIR resource which provide context for the DocumentReference e.g. ServiceRequest which initiated the collection of the data file, or the Specimen from which it originated. |
| author | 1..1 | Identifier | ODS code for the author organization. |
Return Values (Out)
| Name | Cardinality | Type | Documentation |
| return | 1..1 | Bundle | The bundle type is "searchset" containing DocumentReference resource and may include a Binary. If the input url refers to another server, it is at the discretion of the server whether to retrieve it or return an error. |
An example of the Parameters needed to invoke the Operation are provided at Parameters-Generate-Example
The resulting output would be a SearchSet Bundle containing the created DocumentReference, if successful, an example of a DocumentReference for a Genomic Data file can be found at DocumentReference-PharmCAT-Example.
Failure will result in an OperationOutcome detailing the reasons for failure, e.g. missing required parameters, unable to access data file, etc. The full list of possible error scenarios is pending further investigation.