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-ballot 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 resources matching the profiles indicated in the context from the event definition.
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. |
versionId |
Conditional | string | A string displaying the context's version ID. versionId SHALL be present for *-update events. |
priorVersionId |
Optional | string | A string displaying the context's previous version ID. |
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. Subscribers SHALL accept a full FHIR 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 ("-"). Note that this specification uses an asterisk to refer to categories of events (e.g. *-open
for all open events), but that this syntax is not supported when interacting with a Hub.
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. Events defined in the standard event catalog or by implementers SHALL contain only valid FHIR+JSON and MAY contain FHIR resources or datatypes.
All fields available within an event's context SHALL be defined in a table where each field is described by the following attributes:
The key used for indicating a context change event's FHIR resource SHALL be the lower-case resourceType of the resource as defined in the resource type valueset. For example, the patient-open event uses the patient
key to signal the new Patient in context. Note that due to legacy reasons, some events deviate from this pattern. The resources to include are defined in the corresponding event definition in the event catalog.
References to resources other than anchor resources SHALL be named any string which is not a value from the resource type valueset.
In the case in which other events are deriveable from the event in question, additional non-anchor FHIR resources included in the event SHALL be named what they are named in the deriveable event.
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.
Besides a key field, each context element also holds a value element. The field of the value holds the name as its datatype in lowercase: i.e. resource
indicates a FHIR resource, reference
a reference, string
a string.
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 |
UserLogout |
signals that the users session has ended. |
UserHibernate |
signals that the user temporarily suspended their session due to a session time-out or other reason. |
Content sharing events use the suffix update
. The format of content sharing event names is:
ContentSharingEventName ::= ( FHIRresource ) '-' ( 'update' )
*-update
events provide a mechanism to share content in the context of an anchor context
(see anchor context
). *-update
events update the content within the specified anchor context; said another way, most *-update
events are not changing the anchor context
resource rather creating, modifying, or removing the content within the anchor context
. A Subscriber shares content related to the anchor context by providing FHIR resource(s) in a Bundle
contained in the updates
key of a *-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
.
Selection events use the suffix select
. The format of selection event names is:
SelectionEventName ::= ( FHIRresource ) '-' ( 'select' )
*-select
events provide a mechanism to select content in the context an anchor context
(see anchor context
). *-select
events select content resources within the anchor context
, not the anchor context
itself (making the anchor context
the current context is performed by the corresponding *-open
event). The context
array in a select event contains two attributes. A reference to the FHIR resource which is the anchor context
, and a select array indicating the content resource(s) that are selected. If the Subscriber wants to indicate that no resource is selected, the select attribute is an empty array.
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
.