Getting Started with the Microsoft HealthVault SDK - Beta

About HealthVault

Microsoft HealthVault is a new personal health platform that lets consumers gather, store, and share health information online. With HealthVault, users control their own health records, so they can share their health information with family, friends, and health care professionals, and have access to trustworthy online health management applications - including yours!

About This Getting Started Guide

This Getting Started guide will show you how to create a HealthVault application and connect it to the Microsoft HealthVault Pre-Production Environment (PPE). The PPE is a platform server environment that is just like the HealthVault web site, except that it does not provide access to any real customer data. It is provided so that developers can create and test HealthVault applications safely.

More specifically, the guide tells about:

• the materials included in the HealthVault Application SDK.
• the procedure for installing the SDK.
• the requirements for developing a HealthVault Application.
• the process of creating your application and testing it in the HealthVault PPE.
• where you can go to learn more about HealthVault.

This Getting Started guide is available in the SDK installation, online in MSDN (the copy you are viewing now), and as a download from MSDN. The most recent version is always available at the MSDN locations.

For information on connecting your application to the HealthVault production environment and making your application available to HealthVault users, see the Go-Live Guide.

For information about the full process of becoming a HealthVault Solution Provider, see the Getting Started Guide for Potential HealthVault Solution Providers.

What Is a HealthVault Application?

A HealthVault application is a Web application that is available to users of the HealthVault web site. It can communicate with the HealthVault platform servers to determine data access rights, and (rights permitting) to create, read, update, and delete all types of data in the HealthVault system.

Before a HealthVault application can access user data, it must pass several steps of authentication and authorization.

1. The user starts an authenticated brower session using the HealthVault web page and either a LiveID or an OpenID account. This authenticated session is also called the "HealthVault user shell." An easy way to start the user shell is simply to open a HealthVault application (below): the user will be taken to the HealthVault web page and prompted to sign in before the application will run.
2. The user starts the HealthVault application. This can be done in several ways: by entering the application URL, by clicking on a link in the HealthVault Application Directory, or (if the application source code is available) by starting the application in a development environment such as Visual Studio. In addition, if the user is signed in to the HealthVault web site and has run the application before, it may be available in the user's personal application list.
3. The HealthVault platform servers authenticate the application. The Web server that hosts the HealthVault application must also host a certificate that identifies the application.
4. The user authorizes the application. The user shell lists the types of data access requested by the HealthVault application, and the user can choose whether to authorize the application or not. Once an application is authorized, it remains authorized for a given user unless the user revokes the authorization.
5. The application runs.

Exploring HealthVault

You can explore HealthVault without needing to contact Microsoft.

Taking a Look Around

To explore HealthVault:

• Read the HealthVault documentation on MSDN.
• Download and explore the SDK.
• Create a personal HealthVault account at www.healthvault.com. Later, you can create fictional HealthVault account in the developer environment to use when developing and testing your application.
• After installing the SDK, explore the sample applications in C:\Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples.
• Upload data from real and simulated devices using HealthVault Connection Center. After you install the SDK, device simulators are available in the SDK in C:\Program Files\Microsoft HealthVault\SDK\Simulators.

The Big Picture

If you decide you want to wade in and modify the sample apps, you must create an account in the HealthVault Pre-Production Environment (PPE). These accounts exist in an environment that is separate from but functionally equivalent to the Consumer HealthVault environment.

Once you have a PPE account, you can alter the source code of any of the samples to explore your own ideas for HealthVault-compatible applications. When you reach a point where the sample application doesn’t have permission to do what you want to do, it's time to request or generate your own ApplicationID (see Generating an Application ID for more information).

When you decide that your application is ready for consumers and you want to become a HealthVault partner, you kick off the Go Live process (see the Go-Live Guide for more information). When the Go Live process is complete, your application will be available to HealthVault users in the Consumer HealthVault environment.

This diagram summarizes the end-to-end process from hearing about HealthVault to taking your application live on HealthVault.

What’s in the SDK?

After you install the SDK, the following items are available from the Start menu:

• the SDK Reference (Microsoft.Health.chm) containing the managed code interfaces to the HealthVault platform, methods, and types. This information is also available on MSDN for download and for viewing online.
• This Getting Started guide  (check MSDN for updated versions)
• the SDK command prompt

The following items are created in the SDK folder at Program Files\Microsoft HealthVault\SDK:

• Docs
• DotNet
• Native
• PartnerResources
• Simulators
• Source
• Tools

HealthVault SDK Docs Folder

