Introduction to HealthVault for Google Health Developers

  • Article

Welcome Google Health developers.

This guide is intended to make it easier for you to understand the HealthVault platform.

It describes concepts that each system implements, and then provides more detail about key HealthVault concepts. Since working with CCR documents is fundamental to Google Health, the guide also describes how to use CCR documents in HealthVault. Finally, it provides links to further resources to get started building a HealthVault application for the web, mobile devices, or client PCs.

Concept mapping

Google Health and HealthVault have some similar concepts. Here is how the concepts are implemented in each system:

Concept

Google Health

HealthVault
User Login Google Account HealthVault Account, using a choice of credential: Windows Live ID, Facebook or OpenID
Health Information Container Profile Record
Storage Format CCR Data item (or "thing") - an expandable set of types defined by XML Schemas.
Web Authorization Method OAuth HealthVault Application Authorization
Mobile/Client Authorization Method Client Login SODA Mobile Apps
Test Environment H9 HealthVault PPE
Documentation Google Health Docs HealthVault Docs
Developer Forums Google Health Developers HealthVault MSDN Forum

HealthVault Application types

HealthVault supports three different kinds of applications (or three separate application models).

Online

An online application is an application in which the user is interacting while the application is being used; in other words, a HealthVault-enabled website. The first time the user uses the application, the HealthVault shell (https://account.healthvault.com) will authenticate the user and ask the user if they want to share their data with the application. When that process is complete, the application can access the user’s data.

When the user returns to the website, they are required to re-authenticate using their credentials before the application can access the user’s data.

Offline

In an offline application, the user authorizes the application once, and until that authorization is revoked, the application can access the user’s data. This is typically used for applications that push data into HealthVault asynchronously, such as a pharmacy sending prescription data.

There are several ways in which the application can obtain this authorization; see “Connecting a Back-End Clinical System to HealthVault”.

A single application can have both online and offline components.

Mobile

In the mobile model the user performs a one-time authorization in a web browser on the device, and after that is completed there is a persistent connection.

Data Storage

Some applications store all of their data in HealthVault; others have their own databases.

See HealthVault Application Integration Recommendations for more information.

SDKs

It is possible to talk directly to HealthVault via the XML APIs, but most people choose to use one of the available SDKs:

Web:

The .NET library is supported by the HealthVault team; all others are community supported.

Mobile:

The mobile libraries make it easy for the applications to provision their connection to HealthVault and read and write data.

The HealthVault data model

All the health data for a particular person is stored in a HealthVault record, which contains a collection of data items. Each of these items is of a specific type, such as Medication, Condition, or Exercise; there are approximately 80 discrete data types in HealthVault. 

Application access to the data in a user’s record is limited to the types that are defined in the application configuration. That allows a user of an application to grant access to Exercise and Blood Pressure measurement without (for example) sharing information about medications or lab tests results.  The application configuration is reviewed and approved by the HealthVault team before an application can go live against production servers.

In addition to the type-specific data, each instance stores common information, such as the name of the application that created it and any items that are related to it.

Each data instance can also store related binary information a “blobs”; the medical image study type uses this to store x-ray or MRI images, and the file type uses it to store the document contents.

Data instances are retrieved by sending a data query operation to the HealthVault service and specifying a filter; the filter might ask for all Condition data instances, all data instances that were created in the last day, or all Weight instances where the weight value is greater than 200.

HealthVault and CCRs

HealthVault supports CCRs directly as data types; an application can store a CCR directly into a user’s record. However, the majority of HealthVault applications are written to deal with discrete data types rather than a summary like CCR. HealthVault therefore provides some support to exchange data between CCRs and discrete data types.

After a CCR is inserted into a HealthVault record, a user can perform a reconciliation process where the data items are extracted, converted to discrete types, and then added to the record. Users can choose to have this performed automatically whenever a CCR is added to their record.

Adding a CCR to HealthVault (.NET)

The following code can be used to by an online application to add a CCR document to a record using the .NET SDK:

IXPathNavigable ccrDocument = GetCCR();

CCR ccr = new CCR(ccrDocument);

PersonInfo.SelectedRecord.NewItem(ccr);

Adding a CCR to HealthVault (Java)

The following code can be used to add a CCR document to a record using the Java SDK:

String ccr = getCCR();

Request request = new Request();

request.setOfflineUserId("75ac2c6c-c90e-4f7e-b74d-bb7e81787beb");
request.setRecordId("8c390004-3d41-4f5c-8f24-4841651579d6");
request.setMethodName("PutThings");

String info = String.format("<info><thing><type-id>1e1ccbfc-a55d-4d91-8940-fa2fbf73c195</type-id>" +
                                               “<data-xml>%s</data-xml></thing></info>",  ccr);

request.setInfo(info);

SimpleRequestTemplate requestTemplate = new SimpleRequestTemplate(ConnectionFactory.getConnection());

requestTemplate.makeRequest(request);

Creating a CCR from HealthVault data types.

There are several methods to create a CCR from discrete types in HealthVault.

If all the data items can be obtained in a single operation, the built in “toccr” transform can be applied by the HealthVault service and a CCR will be returned from the request.

The .NET SDK provides a HealthRecordExporter class, which can create a CCR from any set of data items.

Accounts and Records

HealthVault makes a distinction between accounts and records.

A husband and wife might each have their own HealthVault accounts; they each have a set of credentials (Live id, Open id, or Facebook) that they can use to authenticate into their account.

Each of them would likely have a “self” record that contains their personal health information. If they wish, they can grant access to their personal records to each other, so that the husband could access both his record and his wife’s record through his account, and vice versa.

Similarly, they can create records for each of their children, and share them as well.

Useful resources: