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: Use Cases and Definitions can be found here.
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.
Considerations for Document Exchange
The optimal document submission option 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.
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
Exchanges can be leveraged using HTTP POST or GET requests as described. Implementers are expected to familiarize themselves with how create interactions are executed using the FHIR RESTful API framework.
Actors, Transactions, and Actor Options
This guide provides detailed information for the following actors, transactions, and actor options for document exchange.
Bundle Option (A)
| Actors | Transaction ID | Name | Endpoint Summary | Optionality |
|---|---|---|---|---|
| Data Source | CA:FeX-1A | Submit FHIR Document | /Bundle |
R |
| Data Consumer | CA:FeX-2A | Search FHIR Document | /Bundle |
R |
| Data Consumer | CA:FeX-3A | Retrieve FHIR Document | /Bundle |
R |
| Data Recipient | CA:FeX-1A | Submit FHIR Document | /Bundle |
R |
| Data Responder | CA:FeX-2A | Search FHIR Document | /Bundle |
R |
| Data Responder | CA:FeX-3A | Retrieve FHIR Document | /Bundle |
R |
Metadata Option (B)
| Actors | Transaction ID | Name | Endpoint Summary | Optionality |
|---|---|---|---|---|
| Data Source | CA:FeX-1B | Generate Metadata | $generate-metadata |
R |
| Data Consumer | CA:FeX-2B | Fetch DocumentReference | $docRef |
R |
| Data Consumer | CA:FeX-3B | Retrieve Document | /Bundle, /Binary, /DocumentReference (not recommended) |
R |
| Data Recipient | CA:FeX-1B | Generate Metadata | $generate-metadata |
R |
| Data Responder | CA:FeX-2B | Fetch DocumentReference | $docRef |
R |
| Data Responder | CA:FeX-3B | Retrieve Document | /Bundle, /Binary, /DocumentReference (not recommended) |
R |
Summary Option (D)
| Actors | Transaction ID | Name | Endpoint Summary | Optionality |
|---|---|---|---|---|
| Data Consumer | CA:FeX-3D | Retrieve Summary | $summary |
R |
| Data Responder | CA:FeX-3D | Retrieve Summary | $summary |
R |
Data Source
A Data Source submits data to a Data Recipient.
Data Consumer
A Data Consumer queries a Data Responder for data matching a set of criteria.
Data Recipient
A Data Recipient receives data from a Data Source.
Data Responder
A Data Responder returns data matching a set of criteria queried by Data Consumer.
Bundle Option (A)
CA:FeX-1A: Submit FHIR Document
This document submission pattern leverages the create interaction against the /Bundle endpoint. It expects a Data Source to submit to a Data Recipient.
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).
For more information, see FHIR Create interaction.
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
/Bundleendpoint, 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.).
CA:FeX-2A: Search FHIR Document
This transaction will execute a search-type against a /Bundle endpoint from a Data Consumer where a Data Responder 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.
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. These searches that are also 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.
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.
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).
CA:FeX-3A: Retrieve FHIR Document
Implementers that are operating in greenfield environments that solely support FHIR Documents can leverage the most straightforward method of retrieving a FHIR Document from a /Bundle endpoint using the read interaction.
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.
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.
Metadata Option (B)
CA:FeX-1B: Generate Metadata
Data Sources and Data Recipients must 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.
CA:FeX expects that only FHIR Documents are submitted.
CA:FeX-2B: Fetch DocumentReference
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.
These 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.
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.
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 a variety of document formats. FHIR Operations present the most promise in this space but currently there are a number being explored for document exchange.
CA:FeX currently only expects that Bundle and Binary resources are exchanged in this manner.
CA:FeX-3B: Retrieve Document
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 /DocumentReference and/or /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 Fetch DocumentReference (CA:FeX-2B), if the $docRef operation is used and the attachment.url identifies the document can be retrieved from a FHIR Binary endpoint.
CA:FeX expects that references in the attachment.url of DocumentReference that identifies where the document can be retrieved refer to only /Bundle and /Binary endpoints.
For more information on retrieval see FHIR Read interaction.
Summary Option (D)
CA:FeX-3D: Retrieve Patient Summary
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.
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.
Notes
We anticipate that both $docRef and $summary 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.
Note: Details on what a Data Responder supports can be found within the CapabilityStatement that the requester retrieves as a separate step from search interactions. 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.
Considerations for using FHIR Operations for Document Search
Both $docRef and $summary 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 $docRef and $summary 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.