11.4    Manual Triggering
  • Subscription
  • 11.0 Introduction
  • 11.1 Architecture
  • 11.2 Channel Types
  • 11.3 Delivery Options
  • 11.4 Manual Triggering
  • 11.5 Topic Subscriptions
    •    Table of Contents

    Topic Subscriptions

    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 Notification✔✔✔See "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);
}
       11.4    Manual Triggering
  • Subscription
  • 11.0 Introduction
  • 11.1 Architecture
  • 11.2 Channel Types
  • 11.3 Delivery Options
  • 11.4 Manual Triggering
  • 11.5 Topic Subscriptions