The following items are available in the Microsoft HealthVault\SDK\Docs folder:

• this Getting Started guide
• the Microsoft.Health.chm file containing the managed code interfaces to the HealthVault platform, methods, and types
• the HealthVault SDK End User License Agreement (EULA)

HealthVault SDK DotNet Folder

The DotNet folder contains several sample applications. Each sample application includes:

• Visual Studio project file and solution file
• The WinHttpCertConfig.exe utility and batch files to grant access rights to network service accounts
• a ReadMe file that provides instructions for installing the application certificate and granting access to network service accounts
• Everything else you need to run the sample and use it as a model for your own application

HealthVault SDK Native Folder

In the Native folder, you can find:

• The C/C++ header for unmanaged applications
• The object file library

HealthVault SDK Partner Resources Folder

The Partner Resources folder contains the framework for the application UI branding available for use in connection with Microsoft-approved HealthVault compatible applications. The primary brand elements available are buttons for the user interface.

HealthVault SDK Simulators Folder

Several simulated devices are provided. You can install, uninstall, plug/unplug, and refresh the devices using the WpdSimInstaller utility in this folder. The DeviceSimulators.xps document in this folder contains more information.

Note: The device simulators provide a quick way to populate a fictional user account with data.

HealthVault SDK Source Folder

The Source folder contains the source code for the following HealthVault .NET assemblies:

• Microsoft.Health.dll
• Microsoft.Health.Web.dll
• Microsoft.Health.ItemTypes.dll

You are welcome to experiment with and reuse this code.

HealthVault SDK Tools Folder

In the Tools folder, you can find:

• ComputerCertificates.msc: a Microsoft Management Console script that helps you import and export certificates to/from the correct certificate store
• HVCC_Consumer.reg: a registry script that points your HealthVault Connection Center at the Consumer environment
• HVCC_Developer.reg: a registry script that points your HealthVault Connection Center at the Developer environment
• WinHttpCertCfg.exe: a utility that can be used to allow the NetworkService account to access your application’s private key

Download and Install the SDK

You download the Microsoft HealthVault SDK installer from the HealthVault Home tab or Downloads tab.

To install the Microsoft HealthVault SDK:

1. Click Download the SDK Installer on the Home tab or HealthVault SDK on the Downloads tab.
2. In the File Downloads - Security Warning dialog box, click Save.
3. In the Save As dialog box, browse to the location where you want to save the SDK installer, and then click Save.
4. Double-click healthvaultsdk.exe to start the installer.
5. In the Open File - Security Warning dialog box, click Run.
6. On the Welcome screen, click Next.
7. On the End User License Agreement screen, read the EULA.
8. Click the link to the privacy statement and read the privacy statement.
9. Select the I accept check box, and then click Next.
10. Wait while the HealthVault SDK is installed.
11. On the final screen, click Finish.

Install a Sample Application Certificate

Your HealthVault application will not run without an application certificate. The HealthVault SDK includes a certificate management utility, "HealthVault Application Manager", that is specifically intended to manage application certificates on a development machine.

To install a sample application certificate using the HealthVault Application Manager:

1. Browse to C:\Program Files\Microsoft HealthVault\SDK\Tools, and then double-click ApplicationManager.exe.
2. Browse to the cert folder of the sample Web application, such as C:\Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples\HelloWorld\cert.
3. Select the certificate (pfx) file for the sample application, such as HelloWorld-SDK_ID-05a059c9-c309-46af-9b86-b06d42510550.pfx. (Note: The file browser does not show *.pfx files by default; you need to select Personal Information Exchange (*.pfx, *.p12) in the Files of type list to display the certificate).
4. Drag and drop the certificate file into the HealthVault Application Manager window.

To manually install a sample application certificate to your computer:

1. Browse to C:\Program Files\Microsoft HealthVault\SDK\Tools, and then double-click ComputerCertificates.msc.
2. In the Computer Certificates window, browse to Personal>Certificates. (Note: some versions of Windows use "My Certificates" instead of "Personal".)
3. Right-click the Certificates folder and select All Tasks>Import.
4. In the Certificate Import Wizard, on the Welcome screen, click Next.
5. On the File to Import wizard screen, browse to Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples\[sample app]\cert, and then select the certificate (pfx) file for the sample application, such as HelloWorld-SDK_ID-05a059c9-c309-46af-9b86-b06d42510550.pfx. (Note: The file browser does not show *.pfx files by default; you need to select Personal Information Exchange (*.pfx, *.p12) in the Files of type list to display the certificate).
6. With the pfx file selected, click Open.
7. On the File to Import wizard screen, with the pfx file name now displayed in the File name field, click Next.
8. On the Password wizard screen, you don’t need to provide a password. Just click Next.
9. On the Certificate Store wizard screen, keep the default selections of Place all certificates in the following store and  Personal in the Certificate Store field, and click Next.
10. On the Completing the Certificate Import Wizard screen, click Finish.
11. In the Certificate Import Wizard message box, click OK.

