Pan-Canadian FHIR Exchange (CA:FeX) IGuide

Document Exchange

HL7 characterizes a document by the following properties:

Persistence – Documents are persistent over time. The content of the document does not change from one moment to another. A document represents information stored at a single instance in time.
Wholeness - A document is a whole unit of information. Parts of the document may be created or edited separately, or may also be authenticated or legally authenticated, but the entire document is still to be treated as a whole unit.
Stewardship - A document is maintained over its lifetime by a custodian, either an organization or a person entrusted with its care.
Context - A clinical document establishes the default context for its contents.
Potential for authentication - A clinical document is an assemblage of information that is intended to be legally authenticated. This specification defines a document as a record (written, printed or electronic) that compiles information about a patient's care for a particular purpose or workflow. Documents are distinct from the medical data that may be included in the document as they provide an additional layer of context and metadata around how and why the pieces of medical data were compiled.

Examples of documents include discharge summaries, history & physical notes, medical imaging reports, patient summaries, and more.

This specification has listed the Document Exchange Framework as one of the exchange paradigms. While HL7 FHIR defines a format for documents that are authored and assembled in FHIR (See FHIR Composition Resource), it is important to acknowledge that FHIR can be used to exchange documents that are constructed in other formats (e.g., FHIR Binary).

This specification has been developed and refined to support an initial round of implementers who will use its transactions to exchange the pan-Canadian Patient Summary (PS-CA) in the form of a FHIR Document. In choosing PS-CA as initial proving ground, this specification has been able to identify and address requirements that are expected to be extrapolated to other types of FHIR Documents.

Note: Prior version of this specification includes the information for the supported transactions (CA:FeX 1, CA:FeX 2A, and CA:FeX 3A) and Use Cases and Definitions.

Exchanging Documents Using RESTful APIs

Documents exchanged using RESTful APIs leverage the syntax and notation identified in RESTful API Interactions.

Often, documents that are exchanged via FHIR RESTful APIs include information that exists across multiple FHIR resources. The structure of the documents being exchanged (e.g., FHIR Binary Resource, Bundle with Composition and compiled resources, DocumentReference that points to these resources) has a direct impact on the endpoints, parameters, and operations that are used.

This guide provides detailed information for the following transactions:

Transaction ID	Description
CA:FeX-1	Submit Data
CA:FeX-2A	Search Against FHIR Assembled Documents Repository
CA:FeX-2B	Search Against Hybrid Documents Repository
CA:FeX-3A	Retrieve Document From FHIR Assembled Documents Repository
CA:FeX-3B	Retrieve Document From Hybrid Documents Repository

CA:FeX-1: Submit Data - Documents

Document Submit Patterns

The optimal document submission pattern for any given implementation is determined by a number of factors. These factors include (but are not limited to): presence/absence of XDS and XCA architecture, organizational short-term and long-term goals for FHIR, current assets and prioritized capabilities, role in the health exchange ecosystem, readiness of contributing actors to adopt FHIR, etc.

The patterns discussed below only apply to Data Recipients that are expecting Data Sources to submit documents using FHIR endpoints.

Some implementers may choose to use the data received through existing workflows and transform it into FHIR, particularly if their electronic medical record systems are not ready to exchange data in FHIR. Other implementations may allow for a FHIR Document to be created "on-demand" in response to a query - both are perfectly legitimate practices that do not require a submission endpoint.

HTTP Operations

This capability can be leveraged using HTTP POST requests. Implementers are expected to familiarize themselves with how create interactions are executed using the FHIR RESTful API framework.

Direct Submissions of FHIR Document Bundle

FHIR Documents are Bundle resources with the type of "document" and which contain a Composition resource as the first entry, and key referenced resources as additional Bundle entries.

Data Recipients that want to receive FHIR Documents from Data Sources need to at a minimum support the submission of the FHIR Document Bundle to a HTTP POST request to a Bundle endpoint.

This will create the new Bundle resource in a server-assigned location with a server assigned id for the Bundle resource. (Note: this transaction pattern does not support conditional create which allows the resource to be created only if it does not already exist on the server).

$generate-metadata Operation

