Profiles & Operations Index > 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.
If no parameters are specified, the server SHALL return a DocumentReference to the patient’s latest patient summary.
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
Parameters
| Use | Name | Cardinality | Type | Binding | Documentation |
|---|---|---|---|---|---|
| IN | patient | 1..* | identifier | The identifier of the patient resource. If there is no match, an empty Bundle is returned. | |
| 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. For patient summary, pass the value "http://loinc.org|60591-5" | |
| IN | category | 0..* | Coding | The parameter is not used for the Ontario patient summary Fetch DocumentReference operation.) | |
| IN | profile | 0..* | canonical | The identifier of the patient resource. If there is no match, an empty Bundle is returned. | |
| OUT | return | 1..1 | Bundle | The bundle type is "searchset"containing DocumentReference resources. Note: As this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource |
Scope
This transaction involves a request by an Ontario Patient Summary document consumer for a set of documents matching the specified search criteria. The request is received by the FHIR server which returns a FHIR Bundle containing references to matching Patient Summary documents.
For example, a physician who has access to Ontario Patient Summary Repository is seeing a new patient and wants to see a list of patient summaries available for that patient. The physician uses the patient information held in the system to query the FHIR server for any patient summary documents that exist for that patient. The server returns a Bundle of any matching patient summaries which is then displayed to the physician as a list containing the metadata (author, dates) of patient summaries. The physician then uses the user interface of their point of service system to retrieve the entire patient summary for viewing.
Specification
This operation is based on FHIR R5 $DocRef operation, as defined in International Patient Access, US Core, FHIR R5, and Pan-Canadian FHIR Exchange (CA:FeX) 2.0.0.
$docref Operation for Fetching DocumentReference
The $docref opreation is used to return references to all patient sumamry 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 this 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, the FHIR server will return a searchset bundle containing one or more 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 Patient Summary page for details.
For details of DocumentReference profile, please refer to DocumentReference (PS-ON) profile page.
Example Fetch DocumentReference Response:
OperationOutcome & Consent Blocks
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 behaviour.
| 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 |
| HTTP Status | Scenario Description | severity | code | details.coding.code | details.coding.display | details.text |
|---|---|---|---|---|---|---|
| 200 OK | Request has been accepted for processing | |||||
| 200 OK | No Patient Summaries matching the specified search criteria are found. Returns an search result Bundle with zero search results. Also returns an OperationOutcome resource with a warning indicating no summaries were found. | warning | not-found | |||
| 400 Bad Request | Missing security token | error | required | Missing required security token: PIN | ||
| 400 Bad Request | When there was syntactical error such as a missing or invalid header, a missing or invalid URL parameter, a request body that can't be parsed or doesn't conform to the basic FHIR JSON/XML syntax rules, etc | error | invalid | |||
| 401 Unauthorized | Failed authentication | error | security | Authorization is required for the interaction that was attempted | ||
| 406 Not Acceptable | The Accept header requested a format that the server does not support | error | not-supported | |||
| 422 Unprocessible Entity | FHIR validation errors such as invalid code, wrong date format, or violation of LOB defined business rules | Will vary depending on the error | Will vary depending on the error | OH-defined error code | OH-defined errror message | |
| 429 Too Many Requests | Rate Limit | error | throttled | Too Many Requests | ||
| 500 Internal Server Error | Unhandled Exception | fatal | exception | Internal Error | ||
| 503 Service Unavailable | Indicates that the services has been temporarily taken down (on purpose) | |||||
| 504 Gateway Timeout | Downstream system(s) did not return timely response | error | timeout |