• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles & Extensions
• Search Params

2.15 Resource SubscriptionTopic - Content

FHIR Infrastructure Work Group

Maturity Level: 0

Trial Use

Security Category: Business

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.15.3 References to this Resource

• Implements: Definition
• Resource References: Subscription, SubscriptionStatus, itself and TriggerDefinition

2.15.4 Resource Content

 

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) , the spreadsheet version & the dependency analysis

2.15.4.1 Terminology Bindings

Path	Definition	Type	Reference
SubscriptionTopic.status	The lifecycle status of an artifact.	Required	PublicationStatus
SubscriptionTopic.jurisdiction	This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used. Note: The codes for countries and country subdivisions are taken from ISO 3166 while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) .	Extensible	Jurisdiction ValueSet
SubscriptionTopic.resourceTrigger.resource	All FHIR types	Extensible	FHIRTypes
SubscriptionTopic.resourceTrigger.supportedInteraction	FHIR RESTful interaction codes used for SubscriptionTopic trigger.	Required	InteractionTrigger
SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate	Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete).	Required	CriteriaNotExistsBehavior
SubscriptionTopic.resourceTrigger.queryCriteria.resultForDelete	Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete).	Required	CriteriaNotExistsBehavior
SubscriptionTopic.eventTrigger.event	Concepts specifying the trigger event for Version 2.x interface messages.	Example	Hl7VSEventTypeCode
SubscriptionTopic.eventTrigger.resource	All FHIR types	Extensible	FHIRTypes
SubscriptionTopic.canFilterBy.resource	All FHIR types	Extensible	FHIRTypes
SubscriptionTopic.canFilterBy.modifier	FHIR search modifiers allowed for use in Subscriptions and SubscriptionTopics.	Required	SubscriptionSearchModifier
SubscriptionTopic.notificationShape.resource	All FHIR types	Extensible	FHIRTypes

2.15.5 Implementation Notes

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.15.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.15.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.15.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 Type value set.

2.15.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.15.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.15.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.15.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 benefit 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 precisely understand what is being defined.

2.15.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.15.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.15.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.15.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.15.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.15.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.15.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 modifier of sa (starts after) has no meaning when applied to a string).

If a search modifier is not provided, it is defaulted to = (no modifier).

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.15.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.15.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.15.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.15.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.15.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.15.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.15.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.15.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).

Note to Implementers: Warning: This section is still in early drafting; feedback from topic authors is welcome to refine the following guidance.

2.15.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.

Name	Type	Description	Expression	In Common
date N	date	Date status first applied	SubscriptionTopic.date
derived-or-self N	uri	A server defined search that matches either the url or derivedFrom	SubscriptionTopic.url | SubscriptionTopic.derivedFrom
identifier	token	Business Identifier for SubscriptionTopic	SubscriptionTopic.identifier
resource N	uri	Allowed Data type or Resource (reference to definition) for this definition, searches resourceTrigger, eventTrigger, and notificationShape for matches.	SubscriptionTopic.resourceTrigger.resource
status N	token	draft | active | retired | unknown	SubscriptionTopic.status
title N	string	Name for this SubscriptionTopic (Human friendly)	SubscriptionTopic.title
trigger-description N	string	Text representation of the trigger	SubscriptionTopic.resourceTrigger.description
url N	uri	Logical canonical URL to reference this SubscriptionTopic (globally unique)	SubscriptionTopic.url
version N	token	Business version of the SubscriptionTopic	SubscriptionTopic.version