This page is part of the Continuous Integration Build of FHIR Specification (v5.0.0: R5 - STU ). This is the current published version in it's permanent home (it will always (will be available incorrect/inconsistent at this URL). For a full list of available versions, see times).
See the Directory of published versions . Page versions: R5 R4B

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

2.14 Resource SubscriptionTopic - Content

Responsible Owner: FHIR Infrastructure Work Group

Maturity Level : 2   Trial Use Normative

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.resourceTrigger.resource SubscriptionTopic.trigger.resource	SubscriptionTypes	Extensible	Types used with Subscriptions
	All Resource Types	ui
SubscriptionTopic.resourceTrigger.supportedInteraction SubscriptionTopic.trigger.supportedInteraction	InteractionTrigger	Required	FHIR RESTful interaction codes used for SubscriptionTopic trigger.
SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate 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.resourceTrigger.queryCriteria.resultForDelete 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.eventTrigger.event SubscriptionTopic.trigger.event	Hl7VSEventTypeCode (a valid code from eventType )	Example	Concepts specifying the trigger event for Version 2.x interface messages.
SubscriptionTopic.eventTrigger.resource SubscriptionTypes Extensible Types used with Subscriptions   All Resource Types ui SubscriptionTopic.canFilterBy.resource SubscriptionTopic.trigger.canFilterBy.resource	SubscriptionTypes	Extensible	Types used with Subscriptions
	All Resource Types	ui
SubscriptionTopic.canFilterBy.comparator SubscriptionTopic.trigger.canFilterBy.comparator	SearchComparator	Required	What Search Comparator Codes are supported in search.
SubscriptionTopic.canFilterBy.modifier SubscriptionTopic.trigger.canFilterBy.modifier	SearchModifierCode	Required	A supported modifier for a search parameter.
SubscriptionTopic.notificationShape.resource 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:

• Trigger Evaluation : Determine how and when triggers will be evaluated in your system. Consider whether evaluation will occur synchronously during resource interactions or asynchronously via background processing, and how this affects notification timing and system performance.
• Filter Application : Plan how subscription filters will be applied to limit notifications. Consider whether filters will be evaluated in-process or via separate queries, and how filter complexity may impact system resources.
• Notification Delivery : Design a reliable mechanism for delivering notifications that handles temporary failures, retries, and subscriber unavailability. Consider whether notifications will be queued, and what happens if delivery repeatedly fails.
• Authorization : Ensure that subscription notifications respect the authorization context of the subscriber. Only send notifications and include resources that the subscriber is authorized to access.
• Performance Impact : Consider the performance implications of subscription processing on your server, especially when many subscriptions are active or when complex trigger criteria are defined. Plan for scaling as subscription usage grows.
• Testing and Validation : Verify that your implementation correctly triggers notifications under all defined conditions and that filters work as expected. Test edge cases like resource creation, deletion, and updates that may partially match criteria.

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 resourceTrigger.resource trigger.resource , via a lower-level grouping (e.g., Resource ),
• multiple resourceTrigger trigger repetitions, each with a different resource value,
a single eventTrigger.resource , via a lower-level grouping (e.g., Resource ), or multiple eventTrigger 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 topic 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 Non-FHIR Data

A Subscription Topic can be intended for use with a non-FHIR focus. There are several approaches for including and describing non-FHIR data in relation to subscriptions. Each approach has different trade-offs in terms of complexity, type safety, and ease of implementation. Below are some common approaches and considerations regarding triggering, filtering, and notifications.

Note that the examples for this section are based on a Patient Admission, which does have relevant FHIR resources and those representations would be used in any real implementation. The examples are purely illustrative of how non-FHIR data could be represented in a Subscription Topic context, and using a familiar use-case makes the examples easier to understand.

2.14.6.3.1 Logical Models

If the non-FHIR data can be represented as a FHIR Logical Model, it can be a good option for triggering and filtering. If the serialization of the model is stable in the implementation context, Logical Models can be used as the notification resource as well (e.g., using a JSON notification format and including a CDS Hooks model).

Authors are encouraged to keep in mind that non-FHIR content is not expected to be accessible via the FHIR-based Logical Model directly during processing. Implementers are likely to map any filtering and triggering logic to the native format of the non-FHIR data instead.

Note additionally that Search Parameter definitions cannot directly target Logical Models. Search Parameter resources can still be defined to establish types and show the relative path.

Related examples:

• SubscriptionTopic for Admission using a Logical Model
• Notification Bundle for a Logical Model

2.14.6.3.2 Basic Representation

If non-FHIR data is expected to be persisted and referenced like other FHIR resources, the Basic resource can be used. However, implementers must be aware that Basic requires mandatory fields (code, subject) that might not be meaningful for all non-FHIR events, and the non-FHIR data must be encoded using extensions or contained resources.