Note that the certificate now appears in the list in the Computer Certificates window.

Grant Access to Network Service Accounts (IIS only)

This step is required if your Web application is hosted by IIS. It is not usually required if your application is hosted by the Development Web Server that is included with Visual Studio, because the Development Web Server does not use isolated machine accounts.  That said, if you are having certificate problems, there is no harm in granting certificate access to other accounts as shown below.

To grant access using the HealthVault Application Manager:

1. Browse to C:\Program Files\Microsoft HealthVault\SDK\Tools, and then double-click ApplicationManager.exe.
2. Right click the certificate file.
3. On the right click menu, select Grant access to IIS process.

To grant access manually:

Before you can run the commands in this section, you need to install winhttpcertcfg.exe on your computer. Winhttpcertcfg.exe is included in the cert subdirectory of each sample in the SDK. You can also install it from the MSDN Web site as part of a server resources kit (search for "Winhttpcertcfg.exe" on MSDN).

The procedure to grant access to a network service account depends on the operating system of your Web server:

Windows XP

To grant the necessary Windows accounts access to the application certificate on Windows XP SP2:

1. In the sample application’s cert folder, run GrantCertificateRightsXP.bat to configure the needed Windows accounts with access to the certificate.
2. Review the output of the batch file to see whether the operation succeeded or failed.

Windows 2003 Server

To grant the necessary Windows accounts access to the application certificate on Windows 2003 Server:

1. In the sample application’s cert folder (SDK\DotNet\WebSamples\[sample app]\cert), run GrantCertificateRights_Win2003.bat to configure the needed Windows accounts with access to the certificate.
2. Review the output of the batch file to confirm that the operation succeeded.

Windows Vista

Note: In Windows Vista, you must run the batch file in Administrator mode (which is not the same as being logged in to an Administrator account) in order to grant the necessary Windows accounts access to the application certificate.

To grant the necessary Windows accounts access to the application certificate on Windows Vista using the batch file:

1. In the sample app’s cert folder (SDK\DotNet\WebSamples\[sample app]\cert), right-click GrantCertificateRights_Win2003.bat.
2. From the context menu, select Run as administrator.
3. Review the output of the batch file to confirm that the operation succeeded.

On Windows Vista, you can also grant certificate access to the computer (IIS) account manually.

To manually grant the necessary Windows accounts access to the application certificate on Windows Vista, using the Microsoft Management Console (MMC):

1. Right-click the certificate you just loaded into the MMC (see Install a Sample Application Certificate). 
2. From the context menu, select All tasks>Manage private keys.
3. In the Permissions dialog box, click Add. 
4. In the Select Users, Computers dialog box, click Locations.
5. Select the computer's name,  and then in the Object Name box, type NETWORK SERVICE. 
6. Click OK in all dialog boxes.

Open the Sample Solution File in Visual Studio

The solution file for each sample is located in the sample application's root folder (SDK\DotNet\WebSamples\[sample app]\[sample app].sln). Double-click the solution file to open it in Visual Studio.

Configure the Web Proxy Server

A HealthVault application interacts with the Microsoft HealthVault servers in two important ways:

• The client’s browser is redirected from your Web application’s server to the Microsoft HealthVault PPE Account Server when the client's user signs in to a HealthVault user account, and again each time the client makes an authorization request.  When these requests are complete, the account server redirects the client’s browser back to your application.
• Your ASP.NET application itself makes requests (in application code, not though a browser) directly to the Microsoft HealthVault PPE Platform Server.

When your ASP.NET application is running behind an organizational firewall (such as in a corporate network), it may be necessary to explicitly tell your ASP.NET application to use a specific proxy server for its Web requests. This alternative works differently from the proxy server settings in the browser, because ASP.NET runs under a different user account from the one you use (for security reasons.) If requests to the Microsoft HealthVault PPE Servers are not working properly, your application will throw an exception immediately after the user signs in to the application, when the Microsoft HealthVault account server redirects to your application.  At this point, the application makes its first calls to the Microsoft HealthVault account server to get basic user information.

