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.
Google Health and HealthVault have some similar concepts. Here is how the concepts are implemented in each system:
|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
|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).
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 (http://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.
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.
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.
Some applications store all of their data in HealthVault; others have their own databases.
See HealthVault Application Integration Recommendations for more information.
It is possible to talk directly to HealthVault via the XML APIs, but most people choose to use one of the available SDKs:
The .NET library is supported by the HealthVault team; all others are community supported.
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);
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();
String info = String.format("<info><thing><type-id>1e1ccbfc-a55d-4d91-8940-fa2fbf73c195</type-id>" +
SimpleRequestTemplate requestTemplate = new SimpleRequestTemplate(ConnectionFactory.getConnection());
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.
- Getting Started with the Microsoft HealthVault SDK
- The HealthVault Developer Center on MSDN
The developer center has a lot of documentation and other useful information on it.
- Practical HealthVault (Presentation)
An introduction to HealthVault and how applications can connect to HealthVault from the 2010 ConnectedHealth conference.
- MSDN Conceptual Documentation
- HealthVault Partner Wiki
- The HealthVault support forum
This is a great place to ask conceptual questions about HealthVault or questions about the .NET SDK. If you have questions about other SDKs, ask them on the forum associated with the SDK.
- HealthVault Service Specification
Useful to understand the low level details of how the HealthVault service works.
- HealthVault Labs
Use this to browse the schemas of the HealthVault methods, vocabularies, and data types.
- Get Real’s Developer X-Ray
Provides a number of useful browsers and query creators.
- Introduction to HealthVault Development
A series of blog articles that walk through developing applications using the .NET library. Presents concepts that are useful for all applications.
- Working with HealthVault XML APIs
A series of blog articles.
- Interacting with HealthVault through the Direct Project
A quick overview of how the Direct project works and how you can use it to get information into HealthVault.