Profiles & Interactions Index > Search DiagnosticReport - Patient Query

Interaction: Search DiagnosticReport - Patient Query

DiagnosticReport search is simple RESTful interactions. It supports retrieving a lab results from OLIS within a date range or on a specific date for a health care practitioner by patient ID and date of birth. The interaction can be performed by using GET HTTP command.

GET [base]/[type]{?[parameters]{&_format=[mime-type]}}

This searches all resources of a particular type using the criteria represented in the parameters.

Note: Supporting GET means that PHI (Personal health information) might appear in search parameters, and therefore in HTTP logs. For this reason logs should be regarded as being as sensitive as the resources themselves. This is a general requirement irrespective of the use of GET.

The AND search operator allows any combination of parameter expressions using “&”, and will create a valid search expression. For example:

GET [base]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|1008624486&patient.gender=male&patient.birthdate=1929-11-29&issued=ge2016-01-02&code=http://loinc.org|11502-2&_count=10

If the search fails (cannot be executed, not that there is no matches), the return value is a status code 4xx or 5xx, usually with an OperationOutcome. If the search succeeds, OLIS returns a 200 OK HTTP status code and the return content is a Bundle with type = searchset containing the results of the search as a collection of resources in a defined order. The server may also return an OperationOutcome resource within the searchset Bundle entries that contains additional information about the search.

Diagnostic Report Search Response

The relationship between the resources used in DiagnosticReport Search response is below:

OLISFHIRResourcesR4

Specification

The OLIS FHIR Patient Query For Providers is based on the FHIR R4 Search interaction.

Diagnostic Report Search Request

The Diagnostic Report Search Request is an HTTP GET operation with multiple query parameters specified in Supported Search Parameters section below. The syntax of the request is

GET [base]/DiagnosticReport?patient.identifier=[system]|[value]&&patient.birthdate=[date]&issued=[le|ge][date]&code=http://loinc.org|11502-2

Note: For the more details please reference to Supported Search Parameters and Diagnostic Report Search Examples sections

Supported Profiles

Extensions

Supported Search Parameters