As an optional capability, data recipients should also support the $generate-metadata operation on a DocumentReference endpoint. This operation enables the creation of the document Bundle and DocumentReference resources in server-assigned locations with server-assigned ids for both resources. When a Bundle is created, the server SHOULD create a DocumentReference as a side effect to enhance document retrieval capabilities.

Considerations for Document Submission Using Bundle Endpoints

Two key attributes of FHIR Documents submitted to the Bundle endpoint are (with limited exceptions):

Self-contained—All of the primary resources used in the document must be included in the document (see Composition in the FHIR standard); other resources used in the document should also be included.
Point-in-time—The entire document is stored under the [base]/Bundle endpoint, and the content is not (generally) updated. If the Data Recipient actor, which supports the /Patient endpoint outside of this transaction, updates an address in a Patient resource under /Patient, a Patient resource inside a Document would not be expected to reflect that.

Submission of a FHIR Document to a Bundle endpoint is not enough on its own for this pattern to be effectively used for document lifecycle management. This pattern is seen as a "building block" that can be further augmented either through a) API interactions and operations, or through b) implementation of significant internal business logic to make determinations on document currency for example.

Despite the fact that a FHIR Document may contain Composition, Patient, Practitioner or other resources, posting a FHIR Document Bundle to a Bundle Endpoint does not make those resources automatically available at their equivalent endpoints (e.g., /Composition, /Patient, /Practitioner, etc.).

Important Note on FHIR Documents: Implementers expecting to support use cases involving multiple patient summaries over time are still expected to familiarize themselves with the boundaries the FHIR standard applies to document immutability. Once assembled into a document bundle, the document is immutable - its content can never be changed, and the document id can never be reused. Note that the document may be represented in either XML or JSON and interconverted between these or have its character encoding changed, all the while remaining the same document. However, the directly referenced content within the document and the presentation of the document cannot change substantially (such that it changes the clinical meaning of the content). Any additional documents derived from the same composition SHALL have a different document id. See https://www.hl7.org/fhir/R4/documents.html#content for more details.

Using FHIR Operations to Create a FHIR Document

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 Document Submit Capability. However, a number of operations exist that are actively being tested by the international standards community that can support the creation of a document. These have been listed below for implementers to test and provide feedback on.

Generate a Document Bundle using the $document Operation - This operation on a Composition (at /Composition/[id]) is helpful for systems that want to generate (and optionally, persist) a document Bundle from an existing Composition, including those that do not retain an original Document used to generate a decomposed Composition.

Compositions stored at the /Composition endpoint are not FHIR Documents, although the $document operation may be used to create point-in-time FHIR Documents from a Composition. This operation has been surfaced in the hyperlink above but is not an official supported document creation pattern in this release. Feedback from implementers on the use of $document is requested.

CA:FeX-2: Search For a Document

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

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

Searches that are intended to return a payload that includes any FHIR Documents that match the parameters provided. These types of queries combine search and retrieval but put more strain on the processing and requesting systems to manage and filter the volume of content in the response in a way that is more manageable to the user.
Searches that are intended to create a pointer to a document (e.g., DocumentReference) or a a FHIR Document or on demand if the repository has content that matches the parameters provided. These types of searches leverage FHIR operations and tend to reduce the burden on requesting systems to have to tailor their request for a document to include the format the document was stored in. This makes this type of search more ideal for querying hybrid repositories.

Note: Details on what the responder supports can be found within the CapabilityStatement that the requester retrieves as a separate step from this search. Querying for a CapabilityStatement is an expected pre-requisite for being able to query a source. However, it is not required to be conducted at the beginning of every session to avoid forcing performance costs on clients that interact with known servers that do not update their security services and/or supported capabilities frequently.

Document Search Patterns

While there is more space for variability of document submission patterns based on a number of factors, variations in supported document search patterns incur a higher cost towards Data Consumers.

A primary driver of this specification is to fill the gap that "FHIR-first" implementers are experiencing with existing document exchange standards like MHD and XDS. One of these particular challenges, is the need to balance efficacious and consistent search patterns against the additional effort incurred to supply supplementary metadata/resources (e.g., DocumentReference) that include more potent attributes to aid in targeted searches.

Clinical systems in US markets are more familiar with using MHD-like patterns to exchange C-CDAs using FHIR - largely due to the proliferation of XDS implementations in the US Market. Many organizations that had already invested in XDS infrastructure opted to support a FHIR façade for retrieving C-CDAs and utilized MHD (and related IHE profiles) as the mechanism for doing so. Naturally, these systems are considering how to retrofit their existing configurations to support search and retrieval of other types of documents in a similar manner.

