For a full list of available versions, see the Directory of published versions

4.1.2. Search Immunization Document Bundle

4.1.2.1. Usage

This interaction is a standard FHIR RESTful search performed against the Bundle resource. The IR responds with a FHIR Bundle of type=document. The first entry in the bundle will always be a Composition resource conforming to the EHR Composition Document profile, which links together all relevant Immunization, Patient, PractitionerRole, and Location resources into a single cohesive document.

Interaction: SEARCH Resource: Bundle HTTP Request: GET [base]/Bundle?patient.identifier=[system]|[value]&type=document

Actor: Client Application
Role: Requests an immunization document bundle from the IR Solution based on specified search criteria.

Actor: IR Solution
Role: Receives, authenticates, validates, and stores incoming immunization document bundles from the Client Application.

4.1.2.2. Parameters

The following search parameters are supported for this interaction.

4.1.2.3. 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.
If no page size is specified in the search query, the default page size will be 50 records. The maximum number of records returned in a page is 100. (_count)

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=-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=-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.

4.1.2.4. 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.

4.1.2.4.1. 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 occurrence (administration 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=-date

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.

4.1.2.4.2. 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.

The maximum number of records returned in a page is 100. (_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.

4.1.2.5. Search Examples

Example 1: Basic Search by Patient Health Card Number Retrieve all immunization records for a patient using their Ontario Health Card Number (HCN). GET [base]/Bundle?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890&type=document

Example 2: Search with date Filter Retrieve immunization records for a patient that were administered on or after January 1, 2023. GET [base]/Bundle?patient.identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn|1234567890&type=document&date=ge2023-01-01

Example 3: Search by Ontario Immunization ID (OIID) Retrieve immunization records using the unique provincial identifier used by Panorama. GET [base]/Bundle?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-panorama-mrn|OIID12345&type=document

Example 4: Search by Pharmacy Medical Record Number (MRN) Retrieve immunization records using the unique pharmacy-specific unique identifier. GET [base]/Bundle?patient.identifier=http://ehealthontario.ca/fhir/NamingSystem/id-pharmacy-mrn|1234P98765ABCD0123&type=document

4.1.2.6. Expected Behavior

The following table details the comprehensive list of expected HTTP Response Codes and corresponding OperationOutcome details for various scenarios, including both clinical business rules and gateway-level access controls:

4.1.2.7. Notes

• Pagination: Standard FHIR pagination using the _count parameter and Bundle.link elements is supported for payloads that exceed the maximum bundle size limits.