Profiles & Interactions > Profiles & Interactions

Interaction: Search DiagnosticReport

Search DiagnosticReport

DiagnosticReport search is simple RESTful interactions. It supports retrieving diagnostic reports by identifier, code, patient ID and other parameters. The interaction can be performed by using either GET or POST HTTP commands.

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

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

Because of the way that some user agents and proxies treat GET and POST requests, in addition to the GET based search method above, CorHealth also supports a POST based search:

POST [base-search]/[type]/_search{?_format=[mime-type]}

Content-Type: application/x-www-form-urlencoded

param1=value&param2=value

This has exactly the same semantics as the equivalent GET command.

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.

All these search interactions take a series of parameters that are a series of name=value pairs encoded in the URL (or as an application/x-www-form-urlencoded submission for a POST).

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

GET [base-search]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&code=http://loinc.org|34133-9&identifier=[id-system-local-base]/diagnostic-report-id|22334455&_include=*&_revinclude=*

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, CorHealth 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 result collection can be long, so server may use paging (adapted from RFC 5005 Feed Paging and Archiving) for breaking the collection into pages if appropriate (see Paging section below). The server may also return an OperationOutcome resource within the searchset Bundle entries that contains additional information about the search.

Interaction Diagram

CorHealth_Search

Search DiagnosticReport Interaction


Actor: Client Application

Role: Requests a set of DiagnosticReport resources from the CorHealth Solution based on specified search criteris.

Actor: CorHealth Solution

Role: Returns a Bundle containing DiagnosticReport and other resoruces (if indicated in the request) that match the search criteria specified by the Client Application.

Specification

The FHIR CorHealth specification is based on the HL7 FHIR R4 Search operation.

DiagnosticReport Search Request

The DiagnosticReport 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-search]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&code=http://loinc.org|34133-9&identifier=[id-system-local-base]/diagnostic-report-id|22334455&_include=*&_revinclude=*

Note: For more details please reference Supported Search Parameters and Search Examples sections

Supported Profiles

Extensions

HealthcareService Period

MRN System URI

Supported Search Parameters

All search parameters defined in the FHIR standard for the DiagnosticReport resource and all the referenced resources when these gets requested using "_include" or "_revinclude" in the search request as well as new search parameters define in this IG.

New Search Parameters defined in this IG

Procedure.report

ServiceRequest.supportingInfo

Managing Returned Resources

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:

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

  • Parameter names and URLs are case-sensitive.
  • Server will choose how many results to return, though the client can use _count as described in the FHIR standard.
  • Server will provide a link to fetch the next page of results.
  • Server will choose how to sort the return results, though it will honor the _sort parameter.

Example

GET [base-search]/DiagnosticReport?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&code=http://loinc.org|34133-9&identifier=[id-system-local-base]/diagnostic-report-id|22334455&_include=*&_revinclude=*

Expected Behaviour

See Response Handling page for a complete listing 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 information not-found Not found: DiagnosticReport matching search parameters
400 Bad Request HTTP (Gateway) request author header is missing error required HTTP (Gateway) request authorization header is missing
400 Bad Request Gateway header content is invalid error structure Gateway authorization header content is invalid
400 Bad Request Gateway context header is missing transaction identifier error required HTTP (Gateway) request transaction identifier header is missing
400 Bad Request Gateway context header is missing UAO identifie error required Gateway authorization header is missing UAO identifier
400 Bad Request Gateway context header is missing UAO identifier type error required Gateway authorization header is missing UAO identifier type
400 Bad Request Gateway context header is missing NAME identifier error required Gateway authorization header is missing SUB identifier
400 Bad Request Invalid search parameter error value Invalid search parameter: parameter-name
400 Bad Request X-GtwyOriginalRequestUriMasked missing error required HTTP (Gateway) request Original Request Uri Masked is missing
400 Bad Request Gateway authorization header is missing ISS error required Gateway authorization header is missing ISS identifier
429 Too Many Requests Rate Limit error exception Too Many Requests
500 Internal Server Error Unhandled Exception fatal exception Internal Error