Operations
The FHIR specification defines a special kind of operations that have an RPC-like functionality. These are called "Execute Operations", or simply "Operations" throughout the FHIR specification. These FHIR operations can be executed against a FHIR server, type, or resource instance. These invocations are named using the convention $name (i.e. the name is prefixed with $) and will generally take a Parameters resource as input and output.
Approach Towards Operations
This specification has identified the following operations that should be supported by the implementations complying to the CA:FeX specification. This list may expand as per the community and implementer's feedback.
$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.
The $docRef operation retrieves reference to documents along with the metadata such as its identifier, type, status, author, and custodian. This operation is useful for querying the metadata associated with a document, such as when searching/filtering for all the documents authored by a particular provider. The document itself can be subsequently retrieved using the link provided in the DocumentReference.content.attachment.url
element. The link could be a FHIR endpoint to a Binary Resource or some other document repository.
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.
The operation can be invoked using the GET Syntax if the complex type parameter is omitted:
GET [base]/DocumentReference/$docref?{parameters}
Otherwise the POST transaction is used as follows:
POST [base]/DocumentReference/$docref
The body of the POST contains the Parameters resource with the operation input parameters.
Examples can also be found on the US Core DocumentReference Quick Start section.
Input Parameters:
- patient is currently a mandatory input parameter for defining the id of the patient resource used in the operation
- start and end are used as optional input parameters to indicate the start and/or end dates of the care related records in the FHIR Document. If neither a start date nor an end date is provided, the most recent or current document is in scope.
- type is used as an optional input parameter to indicate the type of document being requested
- on-demand is an optional input parameter to indicate if the client wants only "on-demand" documents or both "on-demand" and "stable" documents
- profile is the last optional input parameter to indicate that the client only wants to retrieve documents according to a particular profile
Operation Output:
If a FHIR Document can be found that matches the provided input parameters, a Bundle with type of searchset (that includes the DocumentReference) will be returned.
$document Operation
The $document operation in FHIR is a custom operation that can be used to generate a fully bundled document from a Composition resource. The resulting document bundle can be returned to the client as a full document bundle, which contains the Composition resource and any other referenced resources, or returns an error. If any of the referenced resources are located on other servers, it is up to the server to determine whether to retrieve them or return an error.
The $document operation and examples are currently defined in the FHIR specification.
This operation is useful for accessing the actual content of the document, such as when it needs to be displayed or printed.
The operation can be invoked using the GET Syntax if the complex type parameter is omitted:
GET [base]/Composition/$document?{parameters}
GET [base]/Composition/[id]/$document
Otherwise the POST transaction is used as follows:
POST [base]/Composition/$document
POST [base]/Composition/[id]/$document
The body of the POST contains the Parameters resource with the operation input parameters.
Input Parameters:
- id is used as an optional input parameter to define the Composition resource that will be used to anchor and compile the resources included in the document
- persist is used as an optional input parameter to indicate whether the returned bundle should be stored at the Bundle endpoint once it is generated
- graph is used as an optional input parameter to indicate a URL for a GraphDefinition resource that explicitly defines the contents of the bundle returned
Operation Output:
If a FHIR Document can be created using the input parameters (or one already exists that meets the input parameters), a Bundle with type of Document will be returned.
$summary Operation
The $summary
operation is the most efficient (and is the preferred) mechanism to create patient summaries, while $docref is more generic and can be used for a variety of types of documents. Systems SHOULD support $summary but MAY support $docref as well if they have broader needs. $document is more specialized and is less commonly used.
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 operation can be invoked using the GET Syntax if the complex type parameter is omitted:
GET [base]/Patient/$summary?{parameters}
GET [base]/Patient/[id]/$summary
Otherwise the POST transaction is used as follows:
POST [base]/Patient/$summary
POST [base]/Patient/[id]/$summary
The body of the POST contains the Parameters resource with the operation input parameters.
Input Parameters:
- identifier is currently an optional input parameter for the operation (see note below)
- profile is used as an optional input parameter to indicate that the client only wants to retrieve documents according to a particular profile
Note: the Graph parameter is currently in the process of being removed from the IPS OperationDefinition for $summary and has been pre-emptively removed in the input description above.
Operation Output:
If a FHIR Document can be found or created that matches the provided input parameters, a Bundle with type of document will be returned
Other Operations
There are other operations that SHOULD be supported in the implementations based on their specific requirements. While these operations enhance the capabilities of FHIR servers, they may not be necessary for all implementations, particularly those primarily used for basic EMR functions. Implementations focused on specific needs like research, detailed reporting, or extensive data analysis might find these operations more critical. Feedback on the utility and implementation of these operations in different server environments is welcomed to ensure that they meet diverse needs effectively:
- $everything - Patient-everything returns all the information related to one or more patients described in the resource or context on which this operation is invoked.
- $lastn - $lastn can be used to retrieve the most recent or last n=number of observations for one or more subjects.
- $expand - $expand returns the expanded value set i.e. basically collection of codes suitable for use for data entry or validation.
- $validate-code - The operation validate if the coded value is in the code system.
- $translate - Translate a code from one value set to another, based on the specified ConceptMap resource. If no ConceptMap resource is specified, then other additional knowledge available to the server may be used.