FHIRcast, published by HL7 International - Infrastructure and Messaging. This guide is not an authorized publication; it is the continuous build for version 3.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhircast-docs/ and changes regularly. See the Directory of published versions
FHIRcast describes a workflow event subscription and notification scheme with the goal of improving a clinician’s workflow across multiple disparate applications. The set of events defined in this specification is not a closed set; anyone is able to define new events to fit specific use cases and are encouraged to propose those events to the community for standardization.
New events are proposed in a prescribed format using the event template by submitting a pull request. FHIRcast events are versioned, and mature according to the event maturity model.
FHIRcast context events do not communicate previous contexts. For a given event, open and close events are complete replacements of previous communicated context change events, not “deltas”. Understanding a context change event SHALL NOT require receiving a previous or future event.
Each event definition specifies a single event name, a description of the workflow in which the event occurs, and contextual information associated with the event. FHIR is the interoperable data model used by FHIRcast. The context information associated with an event is communicated as subsets of FHIR resources. Resources are formatted in the fhir+json json representation as defined by the base FHIR specification. Event notifications SHALL include the elements of the FHIR resources defined in the context from the event definition. Event notifications MAY include other elements of these resources.
All events are documented in the standard event catalog and SHALL be defined in the following format.
Field | Optionality | Type | Description |
---|---|---|---|
hub.topic |
Required | string | The session topic given in the subscription request. MAY be a Universally Unique Identifier (UUID). |
hub.event |
Required | string | The event that triggered this notification, taken from the list of events from the subscription request. |
context |
Required | array | An array of named FHIR objects corresponding to the user’s context after the given event has occurred. |
The notification’s hub.event
and context
fields inform the Subscriber of the current state of the user’s session. The hub.event
is a user workflow event, from the Event Catalog (or an organization-specific event in reverse-domain name notation). The context
is an array of named FHIR resources (similar to CDS Hooks’s context field) that describe the current content of the user’s session. Each event in the Event Catalog defines what context is included in the notification. The context contains zero, one, or more FHIR resources. Hubs SHOULD use the FHIR _elements parameter to limit the size of the data being passed while also including additional, local identifiers that are likely already in use in production implementations. Subscribers SHALL accept a full FHIR resource or the _elements-limited resource as defined in the Event Catalog.
The Subscriber requesting a context change SHALL ensure consistency of the FHIR resources in the context
array. For example, the Hub will not check that the Patient resource in an Encounter-open context
array is in fact the patient associated with the encounter in the real world.
The event name defines the event. Most FHIRcast events conform to an extensible syntax based upon FHIR resources.
Patterned after the SMART on FHIR scope syntax and expressed in EBNF notation, the FHIRcast syntax for context change related events is:
EventName ::= (FHIRresource | '*') ('-') ( 'open' | 'close' | 'update' | 'select' | '*' )
The FHIRresource
indicates the focus of the event; the suffix
defines the type of event.
Event names are unique and case-insensitive. It is RECOMMENDED to use Upper-Camel case.
Implementers may define their own events. Such proprietary events SHALL be named with reverse domain notation (e.g. org.example.patient_transmogrify
). Reverse domain notation SHALL NOT be used by a standard event catalog. Proprietary events SHALL NOT contain a dash (“-“).
When subscribing to FHIRcast events a list of events is added. These events may contain wild cards. Wild cards are expressed as a *
replacing either the FHIRresource
or suffix
with *
indicates any events that match the resulting definition are requested. The event *
means the Subscriber subscribes to any event. The table below shows some typical examples.
Event | Description |
* |
All events |
*-* |
All events with a FHIRcast defined postfix |
Patient-* |
All events that use the Patient FHIR resource |
*-update |
All update events |
*-select |
All select events |
Describes the set of contextual data associated with this event. Only data logically and necessarily associated with the purpose of this workflow related event should be represented in context. An event SHALL contain all required data fields, MAY contain optional data fields and SHALL NOT contain any additional fields.
All fields available within an event’s context SHALL be defined in a table where each field is described by the following attributes:
A Hub SHALL at least send the elements indicated in FHIR operation to generate context; a Subscriber SHALL gracefully handle receiving a full FHIR resource in the context of a notification. For example, when the ImagingStudy-open
event occurs, the notification sent to a Subscriber includes an ImagingStudy FHIR resource, which contains at least the elements defined in the _elements query parameter, as indicated in the event’s definition. For ImagingStudy, this is defined as: ImagingStudy/{id}?_elements=identifier
. (The _elements query parameter is defined in the FHIR specification).
The key used for indicating a context change event’s FHIR resource SHALL be the lower-case resourceType of the resource. In the case the resource refers to other FHIR resources that represent their own context, these can be included as well. The resources to include are defined in the corresponding event definition in the event catalog.
The Hub SHALL only return FHIR resources that the Subscriber is authorized to receive with the existing OAuth 2.0 access_token’s granted fhircast/
scopes.
The FHIRcast specification supports many different events. These events are defined in the event catalog. The events can be grouped in different types. The following sections define the characteristics of these different event-types.
FHIRcast context-change events that describe context changes SHALL conform to the following extensible syntax. Patterned after the SMART on FHIR scope syntax and expressed in EBNF notation, the FHIRcast syntax for context-change related event names is:
ContextChangeEventName ::= ( FHIRresource ) '-' ( 'open' | 'close' )
Context change events SHALL include the resource the context change relates to. Common FHIR resources are: Patient, Encounter, ImagingStudy, and DiagnosticReport.
In the case the resource refers to other FHIR resources that represent their own context, these can be included as well. For example, an Encounter-open
also refers to the patient that is the subject of the Encounter. What resources to include is defined in the corresponding event definition in the event catalog.
FHIRcast defines profiles for FHIR resources used in *-open
and *-close
events documented in the event catalog
. Each resource used to establish context has a profile for when that resource is used in an *-open
event and a different profile for when that resource is used in a *-close
event. The profiles for *-open
events mandate more attributes than those for *-close
events since all Subscribers need enough information to identify the appropriate information associated with the context resource(s) in their application enabling them to participate in a common context.
FHIRcast does not mandate that contextual subjects have any FHIR persistance; sufficient information to establish a common context may simply be exchanged using FHIR resources as the structure to hold the necessary information without the resources ever existing in a FHIR server (in fact it may be that there is no FHIR server in the infrastructure associated with any Subscriber synchronizing in a FHIRcast topic). As this is an FHIR R4 implementation guide, all profiles and examples conform to FHIR R4 resource specifications. Where relevant/required, notes have been added to the description of the resource profiles indicating how to use the resources in a FHIRcast session using FHIR R5-based resources.
*-open
Event Resource Profiles:
*-close
Event Resource Profiles:
FHIRcast supports all events that follow this format. The most common events definitions have been provided in the event catalog.
This event category contains events required to maintain a FHIRcast session. The main events in this category are:
SyncError |
indicates refusal to follow context or inability to deliver an event |
Heartbeat.html |
for monitoring the connection to the hub |
Selection events use the suffix select
. The format of selection event names is:
SelectionEventName ::= ( FHIRresource ) '-' ( 'select' )
The FHIRresource
indicates the context of the selection. The context
element in a select event contains two fields. One field with the name of the FHIR resource which is the anchor context, and one field named select
which is an array indicating the resources that are selected. If no resource is selected, select
is an empty array.
This allows communication of different select sets for the different anchor-types.
FHIRcast supports all events that follow this format. The most common events definitions have been provided in the event catalog. For an example see DiagnosticReport-select
.
Content sharing events use the suffix update
. The format of selection event names is:
ContentSharingEventName ::= ( FHIRresource ) '-' ( 'update' )
An update
event provides a mechanism to share content in the context of the current anchor context (see anchor context
). A Subscriber shares content related to the anchor context by providing FHIR resources in a Bundle contained in the updates
key of an update
event. See Content Sharing
for a comprehensive description of update
events.
The FHIRresource
indicates the anchor context in which content is being shared.
The context
element in an update event SHALL contain at least two fields. One with the name of the FHIRresource
which holds the anchor context and one named updates
holding a single Bundle
resource with entries holding the content being shared. The Bundle
resource SHALL conform to the FHIRcast content update Bundle profile.
FHIRcast supports all events that follow this format. The most common events definitions have been provided in the event catalog. For an example see DiagnosticReport-update
.