Profiles & Interactions Index > Interaction: Search Patient Summary
Interaction: Search Patient Summary
The Search Patient Summary operation issues a parameterized query that results in a searchset Bundle that contains all Patient Summary Document Bundles that match the search parameters (a searchset Bundle of document Bundles). This operation supports retrieval of a set of instances using the following search criteria:
| Name | Optionality | Type | Description | Usage Note | Example |
|---|---|---|---|---|---|
| composition.patient.identifier | mandatory | token | This parameter specifies an identifier associated with the patient who is the subject of this e.g. medication document. | Generally this would be the patient's jurisdictional health number, but in some cases might be an alternative identifier such as MRN or ECID. Should include both system and value. | GET [Base]/Bundle?composition.patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234-56789 |
| composition.patient.birthdate | conditional | date | This parameter specifies the birth date of patient who is the subject of this e.g. patient summary document. |
This parameter should contain the Date of Birth of the patient as on the Ontario health card. Note: If the patient identifier is ECID, birthdate is optional thus will be ignored and not validated. If the patient identifier is either RWID, HCN, MRN - birthdate must be present and will be validated. |
GET [Base]/Bundle?composition.patient.birthdate=1971-11-28 |
| composition.patient.gender | conditional | token | This parameter specifies the gender of the patient associated with the e.g. patient summary document. |
This parameter should contain the sex at birth as noted on the Ontario health card. Note: If the patient identifier is ECID, gender is optional thus will be ignored and not validated. If the patient identifier is RWID, gender is optional but if provided will be validated. If the patient identifier is HCN or MRN, gender must be present and will be validated. |
GET [Base]/Bundle?composition.patient.gender=female |
| composition.type | optional | token | Composition type is an optional search parameter since the PS service only returns patient summary document. It is used to specify the type of document. This use of composition.type follows the FHIR Chaining Parameters search methodology. | Will be fixed to 60591-5 for patient summary. | GET [Base]/Bundle?composition.type=http://loinc.org|60591-5 |
| composition.status | optional | token | Composition status is an optional search parameter. It is used to specify the status of the Patient Summary document, e.g. "final" or "entered-in-error". This use of composition.status follows the FHIR Chaining Parameters search methodology. | A status of "entered-in-error" indicates a Patient Summary that has been invalidated. | GET [Base]/Bundle?composition.status=final |
| timestamp | optional | date | This parameter specifies when this Patient Summary was created. See FHIR http://hl7.org/fhir/R4/search.html#date for use of the date search type. | If there is no lower limit in the search request, the server will use the default configuration value of 120 days back. Note: The following prefixes can be used for the date parameter: eg, gt, lt, ge and le. If no prefix is present, the prefix eq is assumed. For the full list of parameters prefixes and modifiers click here. Note that this parametetr is applied directly on Bundle.timestamp and does not require chaining. |
POST [Base]/Bundle/_search?timestamp=2022-01-11T14:30:00+01:00 POST [Base]/Bundle/_search?timestamp |
| _lastUpdated | optional | date | This is a standard common parameters defined for all resources. It is used to select resources based on the last time they were changed | If there is no lower limit in the search request, the server will use the default configuration value of 120 days back. Note: The following prefixes can be used for the date parameter: eg, gt, lt, ge and le. If no prefix is present, the prefix eq is assumed. For the full list of parameters prefixes and modifiers click here.This parameter considers the value found in Bundle.meta.lastUpdated. Note that the server always provides this value, and clients have no control over a resource's last updated date. |
POST [Base]/Bundle/_search?_lastUpdated=ge2024-04-10T15:29:22.658+00:00 |
| _sort (_sort=[-]timestamp) | optional | string | This is a search control parameters. It is used to specify sorting criteria. It can be used to sort in either ascending or descending order. The optional "-" prefix indicates descending order. | This allows the sorting of search results based on the creation date of the Patient Summary | POST [Base]/Bundle/_search?_sort=-timestamp POST [Base]/Bundle/_search?_sort=-_lastUpdated |
| _count | optional | integer | This is a search control parameters. It is used to specify how many search results should be returned in a single page. | If there is no _count in the search request, the server will use a configurable default page size, e.g. 50 | POST [Base]/Bundle/_search?_count=10 |
Scope
This transaction involves a request by an Ontario Patient Summary Document Consumer for a set of Patient Summary documents matching the specified search criteria. The request is received by the Ontario Patient Summary Responder which returns a Bundle containing the matching Patient Summary Compositions.
For example, an Electronic Medical Record (EMR) user is seeing a new patient and wants to see a list of Patient Summaries available for that patient. The EMR uses the patient information held in the EMR to query the repository for any Patient Summary documents that exist for that patient. The repository returns a Bundle of any matching Patient Summaries which is then displayed to the EMR user as a list. The EMR or other PoS system is responsibile for listing the available patient summaries for the user to review; this is not an aspect of the query operation its
Interaction Diagram
Actor: Ontario Patient Summary Document Consumer
Role: Requests a set of Patient Summary documents from the Ontario Patient Summary Document Responder based on specified search criteria.
Actor: Ontario Patient Summary Document Responder
Role: Returns a search result Bundle containing Patient Summary documents that match the search criteria specified by the Ontario Patient Summary Document Consumer.
Specification
This specification is based on the FHIR R4 Search operation.
Patient Summary Search Request
The Search operation will return a searchset Bundle resource containing the Patient Summary Compositions (as document Bundles) that match the specified search criteria. The Patient Summary Search Request supports both GET and POST; PS-ON prefers the use of POST to avoid putting PHI in request URLs.
GET [base]/Bundle?([parameters]{&_format=[mime-type]})
POST [base]/Bundle/_search{?&_format=[mime-type]}
Example Search Request parameters
Search by bundle identifier query parameter
[base]/Bundle?identifier=http://ontariohealth.ca/fhir/NamingSystem/id-north-york-general-hospital-epic-ps-document|9881500b-98fe-476a-bf5a-36eae9ae54aeSearch by patient identifier and birth date query parameter.
Note: If the patient identifier (e.g., MRN or HCN) is used as the search parameter, the birth date must also be included.
[base]/Bundle?composition.patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567863&composition.patient.birthdate=1971-11-28Search by patient identifier and birth date and timestamp query parameter
[base]/Bundle?composition.patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567863&composition.patient.birthdate=1971-11-28×tamp=ge2020
Patient Summary Search Response
A Patient Summary Search Response may contain either:
- a searchset Bundle containing zero or more Patient Summary Composition dococument Bundles matching the search criteria. Each Patient Summary document Bundle will include all resources referenced by the Composition resource; no _include search parameter will be required. see note below
- OperationOutcome resource
note: to return a lightweight response that does not include all referenced resources, please see the Fetch DocumentReference operation page to return only DocumentReference resources
Example Search Response
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 or OperationOutcome.issue.diagnostics |
| HTTP Status | Scenario Description | severity | code | details.coding.code | details.coding.display | details.text |
|---|---|---|---|---|---|---|
| 200 OK | At least one Patient Summary matching the specified search criteria is found | HTTP 200 | OK. Returns a search result Bundle containing Patient Summary compositions (document Bundles) that match the search criteria. The document Bundles will be comprised of a Composition bundle entry, and all other referenced FHIR resources (e.g. Patient, Condition, AllergyIntolerance) as subsequent bundle entries. | |||
| 200 OK | At least one Patient Summary 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 | 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 | POST operation contains incorrect header value for "Content-Type" - should be "application/fhir+json" | error | processing | |||
| 400 Bad Request | When there was syntactical error such as a missing or invalid header, a missing or invalid URL parameter (e.g. wrong data type in URL parameter), a request body that can't be parsed or doesn't conform to the basic FHIR JSON/XML syntax rules (e.g. invalid attribute value, incorrect data type, etc.). Returns an OperationOutcome resource indicating an issue. The client must fix the request and try again. | error | invalid | Will vary depending on the 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 Unprocessable Entity | FHIR validation errors such as invalid terminology code, wrong data type value in payload body (e.g. incorrect date format), the proposed resource violated applicable FHIR profiles (e.g. wrong data element name), 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 | Patient Summary 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 |