Parameter	FHIR Query Parameter	Optionality	Type	Description	Usage Note	Example
Patient Identifer(s)	patient.identifier	mandatory	token	This parameter specifies an identifier associated with the patient who is the subject of this lab report. This can be a health card number (HCN) or Medical Record Number (MRN) and SHALL include both system and value.	MRN system URI is a local identifier that contains the ID of the assigning authority (e.g. lab, hospital, specimen collection centre). For the list of possible MRN system values, please refer to Identifiers page. The patient identifiers are listed in the "Local Identifiers" table marked by "OLIS Patient Identifier generated by xxx".	`[base]/DiangosticReport?patient.identifier=[system]\|[value]` Ontario HCN: `patient.identifier=[id-system-global-base]/ca-on-patient-hcn\|12345678` MRN: `patient.identifier= http://ehealthontario.ca/fhir/NamingSystem/lab/patient-id-lab-license-4004\|1234`
Date of Birth	patient.birthdate	mandatory	date	This parameter specifies the birth date of patient who is the subject of this lab report.	SHALL specify a FHIR date value	`[base]/DiangosticReport?patient.birthdate=1950-01-01`
Report issued start date or Specimen collected date	issued or specimen.collected	mandatory	date	This parameter specifies the report issued date or specimen collected date/time	At least one of the following must be specified: report issued start date or specimen collection date/time. SHALL specify a date value, and MAY contain a date specific prefix. Note: Only `ge` and `le` prefixes are supported for the patient query. Using the wrong prefix will return a HTTP 400 error. For the full list of parameters prefixes and modifiers click here	`[base]/DiangosticReport?issued=[ge]2023-01-01` report issue start date: `issued=ge2016-01-02` report issue start date and end date: `issued=ge2015-02-25&issued=le2016-02-27` or `specimen.collected =ge2016-01-02`
DiagnosticReport Type	code	mandatory	token	This parameter specifies the LOINC code indicating a query to only lab reports.	SHALL contain a fixed LOINC code "11502-2" for "Laboratory Report"	`[base]/DiangosticReport?code=http://loinc.org\|11502-2`
Patient Gender	patient.gender	optional	token	This parameter specifies the gender of the patient associated with the lab report.		`[base]/DiangosticReport?patient.gender=male`
Diagostic Report Identifier	identifier	optional	token	This parameter specifies an identifier for the report.	System and value SHALL be provided.	`[base]/DiangosticReport?identifier=[system]\|[value]` `identifier= [id-system-local-base] /lab/report-id-lab-license-4004\|543321`
Test Request Code	result.based-on:ServiceRequest.code	optional	token	This parameter specifies the test request code associated with the lab report.	system and value SHALL be provided.	`result.based-on:ServiceRequest.code= [code-system-local-base] /lab/test-request-codes\|TR11663-2`
Observation Code	result.code	optional	token	This parameter specifies the lab result code associated with the lab report.	System and value SHALL be provided. When used with other observation search parameters, SHALL use one of the composite search parameters defined below	`[base]/DiangosticReport?result.code=[system]\|[value]` `result.code= http://loinc.org\|2028-9`
Observation Status	result.status	optional	token	This parameter specifies the lab result code associated with the lab report.	This parameter maps to OLIS result status as follow. Since OLIS does not support `registered` and `unknown`, query with these values will return 110 error. - `final` maps to OLIS status value `F` and `Z` - `preliminary` maps to `P` - `cancelled` maps to `X` and `N` - `entered-in-error` maps to `W`	`[base]/DiangosticReport?result.status=final]`
Interpretation	result.interpretation	optional	token		This parameter allows the requestor to further restrict the search criteria to retrieve all abnormal results (AB) or critically abnormal only (CR). The meaning of these values are as follows: - If the abnormal result flag parameter contained “AB”, the query result set is further restricted to orders containing test requests having a test result with an abnormal flag containing (L, H, A, LL, HH, AA) field. - If the abnormal result flag parameter contained “CR”, the query result set is further restricted to orders containing test requests having a test result with an abnormal flag containing (LL, HH, AA) field.	`[base]/DiangosticReport?result.interpretation=AB`
_count				Size limit for response paging	If there is no `_count` in the search request, the server will use the default configuration value of 25 records per page. OLIS has a configurable maximal page size value, which is used if the requested page size is greater than this value. For example, if the page size in the request is _count=100 and the maximal page size is 25, OLIS will return 25 records per page.	`_count=10`
search-id					Server will generate and return an additional parameter search-id as per Server Conformance section.	`search-id= 017-11-16T20:37:03.0000000X128987`
_format				JSON (default) or XML		`format=[mime-type]:_format=application/fhir+json` or `_format=application/fhir+xml`

Paging

The server provides next set for the results of a search interaction for sending continuation links to the client when returning a Bundle. This example shows the next page of a search result:


<Bundle xmlns="http://hl7.org/fhir">
  <!-- snip metadata -->
  <!-- This Search. url starts with base search, and adds the effective
    parameters, and additional parameters for search state. All searches
    SHALL return this value.

	  In this case, the search continuation method is that the server
    maintains a state, with page references into the stateful list.
	-->
  <link>
    <relation value="self">


    <url value="[base]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|1008624486&patient.gender=male&patient.birthdate=1929-11-29&issued=ge2016-01-02&_count=10&search-id=017-11-16T20:37:03.0000000X128987"/>
  </link>

  <link>
    <relation value="next"/>
    <url value="[base]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|1008624486&patient.gender=male&patient.birthdate=1929-11-29&issued=ge2016-01-02&_count=10&search-id=017-11-16T20:37:03.0000000X128987"/>
  </link>

  <!-- then the search results... -->
