Publish-box (todo)

• Content
• Examples
• Detailed Descriptions
• Mappings
• Operations
• Search Params
• Profiles
• Extensions
• R4 Conversions

2.14 Resource SubscriptionTopic - Content

FHIR Infrastructure Work Group

Maturity Level: 2

Trial Use

Security Category: Business

Compartments: No defined compartments

Describes a stream of resource state changes or events and annotated with labels useful to filter projections from this topic.

2.14.3 References to this Resource

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

2.14.4 Resource Content

 

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

2.14.4.1 Terminology Bindings

Path	ValueSet	Type	Documentation
SubscriptionTopic.versionAlgorithm[x]	VersionAlgorithm	Extensible	Indicates the mechanism used to compare versions to determine which is more current.
SubscriptionTopic.status	PublicationStatus	Required	The lifecycle status of an artifact.
SubscriptionTopic.jurisdiction	JurisdictionValueSet	Extensible	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) .
SubscriptionTopic.trigger.resource	SubscriptionTypes	Extensible	Types used with Subscriptions
	All Resource Types	ui
SubscriptionTopic.trigger.supportedInteraction	InteractionTrigger	Required	FHIR RESTful interaction codes used for SubscriptionTopic trigger.
SubscriptionTopic.trigger.queryCriteria.resultForCreate	CriteriaNotExistsBehavior	Required	Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete).
SubscriptionTopic.trigger.queryCriteria.resultForDelete	CriteriaNotExistsBehavior	Required	Behavior a server can exhibit when a criteria state does not exist (e.g., state prior to a create or after a delete).
SubscriptionTopic.trigger.event	Hl7VSEventTypeCode (a valid code from eventType )	Example	Concepts specifying the trigger event for Version 2.x interface messages.
SubscriptionTopic.trigger.canFilterBy.resource	SubscriptionTypes	Extensible	Types used with Subscriptions
	All Resource Types	ui
SubscriptionTopic.trigger.canFilterBy.comparator	SearchComparator	Required	What Search Comparator Codes are supported in search.
SubscriptionTopic.trigger.canFilterBy.modifier	SearchModifierCode	Required	A supported modifier for a search parameter.
SubscriptionTopic.trigger.notificationShape.resource	SubscriptionTypes	Extensible	Types used with Subscriptions
	All Resource Types	ui

2.14.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.14.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.14.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.14.6.2 Resource Scope

Note that Subscription Topics are not limited to a single 'base' resource. As described on the Subscriptions Framework page, there are scenarios where multiple resources are in context for a single topic. When multiple resources are in scope, they may appear in:

• a single trigger.resource, via a lower-level grouping (e.g., Resource),
• multiple trigger repetitions, each with a different resource value,

When multiple resources are in scope, topic authors are responsible for ensuring that available filtering parameters are clear in their scope. For example, if a trigger is scoped to Resource, an allowed filter based on _language is clear and applicable to any possible resource. However, a search parameter of patient does not make sense in the context of all resources, since many resources do not include that search parameter. Note that the resource specified in canFilterBy.resource does not need to match the literals specified by triggers. For example, an event that triggers on all resource can specify different filters for each resource type.

2.14.6.3 Triggers vs. Filters

Subscription Topics contain two sets of evaluation criteria - one set as part of triggers (i.e., trigger) and the other as part of filters (i.e., trigger.canFilterBy). Triggers are the tests used to generate any notification by any subscription linked to a topic, while filters are the tests used by each subscription to differentiate the notifications they are interested in. For example, a topic could be defined to trigger for any new MedicationRequest - this allows server implementers to optimize tests at a single point. However, a patient is only interested in medication requests for them, which would be represented by a filter (e.g., on MedicationRequest.patient). The set of allowed filters are defined by the subscription topic, but actual values for filtering are listed in the Subscription.

This logical separation of triggers and filters exists to limit the complexity of topics. However, this specification does not place any architectural requirements on severs regarding the separation of triggers and filters. An implementation is free to separate the two portions or combine the tests as desired.

