Subscriptions in FHIR

In the upcoming R5 release of FHIR there has been some significant changes made regarding the use of subscriptions. The most notable difference is the change from query-defined to topic-based subscription.

A lot of FHIR users expressed a great interest in the these new possibilities and since the R5 release wasn’t planned until later, there seemed to be a need for an earlier update for subscriptions; i.e. R4B, which contains the updated features coming in R5. This update meant that we didn’t have to wait until the release of R5 to be able to use these new features. Instead, we have been developing our usage of the FHIR subscriptions alongside the development of R4B, and since 22–03–2022 we offer our customers the service of subscribing to events for appointments.

Our usage
The Subscription resource contains a wide range of possibilities when it comes to modifying the subscription of events. We decided however to keep it clean and simple in the beginning rather than trying to accomodate all possible use cases. We prefer making it more customizable to the actual needs of our customers further down the line. Instead of trying to make a service that cater to all possibilities, we want to focus on a service that fulfill actual needs. In this first release of subscriptions, we support the following topics:

• AppointmentCreated
• AppointmentUpdated
• AppointmentCancelled

and the following channel types:

• rest-hook

In short, this means that when there is an event that falls under one of the above topics and the customer the event belongs to have an active subscription, a notification about the event will be sent to the customer.

These are changes that will trigger a notification for an “AppointmentUpdated”-subscription:

• new start time
• new end time
• a patient was added to the appointment
• a patient was removed from the appointment
• the primary performer was changed
• the description was changed

Our customers can start subscribing to events without the need for administration from us at Visiba Care. As long as they are registered users of our API, they can set up, modify and end subscriptions without our help. The only requirement is that they can provide us with a valid endpoint for receiving events and handshakes from our subscription service.

For a detailed description on how to start subscribing to events at Visiba Care, visit our guide for developers.

What does a notification contain?
The notification sent is a Bundle that includes a SubscriptionStatus. The payload we support is id-only, which means that we don’t send any information about the resources (appointments) in the subscription notifications. Information about a resource are only available through our API, but each notification entry includes an URL which can be used to access that resource. By using id-only we are able to use preferred authorization and authentication logic, while still minimizing the need for expensive queries by subscribers.

https://argonautproject.github.io/subscription-backport-ig/payloads.html

In addition to the notification entries (i.e. the events), the SubscriptionStatus resource contains information about:

• type of notification (EventNotification/Handshake/QueryStatus /QueryEvent/HeartBeat)
• number of events included in the notification
• the total number of events created since the subscription was created
• a reference (url) to the subscription the notification event belongs to
• a reference (url) to the subscription topic the notification event belongs to
• the status of the subscription

The process
This first version of our subscription service was designed with a specific use case in mind; an integration that was originally built using AMQP queues. It seemed to serve perfectly as a test case for subscriptions. Designing for such a specific use case allowed us to have actual needs and possibilities as a starting ground when we began designing the subscription service. This proved to be helpful during the process as we sometimes found it a bit challenging to clarify what the subscription resource could and should contain.

The challenges were due to the fact that we designed our service during the same time the R5 backport were created by HL7. This meant that we had little documentation that we could be sure was correct, and found ourselves having to use documentation on different releases and interpret the differences as well as we could. To our help we had the test site https://subscriptions.argo.run/ (no longer available) where we could experiment with different settings used to create a subscription. We also had great use of the YouTube series on the subject by Gino Canessa, a developer at Microsoft who is specialized on FHIR.

Since the nuget package for the R5 backport wasn’t yet available when we started the development, we used the fhirCsR4B-models found here as placeholder models while waiting for the actual ones. This allowed us to test our code and build functionality necessary to move forward. We decided that while we would have to update some properties, mappings and maybe even functionality when switching models, the ability to move forward with our project was worth some backtracking and updating. When the time came to update our project with the correct models, it was as expected quite time consuming but considering the alternatives we were still content with our decision.

Connectathon and FHIR community
Since the FHIR Connectathon in January 2022 had a track for subscriptions, we thought that it might be an excellent opportunity for us to get answers to some of our questions and decided to participate. The lecturer for this track was of course Gino Canessa, the subscription guru. The track was mainly focusing on workshops and getting started with creating a subscription service. We felt that most of the workshops were not relevant to us, as we already were well on our way with our solution, but found great use of the discussion sessions where we could ask our questions and get answers to help us move forward. In hindsight we may find that had we had time to prepare a project for the workshops these too could have turned out to be valuable to us as we continued on with our work. If for nothing else, a better understanding of the basics in designing the service.

Another valuable source of information was the FHIR community-forum on Zulip, especially the subscriptions channel. By browsing through old posts we could find answers to questions and issues someone else had before us, and we were also able to ask questions to which we were not able to find answers elsewhere. Due to different time zones the answers would often come long after our work day had ended, but there was never any rushing issues.

Summary
It has been a challenging but interesting learning experience designing a solution before all the components and documentation was available. Looking back it feels like one of the things that made the process difficult was the inability to google for help with our problems. Since we were among the first to use these R5 backport updates there were no answers on Stack overflow (or basically anywhere else) to help us when we ran into problems. As a developer one can often suppose that someone else have had the same problem as you, and that the solution — or at least a part of it — is somewhere to be found if you just use the correct search term. This was not the case for us. Instead we relied heavily on discussions in our team as well as the information channels from Gino Canessa.

We decided early on in our process to create two branches and separate the subscription-flow (create, update and delete subscriptions) from the notification flow (trigger, create and send notifications). In hindsight this decision might not have been the best, considering that all updates we had to do when changing models etc. had to be done twice. Since we sometimes had to make educated guesses to proceed with our work, there were bound to be quite a lot of changes to our logic and model as we discovered later on that there were better solutions. This also caused us to having to update in both branches. Separating the different work-flows might be better for solutions that are not so based on a trial and error-approach.

The insights we’ve had as we completed this first version of our subscription service will come in handy moving forward. After all, there are still many ways to further explore the usage of the updated subscription resource.

Further reading

• Visiba Care development portal — https://developer.visibacare.dev
• Gino Canessa at YouTube — https://www.youtube.com/channel/UCwEwk15U0TXZWosH6Gq6THQ
• FHIR Subscriptions documentation at fhir.org — http://build.fhir.org/branches/R4B/subscription.html
• Zulip forum at FHIR Community — http://community.fhir.org/’

The Integration Team at Visiba Care
Text: Ellen Haglund (also from The Integration Team)