</Bundle>

A server will inform the client of the total number of resources returned by the interaction for which the results are paged using the Bundle.total.

Managing Search Parameters

This interaction searches a set of resources based on some filter criteria. The interaction can be performed by several different HTTP commands.

GET [base]/[type]{?[parameters]{&_format=[mime-type]}}

This searches all resources of a particular type using the criteria represented in the parameters. All these search interactions take a series of parameters that are a series of name=value pairs encoded in the URL (See W3C HTML forms). If the search fails (cannot be executed, not that there is no matches), the return value is a status code 4xx or 5xx with an OperationOutcome. If the search succeeds, the return content is a Bundle with type = searchset containing the results of the search as a list of resources in a defined order.

Page Count

In order to keep the load on clients, server and the network minimized, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. Page links are contained in the returned bundle as links. Server will provide its own parameters in the links that it uses to manage the state of the search as pages are retrieved. These parameters do not need to be understood or processed by the client. The parameter _count is defined as a hint to the server regarding how many resources should be returned in a single page. Server will not return more resources than requested, but is allowed to return less than the client requested. For example, if _count = 3,

The server might define a configurable default and maximal values for count. The server will repeat the original _count parameter in its returned page links so that subsequent paging requests honor the original _count.

Server Conformance

In order to allow the client to be confident about what search parameters were used as criteria by the server, the server will return the parameters that were actually used to process the search. Applications processing search results SHALL check these returned values where necessary. For example, if the server did not support some of the filters specified in the search, a client might manually apply those filters to the retrieved result set, display a warning message to the user or take some other action. In the case of a RESTful search, these parameters are encoded in the self link in the bundle that is returned:


<link>
    <relation value="self"/>
    <url value="[base]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678"/>
  </link>

In other respects, servers have considerable discretion with regards to supporting search:

Server will declare additional parameter search-id in the profiles referenced from their conformance statements. This search-id will be used for continuation pointer.
Parameter names and URLs are case-sensitive.
Server will choose how many results to return, though the client can use _count as above.

Example

Diagnostic Report Search Example

In the returned header:

[base]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|1008624486&patient.gender=male&patient.birthdate=1929-11-29&issued=ge2016-01-02&code=http://loinc.org|11502-2&_count=10&search-id=017-11-16T20:37:03.0000000X128987

Expected Behavior

See Response Handling page for a complete listig of response codes

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
diagnostics = OperationOutcome.issue.diagnostics

HTTP Status	Scenario Description	severity	code	details.coding.code	details.coding.display	details.text/diagnostics
200 OK	Resource successfully returned
200 OK	No matches
200 OK	Personal health information is blocked by a consent directive	warning	information	980	Warning: Please note your personal health information is blocked by a consent directive that restricts health care providers from viewing this information. Please advise your delegates if you do not want them to share this information with others.	Warning: Please note your personal health information is blocked by a consent directive that restricts health care providers from viewing this information. Please advise your delegates if you do not want them to share this information with others.
200 OK	Order {0} contained a virus	warning	information	924	Warning: Order {0} contained a virus that has been removed.	Warning: Order {0} contained a virus that has been removed.
400 Bad Request	Invalid structure	error	structure	110	The structure and/or content is not valid for the following parameter: '{0}'	The structure and/or content is not valid for the following parameter: '{0}'

Examples of a search response can be found below

Resource	Example
Search result containing a simple chemistry report	XML / JSON
Search result containing a panel test report	XML / JSON
Search result containing a microbiology report with 2 organisms and 2 sensitivity panels	XML / JSON
DiagnosticReport with Contained Resources	XML / JSON
ServiceRequest	XML / JSON
Observation	XML / JSON
Specimen	XML / JSON
Patient	XML / JSON
Practitioner	XML / JSON
Organization	XML / JSON
OperationOutcome	XML / JSON
OperationOutcome when request has invalid fhirVersion	XML / JSON