Introduction to HealthVault Development #9: Optional Authorization

  • Article

This week, we have a new customer request. One of our customers wants to track her mood on a daily basis. We can do this by using the Emotion data type, but after talking with our broader customer base, we find that some of them don’t want this information displayed by the application.

What to do? What to do?

Enter optional auth

Optional auth allows different users to grant our application different amounts of data access. All users are requested to grant us the base auth for the application, but our application decides when to ask users for additional data access.

We will use the specific access granted by a user to determine what information to query for and what to display in our user interface.

Setting up our optional authorization rule

Go to the application configuration center, pick your application, and add a new rule, named “Opt_Emotion”, make it optional, ask for Create/Read permissions, and choose the “Emotional State” data type. Save your rule.

Determining type permissions

We can ask the platform for information about our access to the Emotion data type with the following code:

List<Guid> items = new List<Guid>();
items.Add(Emotion.TypeId);
Collection<HealthRecordItemTypePermission> permissions =
        PersonInfo.SelectedRecord.QueryPermissions(items);

This code asks the selected record whether it has access to Emotion. If there is no access, the permissions collection will be empty.

Since we’re only concerned with one rather than several types, I wrote a little wrapper to make our code a bit simpler. Put this at the beginning of Page_Prerender:

HealthRecordItemTypePermission emotionPermission =
                          GetItemPermission(Emotion.TypeId);

If you look at the HealthRecordItemTypePermission class, you’ll see that it stores the permissions for both online and offline access. In our case, we want to look for online access.

if (emotionPermission.OnlineAccessPermissions == HealthRecordItemPermissions.None)
{
    c_linkEnableMoodTracking.Visible = true;
}
else
{
    c_labelMood.Visible = true;
    c_dropDownListMood.Visible = true;
    PopulateDropDownFromEnum(c_dropDownListMood, typeof(Mood));
}

Because I’m going to be defining the rule set, I know ahead of time that the user is either going to have enough access to Emotion for me to do what I want, or no access at all. I can therefore simply test whether there is any access to control my UI.

It’s possible, however, for me to ask for read and write access separately, and if I had done that, I would need to check for specific permissions (Create, Read, Update, or Delete).

It would probably be a good time to run the project to see what happens. There should be a link below the Save button that says “Enable Mood Tracking”.

Asking the user for access

You might remember when you first ran the application, you were redirected to HealthVault so that you could authorize access for the application. For optional authorization, we’re going to send the user back to that same page.

But first, we’d like to explain to the user the advantages of providing us access. That is done with a landing page named AuthorizeEmotion.aspx.

Here’s the code that will do the redirect:

string TargetQuery =
    "appid=f36debe2-c2a3-434a-b822-f8c294fdecf9&onopt1=Opt_Emotion";
RedirectToShellUrl("APPAUTH", TargetQuery);

The appid parameter must be set your application’s application id, and the onopt1 parameter is set to the name of the rule we want to ask for. It is possible to ask for multiple rules and to ask for offline access as well – the details are on the HealthVault Shell Redirect Interfaces page.

Run your application, and choose the “Enable Mood Tracking” button, and click “Authorize”. When you get back to the authorization page, you will now find that it now asks for access to the Emotional State data type, with a checkbox next to it. Click the checkbox, approve access, and you’ll now find that the UI shifts into the “mood-enabled” mode.

Storing and displaying Mood values…

Storing and display Mood values is similar to the code we wrote to store the exercise values. We add the following code after we save the Exercise instance:

Emotion emotion = null;
if (c_labelMood.Visible)
{
    emotion = new Emotion(new HealthServiceDateTime(DateTime.Now));
    emotion.Mood = (Mood) Int32.Parse(c_dropDownListMood.SelectedItem.Value);
    PersonInfo.SelectedRecord.NewItem(emotion);
}

and then modify the code that sets up the relationship:

weight.CommonData.RelatedItems.Add(
             new HealthRecordItemRelationship(exercise.Key));
if (emotion != null)
{
    weight.CommonData.RelatedItems.Add(
            new HealthRecordItemRelationship(emotion.Key));
}

PersonInfo.SelectedRecord.NewItem(weight);

Displaying mood values in the table

The header on the table needs to change based on whether we are tracking mood or not:

if (c_labelMood.Visible)
{
    AddHeaderCells(c_tableWeight, "Date", "Weight", "BMI", "App Name",
                           "Minutes", "Mood", "&nbsp;");
}
else
{
    AddHeaderCells(c_tableWeight, "Date", "Weight", "BMI", "App Name",
                           "Minutes", "&nbsp;");
}

We add the following to our relationship-fetching code:

Emotion emotion = relatedItem as Emotion;
if (emotion != null)
{
    mood = emotion.Mood.ToString();
}

after declaring “string mood” right below “string minutes”.

And finally, we modify our code that adds the data to the table:

if (c_labelMood.Visible)
{
    AddCellsToTable(c_tableWeight, weight.When.ToString(),
               weight.Value.DisplayValue.ToString(), bmiString, appName, minutes, mood);
}
else
{
    AddCellsToTable(c_tableWeight, weight.When.ToString(),
               weight.Value.DisplayValue.ToString(), bmiString, appName, minutes);
}

With that code, the application should now support entering and displaying mood information.

De-authorization

If we want to give the user the opportunity to turn off mood tracking, we can do it by using the same call as we used to authorize the access.

Add a page named DeauthorizeEmotion with appropriate text and code, and then modify the main page code so that it shows the authorize or deauthorize link as applicable.

Current Code

To help keep your code in sync with mine, I’ve uploaded my current code to MSDN Code Gallery. You will need to change my source so that it uses your application ID rather than mine.

Suggestions

I have a list of topics that I’m planning on covering, but if you have a suggestion for what you’d like to see, let me know.

Next Time

Next time, we’ll be looking at how to store hunger information in our application.