Search for a Document

Scope

This capability supports the ability to find documents using parameterized queries.

There are two types of query behavior this capability currently supports.

Queries that are intended to return a payload that includes any FHIR resources that match the parameters provided. These types of queries combine search and retrieval but put more strain on the requesting system to manage and filter the volume of content in the response in a way that is more manageable to the user.
Queries that are intended to return a summary of documents that match the parameters provided. These types of queries are often coupled with a separate query for retrieval of the documents the requester wants to receive.

Use Cases

The following CA:FeX use cases leverage this capability:

UC-02 Query and Retrieve Document vRV1

CA:FeX Transactions

This capability describes the FHIR implementation of the CA:FeX Search Data (CA:FeX-2) transaction found in the Sequence Diagram for UC-02: Query and Retrieve Document.

HTTP Operations

This capability can be leveraged using HTTP GET requests and/or HTTP POST. Implementers are expected to familiarize themselves with how searches are executed using the FHIR RESTful API framework.

See Actors and Transactions for more information on the supported HTTP operations.

HTTP GET

In the simplest case, a search is executed by performing a GET operation in the RESTful framework:

GET [base]/[resourcetype]?name=value&...

HTTP POST

For this RESTful search (see definition in RESTful API), the parameters are a series of name=[value] pairs encoded in the URL or as an application/x-www-form-urlencoded submission for a POST:

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

Considerations for Document Search Patterns

There are two considerations that impact which FHIR resources and search parameters will be used in the HTTP request to return documents.

1) whether the clinical data repository uses FHIR Documents (i.e., Bundle.Composition) exclusively to represent retrievable documents, or if it applies a mixed approach to allow FHIR RESTful retrieval of certain documents in binary.

2) the client and/or server preferences for whether all FHIR resources that meet the search criteria are returned as the response payload in the initial CA:FeX Search Data (CA:FeX-2) transaction.

Note: Querying for a CapabilityStatement is a pre-requisite step for implementers that will provide information to the requester on what the responder supports.

Guidance is provided below anticipating that early adopters will likely start with more fundamental patterns of searching for FHIR Documents before expanding their capabilities to perform more nuanced queries as their needs evolve to exchange documents in more sophisticated ways. One known evolution in this regard, is the departure from supporting only FHIR-assembled documents to supporting a hybrid model that can retrieve FHIR Documents alongside documents in legacy formats (e.g., Binary). This evolution requires a different pattern to be applied. These patterns are differentiated below using an enumerated convention (e.g., 2A, 2B).

Document Search Patterns: Fundamental

CA:FeX-2A (Search Against FHIR Assembled Documents Repository)

The simplest method to search for a FHIR Documents is to construct a query (using the parameters identified below) and to submit that query to a [base]/Bundle endpoint using a HTTP GET or POST command.

This will execute a search which will return the results in the HTTP response as a searchset Bundle containing any document Bundle resources that match the criteria of the search. While the endpoint is anchored around Bundle, the expectation is that composition will be included as a base search parameter to narrow the search to FHIR Documents.

Per the FHIR standard on HTTP search interaction:

Because of the way that some user agents and proxies treat GET and POST requests, in addition to the get based search method servers that support search SHALL also support a POST based search
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 - see the FHIR security page for further commentary.
If the search succeeds, the server SHALL return a 200 OK HTTP status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero or more resources in a defined order.
- Note that resources returned in the search bundle MAY be located on another server than the one that performs the search (i.e. the Bundle.entry.fullUrl may be different to the [base] from the search URL)
If the search fails (cannot be executed, not that there are no matches), the return value return value SHALL be a status code 4xx or 5xx with an OperationOutcome. See Response Handling.

Considerations for Document Search Using Bundle Endpoints

Anchoring searches around Bundle in this search pattern is recommended for implementers that want to retrieve all the FHIR resources for any FHIR Documents that meet their search criteria.

Implementers that use this approach should consider using a combination of search parameters to reduce the processing load on responders and requesters.
The result collection can be long, so servers may use paging. If they do, they SHALL use the method described here for breaking the collection into pages if appropriate.

This search pattern does not separate the act of search from retrieval. Clients that want to provide their users the ability to review high level information (lists, summaries, etc.) for matching documents to support selective retrieval of the desired FHIR Document bundles will need to utilize different search patterns or manage this behavior in the client's user interface.

Note: Due to limitations in querying for discrete resources when the document is loaded as a FHIR Document bundle, performing searches against Composition or other contained resources (e.g., using Patient resource id) will only work for repositories that a) decompose the resources within the submitted bundles, or b) enable the submission of the contents of the document at their individual endpoints or through a transaction bundle so that they might be retrievable. This approach requires significant caution - implementers should be well versed in the Document Handling Obligations before considering either approach. Guidance on both mechanisms is outside the scope of this specification.