When using Basic to represent non-FHIR data, care should be taken to ensure that the structure is well-defined and consistent across notifications. Clear documentation of the expected extension names and data types is essential for implementers to correctly interpret the non-FHIR content. It is recommended to create a Profile based on the Basic resource to formalize the structure and constraints of the non-FHIR data representation.

Note that there are some challenges regarding filtering when using Basic as the root resource. Custom Search Parameters can be defined using FHIRPath expressions to traverse Extensions using navigational functions such as children() and descendants() , but care must be taken in the structure to make extraction feasible. When defining complex extensions, it is recommended to use extension.url values in sub-extensions that are compatible with FHIR search parameter naming conventions to ease mapping between filters and instance content (e.g., no spaces or special characters that require URL encoding).

Authors are encouraged to keep in mind that non-FHIR content is not typically in a Basic format during processing. Implementers are likely to map any filtering and triggering logic to the native format of the non-FHIR data instead.

Related examples:

• SubscriptionTopic for Admission using a Basic resource
• Notification Bundle for a Basic resource

2.14.6.3.3 Parameters Representation

A Parameters resource can be used as the root resource, with parameter parts containing Attachment , uri , url , or base64Binary valued elements to reference external data. This approach allows the structure of the Parameters resource to describe the organization of the non-FHIR data while maintaining type safety through FHIR data types.

For non-FHIR data with complex structure, Parameters can use nested parameter parts to represent hierarchical data. Each parameter.part can be used to encode discrete elements of the non-FHIR data structure. This approach provides a self-describing format where the parameter names indicate the meaning of each data element.

When using Parameters to represent non-FHIR data, care should be taken to ensure that the structure is well-defined and consistent across notifications. Clear documentation of the expected parameter names and data types is essential for implementers to correctly interpret the non-FHIR content. It is recommended to create a Profile based on the Parameters resource to formalize the structure and constraints of the non-FHIR data representation.

Note that there are some challenges regarding filtering when using Parameters as the root resource. Custom Search Parameters can be defined using FHIRPath expressions using navigational functions such as children() and descendants() , but care must be taken in the structure to make extraction feasible. It is recommended to use parameter.name values that are compatible with FHIR search parameter naming conventions to ease mapping between filters and instance content (e.g., no spaces or special characters).

Authors are encouraged to keep in mind that non-FHIR content is not typically in a Parameters format during processing. Implementers are likely to map any filtering and triggering logic to the native format of the non-FHIR data instead.

Related examples:

• SubscriptionTopic for Admission using Parameters
• Notification Bundle for a Parameters resource

2.14.6.3.4 Binary Resources

A Binary resource can be included in the notification to carry raw non-FHIR content. The Binary resource supports any content type via Binary.contentType and includes the data as base64-encoded content in Binary.data . This approach is suitable when the non-FHIR data is a single blob of content (e.g., a PDF document, an HL7v2 message, a proprietary format).

Note that Search Parameters are not expected to be defined for Binary content, so any filtering needs to be expressed against the non-FHIR content directly. This can make defining computable filters more challenging, and authors are encouraged to consider if other representations (e.g., Logical Models, Basic, or Parameters) might be more suitable if filtering is a key requirement.

Related examples:

• SubscriptionTopic for Admission using a Binary resource
• Notification Bundle for a Binary resource

2.14.6.4 Triggers vs. Filters

