owned this note
owned this note
Published
Linked with GitHub
# Subscriptions and Granularity
## Issue Summary
The issue we are looking at in this document is that:
* subscriptions are requested at *topic* granularity,
* *filters* and *shapes* are defined/instantiated at the *resource type* granularity
* notifications are issued per *subscription* - which by definition is *topic* granularity
This can make it hard for clients to understand what has occurred when a Topic could represent many different events.
## Definitions
* **filter**: a way of narrowing a broad *trigger* for a client.
* For example, a topic can represent all new perscriptions with a filter allowing for `Patient.id`.
* Allowed filters are *defined* in the `SubscriptionTopic` resource.
* Allowed filters are *instantiated* (given values) in the `Subscription` resource.
* **notification**: data related to the occurence of a *trigger*, sent to a client.
* This could be a 'ping' that a client should follow-up with, a list of ids to retrieve, full resources, or queries that a client should perform.
* Sent in a `Bundle` with a `SubscriptionStatus` resource.
* *notifications* are related to a single `Subscription`, and thus a single `SubscriptionTopic`.
* **shape**: resources relating to a *trigger* that are relevant to a client.
* The *shape* is used to define which resources can/should be communicated in a *notification*.
* A *shape* includes a **focus** (main) resource and can include **context** (additional) resources.
* For example, a 'patient discharge' trigger could be focused on `Encounter`, but *shaped* to include the relevant `Patient`, `Location`, `Practitioner`, etc..
* Potential/recommended shapes are *defined* in the `SubscriptionTopic` resource.
* Shape inclusions are *implemented* by servers at their discretion.
* **subscriber**: person/client requesting and receiving *notifications*.
* Defined in the `Subscription` resource.
* **subscription**: request for *notifications* based on one more *triggers*.
* Defined in the `Subscription` resource.
* The `Subscription` resource maps to a single `SubscriptionTopic`.
* **trigger**: something that happens.
* Can be described via a change in FHIR data, a coded event, etc..
* The `SubscriptionTopic` resource contains one or more *triggers*.
## Context
Topic-based subscriptions are concerned with *triggers* and *notifications*, using a *subscription* as the linking mechanism.
As the work was done defining these mechanisms, a lot of flexibility was left in by design - especially regarding pieces we did not have a lot of implementation experience with. In this document, we are specifically concerned with the granularity of *triggers* and *subscriptions*.
## What is a Topic, Really?
Noticable by absence in [Definitions](#Definitions) is a **topic**. That is because the definition in this context is what this document is exploring.
As currently specified, a **topic** contains at least one *trigger*, the set of allowed *filters*, and zero or more recommended *shapes* for related *notifications*.
This simplest case then is when a *topic* expresses exactly one *trigger*, one or more *filters* related to that *trigger*, and a desired *shape* for notifications for that *trigger*. This is easily expressable and traceable through all stages (definition in topic, instantiation in subscription, and notifications).
The trick (as usual) comes with complexity. For many expressed use cases, a single *trigger* is insufficient. There are three groups possible: a *single trigger*, *related triggers*, and *arbitrary triggers*. I will note that the lines between the groups are fuzzy (at best), but the distinction is useful nonetheless. For now, we will consider the triggers in isolation, outside of their definitional artifacts.
A *single trigger* is represented as a single set of *trigger* values in a topic, today as either a `resourceTrigger` or an `eventTrigger`. In the case that a trigger is defined by a single FHIR resource change, this is wonderfully simple - e.g., when an `Encounter` resource is created or updated to have a status of `in-progress`. With event definitions, this can a bit more nebulous - while something like a v2 `ADT^A04` event is very 'singular', nothing prohibits the use of a more generic v2 `ADT` as a trigger. Despite this, the parts we are concerned with here mean we can treat all *single trigger* definitions the same - regardless of the actual changes being monitored, these represent a single *trigger*. The defined *filters* and *shape* will be applied to any notifications generated for it, so all modeling choices remain the same.
*Related triggers* are grouped together logically by definition. As mentioned earlier, this grouping is done subjectively by the topic author or implementer. As examples, logical groupings could be: 'Encounter notifications', 'Care Team notifications', or 'Medication notifications'. While not required, *related triggers* will often have filters that can be applied sensibly across all *triggers* in the group. For example, all 'Encounter notifications' can be filtered by `patient`, `practitioner`, `location`, etc..
*Arbitrary triggers* are somewhat orthogonal to groupings in *related triggers*, and are generally more concerned with mapping topics to *subscribers*. For example, a patient may want all Encounter and Medication notifications; a public health agency may want all notifications related to certain Observations, Conditions, or Medications; etc..
## Model and Relationship Summary
For this discussion, the current models can be summarized as:
```mermaid
erDiagram
Topic {
canonical URL "1..1"
backbone resourceTrigger "0..*"
backbone eventTrigger "0..*"
backbone canFilterBy "0..*"
backbone notificationShape "0..*"
}
Subscription {
id id PK "1..1"
canonical topic FK "1..1"
backbone filter "0..*"
}
Notification {
reference subscription FK "1..1"
canonical topic FK "1..1"
backbone event "0..*"
}
Topic ||--o{ Subscription: "referenced by"
Subscription ||--o{ Notification : "referenced by"
Topic ||--o{ Notification : "referenced by"
```
* Topics define:
* The canonical URL used to reference them
* How notifications are triggered - by resource changes, events, or both
* What filters are allowed *for the topic*, *by resource type*
* What resource can/should/may be included (*shape*), *by resource type*
* Subscriptions define:
* The id used to reference them (logical id)
* The topic used to trigger notifications (*exactly one*)
* The filters applied to the topic, *by resource type*
* Notification details (protocol, endpoint, format, etc.)
* Notifications contiain:
* A single *canonical reference* to a topic
* A single *reference* to a subscription
* Zero or more events, all linked to a single subscription and (by definition) a single topic
## Issue Details
For this section, we want to consider the following group of potential triggers/events/topics at different 'levels' of granularity:
| Potential Topic | Trigger Type | Short | Definition |
| --------------------------------- | ------------ | ---------------------------- | ----------------------------------------------------------------------------------------- |
| HL7v2 `ADT^A01` | single | Admit/Visit Notification | Used to notify an addressee that a patient has been admitted. |
| HL7v2 `ADT^A02` | single | Transfer a Patient | Used when a patient is transferred from one location to another within the same facility. |
| HL7v2 `ADT^A03` | single | Discharge/End Visit | Communicates that a patient has been discharged from a hospital or their visit has ended. |
| HL7v2 `ADT` | related | Admit/Discharge/Transfer | Any Admit/Discharge/Transfer notification. |
| US Core `Encounter Notifications` | related | Change to Encounter resource | Changes to the `Encounter` resource that affects one or more elements used in US Core. |
| US Core `Notifications` | arbitrary | Change to any resource | Changes to a resource that affects one or more elements in any resource used in US Core. |
Specific considerations:
1. Implementers have enough granularity to support triggers in ways that make sense to them ([details](#c-1)).
1. Subscribers can ask for notifications at any granularity listed above ([details](#c-2)).
1. Filters need to be applied consistently ([details](#c-3)), e.g.:
* `patient` - e.g., notifications for me as a patient
* patient membership - e.g., notifications for a practitioner on a care team
* Arbitrary orgs/practitioners/etc. in the relevant resource - e.g., referral destination.
1. Subscribers can determine the *exact* trigger for a notification ([details](#c-4)).
### <a id="c-1"></a>Consideration 1: Implementer Granularity
In the current state, discovery is at the *topic* level. There is no consideration that a topic could be partially implemented.
Moving through the enumerated potential events above, this is problematic at any 'grouped' level (related or arbitrary). When a topic encapsulates multiple discrete events, the granularity is essentially lost.
While it is possible to use filters to select from discrete events within a topic, it gets painful quickly. For example, a topic could be defined with a trigger of "HL7v2 `ADT`" and create a *filter* of `adt-event` to narrow the triggering events to values such as `ADT^A01`, `ADT^A02`, etc.:
* subscriber will need to include the `adt-event` parameter in addition to each filter
* servers either need custom logic to determine which filters apply or will waste compute applying many filters that will never apply to the event (e.g., filters for other events)
The core issue here is that topics were defined as the 'smallest' granularity in the subscriptions framework.
### <a id="c-2"></a>Consideration 2: Subscriber Granularity
In the current state, subscription requests are made at the *topic* level.
Moving through the enumerated potential events above, this is problematic at any 'grouped' level (related or arbitrary). When a topic encapsulates multiple discrete events, the granularity is inaccessible.
While it is possible to use filters to select from discrete events within a topic, it gets painful quickly. For example, if the topic only exposed v2 `ADT` but allowed for a *filter* of `adt-event` for specifics:
* filters would need to include the `adt-event` parameter in addition to each filter
* using event filtering can be brittle - if a new version of the topic adds another event to the group, a subscriber may not get notifications for those events by default
* notifications are only granular to the topic level, so discrete notification events cannot be tied back to the actual triggering event
The core issue here is that topics were defined as the 'smallest' granularity in the subscriptions framework.
### <a id="c-3"></a>Consideration 3: Filter Application
In the current state, filters (and shapes) are defined and requested by *resource type*.
Moving through the enumerated potential events above, this is problematic at any 'grouped' level (related or arbitrary). Filters will be applied to any matching resource, which introduces a lot of complexity.
For example, if a 'core' topic covers all v2 `ADT` notifications, you may additionally want to expose a complex filter for discharge events (e.g., patients in a demographic that were prescibed a given medication for a specific condition). Once that filter is defined, it is *very easy* to mistakenly apply it transfer events.
The core issue here is that there is ambiguity between *filters* and *triggers* since they are *not* directly mapped 1:1.
### <a id="c-4"></a>Consideration 4: Notification Granularity
In the current state, notifications are only traceable to a subscription, which is 1:1 with a topic.
Moving through the enumerated potential events above, this is problematic at any 'grouped' level (related or arbitrary). Even though server implementers knew exactly which trigger caused a notification, subscribers will need to try and reconstruct that based on contents of notifications.
The current design was based on having multiple subscriptions if you need multiple topics. However this ends up introducing scaling issues if you have granular topics. It is not desireable to manage 10s of subscriptions per user.
The core issue here is that topics were defined as the 'smallest' granularity in the subscriptions framework.
## The Solution Space
To try and distill the issues above:
* `SubscriptionTopic` resources can define any number of *triggers*, whether or not they are related.
* `Subscription` resource map a single `SubscriptionTopic` to a single *subscriber*.
* *Notifications* are mapped to a single subscription.
To address the issues above, we need to add granularity. We can achieve this in two ways:
* **up**: expand granluarity 'up' by allowing representation of groups of topics, or
* **down**: expand granularity by drilling 'down' into triggers
Note that I chose 'up' and 'down' based on my internal mappings of the relationships - i.e., expanding past the current 'smallest' granularity as down and expanding past the current 'largest' granularity as up. I am happy to relabel if someone has a better pair of terms.
Following is a table comparing the solutions listed below:
| Solution | Conceptual Changes | Structural Changes (R6) | Extension Use (R4-R5) |
| -------------------------------------- | ------------------ | ----------------------- | ----------------------- |
| [Up: Collections of Topics](#s-up) | High | Low | Low |
| [Down A: `Element.id`](#s-down-a) | Low | Low | High |
| [Down B: Collapse Triggers](#s-down-b) | Low | High | High |
### <a id="s-up"></a>Up: Collections of Topics
This proposal moves granularity 'upwards' by adding a collection concept into `Subscription` and revising *topics* to represent the concept of only a single trigger. A topic still could have multiple definitions to account for different ways of triggering an event (e.g., a resource being deleted or getting a status of `entered-in-error`), but there is no granularity below a topic. There is no need to ever reference triggers since topics remain at the 'smallest' granularity.
In relation to each component:
* **topic**
* Topic definitions are constrained down to a single trigger concept.
* **trigger**
* Guidance to restrict triggers to a single 'concept'.
* **filter**
* Filter definitions are unchanged.
* **shape**
* Shape definitions are unchanged.
* **subscription**
* Subscriptions are modified to allow for more than one topic, either by composition (e.g., topics that are `partOf` or topics that `hasMemeber`), by collection (e.g., `List` of topics), or by array (e.g., `topic 0..* [SubscriptionTopic]`).
* In R6, modify the `Subscription.topic` element
* In R4-R5, use an extension to allow expanded references.
* **filter**
* Filter instances need to be tagged with the topic(s) they apply to.
* In R6, add an element to reference one or more topics.
* In R4-R5, use an extension to reference one or more topics.
* **notification**
* Notification events need to be tagged with the topic they were triggered by.
* In R6, add an element to `SubscriptionStatus.notificationEvent` referencing a topic
* In R4B-R5, use an extension to reference the topic on each `notificationEvent`.
* In R4, add a `Parameters.parameter.part` linking a notification event to a topic.
#### Pros
* Very low number of structual changes.
#### Cons
* High level of conceptual changes.
* Allowing multiple topics and/or non-canonical topics can be 'ugly' in backported versions.
#### Examples
<details>
<summary><code>Subscription</code> excerpt (R6)</summary>
```json
"resourceType": "Subscription",
// allow some form of collection of topics
"topic": (encounter-notification-topics),
"filterBy": [{
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add specific topic reference (canonical)
"topic": ["http://example.org/FHIR/SubscriptionTopic/encounter-start"]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R5)</summary>
```json
"resourceType": "Subscription",
// allow some form of collection of topics
"topic": (encounter-notification-topics),
// if array-type is preferred, add extension to bind to additional topics
"_topic": {
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-start"
}]
}
"filterBy": [{
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add topic reference
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-end"
}]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R4, R4B)</summary>
```json
"resourceType": "Subscription",
// allow some form of collection of topics
"criteria": (encounter-notification-topics),
"_criteria": {
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "Encounter?patient=Patient/123",
// add the topic reference
"_valueString": [{
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-end"
}]
}]
}]
}
```
</details>
<details>
<summary><code>SubscriptionStatus</code> excerpt (R4B, R5)</summary>
```json
"resourceType": "SubscriptionStatus",
"type": "event-notification",
"eventsSinceSubscriptionStart": "3",
"notificationEvent": [{
"eventNumber": "2",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
// add topic extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-end"
}]
}, {
"eventNumber": "3",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
// add topic extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-end"
}]
}],
"subscription": {
"reference": "https://example.org/fhir/r5/Subscription/123"
},
// TODO: need to review rules on if we can swap in a value here
"topic": (encounter-notification-topics)
```
</details>
<details>
<summary><code>Parameters</code> (status) excerpt (R4)</summary>
```json
"resourceType": "Parameters",
"parameter": [{
"name": "subscription",
"valueReference": {
"reference": "https://example.org/fhir/Subscription/encounters"
}
}, {
"name": "topic",
// change from canonical to uri to support other types, or repeat this for multiple
"valueUri": (encounter-notification-topics)
}, {
"name": "type",
"valueCode": "event-notification"
}, {
"name": "events-since-subscription-start",
"valueString": "3"
}, {
"name": "notification-event",
"part": [{
"name": "event-number",
"valueString": "2"
}, {
"name": "timestamp",
"valueInstant": "2020-05-29T11:44:13.1882432-05:00"
}, {
"name": "focus",
"valueReference": {
"reference": "https://example.org/fhir/Encounter/..."
}}, {
// add topic part
"name": "topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-start"
}]
}, {
"name": "notification-event",
"part": [{
"name": "event-number",
"valueString": "3"
}, {
"name": "timestamp",
"valueInstant": "2020-05-29T11:44:13.1882432-05:00"
}, {
"name": "focus",
"valueReference": {
"reference": "https://example.org/fhir/Encounter/..."
}}, {
// add topic part
"name": "topic",
"valueCanonical": "http://example.org/FHIR/SubscriptionTopic/encounter-complete"
}]
}]
```
</details>
### <a id="s-down-a"></a>Down A: Tag Triggers with `Element.id`
This option establishes using `Element.id` to link *triggers*, *filters*, *shapes*, and *notifications*. Specifically, a `SubscriptionTopic` identifies each *trigger* with an `id` and an extension is used to link back to each trigger.
Changes for each component:
* **topic**
* Topics need to include an `id` for each trigger and each related component will need to reference it if desired
* **trigger**
* In all FHIR versions, each trigger needs to set an `Element.id`.
* **filter**
* Each filter definition can reference the trigger it is relevant to.
* Filters can continue to use 'resource' level granularity if it makes sense.
* In R6, add an element to reference a trigger
* In R4-R5, use an extension to reference a trigger.
* **shape**
* Each shape definition needs to reference the trigger it is relevant to.
* In R6, add an element to reference a trigger
* In R4-R5, use an extension to reference a trigger.
* **subscription**
* Subscriptions need filters to link to specific triggers, if they are tagged.
* **filter**
* Each filter in a subscription will need to be tagged with an extension pointing to which trigger it is applicable to *if the trigger is tagged*.
* In R6, add an element to reference a trigger
* In R4-R5, use an extension to reference a trigger.
* **notification**
* Each notification needs to reference the triggering `Element.id`.
* In R6, add a reference element to `SubscriptionStatus.notificationEvent` (e.g., `triggerId`).
* In R4B-R5, use an extension on `SubsctiptionStatus.notificationEvent` to reference the trigger.
* In R4, use an additional `Parameters.parameter.part` to reference a trigger.
#### Pros
* Few and simple structural changes
#### Cons
* Leans heavily on extensions
#### Examples
<details>
<summary><code>SubscriptionTopic</code> excerpt (R6)</summary>
```json
"url": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"resourceTrigger": [{
// add a trigger element.id
"id": "encounter-started",
"description": "An Encounter has been started",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=in-progress",
"current": "status=in-progress",
},
}, {
// add a trigger element.id
"id": "encounter-completed",
"description": "An Encounter has been completed",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=completed",
"current": "status=completed",
}
}],
"eventTrigger": [{
// add a trigger element.id
"id": "v2-adt-a01",
"event": {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
},
}],
"canFilterBy": [{
// add filter trigger id, using the trigger element.id
"trigger-id": "encounter-started",
"resource": "Encounter",
"filterParameter": "patient"
}, {
// add filter trigger id, using the trigger element.id
"trigger-id": "encounter-completed",
"resource": "Encounter",
"filterParameter": "patient"
}]
```
</details>
<details>
<summary><code>SubscriptionTopic</code> excerpt (R4B, R5)</summary>
```json
"url": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"resourceTrigger": [{
// add a trigger element.id
"id": "encounter-started",
"description": "An Encounter has been started",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=in-progress",
"current": "status=in-progress",
},
}, {
// add a trigger element.id
"id": "encounter-completed",
"description": "An Encounter has been completed",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=completed",
"current": "status=completed",
}
}],
"eventTrigger": [{
// add a trigger element.id
"id": "v2-adt-a01",
"event": {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
},
}],
"canFilterBy": [{
"resource": "Encounter",
"filterParameter": "patient",
// add trigger-id extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-started"
}]
}, {
"resource": "Encounter",
"filterParameter": "patient",
// add trigger-id extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-completed"
}]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R6)</summary>
```json
"resourceType": "Subscription",
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"filterBy": [{
// add filter trigger id, using the trigger element.id
"trigger-id": "encounter-started",
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example"
}, {
// add filter trigger id, using the trigger element.id
"trigger-id": "encounter-completed",
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example"
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R5)</summary>
```json
"resourceType": "Subscription",
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"filterBy": [{
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add trigger-id extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-started"
}]
}, {
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add trigger-id extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-completed"
}]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R4, R4B)</summary>
```json
"resourceType": "Subscription",
"criteria": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"_criteria": {
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "Encounter?patient=Patient/123",
// add trigger-id extension
"_valueString": [{
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-started"
}]
}]
}, {
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "Encounter?patient=Patient/123",
// add trigger-id extension
"_valueString": [{
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-completed"
}]
}]
}]
}
```
</details>
<details>
<summary><code>SubscriptionStatus</code> excerpt (R6)</summary>
```json
"resourceType": "SubscriptionStatus",
"type": "event-notification",
"eventsSinceSubscriptionStart": "3",
"notificationEvent": [{
// add a notification event trigger id, using the topic trigger element.id
"trigger-id": "encounter-started",
"eventNumber": "2",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
}, {
// add a notification event trigger id, using the topic trigger element.id
"trigger-id": "encounter-completed",
"eventNumber": "3",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
}],
"subscription": {
"reference": "https://example.org/fhir/r5/Subscription/123"
},
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications"
```
</details>
<details>
<summary><code>SubscriptionStatus</code> excerpt (R4B, R5)</summary>
```json
"resourceType": "SubscriptionStatus",
"type": "event-notification",
"eventsSinceSubscriptionStart": "3",
"notificationEvent": [{
"eventNumber": "2",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
// add trigger-id extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-started"
}]
}, {
"eventNumber": "3",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
// add trigger-id extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/trigger-id",
"valueString": "encounter-completed"
}]
}],
"subscription": {
"reference": "https://example.org/fhir/r5/Subscription/123"
},
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications"
```
</details>
<details>
<summary><code>Parameters</code> (status) excerpt (R4)</summary>
```json
"resourceType": "Parameters",
"parameter": [{
"name": "subscription",
"valueReference": {
"reference": "https://example.org/fhir/Subscription/admission"
}
}, {
"name": "topic",
"valueCanonical": "http://hl7.org/SubscriptionTopic/admission"
}, {
"name": "type",
"valueCode": "event-notification"
}, {
"name": "events-since-subscription-start",
"valueString": "3"
}, {
"name": "notification-event",
"part": [{
"name": "event-number",
"valueString": "2"
}, {
"name": "timestamp",
"valueInstant": "2020-05-29T11:44:13.1882432-05:00"
}, {
"name": "focus",
"valueReference": {
"reference": "https://example.org/fhir/Encounter/..."
}},
// add a trigger-id part, using the topic trigger element.id
{
"name": "trigger-id",
"valueString": "encounter-started"
}]
}, {
"name": "notification-event",
"part": [{
"name": "event-number",
"valueString": "3"
}, {
"name": "timestamp",
"valueInstant": "2020-05-29T11:44:13.1882432-05:00"
}, {
"name": "focus",
"valueReference": {
"reference": "https://example.org/fhir/Encounter/..."
}},
// add a trigger-id part, using the topic trigger element.id
{
"name": "trigger-id",
"valueString": "encounter-completed"
}]
}]
```
</details>
### <a id="s-down-b"></a>Down B: Collapse Trigger Types
Currently, the `SubscriptionTopic` resource separates out resource-based triggers and event-based triggers. By collapsing the two types into a unified `trigger`, the event coding could be used to tag any notification.
In order to understand how to apply filters to triggers, the `canFilterBy` definitions in topics also need to be collapsed into the same backbone element (or could use tagging like some other solutions).
Conceptually, this moves all of the definitions into an array of `trigger` definitions that include everything each time.
Note that for R4B and R5, I chose to add an extension to `SubscriptionTopic.resourceTrigger` instead of adding several extensions to `eventTrigger`.
In relation to each component:
* **topic**
* **trigger**
* In R6, `resourceTrigger` and `eventTrigger` are collapsed into `trigger`.
* In R4-R5, add an extension with an event concept to `resourceTrigger`, `canFilterBy`, and `notificationShape`.
* **filter**
* Filters are *only* defined per trigger.
* In R6, `canFilterBy` is moved under `trigger`.
* In R4-R5, add an extension with an event concept `canFilterBy`.
* **shape**
* Shapes are *only* defined per trigger.
* In R6, `notificationShape` is moved under `trigger`.
* In R4-R5, add an extension with an event concept `notificationShape`.
* **subscription**
* Subscriptions should/can tag filters by event. If no event is specified, the filter should be applied to any trigger that contains a matching definition.
* **filter**
* In R6, add an event concept element to `filterBy`.
* In R4-R5, add an extension with an event concept to `filterBy`.
* **notification**
* Notification instances can be explicitly linked to a specific `trigger` via the `triggerEvent`. If there is no event defined by a trigger, the granularity stops at the level of the topic.
* In R6, add an event-concept element to `SubscriptionStatus.notificationEvent`.
* In R4B-R5, add an event-concept extension to `SubscriptionStatus.notificationEvent`.
* In R4, use an additional `Parameters.parameter.part` to reference the event concept.
#### Pros
* Very explicit.
* Clean modeling in R6.
* Low conceptual changes.
#### Cons
* Most structural change.
* Backporting this change involves a lot of extensions.
#### Examples
<details>
<summary><code>SubscriptionTopic</code> excerpt (R6)</summary>
```json
"url": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
// collapse resourceTrigger, eventTrigger, canFilterBy, and notificationShape into trigger
"trigger": [{
"description": "An Encounter has been started",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=in-progress",
"current": "status=in-progress",
},
"event": {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}],
},
"canFilterBy": [{
"filterParameter": "patient"
}]
},{
"description": "An Encounter has been completed",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=completed",
"current": "status=completed",
},
"event": {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}],
},
"canFilterBy": [{
"filterParameter": "patient"
}]
}]
```
</details>
<details>
<summary><code>SubscriptionTopic</code> excerpt (R4B, R5)</summary>
```json
"url": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"resourceTrigger": [{
"description": "An Encounter has been started",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=in-progress",
"current": "status=in-progress",
},
// add the event-trigger extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-trigger",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}]
}, {
"description": "An Encounter has been completed",
"resource": "http://hl7.org/fhir/StructureDefinition/Encounter",
"supportedInteraction": [ "create", "update" ],
"queryCriteria": {
"previous": "status:not=completed",
"current": "status=completed",
},
// add the event-trigger extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-trigger",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
}],
"canFilterBy": [{
"resource": "Encounter",
"filterParameter": "patient",
// add the event-trigger extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-trigger",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}]
}, {
"resource": "Encounter",
"filterParameter": "patient",
// add the event-trigger extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-trigger",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R6)</summary>
```json
"resourceType": "Subscription",
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"filterBy": [{
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add trigger event code
"forEvent": [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}, {
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add trigger event code
"forEvent": [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R5)</summary>
```json
"resourceType": "Subscription",
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"filterBy": [{
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add event-code extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-code",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}]
}, {
"resourceType": "Encounter",
"filterParameter": "patient",
"value": "Patient/example",
// add event-code extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-code",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
}]
```
</details>
<details>
<summary><code>Subscription</code> excerpt (R4, R4B)</summary>
```json
"resourceType": "Subscription",
"criteria": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications",
"_criteria": {
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "Encounter?patient=Patient/123",
// add event code extension
"_valueString": [{
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-code",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}]
}]
}, {
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "Encounter?patient=Patient/123",
// add event code extension
"_valueString": [{
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-code",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
}]
}]
}
```
</details>
<details>
<summary><code>SubscriptionStatus</code> excerpt (R4B, R5)</summary>
```json
"resourceType": "SubscriptionStatus",
"type": "event-notification",
"eventsSinceSubscriptionStart": "3",
"notificationEvent": [{
"eventNumber": "2",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
// add event-code extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-code",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}]
}, {
"eventNumber": "3",
"timestamp": "2020-05-29T11:44:13.1882432-05:00",
"focus": {
"reference": "https://example.org/fhir/Encounter/..."
},
// add event-code extension
"extension": [{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/event-code",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
}],
"subscription": {
"reference": "https://example.org/fhir/r5/Subscription/123"
},
"topic": "http://example.org/FHIR/SubscriptionTopic/encounter-notifications"
```
</details>
<details>
<summary><code>Parameters</code> (status) excerpt (R4)</summary>
```json
"resourceType": "Parameters",
"parameter": [{
"name": "subscription",
"valueReference": {
"reference": "https://example.org/fhir/Subscription/admission"
}
}, {
"name": "topic",
"valueCanonical": "http://hl7.org/SubscriptionTopic/admission"
}, {
"name": "type",
"valueCode": "event-notification"
}, {
"name": "events-since-subscription-start",
"valueString": "3"
}, {
"name": "notification-event",
"part": [{
"name": "event-number",
"valueString": "2"
}, {
"name": "timestamp",
"valueInstant": "2020-05-29T11:44:13.1882432-05:00"
}, {
"name": "focus",
"valueReference": {
"reference": "https://example.org/fhir/Encounter/..."
}}, {
// add for-event part
"name": "for-event",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A01",
"display" : "ADT/ACK - Admit/visit notification"
}]
}]
}, {
"name": "notification-event",
"part": [{
"name": "event-number",
"valueString": "3"
}, {
"name": "timestamp",
"valueInstant": "2020-05-29T11:44:13.1882432-05:00"
}, {
"name": "focus",
"valueReference": {
"reference": "https://example.org/fhir/Encounter/..."
}}, {
// add for-event part
"name": "for-event",
"valueCoding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0003",
"code" : "A03",
"display" : "ADT/ACK - Discharge/end visit"
}]
}]
}]
```
</details>