HealthVault + Your Web Service + Your Client Apps

Cloud hosted services such as HealthVault, Windows Azure, Office365, Dynamics Online, and others provide a great canvas upon which to compose both consumer and enterprise solutions. In this article, we'll establish a foundation upon which to "front-end" a number of HealthVault solution scenarios. We'll illustrate the use of a web-service (hosted on Windows Azure, of course) to encapsulate HealthVault specific feature-areas that we subsequently wish to expose for our client applications. In a subsequent article, we'll illustrate how this approach enables flexible support of differing client types including enterprise systems, mobile devices, and web-applications.

Download this article as a PDF document.

Download corresponding Visual Studio 2012 project files.

Basic Configuration

The figure below illustrates the HealthVault Proxy Service using an Offline application deployment configuration. Notice that the HealthVault Proxy Service is a client of the HealthVault platform whilst Client Apps, interface directly only with the proxy.

This web-service does not need its own database and does not keep any state. It can easily run on an Azure WebSite or within an Azure WebRole. The proxy may also be deployed using an on-premises web-server for an enterprise scenario. Our Proxy Service exposes WCF (i.e. SOAP) service-interfaces. But, the sample could be modified to expose a REST interface instead.  We will defer that exercise for now in favor of some pending experimentation with Windows Azure Mobile Services (coming soon).

Figure 1. Basic Solution Architecture

The HealthVault Proxy Service exposes three primary service-interfaces for client apps. These interfaces correspond to HealthVault feature areas. Specifically, Patient Connect, Get/Put Things, DOPU.

