201701 Resource Subscription Track

Return to January 2017 Proposals

FHIR Resource Subscription Track

Resource Subscription Track Report

Submitting WG/Project/Implementer Group

FHIR Management Group (FMG) (Proposed)

Healthcare Services Platform Consortium (HSPC) (Proposed)

Justification

Proper workflow management and information orchestration is critical for any diverse and complex interoperable health IT ecosystem. A critical component of enabling effective workflow is the ability to receive updates on particular pieces of information of interest. For example, if a patient has a number of tests run during a specific encounter the results of those tests may not be immediately available. A provider that is interested in those results when they arrive could subscribe for notifications about the creation or updating of Observation resources that are associated with that encounter. Another example is where a provider may be interested in getting notifications on the progress of a specific patient’s condition.

FHIR currently provides a couple of different methods to do this:

• Subscription – This enables a client to subscribe to notifications about updates to resources of interest.
• History Interaction – A client can poll a server for the history of a particular resource, type of resource or all resources that have been created, updated, or deleted since a specified time.

About the Methods

Subscription

As part of the Workflow Module, the FHIR specification includes capabilities for a client to subscribe to receive notifications to resources that have been created or updated. The Subscription resource is used to define a push based subscription from a server to another system through a number of defined “channels”. The subscription includes criteria in the form of a search string that, when a resource is created or updated that match it, trigger a notification from the server through the channel specified in the original subscription request. Depending on the subscription request and channel, the notification may take the form of a simple reference, either to the search string or matching resource, or may include the content of the matching resources. One limitation of this approach is that the match criteria is run on the new version of the resource, which means that deletions do not cause notifications to be sent. Likewise, a notification will also not be sent if the new version does not meet the search criteria, even if the previous version did. This could cause a system to no longer receive notifications on resources that it had previously received notifications for.

History Interaction

The FHIR RESTful API Framework identifies a number of interactions that are available if a server chooses to support them. One such interaction is the history interaction, which can be used to retrieve the history of a particular resource, type of resource or all resources that have been created, updated, or deleted. Used in conjunction with its available parameters, a client system wishing to know what resources have been created/updated/deleted, can intermittently perform a history request including the _since parameter.

The purpose of this track is to gain more implementer experience with workflows needing some sort of synchronization or resource updates using the Subscription resource and history interaction polling method. This track can be used to juxtapose the two methods for possible assessment to develop further guidance on which method to use under which cases and identify areas where more definition may be needed in the specification and help move the subscription resource to a higher maturity level.

Proposed Track Lead

See Connectathon_Track_Lead_Responsibilities

• Corey Spears (Skype ID: javachance)
• Simone Heckmann

Expected participants

• Infor
• Health-Comm GmbH
• Health Intersections
• HAPI (Proposed)
• Healthcare Services Platform Consortium (HSPC) (Proposed)

Please sign up!

If you're working on a server, please complete the "servers" tab of the Signup Spreadsheet **This time around you'll need to update the `status` flag to indicate whether you've begun work (or completed work), so clients will know when to start testing.** You'll also share details about how a developer can obtain OAuth client credentials (`client_id` for public apps, or a `client_id` and `client_secret` for confidential apps) as well as user login credentials. You might consider simply sharing a set of fixed credentials in this spreadsheet, or else directing users to a web page where they can complete self-service registration. If absolutely necessary, you can ask developers to e-mail you directly.

If you're working on a client, please complete the "clients" tab of the Sprint 4 Spreadsheet. You'll also need to update the `status` flag to indicate whether you've begun work (or completed work).

Roles

Please include information here regarding how much advance preparation will be required if creating a client and/or server.

Subscription

FHIR Subscription Client

Enable creating, updating, and deleting of subscription resources that include a search string criteria.

FHIR Server, Subscription

Support the receiving and processing of subscription resources and provide notifications for resources through the requested channel (if the channel is supported).

Subscription Notification Receiver

Receive notifications from the server over the channel identified in the subscription resource. Query for the resource information if not provided in the notification payload. (NOTE: The notification receiver may, but does not have to, be the same as the subscription client, particularly considering the receiver may be a mobile device (SMS) or secure emailing system)

History Interaction

FHIR History Polling Client

A client that polls a server for the history of a particular resource, type of resource or all resources that have been created, updated, or deleted since a specified time.

FHIR Server, History

Support the history interaction providing a bundle with the matching resources.

Scenarios

1. Create an Active Subscription

Action: The client creates and submits a Subscription Resource for an Observation resource where "criteria": "/Observation?name=http://loinc.org|1975-2" (Bilirubin). Be sure that the chosen channel is one supported by the FHIR Server (There currently does not seem to be an automated way of doing this except to attempt to register a subscription with a particular channel and see the response returned. For this test you can ask the person managing the Server).

