Profiles & Operations Index >Medication Dispense Search

Operation: MedicationDispense Search

Search Medication Dispenses and Pharmacy Services

MedicationDispense search is simple RESTful interactions. It supports retrieving dispenses handed over within a date range or on a specific date for a consumer by patient ID. The interaction can be performed by using either GET or POST HTTP commands.

GET [base]/[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, DHDR also supports a POST based search:

POST [base]/[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]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&whenprepared=ge2019-02-24

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, DHDR 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.

This project does not implement all FHIR search capabilities as they are not needed for this project. For more information about FHIR search capabilities refer to this page: https://www.hl7.org/fhir/search.html.

**Transaction: Search Medication Dispense Query/Response**

Medication Dispense Search

Allow a client application to search the DHDR repository for MedicationDispense records matching the search criteria
Allow the DHDR solution to return an appropriate set of MedicationDispense records

Search Medication Transaction

Use Case Category: Search Medication Dispense

This describes the use case category for searching for medication dispense information, based on a patient’s Health Number, and optional search criteria. Please note that in the current release, Health Number is the only patient identifier supported for searches, but in the future releases, multiple identifier types might be allowed as query parameters, e.g. a point of care system might get all identifiers associated with a patient from the Provincial Client Registry or from a local EMPI and then search DHDR for all dispenses of a patient using these identifiers.

Search Types: Search by Health Number (and optional range of dispense dates)

Scenario Details: The User of the client application requests retrieval of medication dispense information, using Health Number and optional search criteria as query parameters.

Message Flow:

“GET” or “POST” MedicationDispense search request is sent from the client application to DHDR (via the Gateway), containing query criteria in the URL string.
DHDR (via the Gateway) responds with the search results, in the form of a FHIR Bundle response.

Alternate Flow of Events:

Unable to process the request due to a system-related or business-related issue, the Gateway responds with an HTTP status code, and optionally an OperationOutcome resource.

If no MedicationDispense records are found within the default or the specified date range, then the Gateway will return a bundle with zero search results.

Specification

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

MedicationDispense Search Request

The MedicationDispense 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]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678& whenprepared=ge2018-02-24&whenprepared=le2019-02-26&_sort=-whenprepared&_count=10

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

Medication Dispense Profiles

Extensions

Supported Search Parameters