Note that triggers can be defined in three ways: as part of the conceptual definition, a computable trigger (i.e., a FHIRPath or query-based definition), and/or a possibly-computable event code. Topics without computable definitions are not expected to trigger unless a server has explicitly added support for them. For example, a trigger could be based on a complex set of criteria that is difficult to express or depend on information not available in a FHIR context (e.g., user information). Servers can implement these topics, but they require software changes and cannot be expected to trigger notifications generally. Servers that support the create interaction on SubscriptionTopic MAY reject resources that do not include computable definitions or depend on mechanisms the implementation does not support.

2.14.6.4 Triggers and 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.trigger.resource and SubscriptionTopic.trigger.supportedInteraction elements.

If a topic is designed to cover multiple resources, it can contain multiple trigger elements with each resource. If a topic is generic to all resources, the Resource is available within the FHIR Type value set.

Note that supportedInteraction filters can be used either alone, resulting in notifications for every time a resource has the interaction (e.g., every create), or with queryCriteria or fhirPathCriteria. When one or more supported interactions are defined, criteria SHOULD only be evaluated for interactions that are included. For example, a FHIRPath expression designed for resource updates might not test for the previous state correctly during create processing.

2.14.6.4.1 Trigger Interaction: Create

Subscription Topics that include create interactions are tested each time a resource of the specified type is created. If a topic contains no trigger criteria (either query-based or FHIRPath), a notification will be generated for every instance created. If criteria are specified, the criteria SHOULD only be evaluated after the interaction is confirmed to apply.

When using queryCriteria during a create, the previous test does not have a defined behavior - there is no resource available to test against. In order to filter correctly, a combination of resultForCreate and requireBoth must be specified. For example, setting both resultForCreate and requireBoth to true or false will result in criteria that can be tested against all interactions with expected behavior.

When using fhirPathCriteria during a create, the %previous variable will be set to empty ({}). Authors should ensure that expressions can be evaluated without errors in all applicable situations.

2.14.6.4.2 Trigger Interaction: Delete

Subscription Topics that include delete interactions are triggered each time a resource of the specified type is deleted. If a topic contains no trigger criteria (either query-based or FHIRPath), a notification will be generated for every instance deleted. If criteria are specified, the criteria SHOULD only be evaluated after the interaction is confirmed to apply.

When using queryCriteria during a delete, the current test does not have a defined behavior - there is no resource available to test against. In order to filter correctly, a combination of resultForDelete and requireBoth must be specified. For example, setting both resultForDelete and requireBoth to true or false will result in criteria that can be tested against all interactions with expected behavior.

When using fhirPathCriteria during a delete, the %current variable will be set to empty ({}). Authors should ensure that expressions can be evaluated without errors in all applicable situations.

2.14.6.4.3 Trigger Interaction: Update

Subscription Topics that include 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).

When using queryCriteria during an update, both the previous and current tests can apply. In most cases, an update should set requireBoth and ensure that the elements of interest are the ones changed to avoid generating notifications on unrelated updates. For example, if a topic is looking for changes to Encounter.status, only checking that the current status is in-progress would trigger notifications on changes to the Encounter.diagnosis for an in-progress encounter.

When using fhirPathCriteria during an update, it is recommended to test both the %previous and %current contents to ensure that only desired changes are captured. For example, if a topic is looking for changes to Encounter.status, only checking that the %current status is in-progress would trigger notifications on changes to the Encounter.diagnosis for an in-progress encounter.

2.14.6.5 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.14.6.5.1 Query (Search) Trigger 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 resource specified in trigger.resource (e.g., if the resource is Encounter, the list of available search parameters can be found on the Encounter Resource page).

Because FHIR search expressions are evaluated against a single resource, queryCriteria provides two elements for including criteria - previous for an expression tested against the resource as it existed before the current interaction and current for an expression tested against the resource as it exists after the current interaction.

When using query criteria, it is important to note the interaction between the supportedInteraction element, the previous and resultForCreate elements, the current and resultForDelete elements, and the requireBoth element. More information can be found in the Triggers and Resource Interactions section of this page.

