Pan-Canadian FHIR Exchange (CA:FeX) IGuide 2.2.0 DFT-Ballot

DFT Ballot - This specification is currently in ballot review and subject to change. It is not ready for limited roll-out or production level use. For a full list of available versions, see the Directory of published versions

Operations

FHIR defines a class of RPC‑style interactions called operations (formally “Execute Operations”). An operation invocation is identified by a name prefixed with $ (e.g., $docref) and is submitted to a server, a resource type endpoint, or a specific resource instance. Input and output are conveyed in a Parameters resource.

Approach toward operations

The CA:FeX specification has identified the following operations that SHOULD be supported. This list may expand based on community feedback.

$docref

Implementations such as US Core and International Patient Access (IPA) promote $docref to fetch or generate a DocumentReference “shell” on‑demand when matching FHIR documents exist but lack metadata.
A server MAY generate the document when it returns the DocumentReference (eager) or defer generation until a client accesses the DocumentReference.content.attachment.url (lazy). Server developers should balance the cost of creating unused documents against response‑time requirements (consistent with US Core and IPA direction).

The $docref operation retrieves references to documents together with metadata such as identifier, type, status, author and custodian. The document itself can then be obtained via the URL in DocumentReference.content.attachment.url, which MAY point to a FHIR Binary endpoint or an external repository.

Specification: IPA $docref
CA:FeX mapping: see Operations.

Invocation

GET [base]/DocumentReference/$docref?{parameters}
(only if no composite parameters are needed)
POST [base]/DocumentReference/$docref with a Parameters body

Input parameters

Name	Cardinality	Notes
`patient`	1..1	Patient ID of interest
`start`	0..1	Start of date range
`end`	0..1	End of date range
`type`	0..*	One or more document types
`on-demand`	0..1	`true` → only “on‑demand” docs; omit/`false` → both
`profile`	0..*	Document profile(s) requested

Output

If at least one document matches, the server returns a Bundle of type searchset containing one or more matching DocumentReference resources.

$summary

$summary provides the most efficient, preferred mechanism for obtaining the latest patient summary. While $docref is document‑agnostic, $summary is optimised for concise clinical summaries (e.g., IPS).

Specification: IPS $summary — expansion underway to support additional document profiles.

Invocation

GET [base]/Patient/$summary?{parameters}
GET [base]/Patient/[id]/$summary
POST [base]/Patient/$summary (body = Parameters)
POST [base]/Patient/[id]/$summary

Input parameters

Name	Cardinality	Notes
`identifier`	0..1 (system), N/A (instance)	Patient MRN when invoked at system level
`profile`	0..*	Document profile(s) requested

(Graph parameter has been removed from the IPS draft and is therefore omitted.)

Output

A Bundle of type document containing the generated or pre‑existing patient summary.

Other operations

Implementers MAY support additional FHIR operations where needed:

Operation	Use‑case
`$everything`	Retrieve the complete clinical record for one or more patients.
`$lastn`	Get the most recent n observations for a subject.
`$expand`	Return an expanded `ValueSet` for data entry/validation.
`$validate-code`	Validate a code against a `CodeSystem`.
`$translate`	Translate a code from one value set to another using a `ConceptMap`.

Feedback welcome — especially on performance guidelines for on‑demand documents and the applicability of each optional operation in typical EMR deployments.