Document Search Patterns: Intermediate

CA:FeX-2B (Search Against Hybrid Documents Repository)

Implementers are encouraged to incorporate search patterns that allow for more comprehensive support for both FHIR-assembled and FHIR-enabled documents.

Industry-leading implementations like the US Core and International Patient Access (IPA) are promoting the use of resources like DocumentReference to offer implementers a single way to return pointers to document content, wherever it is stored and irrespective of the format (e.g., binary or FHIR-assembled).

This pattern anchors searches around [base]/DocumentReference using the HTTP GET or POST command.

In this pattern, DocumentReference acts as a metadata shell that provides additional information (beyond Composition elements) that supports finding of desired document(s).

This pattern will be fleshed out further in future releases.

Considerations for Document Search Using DocumentReference Endpoints

This pattern provides an effective option to implementers who would prefer to retrieve a list of potential documents without having to retrieve the documents in their entirety. However, use of DocumentReference is not limited to this use case and can return FHIR Binary resources in the attachment content.

While not in the current scope of this specification, parameters like _include are currently being used by some implementations to return the referenced FHIR resources alongside the DocumentReference.

Implementations like US Core are also actively testing the use of $docRef operation to support the generation of DocumentReference resources on-the-fly to support a single method of query in sources that may not have DocumentReferences for the desired FHIR Documents. See Cutting Edge Capabilities section below.

Document Search Patterns: Supported Search Parameters

The following search parameters are used generically to support document retrieval. These will continue to evolve as new use cases and requirements are identified.

Additional search parameters that are specific to the requirements for a specific use case or IGuide may be further defined by those implementations. See Option 2 - FHIR Health Information Exchange (HIE) Pattern Using CA:FeX in the pan-Canadian Patient Summary (PS-CA) Specification for details and examples of how the parameters below are used to retrieve patient summaries.

Query Search Parameters	Applied to	Description
composition	bundle.composition	This parameter, of type reference, specifies the first resource in the bundle, if the bundle type is "document" - this is a composition, and this parameter provides access to search its contents using chaining. See FHIR Chaining Parameters search methodology.
timestamp	bundle.timestamp	This parameter, of type date, specifies the timestamp when the FHIR bundle was created. See FHIR http://hl7.org/fhir/R4/search.html#date for use of the date search type.
patient.identifier	bundle.composition.patient.identifier documentReference.patient.identifier	This parameter, of type token, specifies an identifier associated with the patient to which the document is assigned. This use of patient.identifier follows the FHIR Chaining Parameters search methodology.
type	bundle.composition.type documentReference.type	This parameter, of type token, specifies the kind of document (LOINC if possible). The use of bundle.composition.type follows the FHIR Chaining Parameters search methodology, whereas type can be applied directly in documentReference searches.
author	bundle.composition.author documentReference.author	This parameter, of type reference, specifies who and/or what authored the document. The use of bundle.composition.author follows the FHIR Chaining Parameters search methodology, whereas author can be applied directly in documentReference searches.
date	bundle.composition.date documentReference.date	This parameter, of type date, specifies when this document reference was created. The use of bundle.composition.date follows the FHIR Chaining Parameters search methodology, whereas date can be applied directly in documentReference searches.

Cutting Edge Capabilities

FHIR Operations

FHIR Operations are used (a) where the server needs to play an active role in formulating the content of the response, not merely return existing information, or (b) where the intended purpose is to cause side effects such as the modification of existing resources, or creation of new resources.

This specification does not currently define any custom operations for the Search for a Document Capability. However, a number of existing operations exist that can support the search for a document. These have been listed below for implementers to test and provide feedback on.

Return the Latest Summary for a Patient

This operation is being tested by IPS, for Patient Summary documents, but could be applied generically for other types of documents. The operation asks for the latest appropriate summary, whether that already exists, or must be newly generated. Unless otherwise specified, the server has discretion to choose how to fulfill the request.

Generate a Document Bundle using $document Operation

This operation is particularly helpful for systems that are not persisting the document Bundle that houses the Composition and its referenced resources.

Fetch Document Reference using $docref Operation

This operation is most helpful for implementers using DocumentReference as a primary method for querying for a list of documents and information about their format (binary, composition, etc.) and endpoint (See DocumentReference resource). This operation is used by US Core and International Patient Access implementations. It is primarily used to find or generate a bundle containing the DocumentReference resources that meet the specified parameters.

Page tree