The HealthVault platform now provides the ability to notify applications when specific conditions are met.
A blood-pressure-tracking application wants to be notified whenever a new blood pressure measurement is added to any of the user records that the application has access to, so it can perform some operation with the data.
With previous releases, the only way to do this was for the application to periodically call GetUpdatedRecordsForApplication(), and then look at each record that was updated to see if the update was a new blood pressure instance.
Each application can now create a series of subscriptions, where each subscription specifies the event to detect and how to notify the application when the event occurs.
The BloodPressureTracker application creates a new subscription, specifies that it wants to be notified when a blood pressure measurement is added, updated or removed, and that the notification should be sent to www.example.com/notificationBloodPressurePage.ashx. The subscription is persistent until the application deletes it.
The notification page must be in a location that is accessible to HealthVault, which means it is accessible to other internet programs. To allow the application to verify that a notification came from the HealthVault platform, the application registers a key with the subscription, and when the notification arrives the application can verify that the HMAC in the message is identical to one computed by the application.
The dispatching of a notification happens on the HealthVault Platform.
The notification processing happens in the HealthVault application.
The processing of the notification should be performed on a separate thread to prevent the possibility of taking so much time that the timeout is reached.
For this release, the platform supports one event type – a change (add/update/delete) of an instance of a specific set of data types in a user’s record – and one delivery method – over an https: connection. We are planning to extend support in future releases – if you would like to influence which events and delivery methods we consider, please send us feedback.
The health record item changed event passes the following information in the notification:
After the notification is received the application will need to fetch the item to determine what change was made. If the object was deleted, it will not be returned from the fetch operation.
The notification URL must be on the same domain as the action url that is registered with the application.
The user must have granted the application offline read access to the data type that the subscription refers to.
An application can only register 25 subscriptions at a time. This number is subject to change.
The HealthVault platform makes a “best effort” to deliver each notification in a timely manner, but does not guarantee delivery. It is not designed for real-time monitoring scenarios.
Notifications are delivered only for changes that are detected in records – the platform does not notify for items that are already existing in a record when the user first authorizes the application, nor does it notify for deletion if a user de-authorizes the application.
We have created a sample application which serves three purposes:
The first time that you run the application, it will generate an application id and a key for you to use. The sample will tell you how to properly define these in the web.config file.
The management part of the application is pretty simple – you merely add a new subscription and then list the data type ids that you want to be monitored.
In many cases, developer machines are not directly reachable from the internet and therefore there is no address that can be used in a subscription. To make it easier to develop notification handlers, the sample application can send simulated notifications to a notification handler for debugging purposes. It provides the following options:
Choose between the URL defined in the subscription, the test notification handler defined in the project, or a URL that you enter.
Choose Normal to have correct authentication headers, send bad HMAC to send an HMAC that is incorrect, or send bad key version to send a key version that is different than the one in the subscription.
The sample application can generate fake instance ids (if you just want to check that the notification handler is set up correctly), send an empty instance list, or select actual instance IDs from the current record.