2.14.6.5.2 FHIRPath Trigger 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, or {} if no previous state exists (e.g., during create)
• Variable %current - resource instance post state change being applied, or {} if no current state exists (e.g., during delete)

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

If the resource trigger includes a supportedInteraction filter, the FHIRPath expression SHALL only be tested for the listed interactions. Note that empty-checking must be included in a FHIRPath test if the test includes properties that do not exist for interactions included in the trigger. To continue with the above example, if the test should be applied to create interactions in addition to update ones, a more complete expression would be: (%previous.empty() | (%previous.status != 'in-progress')) and (%current.status = 'in-progress').

When using FHIRPath criteria, it is important to note the interaction between the supportedInteraction element and the %previous and %current variables. More information can be found in the Triggers and Resource Interactions section of this page.

2.14.6.6 Event Trigger 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. As with other types of trigger definitions, implementers have discretion on whether to support event trigger or not - the inclusion of an event definition in a trigger does not imply support within a server.

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 easily filter event-based topic definitions, event definitions require a "root" FHIR resource that can be referenced. This is defined in the trigger.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 are available. Note that it is not required to use a FHIR resource in this context, but use of non-FHIR-core structures (e.g., Logical Models) or non-FHIR definitions (e.g., a CDS Hook definition) limit access to standard filters. Topics can define filters in-line to enable filtering, but authors need to keep in mind additional implementation complexity.

Note that while having a conceptual description and linking to an event is sufficient for a definition, authors are encouraged to include computable triggers if possible.

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

Note that filters can be defined either to a single resource type (e.g., Patient) or to the 'lower-level' resource types (e.g., Resource). When defining allowed filters across resources, care should be taken to ensure that the parameters correctly apply to all resources included in scope. For example, a filter defined for Resource has well-defined behavior for search parameters like _language, _source, and _tag, but there is not a well-defined behavior for a parameter like patient across resources that are not in the patient compartment. Servers MAY reject subscriptions requests that are include too broad filters, determine at the time of creation which resources the parameter is applied to, or test each resource at runtime. More information is available on the Subscriptions Framework page.

2.14.6.7.1 Filter Parameter

The element canFilterBy.filterParameter contains the name of a parameter used to filter events for the focus 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.14.6.7.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.14.6.7.3 Comparators and Modifiers

In addition to the element or elements for a filter, sometimes it is necessary to describe additional behavior used in the filtering tests (e.g., asking for values in a range). To specify this, filters can specify comparator and modifier values, matching the behaviors defined by SearchParameters. Details about interactions with element types can be found on the search page, in the Modifiers and Prefixes sections.

Note:

• If no comparator or modifier is provided, the comparison is the default = match.
• 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.
• While filters may allow both, no single filter value allowed to have both a comparator and a modifier.

2.14.6.7.4 Filters on Event Triggers

On implementations that support event-based filtering, Subscriptions are able to directly filter based on event triggers defined in the SubscriptionTopic. See Subscription.filterBy.event for more details on usage.

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

Note that while the SubscriptionTopic resource defines filters that can be exposed to clients, actual filters and their values are specified by the Subscription resource.

2.14.6.7.5.1 Filters on Create Interactions

Logically, subscription 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).

2.14.6.7.5.2 Filters on Delete Interactions

Logically, query 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).

2.14.6.7.5.3 Filters on Update Interactions

Logically, query filters evaluated against update interactions MAY be performed either before or after the update occurs. For clarity, it is recommended that a topic does not define filters for the same resource elements being test for the notification triggers. For example, if a topic is looking for changes on the Encounter.status element, a filter for that element would always have different values in the two states. If a topic requires a filter on one of the elements present in the triggers, the author SHOULD explain in the topic definition when filters should be applied.

2.14.6.8 Notification Shape

