Introduction to HealthVault Development #10: Adding additional data to healthvault

Article
03/13/2009

We have a new user request. One of our users would like to store how hungry he whenever he enters a weight value.

We head off to the HealthVault MSDN page, go to the learn page and then the reference page, and then choose HealthRecordItem Type Schema Browser. This page talks to the developer platform to find out what types are currently supported by the platform.

Looking through all the data types available on the page, we don’t find one related to hunger. So, we can just head home for the day and spend some quality time with our XBox.

Or, we could explore other ways to add the hunger data to HealthVault.

The first way is to ask the HealthVault team to add a new data type. We regularly add new data types and revise existing ones to meet the needs of our partners. If you think that the data you want to store is of general interest, please start a conversation with us.

The downside of this is that it’s going to take us a while to figure out what the data type should be, design it, and then add it to a release. At best, it’s about 6 weeks from when we start working on it to when it shows up on your doorstep, gift-wrapped in a small box with a big red bow (gift wrap, box, and bow not included). If the type is complex, requires a lot of research, or if we’re especially busy, it could take longer.

While you wait for us – or if the information is not of general interest – there are three ways to add information:

All data types provide the CommonData.Note and CommonData.Tags properties for your use.
All data types support adding extension data in XML format.
A custom application-specific data type can be created.

Application-specific data types are only accessible by the application that created them, and there is therefore no data liquidity using such types. While there are scenarios where that makes sense, our guideline is that applications should make as much data as possible accessible to other applications, and therefore limit the use of application-specific types.

Extensions

Extensions are created and accessed using the HealthRecordItemExtension class, and there is a collection of these classes on the CommonData property of the data type instance.

The XML for the extension is in the following format:

The meaning of the XML data inside is purely up to the application.

For hunger, we’ll use an entry like this:

<extension><hunger>Moderate</hunger></extension>

Adding the extension to our project

In default.aspx, make the c_lableHunger and c_dropDownListHunger controls visible. Here’s the code we need to parse the values, create the extension, and add it to the weight object:

void AddHungerToWeight(Weight weight)
{
    HealthRecordItemExtension extension = new HealthRecordItemExtension(ExtensionWeightTrackerHunger);
    XPathNavigator navigator = extension.ExtensionData.CreateNavigator();
    string innerXml = @"<extension><hunger>" + c_dropDownListHunger.SelectedItem.Value +
        @"</hunger></extension>";
    navigator.InnerXml = innerXml;

    weight.CommonData.Extensions.Add(extension);
}

That helper is already in the project, so you can just add the call right before the weight value is saved:

AddHungerToWeight(weight);
PersonInfo.SelectedRecord.NewItem(weight);

The ExtensionWeightTrackHunger constant is used to uniquely identify the extension. Because there is a possibility for collision here, it would be a good idea to use a “<application>.<extension-name>” format. The constant that is currently in the project is incorrect – change it to “WeightTracker.Hunger”.

In addition to the actual data stored in the extension (the ExtensionData property), there are a few other items that you can store:

Logo is the url of a logo to display with the extension.
Source is the source identifier.
Transform is the URL of a transform that converts the extension data into an HTML form.
Version is the version number of the extension

We’ll follow our usual pattern in modifying our fetching code:

First, add a “Hunger” header as the second-to-last entry.

Then, we need some code to iterate over all extensions, similar to how we iterated over the related items. There is a helper in the project, but I don’t like the way it works any more, so we’ll use this code instead:

string hunger = String.Empty;
foreach (HealthRecordItemExtension extension in weight.CommonData.Extensions)
{
    if (extension.Source == ExtensionWeightTrackerHunger)
    {
        XPathNavigator navigator = extension.ExtensionData.CreateNavigator();
        XPathNavigator value = navigator.SelectSingleNode("extension/hunger");
        if (value != null)
        {
            hunger = value.Value;
            break;
        }
    }
}

Finally, add hunger to the call to AddCellsToTable(). Run the project and verify that it works.

A Nicer Approach

We can make things better by using a derived class for the extension.

Add a new class to the project, and name it “Hunger Extension”. Visual studio will ask you if you want to put it in App_Code – tell it “yes, that would be lovely”.

Replace the class with the following:

using System;
using System.Xml;
using System.Xml.XPath;
using Microsoft.Health;
using Microsoft.Health.ItemTypes;

public class HungerExtension : HealthRecordItemExtension
{
    static readonly string ExtensionSource = "WeightTracker.Hunger" ;

    string m_hunger;

    public HungerExtension()
    {
    }

    public HungerExtension(string hunger)
                   : base(ExtensionSource)
    {
        m_hunger = hunger;
        Source = ExtensionSource;
    }

    public string Hunger
    {
        get { return m_hunger; }
        set { m_hunger = value; }
    }

    protected override void ParseXml(IXPathNavigable extensionData)
    {
        XPathNavigator navigator = extensionData.CreateNavigator();
        XPathNavigator hungerNode = navigator.SelectSingleNode("extension/Hunger" );

        if (hungerNode != null)
        {
            m_hunger = hungerNode.Value;
        }
    }

    protected override void WriteXml(System.Xml.XmlWriter writer)
    {
        writer.WriteStartElement("Hunger");
        writer.WriteString(m_hunger);
        writer.WriteEndElement();
    }

    public static void RegisterExtensionHandler()
    {
        ItemTypeManager.RegisterExtensionHandler(ExtensionSource, typeof(HungerExtension), true);
    }
}

The class is pretty simple. The ParseXml() method pulls the data out of XML and puts it in the class, and the WriteXml() method does the opposite. The RegisterExtensionHandler() method registers this extension with the SDK, so that when it sees that extension, it creates an instance of our derived type instead of a generic HealthRecordItemExtension instance.

Now that we have the class, it’s much easier to use our extension.

First, add the call to register the extension before the weight values are loaded:

HungerExtension.RegisterExtensionHandler();

Modify the code to fetch the hunger value to the following:

string hunger = String.Empty;
foreach (HealthRecordItemExtension extension in weight.CommonData.Extensions)
{
    HungerExtension hungerExtension = extension as HungerExtension;
    if (hungerExtension != null)
    {
        hunger = hungerExtension.Hunger;
    }
}

Change the code to save the hunger to the following:

weight.CommonData.Extensions.Add(
new HungerExtension(c_dropDownListHunger.SelectedItem.Value));
PersonInfo.SelectedRecord.NewItem(weight);

Run the application, and verify that it works. Then delete the unnecessary helper methods and string constant from default.aspx.cs

Other resources:

There is another set of pages where you can look at the schemas for the item types, and schemas for all the platform methods. We will be unifying these two sources in the future.

Next Time

Next time, we’ll talk about data filtering.