Applications authenticate themselves to the HealthVault platform using the CreateAuthenticatedSessionToken API. Users are authenticated through HealthVault.com, and applications can get tokens for authorization using the HealthVault Shell redirect interface at http://msdn.microsoft.com/en-us/library/ff803620.aspx.

Individual methods are available for an application to fetch record and person authorization details. Most notably, NewApplicationCreationInfo is used by mobile clients to receive security keys from the HealthVault platform.

The core function that lets an application read items from a user’s HealthVault record is GetThings. We will discuss this API in detail in GetThings, but to summarize, this API provides the ability to query HealthVault, fetch a health item with granular details, and fetch large BLOB items, such as images.

The counterpart of GetThings is PutThings. It is used by most applications to update and create health items. We will discuss this function in detail in the section PutThings.

OverwriteThings allows applications to force overwrites on existing health items. This API generally is not used.

HealthVault, unlike most personal health platforms, provides a mechanism to store large files such as medical images. Applications can upload large chunks of information by using the BeginPutBlob API. It is fairly tricky to use, but there is good documentation on how to use it via raw XML interfaces at http://msdn.microsoft.com/en-us/library/ff803584.aspx, as well as through the HealthVault .NET SDK at http://msdn.microsoft.com/en-us/library/ff803576.aspx.

DeleteThings is the one of the simplest HealthVault functions, allowing applications to delete individual health items from a user’s record. HealthVault keeps an audit trail of all operations, including the delete operation.

Several clinical applications use HealthVault to send information to consumers either a single time or continually through backend systems. CreateConnectPackage allows applications to create a one-time package for the user to receive in his HealthVault account, and DeleteConnectPackage allows applications to perform cleanup as necessary. On the other hand, CreateConnectRequest allows applications to establish a continual link with a patient’s HealthVault record. Applications can get the details needed to make the link by using GetAuthorizedConnectRequests.

HealthVault provides several mechanisms for an application to perform asynchronous processing. GetAuthorizedPeople gets information about the people that are authorized to use the application. This function paginates results using a PersonID cursor and provides a way to query authorizations created after a given point in time. Applications have found this function useful to send email updates and reminders to their subscribers. Similarly, GetUpdatedRecordsForApplication retrieves a list of records for an application with things that have been updated since a specified date.

HealthVault provides a powerful publish/subscribe mechanism. Applications can subscribe to events around create, read, update, and delete operations on HealthVault thing types. These events are registered with the platform using the SubscribeToEvent method. In addition to defining the subscribe event, the application registers a secure URI to which the HealthVault platform publishes events. The HealthVault eventing mechanism is documented in detail with appropriate examples at http://msdn.microsoft.com/en-us/library/gg681193.aspx.