Systems that serve non-US markets (or new solutions built entirely in FHIR for document exchange) may not have the same historical context to immediately catalyze investment of effort to supply additional resources for more desirable search behaviors. Recently, new operations have been developed that are more lightweight and may ease the burden of supporting these more potent search attributes. However, these patterns are evolving and their place in the Canadian market is yet to be fully evaluated.

HTTP Operations

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

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

This pattern is intended to represent the most straightforward method of searching for FHIR Documents from a repository that does not have an existing XDS/MHD architecture and has not further augmented their search capabilities.

Implementers who are trialing this pattern will either play the role of a Data Consumer or a Data Responder in an interaction where a query is constructed (using the parameters identified below) and then submitted to a 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 searches will use chaining on a handful of parameters under bundle.composition, to narrow the search to FHIR Documents.

Implementers are encouraged to review the Base FHIR Specification for further details on the HTTP search interaction.

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 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 endpoints for 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.

Supported Search Parameters for Document Search Using Bundle Endpoints

The following search parameters are used generically to support document retrieval anchored around the Bundle endpoint. These can be found on Search Parameters but are called out below to demonstrate the chaining that is required to search against details contained in key resources that are part of the FHIR Document Bundle.

Query Search Parameters	Applied To	Description
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	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	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.
status	bundle.composition.status	This parameter, of type token, specifies the status of the composition. The use of bundle.composition.status follows the FHIR Chaining Parameters search methodology.
author	bundle.composition.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.
date	bundle.composition.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.

Additional search parameters that are specific to the requirements for a particular use case or IGuide may be further defined by those implementations.

There are additional parameters that can be provided in the request that help further order and organize the resources that are returned. These types of parameters are identified in the base specification as standard parameters and result parameters.

CA:FeX does not currently require the support of certain result parameters, since conformance expectations for these types of parameters are implementation-specific and/or conditionally useful (e.g., _count parameter when an implementation expects a high volume of documents could be returned).

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

This pattern is intended to represent the more scalable method of searching for FHIR Documents from a repository that supports a hybrid model for document retrieval.

Earlier versions of this specification circulated a direct query method against a DocumentReference endpoint under this pattern. However, this has been modified in this release (in response to feedback) to better convey the use of FHIR operations as the more lightweight alternative to conventional searching against the DocumentReference endpoint (a noted challenge with the current MHD pattern).

Implementers are encouraged to consider the perspective of Data Consumers that want to have a single way for searching for both FHIR-assembled and FHIR-enabled documents. FHIR Operations present the most promise in this space but currently there are a number being explored for document exchange.

This specification has identified two promising operations ($docRef and $summary) for this pattern. We anticipate that both operations would require further enhancement to account for the current search requirements and capabilities of existing document exchange systems. For this reason, CA:FeX is seeking feedback on which of these operations Canadian implementations would be most likely to use to support FHIR Document Exchange.

Note: $docRef is currently a recommended (SHOULD) operation in the CA:FeX Server Capability Statement. Given the current scope of $summary is intended to generate Patient Summaries, it is recommended for PS-CA implementers but not formally claimed on the CapabilityStatement due to use case specificity.

Generate or Retrieve a DocumentReference using the $docRef Operation Industry-leading implementations like the US Core and International Patient Access (IPA) are promoting the use of operations like $docRef that can fetch and generate the DocumentReference "shell" on-demand if the server contains (or can generate) any FHIR Documents that meet the criteria but do not already have this additional layer of metadata.

A server may generate an on-demand document upon returning its DocumentReference during the $docref response or once the client accesses it. Like US Core and IPA, this specification places no requirements upon when a server generates an on-demand document and encourages server developers to balance the performance cost of creating unread documents against the response time to retrieve new documents.

Implementations that do not want to perform the secondary retrieval for FHIR Documents can choose to augment their implementation to support parameters like _include to return the referenced FHIR resources alongside the generated DocumentReference.

The $docRef operation is currently defined in IPA Fetch DocumentReference and the inputs and outputs are described in detail in the Operations page of this guide. Examples can also be found on the US Core DocumentReference Quick Start section.

