Introduction to HealthVault Development #3: Configuring our application

Now that we have HelloWorld set up and running, we want to move on to developing the real application. We’ll start with a shell application and add to it as we go.

Download the WeightTracker shell, and open the project in Visual Studio. Register the certificate using the same process you used in the previous tutorial. Add a reference to the following HealthVault assembiles in c:\program files\microsoft healthvault\sdk\dotnet\assemblies:

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

Run it, and you will be taken to the HealthVault authorization page for the application. Note that it’s specific to this application – it has its own name, logo, description, and set of requested types.

It is possible to continue in the tutorial using the configuration that comes with WeightTracker, but since configuration is an important part of HealthVault applications, I recommend that you create your own configuration. That’s what we’ll be doing in this part of the tutorial.

Creating a new certificate

When we were working with Hello World, we had to register the application certificate on our system, and we did that through the MMC utility.

This time, we need to create a certificate, register it on our system, then register it with the HealthVault platform. It’s possible to do the work by hand, but we’re going to use a utility that ships with the SDK to do this.

Go to Start-> All Programs –> Microsoft HealthVault –> SDK –> HealthVault Application Manager. If you are running Vista, you’ll need to run as administrator.

You should see the initial application manager screen, and it should list the HelloWorld Sample certificate that you registered in the last part of the tutorial, and it may list other sample applications you have used.

The Application Name isn’t stored as part of the certificate – it is only stored by the ApplicationManager application. The application knows the names of some of the sample applications, which is why they show up.

If you check the “Show Unnamed applications” checkbox, you will see the WeightTracker certificate pop up. You can verify which one it is by matching the application ID (defined in web.config) with the certificate name.

We will create a new certificate by clicking the appropriately-named button. This will bring up a dialog that asks you to enter a name for the application.

I chose to call mine “Weight Tracker Tutorial”, since that’s the name of the application we’ll be writing. You can use the same name or something else, like “Pizza Joe’s spicy vegetarian”.

The main list should refresh and you should see the new certificate listed. When we generated a certificate, it was created with both a private and a public key, and they’re both in the certificate store. The public key is something that we’ll send off to the HealthVault platform so it can use to verify items signed with the private key. Public keys are typically passed around as .cer files.

The private key isn’t something that we should be emailing around, because anybody who has it can pretend to be us. Application manager does allow you to export both the private and public keys in a .pfx file, in case you want to run the application on another server.

The wikipedia articles on public key cryptography and digital signatures are good introductions to this area if you would like to know more. There is also the cryptography overview on MSDN.

Registering a certificate with the HealthVault platform

To register a certificate, right-click on it and choose “Upload certificate”.

This will package the certificate’s public key and the application name (if present) into a request, and send it off to the HealthVault application configuration center. It will then launch your browser to the app config center.

The app config center is a HealthVault application, and access to the configuration of a specific application is limited to a single HealthVault account. When you authenticate, you should use an appropriate account that works for what you are doing – using a shared account when multiple people need to be able to access and modify an application’s configuration.

Once you have authenticated, you will see a list that contains your new application, with the name that you chose, and the generated application id. Click on your application.

You will see the Information page for your application. Here, you set the name, description, and other items that show up on the authorization page, including the logo.

Configuring an application’s data access

We’ll start by configuring the data access that we’ll need to get started.

There are two kinds of access that an application can request. Online access provides access when the user is running your web application, and is what we’ll use in the tutorial. Offline access provides access whenever the application wants access, and is typically used to synchronize information between HealthVault and the application.

Offline access is something users are more careful about granting, especially to groups that they don’t trust, so your application should try to use online access whenever possible.

Click on the “OnlineAccess” tab. To make organization easier, data access is grouped into rules. Choose “add rule”, to bring up the rule editor.

Here you need to give a name for the rule (which isn’t user-visible, so you can name it whatever you want), and a “why string”, which is the justification that is given to the user on the page where they decide whether to grant access to your application. Good why strings are required before you can go live, and if you put some thought into it at this point, things are much easier later on.

I’ll call this rule “Weight”, because that’s what we’re going to ask for. For the why string, I thought of a few possibilities that we could use:

1. Because we need to access your data.
2. Because the application needs access to work correctly.
3. WeightTracker uses access to your Weight measurements to help you effectively manage your weight.
4. All your weight are belong to us.

Which one is best? Please write 500 words explaining why, and have it for me on Monday.

The key here is that the why string is displayed to the user, and it needs to be something that a) the user understands and b) explains the benefit of granting access.

For permissions, I choose “All”, because I want to be able to perform all operations on Weight measurements (create/read/update/delete) , and then I choose the “Weight Measurement” data type from the list, and pick “Save”. That gives me my first rule.

I add a second rule:

Note that I only specified Read access, rather than asking for access that I don’t need. Your application’s access should always be as minimal as possible – don’t ask for access that you don’t need.

You will also need to delete the rule for “Personal Image”.

Now that we’ve done that, the platform configuration is complete. All that is left is to configure the application to use the new application ID.

Configuring the application to use a new certificate

To modify the application, we need to update the application id in web.config file.

In application manager, right-click on your new certificate, and choose “copy certificate name to clipboard”. Switch over to Visual studio, open the web.config file, and look for the “ApplicationId” entry. You will find:

<add key="ApplicationId" value="f36debe2-c2a3-434a-b822-f8c294fdecf9" />

That’s the one that the application is currently using. On startup, the application finds this string, prepends “WildcatApp-“ to it, and then uses that string to search for a certificate to use.

Duplicate the app id entry, and comment one of them out. Paste in your new application ID for the value in the one that isn’t commented out, remove the “WildcatApp-“ part, and save the file.

Here’s what I typically do:

<add key="ApplicationId" value="1b8cbb19-a9ed-4ebc-b498-6ae3d0ed44d7" />

<!—applications ids
    my key
<add key="ApplicationId" value="1b8cbb19-a9ed-4ebc-b498-6ae3d0ed44d7" /> |
    original key
<add key="ApplicationId" value="f36debe2-c2a3-434a-b822-f8c294fdecf9" />
-->

At this point, you should be able to run your application, and get the authorization screen that matches the information that you entered in application configuration center.

I like to keep another application ID around (usually the HelloWorld one) so that I can easily switch to it to see if I’m running into problems due to my application configuration.

Next Time

Next time, we’ll be writing some code.

#4