Profiles & Operations Index > Search Medication Document Bundle
Operation: Search Medication Document Bundle
Search Medication Dispenses, Medication Administration and Pharmacy Services
Medication search is simple RESTful interactions. It supports retrieving medictaion dispenses or medication administrations within a date range or on a specific date for a consumer by patient ID and date of birth. 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, DHDR also supports a POST based search:
POST [base-search]/[type]/_search{?_format=[mime-type]}
Content-Type: application/x-www-form-urlencoded
param1=value¶m2=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]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationdispense.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.
Interaction Diagram
Search Medication Document Bundle Transaction
Actor: Client Application
Role: Requests a set of Medication Documents from the DHDR Solution based on specified search criteris.
Actor: DHDR Solution
Role: Returns a Bundle Document containing MedicationDispense or Medication Administration that match the search criteria specified by the Client Application.
Specification
The FHIR DHDR specification is based on the HL7 FHIR R4 Search operation.
Medication Document Bundle Search Request
The Medication Document Bundle 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]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared&_count=10
Note: For more details please reference Supported Search Parameters and Search Examples sections
Supported Profiles
| Profile | MedicationDispense Scenario | MedicationAdministration Scenario |
|---|---|---|
| Bundle (SearchResult) | ✓ | ✓ |
| Bundle (Document) | ✓ | ✓ |
| Composition (MedicationDispense) | ✓ | |
| Composition (MedicationAdministration) | ✓ | |
| Medication Dispense | ✓ | |
| Medication Administration | ✓ | |
| Medication | ✓ | ✓ |
| Medication Request (Prescription) | ✓ | ✓ |
| Patient | ✓ | ✓ |
| Practitioner | ✓ | ✓ |
| Organization | ✓ | ✓ |
| PractitionerRole | ✓ | ✓ |
| Location | ✓ | |
| Encounter | ✓ | |
| OperationOutcome | ✓ | ✓ |
Extensions
| Extentsion | MedicationDispense Scenario | MedicationAdministration Scenario |
|---|---|---|
| ca-on-medications-ext-quantity-remaining (Dispense Remaining Quantity Extension) | ✓ | |
| ca-on-medications-ext-refills-remaining (Dispense Remaining Refills Extension) | ✓ | |
| ca-on-medications-ext-compound-indicator (Drug Compound Indicator Extension) | ✓ | ✓ |
| ca-on-medications-ext-monitored-drug-indicator (Monitored Drug Extension) | ✓ | ✓ |
Supported Search Parameters
| Query Search Parameters | Description | Usage Note | Example |
|---|---|---|---|
| composition.patient.identifier | Patient ID is a mandatory parameter. Ontario health card number (HCN), Medical Record Number (MRN) or ECID (Ontario Enterprise Client ID ) are allowed as a Patient ID parameter. | Please note that Health Number Version is not supported. DHDR uses Ontario health card 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 | composition.patient.identifier=[id-system-global-base/ca-on-patient-hcn|12345678 composition.patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-pharmacy-mrn|123456-987654321 composition.patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-general-ottawa-hospital-mrn|12345678composition.patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-pcr-eid|12345678 |
| composition.patient.gender | Optional gender parameter | This parameter should contain the sex at birth as noted on the Ontario health card | composition.patient.gender=female |
| composition.patient.birthdate | Mandatory birth date parameter | This parameter should contain the Date of Birth of the patient as on the Ontario health card | composition.patient.birthdate=1971-11-28 |
| composition.type | This is a mandatory parameter specifies the type of document | composition.type=http://loinc.org|29550-1 (Medication Dispense) composition.type=http://loinc.org|80565-5 (Medication Administration) |
|
| composition.medicationdispense.whenprepared (applies for MedicationDispense only) |
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 |
composition.medicationDispense.whenprepared=gt2018-02-24 composition.medicationdispense.whenprepared=ge2018-02-25&composition.medicationdispense.whenprepared=le2019-02-27 |
| composition.medicationadministration.effective-time (applies for MedicationAdministration only) |
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 |
composition.medicationadministration.effective-time=gt2018-02-24 composition.medicationadministration.effective-time=ge2018-02-25&composition.medicationadministration.effective-time=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=composition.medicationdispense.whenprepared (ascending) _sort=-composition.medicationdispense.whenprepared (descending)_sort=composition.medicationadministration.effective-time (ascending) _sort=-composition.medicationadministration.effective-time (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 |
| _format | JSON (default) or XML | _format=application/fhir+xml |
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-search]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared&_count=10"/>
</link>
<link>
<relation value="next"/>
<url value="[base-search]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared&_count=10&_&[url will be provided by server]"/>
</link>
<!-- then the search results... -->
</Bundle>
The Bundle will only contain the first page of results. The URL marked next provides a link to fetch the next page of results. This allows client applications to fetch data in manageable amounts, which improves performance in many cases.
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-search]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28"/>
</link>
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 below.
- 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.
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.
Example
Medication Dispense Bundle Document Search Example
- Search by patient identifier, date of birth & dates
GET [base-search]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared&_count=10
In the returned Bundle, bundle.link (self) will contain a server-generated URL link to the next page: [base-search]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared&_count=10&[server-generated URL]
- Search with date of birth and gender
GET [base-search]/Bundle?composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.patient.gender=female&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared&_count=10
- Search using POST
POST [base-search]/Bundle/_search?_count=10&_format=application/fhir+json Content-Type: application/x-www-form-urlencoded composition.type=http://loinc.org|29550-1&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.patient.gender=female&composition.medicationdispense.whenprepared=ge2019-02-24&composition.medicationdispense.whenprepared=le2019-02-26&_sort=-composition.medicationdispense.whenprepared
Medication Administration Bundle Document Search Example
- Search by patient identifier, date of birth & dates
GET [base-search]/Bundle?composition.type=http://loinc.org|80565-5&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationadministration.effective-time=ge2018-02-24&composition.medicationadministration.effective-time=le2019-02-26&_sort=-composition.medicationadministration.effective-time&_count=10
In the returned Bundle, bundle.link (self) will contain a server-generated URL link to the next page: [base-search]/Bundle?composition.type=http://loinc.org|80565-5&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationadministration.effective-time=ge2018-02-24&composition.medicationadministration.effective-time=le2019-02-26&_sort=-composition.medicationadministration.effective-time&_count=10&[server-generated URL]
- Search with date of birth and gender
[base-search]/Bundle?composition.type=http://loinc.org|80565-5&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.patient.gender=female&composition.medicationadministration.effective-time=ge2018-02-24&composition.medicationadministration.effective-time=le2019-02-26&_sort=-composition.medicationadministration.effective-time&_count=10
- Search using POST
POST [base-search]/Bund/_search?_count=10&_format=application/fhir+json Content-Type: application/x-www-form-urlencoded composition.type=http://loinc.org|80565-5&composition.patient.identifier=[id-system-global-base]/ca-on-patient-hcn|12345678&composition.patient.birthdate=1971-11-28&composition.medicationadministration.effective-time=ge2018-02-24&composition.medicationadministration.effective-time=le2019-02-26&_sort=-composition.medicationadministration.effective-time
Please note that “OperationOutcome Example - Consent" section provides an example of the OperationOutcome resource that would appear in a bundle if there are any records blocked due to a consent directive.
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 | information | not-found | Not found: Medication Document matching search parameters | ||
| 200 OK | Patient has temporarily unblocked access | information | information | Patient has temporarily unblocked access to view and use drug and pharmacy service information. OperationOutcome diagnostics CONSENT_TEMP_UNBLOCK |
||
| 200 OK | Medication Dispense is blocked by consent directive | warning | suppressed | Access to Drug and Pharmacy Service Information has been blocked by the Patient. OperationOutcome diagnostics CONSENT_EXISTS |
||
| 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 medications context header is missing transaction identifier | error | required | HTTP (Gateway) request transaction identifier header is missing | ||
| 400 Bad Request | Gateway medications context header is missing UAO identifie | error | required | Gateway authorization header is missing UAO identifier | ||
| 400 Bad Request | Gateway medications context header is missing UAO identifier type | error | required | Gateway authorization header is missing UAO identifier type | ||
| 400 Bad Request | Gateway medications context header is missing NAME identifier | error | required | Gateway authorization header is missing SUB identifier | ||
| 400 Bad Request | Missing patient identifier | error | required | Missing mandatory search parameter: patient identifier | ||
| 400 Bad Request | Invalid patient identifier | error | value | Invalid search parameter: patient identifier | ||
| 400 Bad Request | Invalid patient identifier type | error | value | Invalid search parameter: patient identifier type | ||
| 400 Bad Request | Invalid dispense date | error | value | Invalid search parameter: dispense date | ||
| 400 Bad Request | Invalid effective date | error | value | Invalid search parameter: effective date | ||
| 400 Bad Request | Invalid patient's date of birth | error | value | Invalid search parameter: patient's date of birth | ||
| 400 Bad Request | Invalid patient's gender | error | value | Invalid search parameter: patient's gender | ||
| 400 Bad Request | Invalid composition type | error | value | Invalid search parameter: composition type | ||
| 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 | ||
| 404 Not Found | HCN is not found in PCR | error | not-found | Not found: ECID for requested Patient ID | ||
| 429 Too Many Requests | Rate Limit | error | exception | Too Many Requests | ||
| 500 Internal Server Error | Unhandled Exception | fatal | exception | Internal Error |
Examples of a search response
| Resource | Example |
|---|---|
| Bundle Document Medication Dispense Response | XML / JSON |
| Bundle Document Medication Administration Response | XML / JSON |
| OperationOutcome | XML / JSON |
| OperationOutcome (Consent Block) | XML / JSON |
| OperationOutcome (Temporary Consent Unblock) | XML / JSON |