Interaction: Search DocumentReference
=Note this page is still under development=
The Search DocumentReference interaction supports a RESTful query that results in a searchset Bundle that contains all DocumentReferences that match the search parameters (a searchset Bundle of DocumentReferences). This operation supports retrieval of a set of instances using the following search criteria:
| Query Search Parameter | Description | Usage Note |
|---|---|---|
| patient.identifier | This mandatory 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. |
| patient.gender | This optional parameter specifies the gender of the patient associated to the document. | Value may be "male", "female", "other", "unknown" |
| patient.birthDate | This optional parameter specifies the date of birth of the patient associated to the document. | |
| identifier | This optional parameter specifies the document identifier assigned by the source system | If used, must include both system and value |
| type | This optional parameter specifies the type of document. | |
| category | This optional parameter specifies the category of document. A document category can be any of the five parts based on document ontology. | |
| doc-status | This optional parameter specifies the status of the document, | preliminary | final | amended | entered-in-error |
| custodian | This optional parameter can be used to query documents based on the organization which maintains the document | Based on chaining methodology, this parameter can use identifier or name of the organization |
| date | This optional parameter can be used to query documents based on the authored date | This parameter can be used with prefix such as lt, gt, le, ge |
| author | This optional parameter can be used to query documents base on the author of the document | |
| _sort | This optional parameter can be used to specify sorting criteria. It can be used to sort in either ascending or descending order. The optional "-" prefix indicates descending order. | |
| _count | This optional parameter specifies how many search results should be returned in a single page. | |
| _id | This is used to return a single document. | This value will use the "id" value from the list returned by the search query with one of the other fields. |
Scope
This interaction involves a request by an acCDR Document Consumer for a set of DocumentReference instances matching the specified search criteria. The request is received by the acCDR FHIR server which returns a Bundle containing the matching DocumentReference instances.
For example, a physician who has access to acCDR is seeing a new patient and wants to see a list of documents available for that patient. The physician uses the patient information held in the system to query acCDR FHIR server for any document that exist for that patient. The server returns a Bundle of any matching documents which is then displayed to the physician as a list. The PoS system is responsibile for listing the available documets for the user to review.
Interaction 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
Search Request
The Search interaction will return a searchset Bundle resource containing the acCDR DocumentReference instances that match the specified search criteria. The search request supports both GET and POST; we prefer the use of POST to avoid putting PHI in request URLs.
GET [base]/DocumentReference?([parameters]{&_format=[mime-type]})
POST [base]/DocumentReference/_search{?&_format=[mime-type]}
For POST request, the parameters SHALL be provided in the form of FHIR Parameters resource in the HTTP body of the request.
Search Response
A Search DocumentReference Response may contain either:
- a searchset Bundle containing zero or more DocumentReference instances matching the search criteria. Note that the documents are not included in the response. To retrieve the documents, use GET to
DocumentReference.content.attachment.urlto retrieve the document.
Example Search Queries
Search By Patient Identifier
GET [base]/DocumentReference?patient.identifier=https%3A%2F%2Ffhir.infoway-inforoute.ca%2FNamingSystem%2Fca-on-patient-hcn|1234567890
OR
POST [base]/DocumentReference?_search with HTTP body patient.identifier=https%3A%2F%2Ffhir.infoway-inforoute.ca%2FNamingSystem%2Fca-on-patient-hcn|1234567890
Search for DocumentReferences for a patient and created in 2020 or Later
[base]DocumentReference?patient.identifier=https%3A%2F%2Ffhir.infoway-inforoute.ca%2FNamingSystem%2Fca-on-patient-hcn|1234567890×tamp=ge2020
OR
POST [base]/DocumentReference?_search with HTTP body patient.identifier=https%3A%2F%2Ffhir.infoway-inforoute.ca%2FNamingSystem%2Fca-on-patient-hcn|1234567890×tamp=ge2020
Example Response
Search Document Response Example =TBD=
Expected Behavior
See
| 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 matching the specified search criteria 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 | Patient has temporarily unblocked access | information | information | CONSENT_TEMP_UNBLOCK | Patient has temporarily unblocked access to view and use acCDR data. | |
| 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 | -- | -- | -- | -- |
| 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 | 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 |