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

CA:FeX retains $docref for generic document discovery and $summary for patient summaries, with PS-CA providing the Canadian patient-summary context. Their placement in CA:FeX is retained by the realignment decision.

Support expectations depend on the claimed actor and option: Option B uses $generate-metadata and $docref, and Option D uses $summary. See Document Exchange for the transactions and Capability Statements for the actor-option requirements. The generic server's SHOULD expectation for $docref does not replace those requirements.

$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 Document Exchange for CA:FeX-2B.

Invocation

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

Input parameters

Output

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

$summary

$summary obtains the latest patient summary under Option D. Its Canadian use-case context is PS-CA; it does not replace $docref for generic document discovery. The retained invocation forms, inputs and outputs below are unchanged by the realignment.

Specification: IPS $summary. The operation remains patient-summary-specific in this guidance.

Invocation

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

Input parameters

(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

The following operations are broader FHIR context, outside the retained CA:FeX document-exchange transactions. Their inclusion here creates no additional CA:FeX conformance requirement:

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