This page is part of the FHIR Specification v4.3.0-snapshot1: R4B Snapshot to support the Jan 2022 Connectathon. About the R4B version of FHIR. The current officially released version is 4.3.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B

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

2.48 Resource SubscriptionTopic - Content

FHIR Infrastructure Work Group

Maturity Level: 0

Draft

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.48.3 References

This resource is referenced by SubscriptionStatus and itself.

This resource implements the Definition pattern.

2.48.4 Resource Content

 

See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions & the dependency analysis

2.48.4.1 Terminology Bindings

Path	Definition	Type	Reference
SubscriptionTopic.status		Required	PublicationStatus
SubscriptionTopic.jurisdiction		Extensible	Jurisdiction ValueSet
SubscriptionTopic.resourceTrigger.resource		Extensible	FHIRDefinedType
SubscriptionTopic.resourceTrigger.supportedInteraction		Required	InteractionTrigger
SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate		Required	CriteriaNotExistsBehavior
SubscriptionTopic.resourceTrigger.queryCriteria.resultForDelete		Required	CriteriaNotExistsBehavior
SubscriptionTopic.eventTrigger.event		Example	Hl7VSEventTypeCode
SubscriptionTopic.eventTrigger.resource		Extensible	FHIRDefinedType
SubscriptionTopic.canFilterBy.resource		Extensible	FHIRDefinedType
SubscriptionTopic.canFilterBy.modifier		Required	SubscriptionSearchModifier
SubscriptionTopic.notificationShape.resource		Extensible	FHIRDefinedType

2.48.5 Finding Subscription Topics

Example and Canonical Subscription Topics can be found at registry.fhir.org . It is strongly suggested that implementers reuse existing topics whenever possible for better compatibility.

2.48.6 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 topics to consider when implementing a Subscription Topic within a server:

2.48.7 Defining Subscription Topics

Defining a new SubscriptionTopic requires clear communication to implementers of both clients and servers around requirements and expectations. Anyone defining a SubscriptionTopic is encouraged to publish their definition at registry.fhir.org . Below are some points which should be considered when creating a SubscriptionTopic.

Definitions for Subscription Topics fall into three categories, which are described in more detail below. Good definitions will have useful definitions for two parts (conceptual and one of the other two), but the server implementation should always prioritize accurately representing the concept definition.

2.48.7.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 implementions will vary and clients will have unexpected behavior.

2.48.7.2 Resource Operation Pairs

Subscription Topics based on Resource Operation Pairs are the simplest to describe - definitions include the resource type (e.g., Patient, Encounter) and the operation of interest (e.g., create, delete).

Subscription Topics for resource-operation pairs are defined using the SubscriptionTopic.resourceTrigger.resource and SubscriptionTopic.resourceTrigger.methodCriteria fields.

2.48.7.2.1 Generic Resource

Some Subscription Topics are designed to apply to all resources. For example, a topic may be designed to cover any resource being deleted, any resource being tagged with a specific tag, etc. In these cases, implementers should use the Resource value from the FHIRDefinedType code system, which is defined as the parent for any resource.

2.48.7.2.2 Resource: Create

Subscription Topics defined around resource create operations 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.

• Example using 'create' operation

2.48.7.2.3 Resource: Delete

Subscription Topics defined around resource delete operations 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., deleting a Patient which has a particular Observation), implementers should use the computable definitions provided by Resource Value Tests.

• Example using 'delete' operation

2.48.7.2.4 Resource: Update

Subscription Topics defined around resource update operations 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 operations 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.

• Example using 'update' operation

2.48.7.3 Resource Value Tests

If a topic requires more granularity than operations provide, a topic can provide either FHIRPath or query (Search) definitions to test against state changes.

Computable Definitions serve two purposes when defining topics. First, some server implementers may be able to use computable definitions directly (or with minimal changes). In this scenario, the benifit of a computable definition is quite large (e.g., user-defined SubscriptionTopics, high portability, etc.). Second, implementers that do not use computable definitions internally will be able to read definitions during their implementation in order to precisley understand what is being defined.

2.48.7.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 SubscriptionTopic.resourceTrigger.resource (e.g., if the resource is an Encounter, the list of available search parameters can be found here).

2.48.7.3.2 FHIRPath Definitions

FHIRPath expressions can be used to define topical state changes in a server. Each FHIRPath expression is assumed to be provided the inputs listed below. If multiple FHIRPath expressions are present in SubscriptionTopic.resourceTrigger.fhirPathCriteria, they are joined together by AND clauses.

FHIRPath expression input variables:

• Variable [previous] = resource instance prior to state change being applied
• Variable [current] - resource instance post state change being applied

2.48.7.4 Referencing an Existing Event

Subscription Topics based on Event Definitions allow for the reuse of existing bodies of work and enable Subscriptions on concepts that may be difficult or impossible to describe based on the FHIR Resource model.