In addition to the triggering information for a topic, this resource also defines the expected 'shape' of notifications via notificationShape. Each shape is defined according to a resource via the trigger.notificationShape.resource element. This is the 'focus' resource of the topic, or one of them if there are more than one, and the root resource for that shape definition. It will be the same, a generality, or a specificity of trigger.resource when it is present.

Note that multiple notificationShape elements can exist for the same resource, so that a server can indicate that there are multiple groupings of resources that may be sent. For example, a business-to-business (B2B) topic may include notifications on all changes to Patient resources, but may want to define that sometimes a Patient will include Encounters and other times Conditions.

2.14.6.8.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., trigger.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 trigger.resource could be set to Resource to trigger on all resources, with shapes 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.14.6.8.2 Including Additional Resources

Sometimes it is beneficial 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 SubscriptionTopic 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. Clients SHOULD be prepared to receive these additional resources, but SHALL function properly without them.

Inclusion directives MAY contain additional logic as allowed by search (e.g., iterating over inclusions). Server implementations are under no obligation to support additional logic, just as they are not required to support shape directives. Servers that do support inclusions but not support complex inclusion logic SHOULD ignore the additional directives in the include and revinclude elements. Note that there is currently no discovery mechanism for advertising or finding the level of shaping support for a server. Server implementers SHOULD document their support so that client implementers can discover this out-of-band.

In the SubscriptionTopic/example example, the focus resource is Encounter and lists several resources to include. The first inclusion, Encounter:patient&iterate=Patient.link requests that patients related to the encounter are included and that the server should follow the Patient.link element to include patients or related persons listed there.

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.

Note that the FHIR specification defines other mechanisms for defining graphs of resources - e.g., GraphDefinition and GraphQL. Currently, adoption of these mechanisms is significantly behind implementations of Search-based include. In order to support this functionality without adding barriers to implementing subscriptions, support for include and revinclude was selected. If another graph-defining mechanism gains widespread adoption, support could be added via an extension with changes to this resource in a future version of FHIR.

2.14.6.8.3 Including Related Queries

It can be beneficial to send queries to a subscriber either in addition to or instead of other contents in a notification (e.g., resource ids or resource contents). For example, when referrals for services that may be scheduled far into the future or when notifying of complex or non-standardized sets of information (e.g., insurance coverage).

In order to facilitate these workflows, a SubscriptionTopic can define a set of queries that MAY be included when a notification is sent. These queries are described as a list of Search Queries and optional coded information about the query (i.e., what information it provides). The queries included in a SubscriptionTopic are not required to be fully-resolvable, but rather a starting point or template for specific queries that are included in notifications. When notifications are generated, a server that supports this feature SHOULD include queries listed via notificationShape.relatedQuery if they exist and the workflow is one that can reasonably expect subscribers to be able to execute the queries. Note that support for including queries is optional and servers are not required to implement this functionality. Clients SHOULD be prepared to receive these queries, but SHALL function properly without them.

2.14.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: This section is still in early drafting; feedback from topic authors is welcome to refine the following guidance.

2.14.8 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource, and check the Extensions registry for search parameters on extensions related to 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	date	Date status first applied	SubscriptionTopic.date	30 Resources
derived-or-self	uri	A server defined search that matches either the url or derivedFrom	SubscriptionTopic.url | SubscriptionTopic.derivedFrom
effective	date	Effective period	SubscriptionTopic.effectivePeriod
event	token	Event trigger	SubscriptionTopic.trigger.event
identifier	token	Business Identifier for SubscriptionTopic	SubscriptionTopic.identifier	36 Resources
resource	uri	Allowed resource for this definition	SubscriptionTopic.trigger.resource
status	token	draft | active | retired | unknown	SubscriptionTopic.status	36 Resources
title	string	Name for this SubscriptionTopic (Human friendly)	SubscriptionTopic.title	27 Resources
trigger-description	string	Text representation of the trigger	SubscriptionTopic.trigger.description
url	uri	Logical canonical URL to reference this SubscriptionTopic (globally unique)	SubscriptionTopic.url	35 Resources
version	token	Business version of the SubscriptionTopic	SubscriptionTopic.version	31 Resources