Profiles & Interactions Index > Search DiagnosticReport - COVID Query

Interaction: Search DiagnosticReport - COVID Query

DiagnosticReport search is simple RESTful interaction. It supports retrieving lab results from OLIS for specific disease such as COVID19. This query is also known as OLIS bulk query or CCM query as it is used by Ministry's Contact Tracing and Management solution.

Note: This query should only be used by public health units.

Scope

This transaction involves a request by the following parameters:

The mandatory parameters for the query:

  • Start Date

The OAuth token must also contain the COVID19 scope. The scope value must include "filter/covid-19".

The optional parameters for the query:

  • Maximum number of records to return

Specification

The OLIS FHIR COVID Query is based on the HL7 FHIR R4 Search operation.

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?&issued=(le|ge|gt|lt)[date][&_count=[num]]

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

Diagnostic Report Search Response

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

OLISFHIRResourcesR4

Extensions

Supported Search Parameters

GET DiagnosticReport (return all COVID19 results issued after specific date)

Parameter FHIR Query Parameter Optionality Type Description Usage Note Example
issued issued mandatory date This parameter specifies the report issued date SHALL specify a date value, and MAY contain a date specific prefix.
Note: Only four prefixes ge, le, gt, and lt are supported for date related parameters. Using the wrong prefix will return a HTTP 400 error. For the full list of parameters prefixes and modifiers click here 		issued=gt2016-01-02

issued=gt2015-02-25&issued=lt2016-02-27

Note: To search for all COVID-19 reports that occurred between Jan 1, 2020 and December 31, 2020 (not including these dates) :

GET [base]/Patient/DiagnosticReport?issued=gt2020-01-01&issued=lt2020-12-31
_count optional Size limit for response paging If there is no _count in the search request, the server will return all matching records in one response. _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

Note: OLIS FHIR COVID query (i.e. Bulk query, CCM query) does not support _format parameter. Including it will result an error. All results will be returned in JSON format only.

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.

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.

Example

Diagnostic Report Search Example

GET [base]/DiagnosticReport?issued=gt2016-01-02&_count=10

In the returned header:

[base]/DiagnosticReport?&issued=gt2016-01-02&_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 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

Resource Example
DiagnosticReport example representing a positive COVID report XML / JSON
Bundle example representing searchset with one positive COVID Report XML / JSON
Patient with Anonymous Identifier XML / JSON