If a proxy server is required, you can place the following sample configuration code into the web.config file of your application (you will need to specify your own proxy server’s address.)

<system.net>
<defaultProxy>
      <proxy bypassonlocal="true" proxyaddress="http://myproxy.mydomain.com" />
   </defaultProxy>
</system.net>

Start the Sample Application

To run the sample application:

1. In Visual Studio, make sure the sample project is selected and press F5.
   The sample application will start and connect to the HealthVault PPE login server.
2. Log in to the HealthVault PPE using the test User ID that you created earlier.
3. Once you have logged in, click on the name of the sample application in the PPE window.
4. When the authorization page opens, click Approve to continue.

You have created a HealthVault application! You are free to modify the application as much as you like.  The sample applications in the SDK provide good starting points for adding functionality to your application.

Make the Application Your Own

The SDK provides several ways to customize your application beyond the examples provided by the sample code.

Application ID

As you continue to develop your application, you will eventually notice some limits on its behavior. For instance, you cannot change its online description, or modify its data access rights. (It always has full access to all HealthVault data, or at least all the data in the PPE environment.) That is because, as far as the PPE server is concerned, it is still the sample application whose application certificate you originally used to install it.

To give your application an identity of its own, you will need to create a new Application ID. With a new Application ID, you can:

• See your own logo and description during sign-in, instead of those belonging to a sample application.
• Explore Offline Access, Open Query, and Send E-mail functionality.
• Configure the data access rights of your application.

For more information about creating an Application ID, see Generating an Application ID.

Data Types

You may also find that your application needs to keep track of information that does not correspond to an existing HealthVault data type.

For information on adding new information to an existing HealthVault data type, see Extending HealthVault Data Types.

For information on creating a completely new data type, see HealthVault Data Types: Custom Data Types.

Resources Available from MSDN

The MS HealthVault Developer Center on MSDN provides links to a variety of useful resources.

On the Home tab:

• Link to the HealthVault Device Logo Program.
• Download the SDK installer.
• Download the DDK installer.
• Open the Getting Started guide.
• Link to the HealthVault blog written by a Microsoft HealthVault developer
• Link to the HealthVault device blog.
• Link to the HealthVault FAQ blog.
• Link to and participate in the HealthVault forum.

The Home tab also provides links to:

• The HealthVault consumer Home page
• The SDK Reference (HealthVault Class Library)
• The Go Live guide
• The Consultant Directory and information for prospective developer consultants

On the Library tab:

• The HealthVault Class Library

On the Learn tab:

• The Getting Started guide.
• A white paper on using a sample application to develop your own application
• The Consultant Directory
• The HealthRecordItem Type Schema Browser: a list of all thing types currently defined, where you can:
  • View a schema, open it as a file, and verify XML against it
  • Add a new Advance Directive thing
  • Insert your thing XML and verify it against the schema, and open the schema as a file
•  Dictionary browser: a list of all Microsoft HealthVault vocabularies, with the ID and name for each type in a vocabulary
•  Raw XML API Reference provides:
  • The Web service methods that can be used to communicate with Microsoft HealthVault.
  • The XML data schemas (thing types) that can be stored in and retrieved from Microsoft HealthVault.
  • Other schemas that get included in the method or thing type schemas.
• Method Schema Browser provides a list of all XML methods that HealthVault currently exposes. You can view request and response schemas and the XML method schemas for the types used in the methods.
• Requirements for development consultants
• How-to guides on a variety of subjects related to developing an application for HealthVault.
• Instructions for the major steps in becoming a HealthVault partner. You can learn how to:
  • Generate an ApplicationID
  • Request a new HealthRecordItem type
  •  Go live

On the Downloads tab, you can download:

• HealthVault SDK
• Makecert.exe, a tool that creates a public key/private key pair
• WinHttpCertConfig.exe, a tool that grants certificate usage rights to the NetworkService account
• SDK Reference, the HealthVault Class Library in CHM format
• the Getting Started guide
• the white paper on using a sample application to develop your own application

On the Support tab, you can:

• Run a search against MSDN, the Microsoft Knowledge Base, MSDN blogs, and MSDN forums
• Post a question to the MSDN HealthVault forum
• View answers to recent questions
• Contact a Microsoft Support professional
• Investigate other support options
• Connect to the Consultant Directory
• Connect to the requirements for becoming a developer consultant

On the Community tab, you can

• View the HealthVault developer blog and FAQ
• View and participate in the HealthVault forum