Precondition: There is a FHIR Server that supports Subscription for the Resource being subscribed to and the notification channel requested is also supported.

Success Criteria: The Subscription resource is accepted by the FHIR Server.

Bonus point: Attempt to register a Subscription resource for a channel that the FHIR Server does not support

Bonus point: Subscribe to notifications where the bilirubin value is above 1.0 mg/dL.

Bonus point: specify an "end" time for which the subscription will be automatically deleted (specify an instant a few minutes ahead of the time of registering the subscription. Be sure to provide enough time to verify that the resource was added before the end time is reached). Verify that the resource has been deleted after the end time has passed.

2. Search for Active Subscriptions

Action: The client searches for all active subscriptions on the FHIR Server

Precondition: One or more matching Subscription resource(s) exist on the FHIR Server

Success Criteria: All active subscriptions are returned in a bundle

Bonus point: The client searches for active subscriptions registered to a specific channel (url that was provided when the client created a subscription in Scenario 1)

3. Receive a Subscription Notification

Action: The FHIR Server has a resource matching a subscription criteria added and the notification is received by the client identified in the registered channel. Use the example in Scenarios 1 (Bilirubin). The notification will have to be triggered. (e.g. a billirubin Observation create and/or update operation).

Precondition: A matching subscription is registered on the FHIR Server and the registered notification channel is prepared to receive the notification

Success Criteria: The client on the registered notification channel receives the notification

Bonus point: Update the Bilirubin Observation resource with a value of 1.4 mg/dL, and the client receives a notification for the high bilirubin observation subscription

4. Delete a Subscription

Action: The client deletes an existing subscription resource. Delete the subscription resource that was created via scenario 1. (Note: if an end time was specified in scenario 1, the tester may need to recreate the subscription.)

Precondition: The subscription resource already exists on the FHIR server.

Success Criteria: The subscription service is deleted from the FHIR Server

Bonus point: The client deletes all Subscription resources registered to a particular channel url. (Subscription.channel.endpoint) This would presumably be the endpoint that the tester has registered subscriptions to. (Note: The tester should create several subscription resources pointing to the end point to verify this scenario).

5. Retrieve a History Content Bundle for Observations

Action: The client makes a history request for all Observations that have been created/modified/deleted since a certain date. The client should be performing this action acting as a FHIR History Polling Client querying for changes in resources intermittently. This should include a regular polling interval changing the time "since" the last (polling) query. (Matching resources will need to be created/modified/deleted during the test.)

Precondition: Observation resources exist on the FHIR Server

Success Criteria: The modified Observation resources are returned by the server for each

Bonus point: The client makes a history requests for all bilirubin Observations.

Testing

These are the STU3 servers we are aware of supporting the subscription resource and history interaction:

• Health Intersections: http://fhir3.healthintersections.com.au/
• HAPI / University Health Network: http://fhirtest.uhn.ca/baseDstu3

Here are the web portals these servers provide:

• Health Intersections: http://fhir3.healthintersections.com.au/open
• HAPI / University Health Network: http://fhirtest.uhn.ca/home?serverId=home_21&pretty=false

Examples

Webscoket

{

   "resourceType": "Subscription",
   "id": "example-201701-fhir-connectathon-resource-bilirubin",
   "criteria": "Observation?code=http://loinc.org|1975-2",
   "reason": "Monitor liver function",
   "status": "requested",
   "channel": {
       "type": "websocket",
   }

}

Rest-Hook

{

   "resourceType": "Subscription",
   "id": "example-201701-fhir-connectathon-resource-bilirubin",
   "criteria": "Observation?name=http://loinc.org|1975-2",
   "reason": "Monitor liver function",
   "status": "requested",
   "channel": {
       "type": "rest-hook",
       "endpoint": "http://www.MyNotificationCenter:8080/liver-function-monitor/bilirubin/onEvent",
       "payload": "application/fhir+json",
       "header": "Authorization: Bearer private-token-123-abc"
   }

}

Observation Resource

This can be posted to a server to trigger a notification (Note that the patient ID is specific to the server and will need to be modified appropriately)

{

   "resourceType": "Observation",
   "id": "cf872504-f720-46d4-9fa6-2af0f934b5",
   "status": "final",
   "code": {
       "coding": [
           {
               "system": "http://loinc.org",
               "code": "1975-2",
               "display": "Transcutaneous Bilirubin"
           }
       ],
       "text": "Transcutaneous Bilirubin"
   },
   "subject": { 
       "reference": "Patient/295"
   }

}

Help Links

Subscription Resource Definition

History Interaction