Project Description
The HealthVault team has recently added the capability to write applications that will run on Mobile Devices and connect directly to the HealthVault Service. HealthVault Windows Phone library enables developers to write Windows Phone applications which interact with a user's personally controlled health record.

This wiki describes the process of connecting to the HealthVault pre-production environment. The “go live” process to deploy an application against the production HealthVault service can be found here.

Information about the API that the HealthVault service exposes can be in the documentation in HealthVault .NET SDK.

Architecture

The mobile support is built upon a capability we call SODA. The developer registers an master application using the Application Configuration Center and marks that application as a SODA application. This enables the mobile application to create child applications using this master application.

The process of the mobile application getting set up to use the HealthVault service is known as “provisioning”, and consists of the following steps:

Obtaining child application information

The application calls the HealthVault service to obtain an identifier for the child application and a shared secret.

Creating and authorizing the application

The application sends the child application information to the HealthVault Shell web site. The user performs the following steps:

  1. Creates a HealthVault account, or authenticates if they already have an existing account
  2. Indicates which record(s) should be accessible to the application, and grants access.

The HealthVault Shell then sends this information to the HealthVault Service, which creates the child application and stores the authorization information.

Connecting and obtaining user information

The mobile application can then call into the HealthVault service and obtain information about the user and record(s) that were authorized.

When this operation has completed, the application may now access the record to read and write health data.

Using the library

To provide the most flexibility and the least resource consumption, any operations that talk to the HealthVault service are asynchronous.

At startup, the application must create an instance of the HealthVaultService class, and call BeginCheckAuthentication before performing any HealthVault operations. When the completion handler is called it needs to set the CurrentRecord property if it has not already been set.

To send a request to the HealthVault service, the application does the following:

  1. Creates an instance of the HealthVaultRequest class, which defines the method to be called, the information to be passed, and a completion handler to be called when the request is finished.
  2. Call HealthVaultService.BeginSendRequest and pass in the request instance.
  3. In the completion handler, check for errors by looking at the ErrorText property on the event arguments.
  4. If the ErrorText property is null, the request was successful and the returned XML can be processed.

In C#, it will look something like this:

void c_SaveWeight_Click(object sender, RoutedEventArgs e)
{
string thingXml = @"<info><thing>
<type-id>3d34d87e-7fc1-4153-800f-f56592cb0d17</type-id>
<thing-state>Active</thing-state>
<flags>0</flags>
<data-xml>
<weight>
{0}
<value>
<kg>{1}</kg>
<display units=""pounds"">{2}</display>
</value>
</weight>
<common/>
</data-xml>
</thing></info>";

double weight = Double.Parse(c_textWeight.Text);
string whenString = GetDateTime(DateTime.Now, "when");
string xml = String.Format(thingXml, whenString, weight / 2.204, weight);

XElement info = XElement.Parse(xml);

HealthVaultRequest request = new HealthVaultRequest("PutThings", "2", info, PutThingsCompleted);

_service.BeginSendRequest(request);
}

void PutThingsCompleted(object sender, HealthVaultResponseEventArgs e)
{
if (e.ErrorText != null)
{
// handle error...
}

XElement response = XElement.Parse(e.ResponseXml);

XElement thingIdNode = response.Descendants("thing-id").Single();

Guid thingId = new Guid(thingIdNode.Value);

Guid versionStamp = new Guid(thingIdNode.Attribute("version-stamp").Value);

}

Working with Data Types

There is a list of all the current data types on the HealthVault developer center. You can use the schemas through whatever XML serialization your platform provides, or by hand-crafting the XML.

If you have a windows box handy, you may find it helpful to write the actions you are wanting to perform in a web application and then examine the XML that is created through Request/Response tracing.

Reference
http://healthvaultwp7.codeplex.com/wikipage?title=Reference

Last edited Jul 10, 2013 at 5:22 AM by philpenn, version 7