Subscription Topics contain two sets of evaluation criteria - one set as part of triggers (i.e., resourceTrigger , eventTrigger trigger ) and the other as part of filters (i.e., canFilterBy 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 resourceTrigger , trigger (i.e., a FHIRPath or query-based definition), and/or a possibly-computable eventTrigger . 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 MAY reject 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 2.14.6.5 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.resourceTrigger.resource SubscriptionTopic.trigger.resource and SubscriptionTopic.resourceTrigger.supportedInteraction SubscriptionTopic.trigger.supportedInteraction elements.

If a topic is designed to cover multiple resources, it can contain multiple resourceTrigger 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 either 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 2.14.6.5.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. For more details, see the Query (Search) Trigger Definitions section.

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 2.14.6.5.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. For more details, see the Query (Search) Trigger Definitions section.

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 2.14.6.5.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 2.14.6.6 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 2.14.6.6.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 resourceTrigger.resource trigger.resource (e.g., if the resource is an Encounter , the list of available search parameters can be found on the here 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 has been applied and current for an expression tested against the resource as it exists after the current interaction.

When using query criteria, it is important Because FHIR Queries cannot work against non-existent resources, the criteria include elements to note define behavior when one side of the interaction between test is not available. The resultForCreate element defines the result of the supportedInteraction previous element, test when the interaction is a create (i.e., no previous resource exists), while the resultForDelete and element defines the result of the resultForCreate current elements, test when the interaction is a delete (i.e., no current resource exists).

The requireBoth and element defines how the results of the two tests are combined. If resultForDelete requireBoth elements, and is true , both tests must evaluate to true for the overall criteria to evaluate to true . If requireBoth element. is false , only one of the two tests needs to evaluate to true for the overall criteria to evaluate to true . More information can be found in the Triggers and Resource Interactions section of this page.

In order to filter correctly on FHIR interactions, a combination of resultForCreate , resultForDelete , and requireBoth must be specified. The following table summarizes the behavior based on the settings of these parameters:

Interaction	resultForCreate	resultForDelete	requireBoth	Behavior
create	test-passes	not used	true	Notification triggered if the current criteria match. Missing prior version passes. Both tests must pass for notification. Current version is tested. If current passes, notification is sent.
create	test-passes	not used	false	Notification is always triggered. Missing prior version passes. Only a single pass is required. Notification is sent.
create	test-fails	not used	true	Notification is never triggered. Missing prior version fails. Two passes are required. Notification is not sent.
create	test-fails	not used	false	Notification triggered if the current criteria match. Missing prior version fails. Only one test must pass for notification. Current version is tested. If current passes, notification is sent.
delete	not used	test-passes	true	Notification triggered if the previous criteria match. Missing current version passes. Both tests must pass for notification. Previous version is tested. If previous passes, notification is sent.
delete	not used	test-passes	false	Notification is always triggered. Missing current version passes. Only a single pass is required. Notification is sent.
delete	not used	test-fails	true	Notification is never triggered. Missing current version fails. Two passes are required. Notification is not sent.
delete	not used	test-fails	false	Notification triggered if the previous criteria match. Missing current version fails. Only one test must pass for notification. Previous version is tested. If previous passes, notification is sent.
update	not used	not used	true	Notification triggered if both previous and current criteria match. Previous version is tested. If previous fails, notification is not sent. Current version is tested If current fails, notification is not sent. If both pass, notification is sent.
update	not used	not used	false	Notification triggered if either previous or current criteria match. Previous version is tested. If previous passes, notification is sent. Current version is tested If current passes, notification is sent.

Note that the query strings specified in previous and current are NOT required to be URL-encoded. Implementers should be defensive when processing these query criteria and check for both URL-encoded and non-URL-encoded forms to ensure compatibility across different implementations.

2.14.6.5.2 2.14.6.6.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 applied, or {} if no previous state exists (e.g., during create )
• Variable %current - resource instance post state change being applied 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 2.14.6.7 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 eventTrigger.resource 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 may be used. 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 resource computable triggers if possible.

2.14.6.7 2.14.6.8 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 2.14.6.8.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 . 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 2.14.6.8.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 2.14.6.8.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 2.14.6.8.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.8.5 Filter Timing and Interactions

Subscription processing (filter evaluation, content collection, and notification dispatch) is independent of the request that changes system state. Implementations are NOT required to block committing create/update/delete operations while evaluating subscriptions and are encouraged to implement their systems so that blocking does not occur. E.g., by performing subscription processing asynchronously via queues or background tasks. Included resources are expected, though not required, to reflect a consistent post-commit view. Temporary delays or failures in subscription processing are expected and SHOULD NOT roll back or affect the originating interaction.

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.4.1 2.14.6.8.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.4.2 2.14.6.8.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.4.3 2.14.6.8.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 2.14.6.9 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 notificationShape.resource 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 resourceTrigger.resource or eventTrigger.resource trigger.resource when they are 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 2.14.6.9.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 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 resourceTrigger.resource trigger.resource could be set to Resource to trigger on all resources. However, resources, with 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.14.6.8.2 2.14.6.9.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 Subscription 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.9.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.

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 the 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 (e.g., the client has access to the server). 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 26 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.eventTrigger.event SubscriptionTopic.trigger.event
experimental	token	Whether the SubscriptionTopic is experimental	SubscriptionTopic.experimental
identifier	token	Business Identifier for SubscriptionTopic	SubscriptionTopic.identifier	34 30 Resources
resource	uri	Allowed resource for this definition	SubscriptionTopic.resourceTrigger.resource | SubscriptionTopic.eventTrigger.resource | SubscriptionTopic.canFilterBy.resource | SubscriptionTopic.notificationShape.resource SubscriptionTopic.trigger.resource
status	token	draft | active | retired | unknown	SubscriptionTopic.status	35 30 Resources
title	string	Name for this SubscriptionTopic (Human friendly)	SubscriptionTopic.title	27 24 Resources
trigger-description	string	Text representation of the trigger	SubscriptionTopic.resourceTrigger.description SubscriptionTopic.trigger.description
url	uri	Logical canonical URL to reference this SubscriptionTopic (globally unique)	SubscriptionTopic.url	34 30 Resources
version	token	Business version of the SubscriptionTopic	SubscriptionTopic.version	30 27 Resources