One of our top partner requests over the last few months has been better support for creating HealthVault-connected applications on Windows 8. I’m happy to announce that we’ve released the HealthVault Library for Windows 8 which provides a first-class experience for building HealthVault-connected applications on Windows 8.

Download the Library

 

With Windows 8, things couldn’t be more exciting for health application developers. Windows 8 brings an unprecedented combination of new capabilities and market reach including:

Couple Windows 8 innovation with the HealthVault app platform, data model, app ecosystem, device integration and the HealthVault user base, and developers have an incredible set of technology and resources at their disposal for building health applications that target professionals and consumers alike. For health application developers, these are exciting times to be certain!

We’re hard at work building our own first-party HealthVault application for Windows 8. We’re making available to developers the same library we’re using to build the app. In fact we’re building the library in parallel with our application development efforts so you can expect regular updates to the library.

Let’s take a tour and introduce the library features.

Library features

The feature areas and components the library supports are summarized below.

image

 

Let’s look at this in more detail.

HealthVault Foundation

This is the core infrastructure for working with HealthVault including service invocation and XML serialization.

Connectivity

These are the protocols for connecting to HealthVault and individual health records in HealthVault. Today, the library supports the SODA method of connecting to HealthVault Records. In future releases of the library we’ll add support for the Patient Connect and DOPU methods of integrating with HealthVault.

Data Experience

This represents features for working with HealthVault’s data type system. The library provides a data type object model so developers can work with health types at a high level of abstraction using C#, VB or Javascript. See later on for code samples.

The library provides implementation for the following 13 data types initially:

  • Allergy, Blood Pressure, Cholesterol, Condition, Dietary Intake, Exercise, File, Height, Immunization, Medication, PersonalImage, Procedure, Weight

We’ll be adding support to the library for other HealthVault data types over time. In the meantime, you can use the existing data type classes in the library as examples for creating your own class implementations of the HealthVault data types.

Support for coding data, retrieving vocabularies and searching vocabularies is also included in the library.

The HealthVault BLOB streaming interface is supported as well. This allows apps to store and read unstructured data of varying size including large medical image studies. The touch-first experiences on Windows 8 bring an exciting new platform on which to build HealthVault-enabled medical imaging apps.

HealthVault's entire query interface is also supported in the library including rich filters and XPath. See below for code samples.

App Framework

The library also includes app framework components to help developers build better applications for HealthVault. For instance, the library supports synchronized views and stored queries which allow views to be defined which are kept synchronized with HealthVault. There’s also an LRU cache and local storage support available for caching and persisting HealthVault data. Over time we’ll add more helpful app framework components that allow developers to focus on adding value in their applications. 

The library package also includes a sample application that demonstrates how to use the library features.

Code Samples

Next, let’s take a look at how to achieve some common tasks with the library. The following code snippets use WinJS, but developers can also use C#/XAML. For more information see XAML-based Windows Store applications for HealthVault.

If you’re new to HealthVault, see the HealthVault Technical Overview for info about HealthVault Records and other core concepts.

Application Authorization

The first thing your application will want to do is gain authorization to a HealthVault Record. The library implements the SODA method for connecting with users. Initiating the authorization process in your application is simple as shown in the following code: 

var app = new HealthVault.Foundation.HealthVaultApp(appID); 
 
// open a new browser, allow user to sign-in to HealthVault and authorize
// the application
app.startAsync().then(onComplete, onError, onProgress);  
 
// Wait while the authorization happens. 
// One possibility is to show a dialog with a "Continue" button the user 
// clicks once done authorizing the app.  
 
// Now that authorization is done, call startAsync() again to start the app. 
app.startAsync().then(onComplete, onError, onProgress);

 

In the code above, onComplete, onError, and onProgress represent functions that handle the Javascript promise. See “Quickstart: using promises” for more on handling complete, error and progress events with Javascript promises.

Executing the code above launches the HealthVault sign-in page in a new browser as shown here:

signin

 

After the user signs in or signs up and selects a Record, the authorization page is displayed to the user as shown here:

appauth

 

This notifies the user of the access being requested by your application and asks the user to accept or reject the requested access. If the user accepts, HealthVault will indicate to the user to return to the app. The app can now exchange data with the Record that was authorized. The authorization process only needs to happen once for a given record. The next time the application runs, it no longer needs to put the user through the authorization loop as it already has access to the Record. However, applications can request access to more Records at a later time, for instance, the app can ask for access to a Record belonging to a family member at a later time.

Get Items

Next, let’s see how to get data from a record. The following code queries for all Weight Measurement items stored in a HealthVault record.

// Get Weight items from the record. 
var query = HealthVault.ItemTypes.Weight.queryFor();
var record = app.userInfo.authorizedRecords[0];
record.getAsync(query).then(onComplete, onError, onPending); 
 

The getAsync method returns the data in a HealthVault.ItemTypes.ItemDataTypedList instance which can be accessed in the onComplete function.

For more information about querying data in HealthVault see “Querying Data”.

Get Items Advanced

The library supports HealthVault’s full query semantics. This includes querying for specific items, querying for items matching a given XPath, supporting multiple filters per query, and multiple queries per getAsync call. Let’s look at a more advanced query.

The following code queries for a maximum of 100 Condition and Medication items that were created after November 1st 2010 and returns the results ordered by the effective date of each item (HealthVault’s default sort order).

// Get a maximum of 100 Condition and Medication items created after 11/1/2010 
var query = HealthVault.Types.ItemQuery();
query.name = “GetThingsAdvanced”;  
var filter = new HealthVault.Types.ItemFilter(new Array(
            HealthVault.ItemTypes.Condition.typeID,
            HealthVault.ltemTypes.Medication.typeID)); 
filter.createdDateMin = new HealthVault.Types.DateTimeValue(“11/1/2010“); 
query.Filters.append(filter); 
var record = app.userInfo.authorizedRecords[0];
record.getAsync(query).then(onComplete, onError, onPending);

Of note is that the key classes used for querying data in the library are HealthVault.Types.ItemQuery and HealthVault.Types.ItemFilter as shown above.

For more information about querying data in HealthVault see “Querying Data”.

Put Items

Storing data in HealthVault is also straightforward. The following code creates and stores a Blood Pressure Measurement item in a HealthVault Record.

// Store a Blood Pressure item in a HealthVault record. 
var bp = new HealthVault.ItemTypes.BloodPressure();
bp.when = HealthVault.Types.StructuredDateTime.now();
bp.systolicValue = 120;
bp.diastolicValue= 80;
bp.pulseValue = 58;
bp.irregularHeartbeat = new HealthVault.Types.BooleanValue(false);
var record = app.userInfo.authorizedRecords[0];
record.putAsync(bp).then(onComplete, onError, onPending); 

For more information about storing data in HealthVault see “Writing Data”.


We’re really excited to see what developers will build with the library. If you have questions/comments or if we can help with anything, don’t hesitate to reach out to us on the HealthVault developer forum.