Profiles & Operations Index > Operation: Search Imaging Study
Interaction: Search Imaging Study
Search Imaging Study
The Search Imaging Study operation issues a parameterized query that results in a searchset Bundle that contains ImagingStudy resources related to a patient.
The mandatory parameter for this query:
- Patient identifier
The optional parameters for this query:
- patient gender
- patient date of birth
- ImagingStudy started (date)
- local procedure code of the MI order associated with the imaging study
- category values of the MI order associated with the imaging study (e.g. procedure code, modality, specialty, body part, laterality)
- Business identifier such as accession number, study instance id
- maxinum number of records to return
- other resources to be included in the result set (_include)
| Search Parameter | Type | Documentation | Usage Notes | |
|---|---|---|---|---|
| patient.identifier (ImagingStudy.patient.identifier) | Identifier | Mandatory parameter This parameter specifies an identifier associated with the patient who is the subject of this imaging study. This use of patient.identifier follows the FHIR Chaining Parameters search methodology. | HCN or MRN or ECID. MRN is preferred. System and value must be provided. | |
| patient.gender (ImagingStudy.patient.gender) | token | Optional parameter This parameter specifies the gender of the patient associated to the imaging study. | Value may be "male", "female", "other", "unknown" | |
| patient.birthDate (imagingstudy.patient.birthDate) | date | Optional parameter This parameter specifies the date of birth of the patient associated to the document. | ||
| started | date | Optional paramater The date range relates to the dates when studies were started | may contain a prefix such as gt, ge, lt, le | |
| basedon:ServiceRequest.code | token | Optional paramater The procedure code of the MI order associated with the imaging study | ||
| basedOn:ServiceRequest.category | Coding | Optional paramater These are the category values of the MI order associated with the imaging study (e.g. procedure code, modality, specialty, body part, laterality) | ||
| basedOn:ServiceRquest.code-category | composite | Optional paramater This parameter supports query by procedure code and category of the same MI order associated with the imaging study | ||
| identifier | Identifier | Optional paramater This is the business identifier of the imaging study, such as accession number, study instance id | Must include system and value | |
| _sort | string | 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. | Relevant sorting parameters include accession number (ImagingStudy.identifier), started date (ImagingStudy.started) | |
| _count | integer | Optional paramater This is the maximum number of records to return. | ||
| _include | string | Optional paramater This specifies the type of referenced resources to be included in the bundle. The value must meet the FHIR syntax defined for _include Example: to include the order referenced from the imaging manifest, use "_include=ImagingStudy:basedOn" |
If the search is successful, it will return a bundle of type 'searchset' containing ImagingStudy resources which conform to the miCDR ImagingStudy profile.
Scope
This interaction involves a request by an miCDR ImagingStudy Consumer for a set of ImagingStudy resources matching the specified search criteria. The request is received by the miCDR FHIR server which returns a Bundle containing the matching ImagingStudy.
For example, a physician who has access to miCDR is seeing a new patient and wants to see a list of imaging studies available for that patient. A physician uses the patient information held in the system to query miCDR FHIR server for any ImagingStudy resources that exist for that patient. A physician can also request searching for imaging studies with specific procedure codes, categories, e.g.modalities, specialties, body parts, etc. (ImagingStudy.category). The server returns a Bundle with matching imaging studies. The PoS system is responsibile for listing the available imaging studies for the user to review.
Interaction Diagram
Actor: miCDR ImagingStudy Consumer
Role: Requests a set of miCDR ImagingStudy resources from the miCDR FHIR server based on specified search criteria.
Actor: miCDR FHIR server
Role: Returns a Bundle containing ImagingStudy instances (as well as reference resources if requested by use of _include and _revinclude parameters) that match the search criteria specified by the miCDR ImagingStudy Consumer.
Specification
Search
The miCDR FHIR server supports both GET and POST; we prefer the use of POST to avoid putting PHI in request URLs.
GET [base]/ImagingStudy?{parameters}
POST [base]/ImagingStudy/_search
For POST request, the parameters SHALL be provided in the form of FHIR Parameters resource in the HTTP body of the request.
Search Response
If the query is valid and at least one ImagingStudy is found, miCDR FHIR server will return a searchset bundle containing matching ImagingStudy resource(s).
ERD Diagram
For details of a ImagingStudy profile, please refer to the ImagingStudy profile page.
Examples
The following search parameters and search parameter combinations are supported:
- Search for all ImagingStudy resources for a patient using the patient search parameter
GET [base]/ImagingStudy?patient.identifier={Type/}[id]
1.1 Example of search by patient's Ontario HCN
Search by HCN only:
GET [base]/ImagingStudy?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890
Search by MRN only:
GET [base]/ImagingStudy?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-cambridge-memorial-mrn|23456789
Search by MRN and study instance ID with Endpoint included in the response:
GET [base]/ImagingStudy?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-cambridge-memorial-mrn|23456789&identifier=urn:dicom:uid|urn:oid:1.2.840.113619.2.55.3.604688123.1234.1599765432&_include=ImagingStudy:endpoint
Response Example: link
1.2 Example of search by multiple patient MRNs (four in this example)
GET [base]/ImagingStudy?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-the-ottawa-hospital-mrn|23456789,"http://ehealthontario.ca/fhir/NamingSystem/id-william-osler-peel-memorial-mrn|23456781,http://ehealthontario.ca/fhir/NamingSystem/id-university-health-network-mrn|23456784,http://ehealthontario.ca/fhir/NamingSystem/id-windsor-regional-hospital-mrn|23456786
1.3 Example of search by patient identifier, start date, local procedure code
GET [base]/ImagingStudy?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890&started=gt2024-01-01&basedOn:ServiceRequest.code=http://snomed.info|12345
1.4 Example of search by patient identifier, start date, local procedure code (SNOMED code: 12345) and category (DICOM Mammography)
GET [base]/ImagingStudy?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890&started=gt2024-01-01&basedOn:ServiceRequest.code-category=http://snomed.info|12345$http://dicom.nema.org/resources/ontology/DCM|MG
Response:
| HTTP Response Code | FHIR Response Payload |
|---|---|
| 200 | link |
- (TBD) Search for ImagingStudy resources using the combination of the patient, start and end date, and ImagingStudy code:
GET [base]/ImagingStudy?patient.identifier=[system]|1234567890&started=ge2023-01-01T00:00:00-04:00&started=le2023-05-01T00:00:00-04:00&category=http://snomed.info/sct%7C418618007
Response:
| Scenario | HTTP Response Code | FHIR Response Payload |
|---|---|---|
| Record found | 200 | link |
| Record found, but not returned due to consent block | 200 | link |
| Some records found, but not all returned due to consent block | 200 | link |
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 imaging study matching the specified search criteria is found | |||||
| 200 OK | At least one imaging study 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 imaging study 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 | |||
| 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 |