Standard Pattern - DocumentReference
This Section of the Implementation Guide is currently a preview, in an Alpha state and subject to change.
Introduction
In version 1.1.0 of the BaRS API Specification, functionality was added to accommodate the use of pointers (DocumentReference resources), to locate existing bookings and referrals.
The FHIR DocumentReference resource allows you to reference and locate clinical documents or resources. This section will walk you through the process of using a FHIR DocumentReference to find a resource's location and retrieve it.
The BaRS API acts as a gateway to the National Record Locator FHIR API for BaRS enabled Services. In the image below the BaRS API is interacted with by Consumers and Producers.
- Consumer - Queries the API for existing DocumentReferences for use in finding existing Bookings and Referrals. This is usually a BaRS Sender.
- Producer - Posts and maintains DocumentReferences for Bookings and Referrals that they have received. This is invariably the BaRS Receiver.
DocumentReferences for Senders
Step 1: Understand the Document Reference Resource
The Document Reference resource in FHIR represents a reference to a clinical document or resource. It contains metadata about the document, such as its type, author, and creation date, subject (the patients NHS number), as well as a reference to the actual document's location (URL) and markers for how the method needed to retrieve it.
Step 2: Search for the Document Reference
To find a resource's location, you need to search for the appropriate DocumentReference resource. The most common way to search for Document References is by using search parameters.
For example, if you are looking for a DocumentReference that represents a referral, you could use the following search query, where a snomed code is used to define the type of the document:
GET [base-URL]/DocumentReference?type=https://snomed.info/ict|736253002
The Booking and Referrals API v1.1.0 specification has more information on search parameters available.
Step 3: Inspect the Document Reference
Once you retrieve the Document Reference(s) from the search, inspect the returned resources to identify the one you need. Look for relevant metadata like the document type, author, creation date or format to confirm it is the correct resource.
identifier: The DocumentReference will have an identifier stating the id of the resource.
"identifier": [
{
"system": "https://fhir.nhs.uk/Id/BaRS-Identifier",
"value": "8c63d621-4d86-4f57-8699-e8e22d49935d"
}
type: Below you can see the type, within the DocumentReference Resource. Within BaRS there is currently only bookings (749001000000101) and Referrals (736253002), described using SNOMED codes.
"type": { "coding": [ { "system": "https://snomed.info/ict", "code": "736253002" } ] }
subject: The subject will describe the patient, by means of an NHS number.
"subject": { "identifier": { "system": "https://fhir.nhs.uk/Id/nhs-number", "value": "9556274839" }
custodian: The custodian element will describe the organization that owns the resource data. This will be a concatenation of ODS codes.
"custodian": { "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "A1001" } }
Step 4: Retrieve the Resource's Location
Access the content element of the Document Reference. This element contains the reference to the location of the actual resource. The content element is typically an array, as a Document Reference can reference multiple versions or representations of the same document. Each item in the array will have a URL element, which specifies the location of the resource.
The content.attachment.URL element in this example is a URL friendly Target Identifier, of which can be used to retrieve the resource. This element can also contain a direct URL if appropriate. The content.format element will contain the coding that describes the format of the resource in question. In this instance this is a BaRS message event of "servicerequest-request".
"content": [ { "attachment": { "language": "en-UK", "URL": "http://fhir.nhs.uk/Id/dos-service-id|111111111", "title": "Physical", "creation": "2005-12-24T09:35:00+11:00" }, "format": [ { "coding": [ { "system": "https://fhir.nhs.uk/CodeSystem/message-events-bars", "code": "servicerequest-request" } ] } ] } ]
Step 5: Retrieve the Resource
Retrieve the resource by making a GET request to the URL specified in the URL element of the Document Reference's content. Ensure that you have the necessary authorization and access privileges to retrieve the resource.
For BaRS, a GET of the relevant resource type using the Target Identifiers. In this simplified example the URL above containing a TargetIdentifier is used in the NHSD-Target-Identifier header to instruct the BaRS proxy to route to the request to that target note: The header is not base64Encoded in this example:
Also, if the content element has a direct URL, this can be obtained using a direct GET request.
Step 6: Handle the Retrieved Resource
Once you have retrieved the resource, you can process it according to your requirements. The format and structure of the resource will depend on the specific resource type, such as Patient or ServiceRequest. Refer to the FHIR documentation or resource-specific or application-specific guides for further information on handling the retrieved resource.
Note: It's important to consider the security and privacy aspects when working with clinical documents and resources. Ensure that you adhere to applicable regulations and best practices to protect patient data.
DocumentReferences for Receivers
Creating a DocumentReference.
The FHIR DocumentReference resource allows you to create a reference to a clinical document or resource. This section describes the process of creating a FHIR DocumentReference for a resource. A DocumentReference will be created when a Receiver accepts a Booking or a Referral. Each request will warrant a distinct Document Reference.
Step 1: Understand the Document Reference Resource
The Document Reference resource in FHIR represents a reference to a clinical document or resource. It contains metadata about the document, such as its type, author, and creation date, along with a reference to the actual document's location. Within BaRS the DocumentReference acts as a pointer towards ServiceRequests, or Appointment resources.
Step 2: Identify the Resource to Reference
Determine the resource that you want to create a Document Reference for. This will be any ServiceRequest or Appointment Resource that has been created in the Receiver system by means of a booking request or a service request.
The resources themselves will have unique identifiers upon creation in the receiver system.
Step 3: Set the Metadata of the Document Reference
Create a new instance of the Document Reference resource and populate the relevant metadata fields. key fields to include are as follows:
type: Specify the type of document or resource being referenced. For example, if you are referencing a referral you would use the value https://snomed.info/ict|736253002 or if it is a booking https://snomed.info/ict|749001000000101.
"type": { "coding": [ { "system": "https://snomed.info/ict", "code": "736253002" } ] }
subject: Specify the subject of the document reference, which is typically the patient associated with the Resource.
"subject": { "identifier": { "system": "https://fhir.nhs.uk/Id/nhs-number", "value": "9556274839" } },
custodian: Set the author of the document reference, which will be the ODS code for the organisation writing the DocumentReference.
"custodian": { "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "A1001" } }
Step 4: Set the Content Reference
The content element of the Document Reference resource contains the reference to the location of the actual resource. Create a new instance of the content element and set the attachment property. The attachment property has a URL field where you specify the location of the resource.
Access the content element of the Document Reference. This element contains the reference to the location of the actual resource. The content element is typically an array, as a DocumentReference can reference multiple versions or representations of the same document. Each item in the array will have a URL element, which specifies the location of the resource.
The content.attachment.URL element in this example is a URL friendly Target Identifier for the receiver endpoint, of which can be used to retrieve the resource via the BaRS proxy by a consumer/sender. This element can also contain a direct URL if appropriate. The content.format element will contain the coding that describes the format of the resource in question. In this instance this is a BaRS message event of "servicerequest-request". ensure you set the creation date of the resource.
"content": [ { "attachment": { "language": "en-UK", "URL": "http://fhir.nhs.uk/Id/dos-service-id|111111111", "title": "Physical", "creation": "2005-12-24T09:35:00+11:00" }, "format": [ { "coding": [ { "system": "https://fhir.nhs.uk/CodeSystem/message-events-bars", "code": "servicerequest-request" } ] } ] } ]
Step 5: Save and Transmit the DocumentReference
Once you have populated all the necessary fields, you will need to perform a POST of the DocumentResource to the /DocumentReference endpoint on the BaRS proxy. This will create a DocumentReference in the NRL.
After saving, the DocumentReference will be assigned a unique id (e.g., DocumentReference/12345). You can use this identifier to reference or retrieve the DocumentReference in the future.
Step 6: Verify the DocumentReference
To ensure that the DocumentReference was created successfully, you can retrieve it using its identifier or search for it using relevant parameters. Make sure to validate the returned DocumentReference to confirm that all the metadata and content references are accurate.
Updating a DocumentReference
A DocumentReference can be updated by performing a PUT request with the updated resource to the /DocumentReference endpoint on the BaRS proxy with the appropriate id. A Read operation must be performed prior to this to ensure that the new DocumentReference is the most up to date.
Note: You can only delete DocumentReference resources that you own and that you created.
Delete a DocumentReference
A DocumentReference can be updated by performing a DELETE request with the resource to the /DocumentReference endpoint on the BaRS proxy with the appropriate id. A Read operation must be performed prior to this to ensure that the Action is appropriate.
Note: You can only delete DocumentReference resources that you own and that you created.
