This page is part of the FHIR Specification (v4.3.0: R4B - STU). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5R4B
Compartments: Not linked to any defined compartments
Describes a stream of resource state changes or events and annotated with labels useful to filter projections from this topic.
2.48.1 Scope and Usage
This document contains information about the SubscriptionTopic resource and details specific to options in it. It is defined as part of the topic-based model of Subscriptions (Publish / Subscribe pattern).
The SubscriptionTopic resource is used to define conceptual or computable events for Subscription resources. Conceptually, subscription topics specify:
What causes a notification, either by referencing an event definition in an event trigger (e.g., http://example.com/fhir/events#something-interesting-happened) or by describing a resource state change in a resource trigger (e.g., an Encounter is created or updated to have an Encounter.state of active).
What filters a client is allowed to request. For example, a topic that allows clients to restrict notifications to a particular patient id or group, a specific procedure, etc., relevant to that particular topic.
What related resources the server MAY include in notifications. For example, while a discharge notification would likely be focused on the Encounter resource, since that is the resource that is updated, it is likely desireable to include the patient information, observations, diagnosed conditions, location information, etc.
Subscription Topics are intended to be discoverable, reusable, and extensible. Definitions should be computably defined whenever possible, but the conceptual definition is the arbiter between any discrepancies. For example, a query-based and a FHIRPath-based definition may differ slightly because of what is expressable in each language. In such cases, the goal is correct implementation of the concept - not literal translations between computable definitions.
2.48.2 Boundaries and Relationships
The SubscriptionTopic resource is used in the Pub/Sub (Publisher/Subscriber) model of FHIR Subscriptions. Information about the Boundaries and Relationships both within the Subscriptions Framework and to other areas of the FHIR specification can be found here.
Each server is responsible for accurately implementing each SubscriptionTopic it advertises support for. Due to the breadth of possible topics, detailed implementation guidance cannot be provided here. Following are a few points to consider when implementing a Subscription Topic within a server:
2.48.6 Defining Subscription Topics
The SubscriptionTopic resource is designed to define what is possible for a subscription - what causes a server to generate notifications, what related information notifications contain, and what a client can use to filter a class of possible subscriptions down to what that particular client is interested in. Implementers and users SHOULD be able to use a subscription topic to arrive at the same expectations.
Defining a new SubscriptionTopic requires clear communication around requirements and expectations. Anyone defining a SubscriptionTopic is encouraged to publish their definition at registry.fhir.org . Similarly, before defining a new SubscriptionTopic implementers are encouraged to check the registry to see if an existing definition can be reused (either directly or as a base for derivation).
Note that SubscriptionTopic is a Canonical Resource and inherits many elements related to authoring and publication. Authors SHOULD review inherited elements and populate them accordingly.
2.48.6.1 Conceptual Definition
Subscription Topics MUST always document the concept it represents. While a short definition is included in the SubscriptionTopic itself, this documentation will typically not be sufficient for implementers. Definitions must be clear and specific. For example, if the goal is to define an 'admission' topic, the single word is common enough to feel sufficient - implementers generally know what an 'admission' is and could implement something that would qualify. However, is the intention to represent a patient being physically admitted to a care facility, or the start of a clinical encounter? Either definition is common, and without more information implementations will not be consistent. Without complete and specific definitions, server implementations will vary and clients will have unexpected behavior.
2.48.6.2 Resource Interactions
Subscription Topics based on Resource Interactions are simple to describe - definitions include the resource type (e.g., Patient, Encounter) and the interaction of interest (e.g., create, delete).
Subscription Topics for resource interactions are defined using the SubscriptionTopic.resourceTrigger.resource and SubscriptionTopic.resourceTrigger.supportedInteraction elements.
If a topic is designed to cover multiple resources, it can contain multiple resourceTrigger elements with each resource. If a topic is generic to all resources, the Resource is available within the FHIR Defined Type value set.
2.48.6.2.1 Resource Interaction: Create
Subscription Topics defined on create interactions are triggered each time a resource of the specified type is created.
Filters for create operations are restricted to the type of resource being created and must be evaluated on the created resource instance. If more complicated filtering is required (e.g., new Observations when a Patient has a given diagnosis), implementers should use the computable definitions provided by Resource Value Tests.
resource: Patient, supportedInteraction: create: notify each time a new patient is created on the server, e.g., to send 'new patient' information.
resource: AdverseEvent, supportedInteraction: create: notify each time a new Adverse Event is created on the server, e.g., to perform internal review.
resource: Resource, supportedInteraction: create: notify each time any resource is created on the server, e.g., for internal logging/processing.
2.48.6.2.2 Resource Interaction: Delete
Subscription Topics defined on delete interactions are triggered each time a resource of the specified type is deleted.
Filters for delete operations are restricted to the type of resource being deleted and must be evaluated on the resource instance being deleted. If more complicated filtering is required (e.g., notifications for deleting a Patient which has a particular Condition), implementers should use the computable definitions provided by Resource Value Tests.
resource: Resource, supportedInteraction: delete: notify each time a new resource is delete on the server, e.g., for internal logging/processing.
2.48.6.2.3 Resource Interaction: Update
Subscription Topics defined on update interactions are triggered each time the server updates a resource of the specified type. Triggering an update operation does not imply that the resource has changes visible to the subscriber, nor does it require servers to monitor resources for actual changes. Servers MAY generate notifications on their internal triggers, regardless of actual changes (e.g., a client issuing an HTTP PUT with an identical resource).
Filters for update interactions are restricted to the type of resource being updated and must be evaluated on the resource instance after the update is performed (e.g., post-state change). If more complicated filtering is required (e.g., detecting when an Encounter leaves the 'in-progress' state), implementers should use the computable definitions provided by Resource Value Tests.
resource: Patient, supportedInteraction: update: notify each time a patient is modified on the server, e.g., to a processing server to determine further actions.
resource: CarePlan, supportedInteraction: update: notify each time a Care Plan is modified on the server, e.g., to notify a care team of changes.
resource: Resource, supportedInteraction: update: notify each time any resource is modified on the server, e.g., for internal logging/processing.
2.48.6.3 Resource Value Tests
If a topic requires more granularity than interactions provide, a topic can provide state-change tests using either FHIRPath or query (Search) definitions.
Computable Definitions serve two purposes when defining topics. First, some server implementers may be able to use computable definitions directly or with minimal changes. In this scenario, the benifit of a computable definition is quite large (e.g., user-defined Subscription Topics, high portability, etc.). Second, implementers that do not use computable definitions directly will be able to read definitions during their implementation in order to precisley understand what is being defined.
2.48.6.3.1 Query (Search) Definitions
Query definitions are based on Search evaluations performed before and/or after a state change in the server. Allowed query parameters are based on the resourceTrigger.resource (e.g., if the resource is an Encounter, the list of available search parameters can be found here).
2.48.6.3.2 FHIRPath Definitions
FHIRPath expressions can be used to define topical state changes in a server. The FHIRPath expression is assumed to be provided the inputs listed below.
FHIRPath expression input variables:
Variable [previous] = resource instance prior to state change being applied
Variable [current] - resource instance post state change being applied
For example, the expression: %previous.status!='in-progress' and %current.status='in-progress' indicates that the resource has an element, status, and that notifications are generated if the pre-update version status is not 'in-progress' and the post-update version is 'in-progress'.
2.48.6.4 Event Definitions
There are use-cases when a triggering event is not easily described in terms of FHIR resources (e.g., shift change at a facility) or that an existing workflow is already defined on an event-based system (e.g., patient admission in HL7v2). To support these scenarios Subscription Topics MAY include an event trigger, either instead of or in addition to resource triggers.
Event triggers are straightforward to define, since most of the definition exists in the event. The event element references the event which causes a Subscription to trigger. For example, using the event http://terminology.hl7.org/CodeSystem/v2-0003#A01 indicates that a Subscription activates under the same conditions that a HL7v2 system would send an ADT^A01 message. Similarly, an event trigger using http://fhircast.org/events/patient-open indicates that a Subscription activates under the same conditions that a FHIRcast Hub generates a patient-open message.
In order to allow Subscriptions to filter event-based topic definitions, event definitions require a "root" FHIR resource that can be referenced. This is defined in the eventTrigger.resource element. For example, a HL7v2 patient admission event (http://terminology.hl7.org/CodeSystem/v2-0003#A01) would likely be rooted in an Encounter resource, while a FHIRcast patient open event (http://fhircast.org/events/patient-open) would likely be rooted in a Patient resource. By establishing the appropriate root resource for an event, topics can expose filters that are appropriate for notifications. If there is no logical resource available (e.g., events referencing non-FHIR events), resources such as Parameters or Basic may be used.
Note that while having a conceptual description and linking to an event is sufficient for a definition, authors are encouraged to include resource triggers if possible.
2.48.6.5 Defining Allowed Filters
To help servers filter a large set of topic notifications into a smaller set of events that a particular client is interested in, each SubscriptionTopic defines a set of filters that clients are allowed to request. For example, filters can be used to allow a Subscription to narrow down notifications from a topic defining all patient admissions to a just admissions for patients for a specific care team.
2.48.6.5.1 Filter Parameter
The element canFilterBy.filterParameter contains the name of a parameter used to filter events for the focus resource, as defined by resourceTrigger.resource or eventTrigger.resource. The name used in this element is only valid in the context of the Subscription Topic.
The filter parameter MAY be a Search Parameter, either from the list of Parameters for all resources (e.g., _id, _tag) or Search Parameter defined for a specific resource (e.g., Encounter Search Parameters, Patient search parameters, etc.). When a Search Parameter is used, the topic SHALL contain a reference to a valid canonical definition in the canFilterBy.filterDefinition element.
The filter parameter MAY be a filter defined in the context of a topic. When a parameter is defined by a topic, the canFilterBy.filterDefinition SHOULD point to a URL containing detailed information about the parameter - e.g., datatype of the parameter.
2.48.6.5.2 Filter Definition
Filters MAY have external definitions. For example, Search Parameters defined in the FHIR Specifications have canonical URLs in the format of http://hl7.org/fhir/SearchParameter/[id] (see Search Parameter Registry). with Search Parameters, it is possible that two externally-defined filters share the same "short" name. In these cases, the URI contained in the filterDefinition element is used to link a context-local name for the parameter (filterParameter) to the complete definition.
As described in Filter Parameter, parameters backed by full Search Parameter definitions SHALL contain a link to the canonical URL in this element and other parameters SHOULD contain a useful URI in this element.
2.48.6.5.3 Modifier
The element canFilterBy.modifier contains a search modifier used when evaluating a change. Allowed search parameters are pulled from Search, with the addition of = to show simple equality (e.g., no modifier). Note that modifiers are only valid for specific types of data (e.g., a modifer of sa (starts after) has no meaning when applied to a string).
If a search modifier is not provided, it is defaulted to = (no modifer).
If a filter parameter is a defined Search Parameter, the list of allowed modifiers SHALL be a strict subset of the modifiers defined on the Search Parameter.
2.48.6.5.4 Filter Timing and Interactions
When a server evaluates filters depends on the type of change covered by the topic. Guidance is provided based on implementation feedback, but note that all filters are defined to explicitly describe the state before and after the interaction occurs.
2.48.6.5.4.1 Create
Logically, filters evaluated against create interactions must be performed after the resource has been created. For example, a topic interested in new patients may allow filters on elements within the patient resource (e.g., new patients in a specified age range).
Tests can specifically include or exclude changes caused by a create interactions, either via null testing in FHIRPath (e.g., %previous is null) or via the resourceTrigger.queryCriteria.resultForCreate element for query-based definitions.
2.48.6.5.4.2 Delete
Logically, filters evaluated against delete interactions must be performed before the resource has been deleted. For example, a topic interested in practitioners being removed may allow filters on the practitioner resource (e.g., removed practitioners with a specific qualification).
Tests can specifically include or exclude changes caused by a delete interactions, either via null testing in FHIRPath (e.g., %current is null) or via the resourceTrigger.queryCriteria.resultForDelete element for query-based definitions.
2.48.6.5.4.3 Update
Logically, filters evaluated against update interactions MAY be performed either before or after the update occurs. Note however that filters are explicitly defined against the two states: previous and current. Notifications based on resource changes SHALL NOT be sent if the update request fails, since no state change occurred.
2.48.6.6 Notification Shape
In addition to the triggering information for a topic, this resource also defines the expected 'shape' of notifications via notificationShape. This element defines the possible 'root' resources for a notification, as well as additional resources that may be included.
2.48.6.6.1 Root Resource
The element notificationShape.resource defines a 'root' resource for notifications. Typically, this resource will be the same as the triggering resource (e.g., resourceTrigger.resource or eventTrigger.resource), however there may be situations where this is not the case. For example, a topic may be defined across all resources (e.g., every time a resource is deleted), but the author may want additional information depending on which resource is involved. In that scenario, the resourceTrigger.resource could be set to Resource to trigger on all resources. However, shapes could be defined for each resource in the patient compartment to include patient information with those notifications (e.g., if an Encounter is deleted, include the Patient record as well). Note that the opposite scenario is also supported - an author may define multiple triggers on different types of events and simply define a shape that is valid for all of those resources.
2.48.6.6.2 Including Additional Resources
Sometimes it is benficial to include additional resources with a subscription notification. For example, queries for additional resources may be complex in the future, but simple at the time of notification due to context in the event. Alternatively, the subscriber may have limited ability to request additional resource (e.g., a client that is generally offline).
In order to facilitate these workflows, a Subscription can define additional resources that MAY be included when a notification is sent. These additions are based off of the focus resource of the notification, and are described as a list of _include and _revinclude directives. When notifications are generated, a server SHOULD check the appropriate notificationShape.resource for a matching resource and SHOULD include any additional resources listed via notificationShape.include and notificationShape.revInclude, if they exist and the user context for the subscription is authorized to access them.
Included resources should be added in the same style as the focus resource - e.g., if notifications are id-only, then included resources should only include their ids as well.
2.48.7 Deriving from existing Subscription Topics
By populating the derivedFrom element, implementers can advertise that a new topic is compatible with, and offers additional features on top of, another Subscription Topic. A derived topic can add additional filters, but cannot remove existing ones nor change the 'concept' of a topic during derivation. For example:
Deriving a new SubscriptionTopic with the same concept but a different computable definition is OK.
Deriving a new SubscriptionTopic to expose additional canFilterBy parameters is OK.
Deriving a new SubscriptionTopic to remove an existing canFilterBy parameter is NOT ok.
Deriving a new SubscriptionTopic based on a different resource than its parent is NOT ok (e.g., start/end of medication derived from encounter).
Trial-Use Note:
Warning: This section is still in early drafting; feedback from topic authors is welcome to refine the following guidance.
2.48.8 Search Parameters
Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.
Allowed Data type or Resource (reference to definition) for this definition, searches resourceTrigger, eventTrigger, and notificationShape for matches.
Foundation
. Page versions: R5 R4B
SubscriptionTopic 
url 
identifier 
derivedFrom 
resourceTrigger 
<!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension --> <url value="[uri]"/><!-- 1..1 Canonical identifier for this subscription topic definition, represented as a URI (globally unique) --> <identifier><!-- 0..* Identifier Business Identifier for this subscription topic --></identifier> <version value="[string]"/><!-- 0..1 Business version of the subscription topic --> <title value="[string]"/><!-- 0..1 Name for this subscription topic (Human friendly) --> <derivedFrom><!-- 0..* canonical(SubscriptionTopic) Based on FHIR protocol or definition --></derivedFrom> <status value="[code]"/><!-- 1..1 draft | active | retired | unknown --> <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage --> <date value="[dateTime]"/><!-- 0..1 Date status first applied --> <publisher value="[string]"/><!-- 0..1 The name of the individual or organization that published the SubscriptionTopic --> <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact> <description value="[markdown]"/><!-- 0..1 Natural language description of the SubscriptionTopic --> <useContext><!-- 0..* UsageContext Content intends to support these contexts --></useContext> <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction of the SubscriptionTopic (if applicable) --></jurisdiction> <purpose value="[markdown]"/><!-- 0..1 Why this SubscriptionTopic is defined --> <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions --> <approvalDate value="[date]"/><!-- 0..1 When SubscriptionTopic is/was approved by publisher --> <lastReviewDate value="[date]"/><!-- 0..1 Date the Subscription Topic was last reviewed by the publisher --> <effectivePeriod><!-- 0..1 Period The effective date range for the SubscriptionTopic --></effectivePeriod> <resourceTrigger> <!-- 0..* Definition of a resource-based trigger for the subscription topic --> <description value="[markdown]"/><!-- 0..1 Text representation of the resource trigger --> <resource value="[uri]"/><!-- 1..1 Data Type or Resource (reference to definition) for this trigger definition --> <supportedInteraction value="[code]"/><!-- 0..* create | update | delete --> <queryCriteria> <!-- 0..1 Query based trigger rule --> <previous value="[string]"/><!-- 0..1 Rule applied to previous resource state --> <resultForCreate value="[code]"/><!-- 0..1 test-passes | test-fails --> <current value="[string]"/><!-- 0..1 Rule applied to current resource state --> <resultForDelete value="[code]"/><!-- 0..1 test-passes | test-fails --> <requireBoth value="[boolean]"/><!-- 0..1 Both must be true flag --> </queryCriteria> <fhirPathCriteria value="[string]"/><!-- 0..1 FHIRPath based trigger rule --> </resourceTrigger> <eventTrigger> <!-- 0..* Event definitions the SubscriptionTopic --> <description value="[markdown]"/><!-- 0..1 Text representation of the event trigger --> <event><!-- 1..1 CodeableConcept Event which can trigger a notification from the SubscriptionTopic
|
Propose a change