Smile CDR v2024.05.PRE
On this page:

11.5.1Topic Subscriptions
Experimental

 

FHIR R4 Subscriptions are based on a single Subscription resource that defines both the criteria for triggering a resource change notification as well as the channel for sending a notification.

FHIR R5 Subscriptions separates these functions. The criteria for triggering a notification is now defined in a new SubscriptionTopic resource while the channel delivery detail remains in the Subscription resource. The two are linked via a canonical identifier:

Subscription.topic SubscriptionTopic.url

In R5, multiple Subscription resources can subscribe to the same SubscriptionTopic, and refine the notifications they accept via filters.

Also, R5 SubscriptionTopic triggers are greatly expanded from the criteria available in R4. A R4 Subscription contains a single query string, e.g. Observation?code=DIAB that will only match CREATE and UPDATE operations and can only evaluate the most recent version of the resource. A R5 SubscriptionTopic, on the other hand, defines a rich collection of triggers that can match details of the previous version of a resource as well as the new version. R5 SubscriptionTopic triggers can detect specific resource state transitions, or DELETE operations on specified resources. R5 SubscriptionTopic resources can also define arbitrary business event triggers that have nothing to do with resource changes.

FHIR R5 functionality is available to FHRI R4 systems in one of two ways:

FHIR R4B extends FHIR R4 by adding the SubscriptionTopic and SubscriptionStatus resources as well as defining a number of extensions to support R5-style subscriptions.

The FHIR R5 Subscription Backport to R4 offers limited capability to R4 systems via extensions and namespaces defined in an IG.

11.5.1.1Topic Subscription Support in Smile CDR

Limited Subscription R5 functionality, as well as the backports to R4B and R4 is now available in Smile CDR. Here is a summary of what is currently supported.

FeatureR5R4BR4Notes
Topic Subscription
SubscriptionTopic
SubscriptionStatus
Notification Bundle
Event NotificationSee "Dispatching Subscription Notifications" below
Cross-partition matching Cross-partition matching is currently only supported for DSTU3 and R4 (i.e. non-topic-based) Subscriptions
Subscription/$status

This list does not cover all fields, just the most common fields used in matching and delivery logic.

ResourceFieldR5R4BR4Notes
SubscriptionStatuseventsSinceSubscriptionStart~~ Currently this only counts the number of deliveries for this subscription on this server
SubscriptionStatusnotificationEvent.eventNumber~~ This is the same as eventsSinceSubscriptionStart and is only unique on the server it is running on
SusbcriptionTopicqueryCriteria.previous
SusbcriptionTopicqueryCriteria.current
SusbcriptionTopicqueryCriteria.requireBoth
SusbcriptionTopicqueryCriteria.resultForCreate
SusbcriptionTopicqueryCriteria.resultForDelete
SusbcriptionTopicfhirPathCriteria
SusbcriptionTopiccanFilterBy The system assumes all search parameters are valid filters
SusbcriptionTopicnotificationShape E.g. include, revinclude
SusbcriptionfilterBy.resourceType
SusbcriptionfilterBy.filterParameter
SusbcriptionfilterBy.comparator~~~only EQ and NE are currently supported. The R4 backport currently only supports EQ.
SusbcriptionfilterBy.modifier
SusbcriptionfilterBy.value
Susbcriptioncontent~~~Only full-resource is supported

11.5.1.1.1Dispatching Subscription Notifications

In most cases the resource trigger for event notification will be fully defined within a SubscriptionTopic and the matching and delivery will happen automatically. However for event triggers, or in the case of R4 where there are no SubscriptionTopic resources, delivery of notifications to topic subscriptions must be triggered manually. This is done in Java through the use of the SubscriptionTopicDispatcher service. This service can be autowired into an interceptor or other Java extension. There are two methods available. Both methods return the number of notifications successfully queued for delivery.

int mySubscriptionTopicDispatcher.dispatch(String theTopicUrl, List<IBaseResource> theResources, RestOperationTypeEnum theRequestType)
ParameterDescription
theTopicUrlDeliver to subscriptions for this topic
theResourcesThe list of resources to deliver. The first resource will be the primary "focus" resource per the Subscription documentation. This list should not include the SubscriptionStatus. The SubscriptionStatus will be added as the first element to the delivered bundle. The reason for this is that the SubscriptionStatus needs to reference the subscription ID, which is not known until the bundle is delivered.
theRequestTypeThe type of request that led to this dispatch. This determines the request type of the bundle entries

If filtering is required, then the following method can be used:

int mySubscriptionTopicDispatcher.dispatch(SubscriptionTopicDispatchRequest theSubscriptionTopicDispatchRequest)

The SubscriptionTopicDispatchRequest constructor has the following fields:

ParameterDescription
theTopicUrlDeliver to subscriptions for this topic
theResourcesThe list of resources to deliver. The first resource will be the primary "focus" resource per the Subscription documentation. This list should not include the SubscriptionStatus. The SubscriptionStatus will be added as the first element to the delivered bundle. The reason for this is that the SubscriptionStatus needs to reference the subscription ID, which is not known until the bundle is delivered.
theSubscriptionTopicFilterMatcheris used to match the primary "focus" resource against the subscription filters
theRequestTypeThe type of request that led to this dispatch. This determines the request type of the bundle entries
theInMemoryMatchResultInformation about the match event that led to this dispatch that is sent to SUBSCRIPTION_RESOURCE_MATCHED
theRequestPartitionIdThe request partitions of the request, if any. This is used by subscriptions that need to perform repository operations as a result of the notification
theTransactionIdThe transaction ID of the request, if any. This is used by subscriptions that need to perform repository operations as a result of the notification

Here is the definition of the ISubscriptionTopicFilterMatcher interface:

public interface ISubscriptionTopicFilterMatcher {
	InMemoryMatchResult match(CanonicalTopicSubscriptionFilter theCanonicalTopicSubscriptionFilter, IBaseResource theIBaseResource);
}