Ontario Medical Imaging HL7® FHIR® Implementation Guide v1.0.0-Ballot
For a full list of available versions, see the Directory of published versions
The Search DocumentReference interaction is used to return all MI data related to a patient in the format of FHIR DocumentReferences. It operates across all MI DocumentReference instances generated for each submission of MI order, report and imaging studies.
This interaction requires a patient identifier and takes the optional input parameters:
and returns a searchset Bundle containing DocumentReference resources for the patient. The returned DocumentReference instances contains the url to the associated MI data entities. This interaction’s intended use is to provide a way for providers or patients to access their available MI data without specifying the type of the data. The data entity itself can be subsequently retrieved using the link provided in the DocumentReference.content.attachment.url element.
The interaction requires a patient id and also supports additional optional parameters as specified below:
| Name | Cardinality | Type | Documentation | Usage Notes | |
|---|---|---|---|---|---|
| patient.identifier | 1..1 | identifier | This mandatory 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. | |
| patient.gender | 0..1 | token | This Optional parameter specifies the gender of the patient associated to the document. | Value may be "male", "female", "other", "unknown" | |
| patient.birthDate | 0..1 | date | This Optional parameter specifies the date of birth of the patient associated to the document. | ||
| identifier | 0..1 | Identifier | Optional business identifier for the document such as accession number | the identifier must include system and value | |
| date | 0..1 | date | Optional When this document reference was created | ||
| category | 0..1 | datetime | Optional 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. | ||
| type | 0..* | token | Optional The type relates to MI document type. This should be a provincial LOINC code for MI document type (e.g. order, report, imaging study). | ||
| category | 0..* | token | Optional Categorization of MI entities such as modality, service type, bodypart, laterality, contrast. | modality (DICOM code), specialty (SNOMED CT code), bodypart (DICOM or SNOMED CT code), laterality (SNOMED CT code) | |
| _count | 0..1 | integer | Optional maximum number of records to return | ||
| _include | 0..1 | Optional other types of resources to be included in the response |
This interaction involves a request by an miCDR Consumer for a set of MI DocumentReference resources matching the specified search criteria. The request is received by the miCDR FHIR server which returns a Bundle containing the matching DocumentReference instances.
For example, a physician who has access to miCDR is seeing a new patient and wants to see a list of MI data available for that patient. A physician uses the patient information held in the system to query miCDR FHIR server for any MI resources that exist for that patient. A physician can also request searching for data with specific accession number (DocumentReference.identifer) and/or categories, e.g.modalities, specialties, body parts, etc. (DocumentReference.category). The server returns a Bundle with matching MI data that may include orders, reports and imaging studies. The PoS system is responsible for listing the available MI data for the user to review.
Actor: miCDR Consumer
Role: Requests a set of MI data as DocumentReferences from the miCDR FHIR server based on specified search criteria.
Actor: miCDR FHIR server
Role: Returns a Bundle containing DocumentReference instances (as well as reference resources if requested by use of _include and _revinclude parameters) that match the search criteria specified by the miCDR Consumer.
The miCDR FHIR server supports both GET and POST; we prefer the use of POST to avoid putting PHI in request URLs.
GET [base]/DocumentReference?{parameters}
POST [base]/DocumentReference/_search
For POST request, the parameters SHALL be provided in the form of name pair values in the HTTP body of the request.
If the query is valid and at least one DocumentReference is found, miCDR FHIR server will return a searchset bundle containing matching DocumentReference resource(s).
For details of DocumentReference profile, please refer to the DocumentReference profile page.
Examples
The following search parameters and search parameter combinations are supported:
GET [base]/DocumentReference?patient={Type/}[id]
1.1 Example of search by patient's Ontario HCN
GET [base]/DocumentReference?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890
Search by MRN only:
GET [base]/DocumentReference?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-cambridge-memorial-mrn|23456789
Search by MRN and Accession Number:
GET [base]/DocumentReference?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-cambridge-memorial-mrn|23456789&identifier=urn:oid:2.16.840.1.113883.3.239.23.18.10|1111-111-111
Response Example: link
1.2 Example of search by multiple patient MRNs
GET [base]/DocumentReference?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-the-ottawa-hospital-mrn|23456789,http://ehealthontario.ca/fhir/NamingSystem/id-mackenzie-health-hospital-mrn|23456783,http://ehealthontario.ca/fhir/NamingSystem/id-providence-care-mrn|11233,http://ehealthontario.ca/fhir/NamingSystem/id-windsor-regional-hospital-mrn|23456786
1.3 Search for DocumentReference resources using the combination of the patient, start and end date, and DocumentReference type (LOINC code for imaging order, report, or manifest):
GET [base]/DocumentReference?patient.identifier=[system]|1234567890&issued=ge2023-01-01T00:00:00-04:00&issued=le2023-05-01T00:00:00-04:00&type=http://loinc.org/55665-5
1.5 Example of search by patient identifier, start date, and data category (e.g. modality)
GET [base]/DiagnosticReport?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890&started=gt2024-01-01&category=http://snomed.info|12345$http://dicom.nema.org/resources/ontology/DCM|MG
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 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 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 | -- | -- | -- | -- |
| 406 Not Acceptable | The Accept header requested a format that the server does not support | error | not-supported | |||
| 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 | error | timeout |