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

2.49 Resource SubscriptionTopic - Content

FHIR Infrastructure Work Group

Maturity Level: 0

Trial Use

Security Category: Business

Compartments: Not linked to any defined compartments

Describes a stream of resource state changes identified by trigger criteria and annotated with labels useful to filter projections from this topic.

2.49.3 References

This resource is referenced by Subscription, SubscriptionStatus and itself.

This resource implements the Definition pattern.

2.49.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 spreadsheet version & the dependency analysis a

2.49.4.1 Terminology Bindings

Path	Definition	Type	Reference
SubscriptionTopic.status		Required	PublicationStatus
SubscriptionTopic.jurisdiction		Extensible	Jurisdiction ValueSet
SubscriptionTopic.resourceTrigger.resourceType		Extensible	FHIRDefinedType
SubscriptionTopic.resourceTrigger.methodCriteria		Required	InteractionTrigger
SubscriptionTopic.resourceTrigger.queryCriteria.resultForCreate		Required	CriteriaNotExistsBehavior
SubscriptionTopic.resourceTrigger.queryCriteria.resultForDelete		Required	CriteriaNotExistsBehavior
SubscriptionTopic.resourceTrigger.canFilterBy.searchModifier		Required	SubscriptionSearchModifier

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

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

2.49.6.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.resourceType and SubscriptionTopic.resourceTrigger.methodCriteria fields.

2.49.6.2.1 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.49.6.2.2 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.49.6.2.3 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.49.6.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.49.6.3.1 Query (Search) Definitions

Query definitions are based on Search evaluations performed before and/or after a state change in the server. Allowed query parameters are based on the SubscriptionTopic.resourceTrigger.resourceType (e.g., if the resource is an Encounter, the list of available search parameters can be found here).

2.49.6.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.49.6.4 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.49.6.4.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.resourceType). 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.49.6.4.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.49.6.4.3 Filter Timing

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

2.49.6.4.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.49.6.4.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.49.6.4.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.49.7 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.49.8 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
date N	date	Date status first applied	SubscriptionTopic.date
derived-or-self N	uri	A server defined search that matches either the url or derivedFrom	SubscriptionTopic.url | SubscriptionTopic.derivedFrom
identifier	token	Business Identifier for SubscriptionTopic	SubscriptionTopic.identifier
publisher	reference	The name of the individual or organization that published the SubscriptionTopic	SubscriptionTopic.publisher (Practitioner, Organization, PractitionerRole)
resource-type N	uri	Allowed Data type or Resource (reference to definition) for this definition	SubscriptionTopic.resourceTrigger.resourceType
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