Generate or Retrieve a Patient Summary using the $summary Operation

Specifications like the International Patient Summary (IPS) have surfaced the $summary operation as well. This operation asks for the latest appropriate summary (whether that already exists or must be newly generated) and returns the latest summary in the form of a FHIR Document. However, this is configurable to claim other document profiles. One benefit of this approach over $docRef is that it circumvents the need to support an _includes parameter or perform a secondary retrieval step for the FHIR Document.

The $summary operation is currently defined in IPS, but is being considered for broadening to return other FHIR Documents as well. The inputs and outputs of this operation are described in detail in the Operations page of this guide.

Considerations for using FHIR Operations for Document Search

Both proposed operations currently rely on the Patient resource - which would necessitate that server of the Data Responder has a patient resource to anchor around. This presents a challenge to implementers who do not have plans to support a Patient resource outside of the contained content in the FHIR Document. This specification is actively seeking feedback from implementations who are considering this approach - on whether further customization is necessary.

Both operations have flexibility in whether the FHIR Document is persisted on the requester and responder servers, however the $docRef operation is more commonly used to save a DocumentReference and Bundle on the responder server.

The $docRef operation 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 use of this operation also supports DocumentReferences that contain FHIR Binary resources in the attachment content.

CA:FeX-3: Retrieve a Document

This capability supports the ability to retrieve known documents using the document's resource id.

Document Retrieve Patterns

These patterns are predicated on the requestor knowing the id of the resource they are attempting to retrieve.

Depending on the maturity and scope of the repository, the endpoints supported may be isolated to [base]/Bundle but the repository could potentially support additional document formats which would be retrieved from different endpoints like [base]/Binary.

Guidance is provided below anticipating that some adopters will solely support the ability to retrieve FHIR Documents directly, while others may choose to augment their capabilities to support a hybridized model that supports FHIR Documents alongside documents in legacy formats (e.g., Binary). This augmentation represents a different pattern that could be applied, these patterns are differentiated below using an enumerated convention (e.g., 3A, 3B)

HTTP Operations

This capability can be leveraged using HTTP GET request to perform a read interaction against a resource id at a desired endpoint. Implementers are expected to familiarize themselves with how read interactions are executed using the FHIR RESTful API framework.

Document Retrieve Patterns: CA:FeX-3A (Retrieve Document From FHIR Assembled Documents Repository)

Implementers that are operating in greenfield environments that solely support FHIR Assembled Documents can leverage the most straightforward method of retrieving a FHIR Document from a [base]/Bundle endpoint.

Considerations for Document Retrieve Using Bundle Endpoints

Anchoring retrievals around a Bundle endpoint in this retrieval pattern is recommended for implementers that want to retrieve the FHIR Document using the known id for the Bundle. This retrieval pattern is expected to be used by implementers re-retrieving a Bundle that was previously identified in a search/or prior retrieval.

Document Retrieve Patterns: CA:FeX-3B (Retrieve Document from Hybrid Documents Repository)

Implementers are encouraged to incorporate patterns that allow for more comprehensive support for both FHIR-assembled and FHIR-enabled documents. Implementers that extend their capabilities can subsequently expect to support retrieval of documents using additional FHIR endpoints.

This pattern anchors retrieval around [base]/DocumentReference and/or [base]/Binary endpoints using the HTTP GET command. Best practice with DocumentReference is typically to store the 'data' as a separate resource instance (Binary, Bundle, etc.) and then point to that data from the DocumentReference. This allows the DocumentReference instances to be retrieved without necessarily retrieving the content, which is useful in indexing scenarios.

Anchoring retrievals around a DocumentReference endpoint in this retrieval pattern is recommended for implementers that know the document they are retrieving is an embedded attachment in DocumentReference. This pattern can also be used to retrieve a DocumentReference if it was created and persisted through the use of the $docRef operation (see CA:FeX 2B), however this is not its primary function.

Anchoring retrievals around a Binary endpoint in this retrieval pattern is recommended for implementers that know the document that they are retrieving is a Binary resource. This retrieval pattern is expected to follow a CA:FeX Search Against Hybrid Documents Repository (CA:FeX-2B), if the $docRef operation is used and the attachment.url identifies the document can be retrieved from a FHIR Binary endpoint.