Scope

This capability is currently scoped to the ability to submit new FHIR Documents.

While there are a variety of ways documents can be modeled and exchanged in FHIR, the initial release of this specification is focused on the submission patterns expected to be used by early implementers of the PS-CA (pan-Canadian Patient Summary). Patient Summaries are a relatively new document type (e.g., legacy implementations not expected) and have been modeled as FHIR Documents.

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. For more on FHIR Documents, see Documents.

Out of Scope

As this specification evolves, and new document types and architectures are included, this scope will also evolve to supply guidance for those business cases.

Global, pan-Canadian, and jurisdictional practices for document lifecycle management of patient summaries are still in development. For this reason, the management, verification, replacement and deprecation of documents, are out of scope of the guidance included in this release.

Info

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/documents.html#content for more details.

Use Cases

The following CA:FeX use case leverages this capability:

  • UC-01 Create and Submit Document

CA:FeX Transactions

This capability describes the FHIR implementation of the CA:FeX Submit Data (CA:FeX-1) transaction found in the Sequence Diagram for UC-01: Create and Submit Document.

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.

For more information on the supported HTTP operations, refer to the section Actors and Transactions.

HTTP POST

A create is executed by performing a POST operation in the RESTful framework:

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

Content Types and Encodings:

Either application/fhir+json or application/fhir+xml content types are permitted

Document Submit Patterns: Fundamental

The simplest method to submit documents is through the submission of the FHIR Document Bundle to a HTTP POST request to a[base]/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.)

Per the FHIR standard on HTTP create interaction:

  • The request body SHALL be a valid FHIR Resource (in this case, a FHIR Release 4 Bundle resource) 
  • The resource does not need to have an id element (this is one of the few cases where a resource exists without an id element). If an id is provided, the server SHALL ignore it.
  • If the request body includes a meta, the server SHALL ignore the existing versionId and lastUpdated values. The server SHALL populate the id, meta.versionId and meta.lastUpdated with the new correct values
  • Servers are allowed to review and alter the other metadata values, but SHOULD refrain from doing so (see metadata description for further information).
  • A server SHOULD otherwise accept the resource as submitted when it accepts the create, and return the same content when it is subsequently read. However, some systems might not be able to do this; see the note on transactional integrity for discussion.
  • The server returns a 201 Created HTTP status code, and SHALL also return a Location header which contains the new Logical Id and Version Id of the created resource version. See Response Handling for more details.

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 /Bundle endpoint, and the content is not (generally) updated. If Data Receiver 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.

Note: 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.).

Outside of the scope of this specification's guidance, an implementation may choose to decompose a received FHIR Document, and manage the included resources individually. An implementation that does this should consider several issues, including:

  • Resource deduplication (e.g., when the Patient or Composition resource in a document is actually the same as an already known Patient or Composition resource, perhaps obtained from another document)
  • Sources of truth for various resources and document currency (e.g., whether to update an existing patient address based on a 10-year old document)
  • Whether and how updates to the extracted resources feed back into the submitted document
  • Document lifecycle compared to resource lifecycle (i.e., if a Practitioner resource is removed from the system 5 years after the Practitioner retires, is a FHIR Document or the Composition extracted from it still usable, etc.)
  • Whether to persist the submitted document as well as the extracted resources

Document Submit Patterns: Intermediate

The section will evolve in future releases to cover additional submission patterns for documents (e.g., submitting a binary version of the document, performing a bundle transaction, submitting supporting resources that aid in the finding of the document, etc.).

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 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 below but is not an official supported document creation pattern in this release. Feedback from implementers on the use of $document is requested.


  • No labels