Page tree
Skip to end of metadata
Go to start of metadata

Submitting WG/Project/Implementer Group

FHIR-I

Justification and Objectives

This track is an important step in advancing the maturity of the interactions and resources associated with FHIR Subscriptions.

The subscription pub/sub pattern enables FHIR clients to retrieve data from a server without performing a more expensive periodic polling queries.

Specifically for this track, we will continue to have the Rest Hook option, but would like to make sure we have participants that give feedback on web sockets.

In addition, we would like to discuss and get feedback on using EventDefinition: https://chat.fhir.org/#narrow/stream/179229-subscriptions/topic/Event.20Definition

This track will use version R4  of FHIR.

Criteria vs event subscriptions

We will have a special break out session in Salon 1 on Saturday at 16:00 to discuss more in person about Event subscriptions. (Slides: http://bit.ly/subscriptions-May2019) (Josh's examples: https://github.com/argonautproject/subscriptions/blob/master/subscriptions-as-event-streams.md)

We will have a break out session in Salon 6 on Sunday at 15:00 to discuss more on Event subscriptions See proposal discussed here: https://docs.google.com/document/d/1FkrBY6gykrCFkeRWLWdrpdIPSho6s-yvVu_CaZ9lQhs/edit?ts=5ccf3464#

(note, this was built out more during the WGM and is now here: https://docs.google.com/document/d/1rjOI49M-PBVDT7DpLT9LolV4e3qNU1jZbBKdxTwtRE8/edit )

Many clinical systems are event-based and support an event-based notification mechanism, in which events are defined ahead of time; whereas, the FHIR Subscriptions criteria element requires FHIR servers to detect changes as they occur. While native FHIR servers may reasonably be able to execute subscribed FHIR queries against every resource as it's created or modified, this would not work well for systems that implement clinical workflow.

An implementable subscription criteria would rather be based on an event and then narrowed to specific attributes/criteria. By using a FHIR EventDefinition, clients may create and subscribe to defined events via fhirpath in native FHIR servers or simply subscribe to named EventDefinitions in clinical workflow servers. 

Example EventDefinition extension

GET <fhir base url>/EventDefinition?name=patient-admit

{
  "resourceType": "EventDefinition",
  "id": "123",
  "status": "active",
  "name": "patient-admit",
  "description": "Patient admitted",
  "trigger": {
    "type": "named-event",
    "name": "patient-admit",
    "data" : {
      "type":"Encounter"
    },
    "condition": {
      "description": "Encounter is newly arrived",
      "language": "text/fhirpath",
      "expression": "this.status == "arrived" and %previous.status != "arrived""
    }
  }
}

POST <fhir base url>/Subscription
{
  "resourceType": "Subscription",
  "criteria": "Patient/abc",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://biliwatch.com/customers/mount-auburn-miu/on-result",
    "payload": "application/fhir+json"
    },
  "id": "00000000007C2DCBF35FA1921026459D",
  "extension": [{
  "valueReference": {
    "reference": "https://example.com/EventDefinition/123",
    "display": "patient admitted"
    },
  "url": "http://hl7.org/fhir/subscription/topics"
  }]
}



Notes from Saturday Breakout

  • Traditional Subscription challenges:
    • Computationally expensive for pure FHIR server as well (linear)
    • Not "discoverable" - can't tell what subscriptions a server supports programmatically (and most servers will limit)
    • Doesn't alert when it's no longer in the criteria (just "disappears")
  • Event Subscription challenges:
    • defined meaning/shared meaning, if it's named we need to ensure that they're consistent
  • EventDefinition: streams (ORs)
    • Event Filter: removes/identifies specific events in the stream
    • union(admission).union(discharge).union(transfer).filter(patient=123)
  • Could describe 1 firehose, other definitions as "filters". EG: firehose.intersect(admission).intersect(patient=123)
  • Filters in example seem to be disconnected from definitions
  • EventDefinition to compartment? Group, Patient,... - this is much more limited and scalable
    • it may not allow for all use cases we have (slots, all updates to keep local copies up to date)
      • EG: byCompartment: [Patient/1, Patient/2, Patient/3, Group/5], topic: [new-lab, new-med,..]
  • These don't remove the "things just drop off" concerns. Security, moving out of a group, etc could still cause it to disappear
    • could create a delete topic/event to catch *some* of the previously missing items

Summary of common Goals:

  • Decouple subscription from definition
  • Solve falling out problem
  • Desire to be able to pre-define criteria (potentiall with limited number of params)
    • more params may have an effect on optimization

Proposed Track Lead

Jenni Syed (https://chat.fhir.org/#narrow/pm-with/191356-jenni.syed)  

Expected participants

Servers and/or Client apps:

  • Allscripts
  • Apple
  • CareEvolution
  • Cerner
  • Google
  • Lantana Consulting
  • Lamprey/Continua
  • Microsoft

Interested Parties:

  • Chuck Feltner
  • Edward Yurcisin
  • Epic

Track Orientation

Monday, April 29 at 1PM America/Chicago.

https://cernermeeting.webex.com/cernermeeting/j.php?MTID=m30bdc83bd6c80e4c7171f09354dbee38
Meeting number (access code): 590 383 013 
Meeting password: 8vX4mayB

Join from a video system or application
Dial 590383013@cernermeeting.webex.com 
You can also dial 173.243.2.68 and enter your meeting number.

Join by phone 
+1-866-662-9987 US Toll Free 
+1-210-795-1110 US Toll

Slides: https://docs.google.com/presentation/d/1CApayMqvBy7IcBx8qo53IDHuVcU1Bzw98izhOC5ynWs/edit?usp=sharing

Video: Subscription Track Orientation-20190429 1802-1.mp4

System Roles

FHIR Server

The FHIR Server supports the Subscription resource and notifying subscribed clients of changes.

  • Must expose a Subscriptions resource supporting read, create and update.
  • Must also act as a client to send notifications.
  • Should expose capabilities to use web sockets on the subscription.

Subscribing client

Subscribes to FHIR server and gets updates.

  • Must create a Subscriptions instance on external FHIR server.
  • Must expose an endpoint to accept notifications.
  • Should be capable of using web sockets to receive updates.

Scenarios

Create FHIR Subscription

Action: Subscribing client creates a Subscription instance on FHIR Server.

Precondition: n/a

Success Criteria: Subscribing client POSTs new subscription resource to FHIR server specifying a criteria and a channel.type of rest-hook. FHIR Server persists active subscription resource. Subscribing client can read newly created Subscription. 

Bonus point: Subscribing client updates Subscription instance's status element to off once the subscription is no longer needed. FHIR server respects this setting.

REST Hook notifies client

Action: FHIR Server notifies Subscribing client by POSTing to the endpoint identified in the subscription resource instance.

Precondition: Create FHIR Subscription scenario

Success Criteria: FHIR server POSTs when the criteria in the Subscription is met within the FHIR server.

Create FHIR Subscription with Authentication (Bonus)

Action: Subscribing client creates a Subscription instance on FHIR Server.

Precondition: n/a

Success Criteria: Subscribing client POSTs new subscription resource to FHIR server specifying a criteria and a channel.type of rest-hook. FHIR Server persists active subscription resource. Subscribing client can read newly created Subscription.

Bonus point: Subscribing client updates Subscription instance's status element to off once the subscription is no longer needed. FHIR server respects this setting.

Server authenticates and notifies client (Bonus)

Action: FHIR Server notifies Subscribing client by POSTing to the endpoint identified in the subscription resource instance.

Precondition: Create FHIR Subscription scenario

Success Criteria: FHIR server POSTs when the criteria in the Subscription is met within the FHIR server, and the authorization header is sent and validated by the client.

Create FHIR Subscription with web socket

Action: Subscribing client creates a Subscription instance on FHIR Server.

Precondition: n/a

Success Criteria: Subscribing client POSTs new subscription resource to FHIR server specifying a criteria and a channel.type of websocket. FHIR Server persists active subscription resource. Subscribing client can read newly created Subscription.

Bonus point: Subscribing client updates Subscription instance's status element to off once the subscription is no longer needed. FHIR server respects this setting.

Server authenticates and notifies client via web socket

Action: FHIR Server notifies Subscribing client by sending a PING to the URI in the subscription resource instance.

Precondition: Create FHIR Subscription with web socket scenario

Success Criteria: FHIR server PINGs when the criteria in the Subscription is met within the FHIR server.

Create FHIR Subscription with EventDefinition in extension


TestScript(s)

Indicate any test scripts that will be used to help verify system behavior

Security and Privacy Considerations

The Subscription specification allows the subscribing client to include an Authorization header that should be sent to the client with notifications. Servers should support this capability during the connectathon.


Outcomes

(The official connectathon outcome document is located here:  https://docs.google.com/document/d/1uzgofMt_lYhSqTZgv_9QpO4ct6VvtqjubGyBGvG4p1E/edit#heading=h.pk4upo4qc189 )

Achievements

  • We were able to get multiple webSocket client and servers talking.
    • This included over TLS (wss) but had challenges authenticating to Grahame's server
    • Discovered some misunderstanding of subscription. EG: some servers gathered common subscriptions as a single bind (based on criteria).
  • A lot of discussion occurred around event model vs criteria model. Many servers are concerned about how to scale the current Subscription model that allows all criteria possible in the spec, and no way to programmatically discover what a server supports.
  • Found a few places in the specification that need clarification, or that surprised participants. Logged trackers.

CareEvolution

Apple tested subscribing to our server using Web sockets, we tested Web socket subscription on the Microsoft server. Our test app connected to our server, showing the criteria, the subscriptions with the number of pings received, the content of the subscribed list:

Michele also provided an example of what an email notification might look like on chat.fhir.org:

Apple

WebSocket Subscription Java/JavaScript Clients

Microsoft Server
https://fhir-subscriptions.azurewebsites.net
- Created Simple Subscription with criteria "Observation?code=http://loinc.org|72166-2"
- Found WebSocket Endpoint in Capability Statement
- Connected wss with no additional authorization 
- Bound to created subscription
- Created an Observation to trigger the Subscription
- Received Ping from server

Lantana Server
https://hapi4-dev.lantanagroup.com/baseR4
- Created Simple Subscription with criteria "Observation?code=http://loinc.org|72166-2"
- WebSocket Endpoint hardcoded wss://hapi4-dev.lantanagroup.com/websocket
- Connected wss with no additional authorization 
- Bound to created subscription
- Created an Observation to trigger the Subscription
- Received Ping from server

CareEvolution Server
https://b3-notify-3900-consumers-notify.b3-deploys.com/notify.Adapter1.WebClient/api/fhir
- Created Subscription with criteria "List?_id=b3b739c9-4cd6-4699-a197-d5a329a3cf3e"
- Found WebSocket Endpoint in Capability Statement
- Connected ws with no additional authorization 
- Bound to created subscription
- Subscription triggered on their side
- Received Ping from server

Graham's Open Server
http://test.fhir.org/r4
- Did not create a Subscription
- Found WebSocket Endpoint in Capability Statement
- Connected ws with no additional authorization 
- Bound "123"
- Did not trigger

Graham's Secured Server
https://test.fhir.org/r4
- Found WebSocket Endpoint in Capability Statement
- Attempted to connect wss WITH additional authorization 
Could not get connected
Tried without additional authorization -> 401 Unauthorized
Tried with Authorization header -> 500

Issues/Questions

Now What?

  • Continue discussion about events. 
  • Continue discussions on topics above and trackers.
  • If we change the approach, next connectathon should concentrate on the event approach.


  • No labels