Subscription Topics for external event definitions are specified using the SubscriptionTopic.eventTrigger fields.

2.48.7.4.1 Defining a Focus Resource Type (from many)

Some events may definitionally include more than one resource. As an example, the HL7 v2 to FHIR mapping implementation guide (not yet published) currently includes the mapping for an ADT A01 message, which covers a patient admission event. In that mapping, the v2 message is converted into a FHIR Bundle, which may include instances of: Patient, Observation, RelatedPerson, Account, Encounter, AllergyIntolerance, and more. While the subscriptions framework can be used to include all the relevant resources, FHIR RESTful interactions are generally centered around a single resource. In order to establish better equivalency between the models, event definitions must also define a single focus resource type. Continuing with the example, a patient visit is generally rooted in the Encounter resource, so that would be a sensible root for such an event.

2.48.7.4.2 Defining a Focus Resource Type (from none)

Some events may not have a logical resource mapping in the current FHIR version. As an example, a system may want to define subscriptions around hosptial staff sign-ins (e.g., a practitioner has become 'available'). In this case, it is recommended that Subscription Topics use the Parameters resource as the focus, with parameter name-value pairs to convey the required information. Implementers creating topics that use Parameters this way should document what information is available, if possible both in the eventTrigger.description element and a more formal Profile.

2.48.7.5 Defining Filters for Subscriptions

In order to reduce the complexity of evaluating Subscription requests at runtime, topics define what filters clients are allowed to request. These filters are applied in servers to filter possible events into events that a particular client is interested in (e.g., from a topic defining all all admissions to a subscription for admissions on patients within a care team).

2.48.7.5.1 Search Parameter Name

The element SubscriptionTopic.canFilterBy.searchParamName contains the name of the search parameter used to filter events for the focus resource (defined by SubscriptionTopic.resourceTrigger.resource). The search parameter must be either from the list of Parameters for all resources (e.g., _id, _tag) or the parameters defined by the specific resource (e.g., Encounter Search Parameters, Patient search parameters, etc.).

If a search parameter name is not provided, it is defaulted to _id.

2.48.7.5.2 Search Modifier

The element SubscriptionTopic.canFilterBy.searchModifier contains the search modifier used when evaluating a change. Allowed search parameters are pulled from Search, with the addition of = to show simple equality (e.g., no modifier). Note that modifiers are only valid for specific types of data (e.g., a modifer of sa (starts after) has no meaning when applied to a string).

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

2.48.7.5.3 Filter Timing

When to evaluate filters depends on the type of change covered by the topic.

2.48.7.5.3.1 Create

Filters for create operations must be applied 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.48.7.5.3.2 Delete

Filters for delete operations must be applied 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.48.7.5.3.3 Update

Filters for update operations can be applied to either the pre-update or post-update state. Servers SHOULD document their method of operation.

2.48.7.6 Notification Shape

In addition to the triggering information for a topic, this resource also defines the expected 'shape' of notifications via SubscriptionTopic.notificationShape. This element defines the possible 'root' resources for a notification, as well as additional resources that may be included.

2.48.7.6.1 Root Resource

The element SubscriptionTopic.notificationShape.resource defines a 'root' resource for notifications. Typically, this resource will be the same as the triggering resource (e.g., SubscriptionTopic.resourceTrigger.resource or SubscriptionTopic.eventTrigger.resource), however there may be situations where this is not the case. For example, a topic may be defined across all resources (e.g., every time a resource is deleted), but the author may want additional information depending on which resource is involved. In that scenario, the resourceTrigger.resource could be set to Resource to trigger on all resources. However, shapes could be defined for each resource in the patient compartment to include patient information with those notifications (e.g., if an Encounter is deleted, include the Patient record as well). Note that the opposite scenario is also supported - an author may define multiple triggers on different types of events and simply define a shape that is valid for all of those resources.

2.48.7.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 SubscriptionTopic.notificationShape.resource for a matching resource and SHOULD include any additional resources listed via SubscriptionTopic.notificationShape.include and SubscriptionTopic.notificationShape.revInclude, if they exist and the user context for the subscription is authorized to access them.

Included resources should be added in the same style as the focus resource - e.g., if notifications are id-only, then included resources should only include their ids as well.

2.48.8 Deriving from existing Subscription Topics

Implementers are encouraged to add additional filters, but cannot remove existing ones nor change the 'concept' of a SubscriptionTopic during derivation. For example:

• Deriving a new SubscriptionTopic with the same concept but a different computable definition is OK.
• Deriving a new SubscriptionTopic to expose additional canFilterBy parameters is OK.
• Deriving a new SubscriptionTopic to remove an existing canFilterBy parameter is NOT ok.
• Deriving a new SubscriptionTopic based on a different resource than its parent is NOT ok (e.g., start/end of medication derived from encounter).

Trial-Use Note: Warning: This section is still in early drafting.

2.48.9 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 TU	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