# Topic Subscriptions [EAP](/content/docs/hdp_product/maturity_model.html)

[FHIR R4 Subscriptions](https://hl7.org/fhir/R4/subscription.html) 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](http://hl7.org/fhir/R5/subscriptions.html) 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](http://build.fhir.org/ig/HL7/fhir-subscription-backport-ig/components.html) offers limited capability to R4 systems via extensions and namespaces defined in an IG.

## Topic 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.

| Feature | R5 | R4B | R4 | Notes |
| --- | --- | --- | --- | --- |
| Topic Subscription | ✔ | ✔ | ✔ |  |
| SubscriptionTopic | ✔ | ✔ | \* | \\* In R4, SubscriptionTopic is represented as a Basic resource with extensions per the [Subscriptions R5 Backport Specification](https://hl7.org/fhir/uv/subscriptions-backport/2024Jan/) |
| SubscriptionStatus | ✔ | ✔ | \* | \\* In R4, SubscriptionStatus is represented as a Parameters resource per the [Subscriptions R5 Backport Specification](https://hl7.org/fhir/uv/subscriptions-backport/2024Jan/) |
| 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.

| Resource | Field | R5 | R4B | R4 | Notes |
| --- | --- | --- | --- | --- | --- |
| SubscriptionStatus | eventsSinceSubscriptionStart | ~ | ~ | ~ | Currently this only counts the number of deliveries for this subscription on this server |
| SubscriptionStatus | notificationEvent.eventNumber | ~ | ~ | ~ | This is the same as eventsSinceSubscriptionStart and is only unique on the server it is running on |
| SusbcriptionTopic | queryCriteria.previous | ✔ | ✔ | ✔ |  |
| SusbcriptionTopic | queryCriteria.current | ✔ | ✔ | ✔ |  |
| SusbcriptionTopic | queryCriteria.requireBoth | ✔ | ✔ | ✔ |  |
| SusbcriptionTopic | queryCriteria.resultForCreate |  |  |  |  |
| SusbcriptionTopic | queryCriteria.resultForDelete |  |  |  |  |
| SusbcriptionTopic | fhirPathCriteria |  |  |  |  |
| SusbcriptionTopic | canFilterBy |  |  |  | The system assumes all search parameters are valid filters |
| SusbcriptionTopic | notificationShape | ✔ | ✔ | ✔ | E.g. include, revinclude |
| Susbcription | filterBy.resourceType | ✔ | ✔ | ✔ |  |
| Susbcription | filterBy.filterParameter | ✔ | ✔ | ✔ |  |
| Susbcription | filterBy.comparator | ~ | ~ | ~ | only EQ and NE are currently supported. The R4 backport currently only supports EQ. |
| Susbcription | filterBy.modifier |  |  |  |  |
| Susbcription | filterBy.value | ✔ | ✔ | ✔ |  |
| Susbcription | content | ~ | ~ | ~ | Only full-resource is supported |

**Dispatching 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 when manual dispatching is needed, notifications to topic subscriptions can be triggered programmatically. 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.

```java
int mySubscriptionTopicDispatcher.dispatch(String theTopicUrl, List<IBaseResource> theResources, RestOperationTypeEnum theRequestType)
```

Copy

| Parameter | Description |
| --- | --- |
| theTopicUrl | Deliver to subscriptions for this topic |
| theResources | The 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. |
| theRequestType | The 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:

```java
int mySubscriptionTopicDispatcher.dispatch(SubscriptionTopicDispatchRequest theSubscriptionTopicDispatchRequest)
```

Copy

The `SubscriptionTopicDispatchRequest` constructor has the following fields:

Here is the definition of the `ISubscriptionTopicFilterMatcher` interface:

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

Copy

[Manual Triggering](/content/docs/subscription/manual_triggering.html)

Topic Subscriptions

Subscription

[Introduction](/content/docs/subscription/introduction.html)
[Architecture](/content/docs/subscription/architecture.html)
[Channel Types](/content/docs/subscription/channels.html)
[Delivery Options](/content/docs/subscription/delivery.html)
[Manual Triggering](/content/docs/subscription/manual_triggering.html)
[Topic Subscriptions](/content/docs/subscription/topic.html)