Note: Learn more about HealthVault solution architectures and platform features at (https://blogs.msdn.com/b/healthvault/archive/2013/05/18/revisiting-connectivity-models-and-solutions-architectures.aspx).

Establish your Development and Test Environment

The Pre-Production Environment

From a platform perspective, HealthVault supports an ecosystem of applications and devices.   The HealthVault platform is well-documented with open support for practically any web-based client solution.  However, for integrity and security purposes, programmatic access to real user accounts is controlled.  In order to access the production HealthVault service, client applications must be authorized to access not only the production service itself but also individual consumer accounts hosted therein.  

This authorization process first involves development of your application utilizing a freely accessible Pre-Production Environment (PPE).   Once you have completed development and testing of your application using the PPE, then you may apply for authorized access to the production environment; a process termed “Go Live”.  

The Pre-Production Environment enables you to develop and test a complete end-to-end solution and thus gain a high-degree of confidence prior to final deployment.   Note that all PPE uniform resource identifiers (URIs) correspond to production environment URIs but with the “-ppe” suffix appended to the domain name (e.g. account.healthvault-ppe.com).  

Spend a few moments up-front establishing a HealthVault PPE “existing” user-account for your development purposes.  User logon and authentication to PPE corresponds exactly to the production HealthVault platform in that you may select from Windows Live, Facebook, or OpenID authentication.   We recommend creating a new test account using Outlook.com as illustrated.   You should first create the test account using Outlook.com, Facebook, or OpenID, and then proceed to the PPE environment in order to associate your new user-account with a corresponding HealthVault PPE account.

When you now logon to the HealthVault PPE Shell as a new user, the Shell creates an authorization workflow that associates your user-account with your corresponding authentication service.  

Consider end-user usage scenarios.  A common HealthVault end-user usage scenario involves a family.  A family healthcare manager (e.g. “Mom”) may configure, access, and manage HealthVault accounts for each family member (e.g. “Dad”, “Son”, “Daughter”).   Spend a few moments exploring the HealthVault PPE Shell.   Note that the “Health Information” section corresponds to collections of data-types that you may access from your solutions.

Register your HealthVault Proxy Service Application

The proxy service will need to be registered as a HealthVault application with a corresponding Application ID. Additionally, an X.509 Certificate will need to be generated and the public key provided to the HealthVault platform. The corresponding private key will be hosted within the proxy service itself and utilized for mutual authentication and encryption between the proxy service and HealthVault. You’ll want to first install the HealthVault .NET SDK on your development workstation along with Visual Studio.

After installation of the HealthVault .NET SDK, you will need to register your proxy application using the HealthVault Application Configuration Center (ACC).  The ACC enables a solution developer to associate an Application ID as well as a Public Key Certificate with a new HealthVault application.   A view of the ACC portal appears below.  Although you may accomplish the necessary registration steps using just the portal, don’t do so now.   We will instead utilize a tool included with the HealthVault SDK, the Application Manager, which automates this task.

From the Tools folder within the HealthVault .NET SDK installation path (e.g. C:\Program Files (x86)\Microsoft HealthVault\SDK\Tools) start the HealthVault Application Manager (i.e. ApplicationManager.exe).   Within the illustration below, note that I’ve already used Application Manager to create a new “HealthVaultProxy” sample.   Also note the link to the HealthVault Application Configuration Center (ACC) along with a short-cut to the local machine Computer Certificates store.   For our HealthVault proxy-service application, we will instead utilize the “Create New Application” feature.

Press the Create New Application button now.   This action opens the following dialog window.  For this scenario, we will not ask the Application Manager to also create a Visual Studio project directly but rather only utilize Application Manager to configure our application meta-data including Application ID and Certificate.

Within the Create New Application dialog window, type your solution name and uncheck the field labeled “Automatically create Visual Studio website for this Appliction”.   Press Create and Register Application.

Notice that this action launches the HealthVault Application Configuration Center (ACC) within a browser window.   You will first be prompted to logon.   Use an account that will be considered your Development Manager or Release Manager Account.  At the Terms and Conditions page, read and accept the agreement then select Create Application.  This registers your application with the HealthVault Pre-Production Environment and redirects your browser to the Application Configuration Center default page.   Your application name and assigned Application ID appear listed therein. The image below will differ based upon your specific application name and Application ID.

Also notice that the HealthVault Application Manager displays a new entry with a corresponding new self-signed certificate.  By convention, the Certificate Name corresponds to the assigned Application ID. 

Click the Computer Certificates link.   Notice the corresponding new certificate stored within the Local Computer certificate store.   Be sure to save and protect this certificate as it contains both your public and private RSA keys.   Plan to distribute only an exported certificate file containing your public key (typically saved as a file with the .cer extension).   A certificate containing only your public key has been automatically added to the Application Configuration Center during the Create Application step above.  Before moving your application to production, you may wish to assign a new production-only public-private key pair (i.e. a new certificate).

Let’s export the certificate file.  This may be done either from the ComputerCertificates console immediately above or via the HealthVault Application Manager.   Using the HealthVault Application Manager, right-click the Certificate Name and select Export public and private keys (.pfx).    Choose a destination folder that will be associated with the proxy-service solution files included with the Solutions Accelerator. The Visual Studio project’s “App_Data” folder is a good choice for prototype development purposes.

We are now ready to return to the HealthVault Application Configuration Center and complete the application registration process.  Within your browser, click on the Application ID link for the HealthVault Proxy Service application.

The resultant tab’ed web page represents your opportunity to tell the HealthVault platform about your application including why it needs access to HealthVault user-information, what fields will be accessed, whom to contact for management purposes, and additional rules and properties that you can explore later.   For now, navigate to the Offline Rules tab and select Edit.

Each HealthVault application will have a unique set of data-access requirements depending upon your solution requirements.  Hence, we’ll need access to a specific and custom set of information data-types within consumer HealthVault records.   Select that field group as illustrated below.   Be careful to also scroll the window further down and press the Save button.

Note: It’s common to configure both an Online rule and an Offline rule with the same configuration. This provides flexibility in solution architecture in that you may then provide both a User Portal as well as a Web Service usage experience.

Next, switch to the Methods tab within the HealthVault Application Configuration Center web-page. Configure your application as indicated within the following image. These "method" settings enable our application to utilize HealthVault platform features including "Patient Connect", "Drop-Off and Pick-Up", and to send insecure email messages.

Browse the additional tabs to familiarize yourself with additional configuration options. The Admins tab enables you to invite additional configuration managers to access this application configuration. At this point, you have everything you need to now configure and build the proxy-service sample application.

Configure, Build, and Deploy Your HealthVault Proxy Service

Modify your Project Settings

Now that you’ve utilized the HealthVault Application Configuration Center to register a new Application ID and a have corresponding X.509 certificate file, you may proceed to configure the sample proxy service project. Download the project files using the link provided at the start of this article.  Open the solution using Visual Studio. From within Solution Explorer, select and edit the HealthVaultAppSetting.cs file as illustrated.

Replace the dummy ApplicationID with your own as illustrated. Also set the .pfx certificate file name to match your new certificate file.

Note: Copy your certificate file (.pfx) into the solution’s App_Data folder. Be sure to set the certificate file property as “copy if newer” within the Visual Studio solution.

Also, note the myValidTokens Guid array within the AppSettings class. The corresponding list of tokens represents the list of client systems authorized (by you) to utilize this proxy service for access to HealthVault records. You must utilize and manage these tokens according to your business and solution deployment requirements. A typical scenario is to assign individual tokens to either separate departmental clinical systems or to individual client applications (e.g. enterprise tablets).  

Note: Each of your client applications will share the same consumer record-set associated with your Application ID. You will need to understand this scenario and ensure that your organizational access to HealthVault lands within the purview of terms of service and privacy constraints. In effect you are responsible for authenticated and secure access to consumer records accessible via your web-service. The sample code provided is for illustration and concept discovery purposes only and does not represent implementation of a web-service with complete authentication nor secure-access features.

In effect, our "token list" represents a shared-secret model of client-application support. Before moving this sample to production, you would want to implement a more sophisticated token-management facility than the simple Guid array provided. One possible approach is to implement a management interface that enables both application authentication as well as timeout-period token-generation. This article does not address security considerations beyond configuration of SSL for transport-level encryption between registered clients and the service.

Build and Test your Project

Use Visual Studio to build your web-service project. A console application project is also included within the sample solution. You may utilize this console application in debug-mode directly from Visual Studio in order to test connectivity and functionality of the web-service project prior to deployment to a hosted environment.

First, update the Service References section of the test client application. Initially, configure these service references to utilize the in-solution HealthVaultProxy library project.

Before running the test-client, look at the command-line usage options in file HVProxyTest.cs. Initially, just choose the "-createconnection" command-line option.

Open the project properties windows and configure the Command line arguments section as illustrated.

The -createconnection option will walk you through a sequence of questions and subsequently invoke the following TestCreateConnection method. Each of the remaining command-line options have a similar test-method illustrating the use of each web-service interface methods. Review file HVProxyTest.cs.

Deploy your HealthVault Proxy Service

Deploy the WCF web-service project to any IIS web-server reachable via HTTP or HTTPS. Windows Azure offers several web-site hosting environment options. We’ve utilized Azure WebSites for hosting our service during development and testing. This approach is very convenient, but not acceptable for production hosting because Azure WebSites doesn’t currently support HTTPS endpoints.  For production deployment, you’ll want to use the Azure Web Role option instead.  Proceeding with development/prototype deployment, configure your Windows Azure WebSite using the instructions provided here.

Once you have an Azure WebSite endpoint available, download the publish profile as illustrated. You will import this profile into your HealthVaultProxy project from the Publish menu.

You can easily deploy to an Azure website from within Visual Studio simply by right-clicking your HealthVaultProxy project within Solution Explorer and selecting Publish. Select Import and open the publish profile previously obtained from your Windows Azure dashboard.

Once you have your proxy web-service published to a hosted environment, note the service URL from the Windows Azure WebSite Dashboard. Copy this URL and use it to reconfigure your client-application Service Reference endpoints. Note they should point to your new hosted service URL (e.g. "MyProxy.AzureWebSites.net/HVConnect.svc").

Enable Transport Security for your HealthVault Proxy Service

Windows Azure WebSites are great for lots of scenarios including hosted web-services. However, this convenient hosting environment currently doesn’t support HTTPS (i.e. SSL).  [6/03/2013 : Correction.  Azure Websites now offers SSL support.]  Hence, you’ll need to instead utilize the Windows Azure Web Role (i.e. dedicated virtual machine) deployment model in order to support SSL certificates.

You will need to modify your solution to add an Azure Web Role project as indicated.  Your HealthVaultProxy service will be hosted on a dedicated (but not state persistent) virtual machine.   Learn more about developing solutions with Azure Virtual Machines via the links provided at the end of this article.

See the following references section for information on using HTTPS with Windows Azure Web Role hosted services.

• Configuring SSL for an application in Windows Azure (https://www.windowsazure.com/en-us/develop/net/common-tasks/enable-ssl)
• Configure an SSL Certificate on an HTTPS Endpoint (https://msdn.microsoft.com/en-us/library/windowsazure/ff795779.aspx)

Corresponding modifications to the HealthVaultProxy project are limited to the web.config file and the system.servicemodel section as illustrated.

Next-Steps

Please note the following key-points.

1. This project intentionally does not depend upon any HealthVault SDK components on the client-side. All SDK constructs are hidden within the server-side proxy service. This approach is optional. Advantages include removing client-side dependencies and extending the range of possible client types. You may decide to import the Microsoft.Health.ItemTypes.dll assembly into your .NET client application project in order to work with "Thing Types" via C# classes instead of raw XML. Other options include writing simple wrapper classes (as I've done) or perhaps utilizing XSD.exe to generate C# classes from HealthVault Thing Type schema (see the schema type browser at https://developer.healthvault.com).
2. The HealthVault Proxy Service serializes Thing Type data into XML. JSON serialization API's are also available using the HealthVault SDK.
3. Our project utilizes WCF to expose SOAP based services. This approach is nice for many client application types (especially if you can use tools to generate the client-side proxies). However, it's not so nice for browser-based or JavaScript clients. For that scenario, a REST or HTTP Handler approach would be more ideal. We'll work on that demonstration soon.
4. There are lots of HealthVault features that we're leaving on the table. One of those is the ability to use built-in Thing Type transforms. A client could use these transforms to render data to HTML, for example, and thus achieve an easily coded HealthVault data-type viewer.
5. We recommend setting break-points within HealthVaultProxyTest and simply walk-thru the service interface methods to explore how Patient Connect, Get/Put Things, and DOPU work.
6. Integrate additional Windows Azure platform features.   https://www.windowsazure.com/en-us/develop/net/app-services/  and https://www.windowsazure.com/en-us/develop/net/fundamentals/intro-to-windows-azure/
7. Windows Azure virtual machines come in two flavors (persistent and not persistent).   Web-role hosted virtual machines are not persistent (also referred to as Platform as a Service, or PAAS).   You may wish to use the persistent variety instead (also referred to as Infrastructure as a Service, or IAAS).   Advantages of IAAS hosting include easy integration with on-premises services including your Virtual Networks and Active Directory.