Profiles & Operations Index > Operation: Fetch DocumentReference
Operation: Fetch DocumentReference
Fetch DocumentReference
The Fetch DocumentReference operation is used to return all the references to MI documents related to a patient. It is invoked on the DocumentReference endpoint (e.g. [base]/DocumentReference/$docref) and operates across all MI DocumentReference instances. This operation requires a patient id and takes the optional input parameters:
- patient gender
- patient date of birth
- start date
- end date
- document type
- document event
- document identifier such as accession number
- maxinum number of records to return
- other resources to be included in the result set (_include)
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 MI documents. This operation’s intended use is to provide a way for providers or patients to access their available MI 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.
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 MI document. | This can be an HCN, MRN, or ECID (Enterprise Client ID) and SHALL include both system and value. | |
| IN | patient.gender | 0..1 | token | This parameter specifies the gender of the patient associated to the document. | Value may be "male", "female", "other", "unknown" | |
| IN | patient.birthDate | 0..1 | date | This parameter specifies the date of birth of the patient associated to the document. | ||
| 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 MI 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 MI 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..* | token | The type relates to MI document type. This should be a provincial LOINC code for MI document type. | ||
| IN | event | 0..* | token | Main clinical event documented. In miCDR, this refers to the clinical cateogry of the MI order: procedure code, modality, specialty, bodypart, laterality | procedure code (local, provincial or SNOMED CT code), modality (DICOM code), specialty (SNOMED CT code), bodypart (DICOM or SNOMED CT code), laterality (SNOMED CT code) | |
| IN | identifier | 0..1 | Identifier | business identifier for the document such as accession number | the identifier must include system and value | |
| IN | _count | 0..1 | integer | maximum number of records to return | ||
| IN | _include | 0..1 | other types of resources to be included in the response | |||
| OUT | return | 1..1 | Bundle | The bundle type is 'searchset' containing DocumentReference resources which conform to the miCDR DocumentReference profile |
Scope
This interaction involves a request by an miCDR Document Consumer for a set of documents matching the specified search criteria. The request is received by the miCDR FHIR server which returns a Bundle containing the matching Document.
For example, a physician who has access to miCDR is seeing a new patient and wants to see a list of MI reports available for that patient. The physician uses the patient information held in the system to query miCDR FHIR server for any MI report documents that exist for that patient. The server returns a Bundle of any matching MI reports which is then displayed to the physician as a list. The PoS system is responsibile for listing the available MI reports for the user to review.
Interaction Diagram
Actor: miCDR Document Consumer
Role: Requests a set of miCDR documents from the miCDR FHIR server based on specified search criteria.
Actor: miCDR FHIR server
Role: Returns a Bundle containing DocumentReference instances that match the search criteria specified by the miCDR 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.
Example:
- POST parameter of a patient identifier.
patient.identifier=[system]|1234567890
- POST parameter using a combination of the patient, start and end date, and category (SNOMED CT code "418618007" - "Computed tomography of sacroiliac joints") parameters:
patient.identifier=[system]|1234567890&start=2023-01-01T00:00:00-04:00&end=2023-03-01T00:00:00-04:00&category=http://snomed.info/sct%7C418618007
Query Response
If the query is valid and at least one document is found, miCDR 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 page for details.
For details of the DocumentReference profile, please refer to the DocumentReference profile page.
Examples
Fetch DocumentReference Response Example
Paging
The server provides paging for the results of a search interaction, and conforms to method adapted from RFC 5005 (Feed Paging and Archiving) for sending continuation links to the client when returning a Bundle.
This example shows the third page of a search result:
<Bundle xmlns="http://hl7.org/fhir">
<!-- snip metadata -->
<!-- This Search url starts with base search, and adds the effective
parameters, and additional parameters for search state. All searches
SHALL return this value.
In this case, the search continuation method is that the server
maintains a state, with page references into the stateful list.
-->
<link>
<relation value="self">
<url value="[base]/DocumentReference?patient.identifier=[system]|1234567890&start=ge2023-02-26&category=http://snomed.info/sct%7C418618007&_count=10&_getpages=76395924-28c2-4cb1-93c1-608fb6eea979&&_getpagesoffset=20"/>
</link>
<link>
<relation value="next"/>
<url value="[base]/DocumentReference?patient.identifier=[system]|1234567890&start=ge2023-02-26&category=http://snomed.info/sct%7C418618007&_count=10&_getpages=76395924-28c2-4cb1-93c1-608fb6eea979&&_getpagesoffset=30"/>
</link>
<!-- then the search results... -->
</Bundle>
A server will inform the client of the total number of resources returned by the interaction for which the results are paged using the Bundle.total. Please refer to the "Bundle Example" section, which shows use of Total and to the text in “Bundle Resource” section, which provides detailed explanation of Total.
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 | At least one DocumentReference matching the specified search criteria is found | |||||
| 200 OK | At least one Documentreference is found, but there is a consent block that prevents disclosure of patient data. Returns an OperationOutcome resource indicating that there is a consent block on the patient's record that prevents disclosure of patient data. | warning | suppressed | |||
| 200 OK | No DocumentReference matching the specified search criteria are found. | warning | not-found | |||
| 400 Bad Request | Missing security token | error | required | Missing required security token: PIN | ||
| 400 Bad Request | Request is malformed (e.g. incorrect header value, patient identifier is missing system or value, etc) | error | -- | -- | -- | -- |
| 500 Internal Server Error | API validates the request but cannot return a valid response due to internal issues. | 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 |