Acute and Community Clinical Data Repository HL7® FHIR® Query Implementation Guide

Profiles & Operations > Operation: Fetch DocumentReference

Operation: Fetch DocumentReference

This operation is used to return all the references to documents related to a patient. It is invoked on a FHIR Server’s DocumentReference endpoint (e.g., [base]/DocumentReference/$docref) and operates across all DocumentReference instances.

The operation requires a patient identifier and takes the optional input parameters:

start date
end date
document type
document category
profile

and returns a searchset Bundle containing DocumentReference resources for the patient. If the server has stored documents, the server returns the DocumentReference resources associated with documents. This operation’s intended use is to provide a way for providers or patients to access their available documents. The document itself can be subsequently retrieved using the link provided in the DocumentReference.content.attachment.url element. The link could be a FHIR endpoint to a Binary Resource or some other document repository.

At this time, the 'on-demand' parameter defined in the $DocRef operation in IPA-UV, US-Core, and FHIR R5 is not supported.

URL: [base]/DocumentReference/$docref

The operation requires a patient id and also supports additional optional parameters as specified below:

Use	Name	Cardinality	Type	Documentation	Usage Notes
IN	patient.identifier	1..1	identifier	This parameter specifies an identifier associated with the patient who is the subject of this document.	This can be an HCN, MRN, or ECID (Enterprise Client ID) and SHALL include both system and value.
IN	start	0..1	datetime	The date range relates to care dates, not record currency dates - e.g., all records relating to care provided in a specific date range. If no start date is provided, all documents before the end date are in scope. The most recent or current document is in scope if neither a start date nor an end date is provided. The client SHOULD provide values precise to the second + time offset.
IN	end	0..1	datetime	The date range relates to care dates, not record currency dates - e.g., all records relating to care provided in a specific date range. If no end date is provided, all documents after the start date are in scope. The most recent or current document is in scope if neither a start date nor an end date is provided. The client SHOULD provide values precise to the second + time offset.
IN	type	0..*	Coding	The type relates to document type. This should be a provincial LOINC code for document type.
IN	category	0..*	Coding	the category indicating the document ontology axis of the provincial LOINC code for the document type (e.g. type of service, subject matter domain, etc)
OUT	return	1..1	Bundle	The bundle type is 'searchset' containing DocumentReference resources which conform to the acCDR DocumentReference profile.

Scope

This transaction involves a request by an acCDR Document Consumer for a set of documents matching the specified search criteria. The request is received by the acCDR FHIR server which returns a Bundle containing the matching Document.

For example, a physician who has access to acCDR is seeing a new patient and wants to see a list of discharge summaries available for that patient. The physician uses the patient information held in the system to query acCDR FHIR server for any discharge summary documents that exist for that patient. The server returns a Bundle of any matching discharge summaries which is then displayed to the physician as a list. The PoS system is responsibile for listing the available discharge summaries for the user to review.

Note that in the first release of this implementation guide, we will only support a limited seach scenarios based on category. These are the scenarios and the corresponding category search parameter values. (NOTE this is work in progress)

Clinical Viewer Portlet	Scenario	LOINC search query expression	FHIR Search by Document Category expression
Document Notes	Search for documents related to care or a procedure that is not diagnostic nature, such as discharge summaries, procedure notes, clinic and progress notes	!LP173115-9	category:not=LP173115-9
Other Results	Search for documents related to a diagnostic procedure but not sent to DICS, such as cardiology reports, speech-language dignostic reports, neurology diagnostic reports (EEG). These are reports where type of service is a Dignostic Study but they are not sent to DICS (i.e. not mapped to acCDR code with DI modality)	LP173115-9	category=LP173115-9

Interaction Diagram

search-document-diagram

Actor: acCDR Document Consumer

Role: Requests a set of acCDR documents from the acCDR FHIR server based on specified search criteria.

Actor: acCDR FHIR server

Role: Returns a Bundle containing DocumentReference instances that match the search criteria specified by the acCDR Document Consumer.

Specification

This operation is based on FHIR R4 $docref operation.

$docref Operation for Fetching DocumentReference

The $docref opreation is used to return references to all documents related to a patient, meeting the parameters criteria. Since the "patient identifier" parameter is required and is not a a primitive type (type is identifier), the $DocRef operation must be executed using POST with the Parameters resource in the request body.

POST [base]/DocumentReference/$docref

For POST request, the parameters SHALL be provided in the form of FHIR Parameters resource in the HTTP body of the request.

Query Response

If the query is valid and at least one document is found, acCDR FHIR server will return a searchset bundle containing a matching DocumentReference resource. A pointer to the document is contained in DocumentReference.content.attachment.url. To retrieve the document, issue a GET request to the url and refer to Retrieve Document for details

For details of DocumentReference profile, please refer to DocumentReference profile page.

Examples

The following search parameters and search parameter combinations are supported:

Search for all documents for a patient using the patient search parameter

GET [base]/DocumentReference/$docref?patient={Type/}[id]

1.1 Example of search by patient identifier (HCN or MRN)

GET [base]/DocumentReference/$docref?patient.identifier=[system]|1234567890

Search for documents using the combination of the patient, start and end date, and document type:

GET [base]/DocumentReference?patient.identifier=patient.identifier=[system]|1234567890&start=2023-01-01T00:00:00-04:00&end=2023-03-01T00:00:00-04:00&type=http://loinc.org|LP29684-5

Examples

Fetch DocumentReference Response Example

When an OperationOutcome is returned to indicate that the resource is blocked by a patient consent directive, the following elements will be populated:

OperationOutcome.issue.severity=warning
OperationOutcome.issue.code=suppressed (from req valueset http://hl7.org/fhir/R4/valueset-issue-type.html)

Expected Behavior

See Response Handling page for additional response handling behavior.

Legend
code = OperationOutcome.issue.code
severity = OperationOutcome.issue.severity
details.coding.code=OperationOutcome.issue.details.coding.code
details.coding.display=OperationOutcome.issue.details.coding.display
details.text = OperationOutcome.issue.details.coding.text