## Document Search To retrieve a list of documents for a patient with additional search parameters, the request is a search operation on DocumentReference resource. The response is a bundle of DocumentReference resources. Each resource contains the metadata about a document and a url pointing to its location. ### Request `GET [base]/DocumentReference[?search-expression]` The search expression must include the following information: - Patient identifier - either a client unique ID (Client GUID) or HCN + DOB + Gender - document category - this contains a cGTA or LOINC part number code identifying the category of the document to search for. Multiple codes may be combined for complex searches. Please see how to combine multiple search parameters later in this section. - document create time - this contains a FHIR date value indicating when the document was created. A range can be specified using search modifiers (e.g. le, gt) on the prefix of the value. Alternatively, the search can be done via POST in the format below: `POST [base]/DocumentReference/_search[?search-expression]` where search-expression is based on the composition field and its properties below. **All the search parameters listed below are mandatory.** | search parameter | description | type | example | |- | patient | information about the subject of the document which is the patient (Client GUID or HCN + DOB + Gender) | reference | example | | category | search by document category identified a code as part of the LOINC document ontology. Multiple category values can be combined to form a complex boolean expression in the search. | token | example | | created | document creation date in the format of `yyyy-mm-dd` | date | example In addition to the mandatory search parameters, we also support optional search parameters below. | search parameter | description | type | example | |- | _summary | if _summary=true, only return fields identified with summary flag. If not used or value equals false, all mandatory fields will be returned. | boolean | _summary=true\|false | | _include | to include other resources in the response bundle. Currently only encounter is supported (i.e. _include=DocumentReference:patient) | string | _include=DocumentReference:patient | | _sort | indicate which order to return the results, contains a comma separated list of sort rules in priority order. By default it is in increasing order. Use "-" prefix if using decreasing order | string | _sort=-created | No other search parameters are supported. Query which contains unsupported search parameters will be rejected with HTTP 400 (Bad request) error. Multiple search parameters can be combined to create AND or OR. - "&" is used to create AND (i.e. `[search-parameter-1] = value1 & [search-parameter-2] = value2 ` - "," is used to create OR (i.e. `[search-parameter] = value1, value2`) For datetime range, the following modifiers can be used as defined in [here](https://www.hl7.org/fhir/stu3/search.html#date). See table below for summary of supported prefix | prefix | description | Note | example | |- | eq | the value for the parameter in the resource is equal to the provided value | the range of the search value fully contains the range of the target value | `created=eq2019-01-01` |2019-01-01 matches 2019-01-02 does not match, it is not in the range| | gt | the value for the parameter in the resource is greater than the provided value | the range above the search value intersects (i.e. overlaps) with the range of the target value | `created=gt2019-01-01` | 2019-01-02 matches, 2018-01-31 or 2019-01-01 does notmatch, it is not in the range| | lt | the value for the parameter in the resource is less than the provided value | the range below the search value intersects (i.e. overlaps) with the range of the target value | `created=lt2019-01-01` | 2018-12-31 matches, 2018-01-01 does not match, it is not in the range| | ge | the value for the parameter in the resource is greater or equal to the provided value | the range above the search value intersects (i.e. overlaps) with the range of the target value, or the range of the search value fully contains the range of the target value | `created=ge2019-01-01` | 2019-01-02 or 2019-01-01 matches, 2018-01-31 does notmatch, it is not in the range | le | the value for the parameter in the resource is less or equal to the provided value | the range below the search value intersects (i.e. overlaps) with the range of the target value or the range of the search value fully contains the range of the target value | `created=le2019-01-01` | 2018-12-31 or 2019-01-01 matches, 2019-01-02 does notmatch, it is not in the range | sa | the value for the parameter in the resource starts after the provided value | the range of the search value does not overlap with the range of the target value, and the range above the search value contains the range of the target value | `created=sa2019-01-01` | Before and ending before 2018-01-31 is not included because that period ends before 2019-01-01. 2019-01-02 onwards is included because that period starts after 2019-01-01 | eb | the value for the parameter in the resource ends before the provided value | the range of the search value does overlap not with the range of the target value, and the range below the search value contains the range of the target value | `created=eb2019-01-01` | 2019-01-02 onwards is not included because that period starts after 2019-01-01. Before and ending before 2018-01-31 is included because that period ends before 2019-01-01 Example of a search: | Scenario | Example | |- | Search for all discharge summaries for patient with Client Unique ID `e81c53a7-2f60-4cff-bd2c-bcd0e6abbe7f` authored since January 1, 2019 | `GET [base]/DocumentReference?patient.identifier=[cuid_uri]|e81c53a7-2f60-4cff-bd2c-bcd0e6abbe7f&category=LP173221-5&created=ge2018-01-01` |Search for all discharge summaries for patient with HCN, DOB, and gender and creation time between January 1, 2018 and January 1, 2019|`GET [base]/DocumentReference?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890&patient.birthDate='1982-01-01'&patient.gender=female&category=LP173221-5&created=ge2018-01-01&created=le2019-01-01`| |Search for nephrology discharge summary documents (LOINC type of service: LP173221-5, subject matter: LP172962-5) for patient with Client Unique ID `e81c53a7-2f60-4cff-bd2c-bcd0e6abbe7f` |`GET [base]/DocumentReference?patient.identifier=[cuid_uri]|e81c53a7-2f60-4cff-bd2c-bcd0e6abbe7f&category=LP173221-5&category=LP172962-5`| |Search for neuphorology consults (LOINC type of service: LP1731110-0, subject matter: LP172962-5) for patient with Client Unique ID `e81c53a7-2f60-4cff-bd2c-bcd0e6abbe7f` |`GET [base]/DocumentReference?patient.identifier=[cuid_uri]|e81c53a7-2f60-4cff-bd2c-bcd0e6abbe7f&category=LP173110-0&category=LP172962-5`| ### Response The response contains a bundle of DocumentReference resources. Please see the response profile below. The document URL is contained in the contentAttachment.url field. To retrieve the document, a simple GET is used. Note that the documentReference will contain one or more internally referenced resources under `DocumentReference.contains` field. In the response bundle profile, paging may be used by populating the bundle.link field with link urls to retrieve the first, last, previous and next pages. Please refer to the paging section in [Implementation Considerations](implementationconsiderations) page. * [search-response-bundle profile](https://simplifier.net/ontarioaccdrfhirimplementationguide/search-response-bundle) * [document-reference profile](https://simplifier.net/ontarioaccdrfhirimplementationguide/document-reference) This profile will contain other resources for internal reference such as visit encounter details, etc. The following profile is defined. * [patient-encounter profile](https://simplifier.net/ontarioaccdrfhirimplementationguide/myencounter) Patient and practitioner details are provided as references. The patient reference will use `reference.identifier` that contains the patient's enterprise Client ID (ECID). The practitioner reference will use the following fields: - `Practitioner.identifier`- an identifier which may be the license number or a local identifier defined by originating HSP. - `Practitioner.display` - a string value identifying the practitioner name from originating HSP. #### Error Response If query fails, an HTTP error response containing an OperationOutcome resource will be returned. Table below is a summary of error responses. | Scenario | HTTP error code |- | Malformed query | 400 (bad request) with Operationoutcome details | | Valid query but server could not return a valid response due to internal error | 500 (Internal Server Error) with OperationOutcome details |