Query Search Parameters	Description	Usage Note	Example
patient.identifier	Patient ID is a mandatory parameter. Only Ontario Health Number is allowed as a Patient ID parameter in the current release.	Please note that Health Number Version is not supported. DHDR uses Ontario Health Number for unique identification of a patient while a version number is usually used for verification of the provincial coverage eligibility, which is out of scope for DHDR	`patient.identifier=[id-system-global-base/ca-on-patient-hcn\|12345678`
whenprepared	Optional date parameter	If there is no lower limit in the search request, the server will use a configured default, e.g. 120 days back. Note: The following prefixes can be used for the date parameter: eg, gt, lt, ge and le. If no prefix is present, the prefix eq is assumed. For the full list of parameters prefixes and modifiers click here	`whenprepared=gt2018-02-24` `whenprepared=ge2018-02-25&whenprepared=le2019-02-27`
_sort	Sort order only by whenprepared parameter	If not indicated in the request, the default sort order is by whenprepared descending	`_sort=whenprepared` (ascending) `_sort=-whenprepared` (descending)
_count	Size limit for response paging	If there is no _count in the search request, the server will use a configurable default page size, e.g. 50. DHDR 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=2000` and the maximal page size is 1000, DHDR will return 1000 dispense records per page.	`_count=10`
_summary	The parameter requests the server to return a subset of the resource.	DHDR supports only count (search only: just return a count of the matching resources, without returning the actual matches) and false (return all parts of the resource(s)) The intent of the _summary parameter is to reduce the total processing load on server, client, and resources between them such as the network. The purpose of the summary form is to allow a client to quickly retrieve a large set of resources, and let a user pick the appropriate one. The summary for an element is defined to allow a user to quickly sort and filter the resources, and typically omit important content on the basis that the entire resource will be retrieved when the user selects a resource. Server will mark the resources with the tag SUBSETTED to ensure that the incomplete resource is not accidentally used to overwrite a complete resource	`_summary=count` Note: Count of records (no records would be returned)
search-id	Server will generate and return an additional parameter search-id, as per Paging section below.		`search-id=76395924-28c2-4cb1-93c1-608fb6eea979`
format	JSON (default) or XML		`format=[mime-type]:_format=application/fhir+json or _format=application/fhir+xmlL`

Paging

The server provides paging for the results of a search interaction, and conforms to method adapted from RFC 5005 (Feed Paging and Archiving) for sending continuation links to the client when returning a Bundle.

This example shows the third 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]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&whenprepared=ge2015-02-24&whenprepared=le2016-02-26&_sort=-whenprepared&_count=10&search-id=76395924-28c2-4cb1-93c1-608fb6eea979&page=3"/>
  </link>

  <link>
    <relation value="next"/>
    <url value="[base]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&whenprepared=ge2015-02-24&whenprepared=le2016-02-26&_sort=-whenprepared&_count=10&search-id=76395924-28c2-4cb1-93c1-608fb6eea979&page=4"/>
  </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. Please refer to the "Bundle Example" section, which shows use of Total and to the text in “Bundle Resource” section, which provides detailed explanation of Total.

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:

<link>
    <relation value="self"/>
     <url value="[base]/MedicationDispense?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 generated for each search request, logged in audit database along with the search request & search response and returned to the client, who is expected to log this in their audit database too.
Parameter names and URLs are case-sensitive.
Server will choose how many results to return, though the client can use _count as described below.
Server will choose how to sort the return results, though it will honor the _sort parameter.

Sorting

The client can indicate which order to return the results by using the parameter _sort, which can have a value of one of the search parameters. The _sort parameter can repeat to indicate sort order, with the repeats indicating a lower sort priority sequentially. In the current release, only sorting by whenprepared (dispense date) is supported. Each item in the comma separated list is a search parameter, optionally with a '-' prefix. The prefix indicates decreasing order; in its absence, the parameter is applied in increasing order. E.g.: sort=-whenprepared

Note:

The server returns the sort it performs as part of the returned search parameters (see below).
A search parameter can refer to an element that repeats, and therefore there can be multiple values for a given search parameter for a single resource. In this case, the sort is based on the item in the set of multiple parameters that comes earliest in the specified sort order when ordering the returned resources.
When sorting on string search parameters, sorting will be performed on a case-insensitive basis. Accents will be ignored.

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. The server might define a configurable default and maximal values for count in the future release. The server will repeat the original _count parameter in its returned page links so that subsequent paging requests honor the original _count.

Note: The combination of _sort and _count can be used to return only the latest resource that meets a particular criteria - set the criteria, and then sort by date in descending order, with _count=1. This way, the last matching resource will be returned.

Examples

Medication Dispense Search Example

Search by patient identifier & dates

GET [base]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&whenprepared=ge2018-02-24&whenprepared=le2019-02-26&_sort=-whenprepared&_count=10

In the returned Bundle, bundle.link (self) will contain an URL with a server-generated search-id value: [base]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&whenprepared=ge2018-02-24&whenprepared=le2019-02-26&_sort=-whenprepared&_count=10&search-id=76395924-28c2-4cb1-93c1-608fb6eea979

Get the count of records

GET [base]/MedicationDispense?patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&whenprepared=ge2018-02-24&whenprepared=le2019-02-26&_summary=count

Search using POST

POST [base]/MedicationDispense/_search?_count=10&_format=application/fhir+json Content-Type: application/x-www-form-urlencoded patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678& whenprepared=ge2018-02-24&whenprepared=le2019-02-26&_sort=-whenprepared

Expected Behaviour

See Response Handling page for a complete listing of response codes

Operation	Validation	HTTP Response Code	OpOutcome Code	OpOutcome Severity	OperationOutcome.details.text&OperationOutcome.text
MedicationDispense Search	Success - Return resources	200
MedicationDispense Search	HTTP (Gateway) request author header is missing	400	required	error	HTTP (Gateway) request authorization header is missing
MedicationDispense Search	Gateway header content is invalid	400	structure	error	Gateway authorization header content is invalid
MedicationDispense Search	Gateway medications context header is missing transaction identifier	400	required	error	HTTP (Gateway) request transaction identifier is missing
MedicationDispense Search	Gateway medications context header is missing login identifier	400	required	error	Gateway authorization header is missing SUB identifier
MedicationDispense Search	Missing patient identifier	400	required	error	Missing mandatory search parameter: patient identifier
MedicationDispense Search	Invalid patient identifier	400	value	error	Invalid search parameter: patient identifier
MedicationDispense Search	Invalid patient identifier type	400	value	error	Invalid search parameter: patient identifier type
MedicationDispense Search	Invalid dispense date	400	value	error	Invalid search parameter: dispense date
MedicationDispense Search	No matches	200	not-found	information	Not found: Medication Dispenses matching search parameters
MedicationDispense Search	Unhandled Exception	500
MedicationDispense Search	X-GtwyOriginalRequestUriMasked missing	400	required	error	HTTP (Gateway) request Original Request Uri Masked is missing.

Examples of a search response

Resource	Example
Medication	XML / JSON
Bundle (Medication Dispense Contained Resources)	XML / JSON
Organization (Dispensing Pharmacy)	XML / JSON
Patient	XML / JSON
Practitioner (Prescriber)	XML / JSON
Practitioner (Dispensing Pharmacist)	XML / JSON
OperationOutcome	XML / JSON
OperationOutcome (COVax_ON)	XML / JSON