The InstantPHR application from GetReal Consulting (http://www.getrealconsulting.com/instantphr/) is a good example of an application that uses HealthVault’s asynchronous processing and eventing in particular to notify users of changes in their health records.

Applications using HealthVault can send email messages to HealthVault users. The SendInsecureMessageFromApplication API allows the application to choose the sender address and specify its domain.

Terminologies, also known as vocabularies, are a list of codes associated with well-known terms in a particular domain. HealthVault hosts numerous terminologies. Most of these are tagged as wc and are created by Microsoft. However, several third-party terminologies from the National Library of Medicine, USDA, HL7, and other institutions are also hosted.

PS C:> (Get-Vocabulary).Count
150

The terminologies can be accessed using the GetVocabulary API. Accessing the terminologies does not require user authentication; these are application-only APIs. Some terminologies hosted by HealthVault, such as RxNorm, are huge. RxNorm is a terminology that attempts to normalize all medication names and contains more than 200,000 entries. The SearchVocabulary API provides an XML interface as well as a JSON interface to search vocabularies. In fact, one can get an auto-completion text box for entering a medication by using SearchVocabulary on RxNorm. The HealthVault user interface provides auto-completion for medications, conditions, and other health item types using the SearchVocabulary API.

The SetApplicationSettings and GetApplicationSettings APIs provide a way for applications to store and retrieve their record-specific settings in HealthVault. Information such as theme selection by a particular user or order of authorized records can be stored in application settings. The multiple record management (MRA) functionality detailed later in this chapter can be implemented using these APIs.

HealthVault also allows a certain kind of application called a Master Application to create and manage other applications. Master Applications use the AddApplication and UpdateApplication functions to manage the “child” applications they create.

The GetServiceDefinition function provides access to all the details of HealthVault applications, including Methods, Schemas, and Configurations for the service. Using GetServiceDefinition, an application can programmatically discover HealthVault service information and keep it up to date.

PS C:Windowssystem32> Get-ServiceDefinition

HealthServiceUrl       : https://platform.healthvault-ppe.com/platform/wildcat.ashx
Version                : 1.9.2679.7415
HealthServiceShellInfo : Microsoft.Health.HealthServiceShellInfo
Assemblies             : {}
Methods                : {AddApplication, AllocatePackageId, AssociateAlternateId, 
                         BeginPutBlob...}
IncludedSchemaUrls     : {https://platform.healthvault-ppe.com/platform/XSD/types.xsd, 
                        https://platform.healthvault-ppe.com/platform/XSD/auth.xsd, 
                        https://platform.healthvault-ppe.com/platform/XSD/application.xsd,
                        https://platform.healthvault-ppe.com/platform/XSD/vocab.xsd...}
ConfigurationValues    : {[allowedDocumentExtensions, .avi,.bluebutton,.bmp,.ccd,.ccr,.cda,
                         .doc,.docm,.docx,.eml,.gif,.jpg,.mp3,.one,.pdf,.png,.ppsm,.ppsx,
                         .ppt,.pptm,.pptx,.pub,.rpmsg,.rtf,.scp,.tif,.tiff,.txt,.vsd,.wav,
                         .wma,.wmv,.xls,.xlsb,.xlsm,.xlsx,.xltx,.xml,.xps], 
                         [autoReconcilableTypes, 1e1ccbfc-a55d-4d91-8940-fa2fbf73c195,
                         9c48a2b8-952c-4f5a-935d-f3292326bf54], [blobHashBlockSizeBytes, 
                         2097152], [blobHashDefaultAlgorithm, SHA256Block]...}

Open Query is an insecure mechanism for running preconfigured queries invoked with an identifier on HealthVault data. For example, the following query:

invokes a saved request that corresponds to the specified identifier. Only queries associated with GetThings can be saved with SaveOpenQuery. The invocation of the open query doesn’t require authentication and authorization, and the HealthVault team discourages its use and might remove it in future updates.

The best way to understand GetThings API is to look at the XML that an application would send to HealthVault platform to request a set of things (Example 3-3).

<wc-request:request xmlns:wc-request="urn:com.microsoft.wc.request">
  <auth>...</auth>
  <header>...</header>
  <info>
    <group name="GetWeights" max="10"> 
      <id>d8460ea8-50d4-4c30-ad92-49d1a1020b52</id>
      <filter>
        <type-id>d8460ea8-50d4-4c30-ad92-49d1a1020b52</type-id> 
        <thing-state>Active</thing-state> 
        <created-app-id>1F82D899-22E0-43F2-A645-59EDB6927645</created-app-id> 
        <xpath>/thing/data-xml/weight/value/kg[.>=60]</xpath> 
      </filter>
      <format>
        <section>core</section> 
        <xml /> 
      </format>
      <current-version-only>true</current-version-only> 
    </group>
  </info>
</wc-request:request>

Each GetThings request can have multiple queries called a group (Line ). Each group is identified by its name. The response from HealthVault combines the items returned by the group; group-name is used to index items returned for a particular query group. The group element can take one or more attributes to control the results. The attribute used in the previous example is max, which tells the HealthVault platform to return the top 10 items for this query.

Each query group can contain <filter> subelements to return particular items with a specific identification. Example 3-3 requests items with a specific type-id (Line ). The d84..52 identifier is associated with a particular instance of the weight type. Multiple IDs can be specified in each request. Other elements, such as client identifiers and thing keys, can also be used instead of an ID. The filter also restricts results to those that have an active thing-state (Line ) and were created using the Withings application (Line ). Items also can be filtered using XPath; on Line we are looking for weight items whose values are greater than 60 kg, maybe because we know that the scale was misconfigured during this time. To sum up, the query in Example 3-3 returns the core XML sections of the top 10 weight elements that were created by the Withings application and have values greater than 60 kg.

The format and quantity of information returned by the GetThings query can be controlled by format specifiers. Using the section tag, we can specify that we just want the core elements of the requested thing types (Line ). Other section tags could specify digital signatures, audit information, or effective permissions for the request. Using the xml tag (Line ), one can run an XSL transform on the thing types or choose from existing transforms available for the type. Our xml tag is empty, so no transform is run in the sample query. We will discuss MTT, STT, and other transforms in Chapter 4.

An application can request only the current versions of HealthVault thing types (Line ), although the platform does store older versions of the data.

To complete the discussion on the format of the GetThings request, note that I have collapsed the auth and header tags at the beginning of the code block. These elements specify the authorization information for the method and various other header elements, such as the method name, final-xsl, version, user, and application tokens.

Table 3-4 summarizes the querying ability of the GetThings method. To learn more, please refer to the methods schema documentation at http://developer.healthvault.com/pages/methods/methods.aspx and associated HealthVault SDK reference at http://msdn.microsoft.com/en-us/library/hh672196.aspx.

Now that we understand the paradigm through which one can access things from HealthVault using the GetThings methods, let’s look at how we can utilize querying to display weight values in our application.

Our application currently fetches all the weight readings. However, we want to be able to explore the readings on a graph one week at a time. Example 3-4 shows how we can do it. As Line shows, we begin by creating a searcher object for the record we are working with, and then create a new filter for the weight type (Line ). Once we have the filter, we add properties to filter the value so that we get only those weight items that are dated for the previous week using EffectiveDateMin (Line ).

Once the query is constructed, we issue a GetThings request to HealthVault (Line ). Because we have only one group, we index for the results in the first set of matching results (GetMatchingItems()[0]).

    protected void Btn_ShowWeeklyWeightReadings_Click(object sender, EventArgs e) 
    {
        HealthRecordSearcher searcher = PersonInfo.SelectedRecord.CreateSearcher(); 
        HealthRecordFilter filter = new HealthRecordFilter(Weight.TypeId); 
        filter.EffectiveDateMin = DateTime.Now.Subtract(new TimeSpan(7, 0, 0, 0)); 
        searcher.Filters.Add(filter);

        HealthRecordItemCollection items = searcher.GetMatchingItems()[0]; 

        TimeSeries t = new TimeSeries("Weight Graph"); 

        foreach (Weight item in items)
        {
            //Assuming all data is in one unit
            t.SeriesValue.Add(new TimeSeries.TimeSeriesValues(
                 item.EffectiveDate, item.Value.DisplayValue.Value));
        }
        TimeplotView.Plots.Add(t); 
        TimeplotView.DataBind();
        TimeplotView.Visible = true;
    }

After getting the matching items, we create a new TimeSeries (Line ) and add each item individually to the series. The TimeSeries.ascx.cs file contains an implementation of this class. You can choose to use your own implementation with any other graphing library. In this example, I’m using the Flot JavaScript graphing library (http://code.google.com/p/flot/). TimeplotView (Line ) is an instance of a user control that has a Flot graphing object.

In the last three lines we add the constructed TimeSeries to the graphing object and make it visible on the screen. Figure 3-3 shows the results of running this query on the selected record.

Figure 3-3. Filtering weight data for the week

As with GetThings, we’ll begin our coverage of the PutThings API by looking at the XML an application would send to HealthVault to create or update a set of things. Compared to GetThings, this is a simple request (Example 3-5).

<wc-request:request xmlns:wc-request="urn:com.microsoft.wc.request">
  <auth>
    <hmac-data algName="HMACSHA1">IB7cdWXFNKE+xhrvE5poT5ulueE=</hmac-data>
  </auth>
  <header>...</header>
  <info>
    <thing> 
      <type-id>0a5f9a43-dc88-4e9f-890f-1f9159b76e7b</type-id> 
      <thing-state>Active</thing-state>
      <data-xml>...</data-xml> 
    </thing>
  </info>
</wc-request:request>

Each PutThings request can add instances of a thing (Line ). Each thing has a type-id (Line ) that identifies what kind of data item it is. In Example 3-5, the thing is of type Weight. Because we are adding a weight thing, the data-xml (Line ) part of this request needs to adhere to the schema for this particular type. In Chapter 4, we will discuss the thing-type schema. The important aspect of using this schema is to make sure to use a unique thing-id. In case of an update, the thing-id is the instance of weight you want to update. Additionally, the thing-version-id element should be the version ID of the element that is currently in the HealthVault. HealthVault offers optimistic concurrency, which means that if an application tries to update an old thing that has already been updated by some other application, its version ID will have changed and the new put won’t succeed. The thing-version-id is critical to make sure one update does not override another.

Let’s modify our application to add a new Weight element to HealthVault. On the Default.aspx page, we construct a text box to enter weight in pounds and associate a “save” button with it, with the action as Btn_SubmitWeight_Click.

Example 3-6 illustrates how we will go about saving a new element to HealthVault. Notice the HealthVault-specific DateTime field (HealthServiceDateTime) on Line and a way to differentiate the actual WeightValue from DisplayValue on Lines –. HealthVault enables health items to have a flexible date and time. It also stores measurements in a canonical format and allows users to see them in the format in which they entered the data.

In the case of Weight, it is stored canonically in kilograms, but we assume the user prefers to enter and display the weight in pounds. So, on Line we multiply the value entered by the user by 1.6. The DisplayValue of the weight is in pounds (lbs), which the applications working with this type can use to show the value to the user.

    protected void Btn_SubmitWeight_Click(object sender, EventArgs e)
    {
        double weight = double.Parse(Txt_Weight.Text);
        Weight w = new Weight( 
                new HealthServiceDateTime(DateTime.Now), 
                new WeightValue( 
                    weight * 1.6, new DisplayValue(weight, "lbs", "lbs"))); 
        
        PersonInfo.SelectedRecord.NewItem(w);
    }

Having a well-formed weight health item, we can send it to HealthVault by calling the NewItem method in the HealthVault .NET SDK. Under the hood, the NewItem call issues a PutThings request to the HealthVault platform. The HealthVault SDK also has an UpdateItem method, which saves changes to an existing item using the PutThings method.

To update an existing item, one essentially does the same thing as shown, except you use the UpdateItem SDK method instead of NewItem.

public void PutThing() throws Exception
    {
        long weightValueInKg = 80;
        
        DisplayValue dv = new DisplayValue();
        dv.setUnits("lb");
        dv.setUnitsCode("lb");
        dv.setValue(weightValueInKg/2.2);
        
        WeightValue wv = new WeightValue();
        wv.setKg(weightValueInKg);
        wv.setDisplay(dv);
        
        Weight weight = new Weight();
        weight.setValue(wv);
        weight.setWhen(DateTime.fromCalendar(Calendar.getInstance()));
        
        Thing thing = new Thing();
        thing.setData(weight);

        SimpleRequestTemplate requestTemplate = new SimpleRequestTemplate(
                ConnectionFactory.getConnection());
        requestTemplate.setPersonId("75ac2c6c-c90e-4f7e-b74d-bb7e81787beb");
        requestTemplate.setRecordId("8c390004-3d41-4f5c-8f24-4841651579d6");
        
        PutThingsRequest request = new PutThingsRequest();
        request.getThing().add(thing);
        
        PutThingsResponse response = (PutThingsResponse)requestTemplate.makeRequest(request);
    }

For an application working with a single record, HealthVault provides a simple mechanism to switch to another record using a switch record hyperlink. In order for an application to switch to a different record, the application needs to tell the HealthVault Shell to allow the user to switch the record and have a preconfigured receiving end point for the HealthVault Shell to send the user back to a notification to change the selected record, termed a SELECTEDRECORD. The application redirects the user with a hyperlink URL like the one shown in the following example. The AUTH target implies an authentication request, the appid implies the identifier associated with the calling application, and the forceappauth string makes sure that the user is able to change the record.

Using the HealthVault .NET Web SDK, this can be done with following line of code. The last variable enables applications to pass any optional parameters that need to pass through the URL redirection:

this.RedirectToShellUrl("AUTH", "appid=" + this.ApplicationId.ToString() +
"&forceappauth=true", "passthroughParam=optional");

As a simple example, Figure 3-4 shows how one can associate the Switch Account functionality to an existing HealthVault application. Enabling this functionality involves two steps. First is to create an appropriate URL to send the user to HealthVault; Example 3-8 shows the associated code. The second step in this process is to create a receiving URL so that HealthVault can send the user back to your application. Example 3-9 shows the associated code required to configure a SelectedRecordChanged end-point page in the HealthVault SDK’s web.config file. These two steps are relatively simple and can be accomplished with any programming language. HealthVault Shell Interface explains the HealthVault shell interface, and HealthVault SDK and Open Source Libraries lists the available libraries.

Figure 3-4. Adding the ability to switch accounts

In Example 3-8, notice that in Line , we are using the RedirectToShellUrl HealthVault SDK functionality to enable creating the appropriate redirection URL for HealthVault.

    protected void Lnk_SwitchAccount_Click(object sender, EventArgs e)
    {
        this.RedirectToShellUrl("AUTH", "appid=" + this.ApplicationId.ToString() + 
            "&forceappauth=true", "passthroughParam=optional");
    }

In Example 3-9, we are creating a key in the web.config file to associate a receiving end point for the selected “record changed” action. In the next section, we explain the HealthVault shell interface in detail.

    <!-- Handling selected record changed -->
    <add key="WCPage_ActionSelectedRecordChanged" value="default.aspx"/>

The Mayo Clinic Health Manager works with all the records associated with the account and functions as a multiple-record application (MRA). As illustrated in Figure 3-5, I can switch from my record to my mom’s record seamlessly within the Mayo Clinic application. This flexibility can be achieved in an application by including IsMRA=true while communicating with HealthVault Shell’s Authentication (AUTH) mechanism, as detailed in HealthVault Shell Interface. Using this capability, the application can then authenticate multiple records at the same time and make requests to access health information for each one of them. For the application to remember the previous active record before switching to any associated record, it should store the current record identifier in the application settings associated with the person before making the switch.

Figure 3-5. An application working with multiple records

Continua Health Alliance is a nonprofit, open industry organization of health care and technology companies joining together to improve the quality of personal connected health care. With more than 230 member companies around the world, it is the leading consortium for personal health care devices. HealthVault has announced that support for Continua drivers will be available in the future. When this happens, devices will be able to play well in the HealthVault and Continua ecosystem, either by using the HealthVault Web API or by converting data into IEEE 11073 formats.

Continua is not a standards body, but has identified a set of standards that together enable a personal connected health care ecosystem. At its heart is the IEEE 11073 Personal Health Data Standard, which dictates various data standard profiles for devices ranging from blood pressure cuffs to weighing scales. IEEE 11073 is a data standard and is independent of transport.

On the transport layer, Continua supports USB personal Health Class devices, Bluetooth health care device profiles, and other transports as they become compliant in the future.

Figure 3-7 shows the interfaces supported by Continua.

Figure 3-7. Continua-complaint devices

In addition to data storage, native HealthVault applications can use HealthVault for user authentication and authorization. Any data accessed using this mode requires the user’s explicit permission each time the application interacts with HealthVault.

Mayo Clinic Health Manager, https://healthmanager.mayoclinic.com/, is a native HealthVault application.

Applications can choose to simply store and access data from HealthVault without using HealthVault as a primary authentication and authorization entity.

FitBit (http://www.fitbit.com/) is a good example of an offline application. It links a FitBit account with a HealthVault user record and account, and then interacts with the health items therein.

The Direct project, formerly known as NHIN Direct, is collaboration between the public and private sector to develop a simple, secure, and standards-based method to send encrypted health information directly to known, trusted recipients over the Internet. This project aims at replacing the fax machine in health care. Providers are able to send documents to each other securely.

Direct integration is the easiest kind of integration with HealthVault, and trusted applications can actually send and receive documents to and from HealthVault using a Direct-enabled email address. HealthVault users get an email address in the format <handle>@direct.healthvault.com. As part of its Direct implementation, HealthVault automatically adds any recognized attachments (for example, CCDs or CCRs) to the user’s record.

Google Health was able to interface with HealthVault using the Direct integration. For HealthVault to accept emails from a new direct domain, the application needs to register the public key with HealthVault. If the application sends email to [email protected] with the user’s email address in the subject line, HealthVault stores the email in a password-encrypted package and sends an email to the user to associate the dropped-off information to their record. The user can also sign into her HealthVault record and read the message in the HealthVault Message Center.

Application Provisioning refers to providing an application in HealthVault’s production environment, which the HeathVault team does for all of the connectivity models discussed so far. However, in special cases it provides the ability for applications known as “master” applications to provision individual HealthVault “child” applications.

Frequently, solution providers develop HealthVault integration for common scenarios such as uploading lab information or sending clinical care record information from a facility’s EMR system. These solutions are deployed separately for each institution. The HealthVault team delegates the responsibility for creating these individual application instances to the solution provider through the Master Application mechanism.

Thus, for instance, if we wanted to deploy an individual instance of a Weight Tracker application per institution, we would use the AddApplication API available from the HealthVault Platform. Further Resources has links to examples and resources about how to create a child application.