Authorizing Additional Records or Switching the Active Record
We’ve gotten a lot of questions about how users can connect to and use their application for multiple HealthVault records from partners lately; we’ve also found a number of partners who didn’t consider the scenario of an existing user wanting to switch which HealthVault record is currently connected and authorized for their application. These are all very important scenarios, and every HealthVault application should carefully consider how to handle them effectively.
The nice part is that it’s very easy to do so. HealthVault has been designed to manage switching records and using multiple records with an application in a very lightweight way that requires very little work on the part of the application developer.
This is going to be a pretty long post—so if you want to skip over all the scenarios and context, and head straight to the implementation details and code, just scroll to the bottom. There’s not much code required, and it’s down at the end.
Also, keep in mind that there are still two types of applications to consider here—“Single Record Applications” (or SRAs) that only work with one HealthVault record at a time, and “Multi Record Applications” (or MRAs) that understand how to work with multiple records simultaneously. For the purposes of this post, we’re going to talk only about SRA applications, which are the most common type of application. We’re also only talking about applications with an online user experience—so no PatientConnect or Drop-off-Pick-Up applications apply here either.
So, let’s get started. Before we get to how to do this, we want to make sure everyone understands why this is important and why effectively every application should include this functionality. Let’s start from the beginning: the first time a user goes to your application and connects to HealthVault, they are redirected to HealthVault where they:
1. Create a new account, or sign into an existing account
2. Create a new health record, or select an existing health record
3. Review the application authorization request, and accept/reject it, and are then redirected back to the application
In #1 and #2, it’s important to note that a HV account can create and manage multiple health records (where each health record is for a single individual)… and that a record can be managed by multiple accounts. There is a many-to-many relationship there. If my wife and I both create accounts, and create records, and then share custodial access to our records with each other… then there will be two accounts, each with access to the same two records. Or, if my wife creates an account, she can then create a record for herself, and a record for her mother, and another for a child (for example). She would have one account that then has three records for three individuals… all using the same account sign in credentials.
In general, HealthVault manages this complexity for applications. You simply direct users off to authorize your application, and at the end you get either a wctoken to represent the signed in online session, or a PersonID/RecordID that can be used for offline communication to/from a user’s HealthVault record.
However, there are a few user scenarios that make it a good idea to display to the user which record is currently linked (or “active”), and to display a link or button to change the current linked/active record. This is because with the default parameters, returning users will automatically be using the previously active record (for online connections) or for applications using offline connections the PersonID and RecordID are stored by the app and don’t change unless the app lets the user change them. The most relevant scenarios in which the app needs to let the user change active records are:
1. If it’s been a few months since the user set things up, he may want to verify that the app is set up to read/write data to the correct HV record (he may have forgotten which record he authorized, for example), or may just want to head back to the app to make sure things are set up properly. The user would click on the link on the HV side to go back to the application, and that would go to the Action URL’s HOME target. The user would expect to be able to verify that they’ve already set up a connection, and to see the name of the HealthVault record currently receiving data.
2. If the user accidentally selected the wrong record when authorizing your app (example: user has a HV account that manages 4 records, they intended to pick the 4th record but instead left the default/1st record selected), they may want to go back to the application and switch which record is set up to receive data. This would change the association between the application user ID and the HealthVault record.
3. If the user decides to create a new HealthVault account or record, and abandon the old one, they may want to go back to the application and either remove access (and then later add it to the new record), or switch from the old to the new in a single operation.
Some of these can be handled somewhat by severing the connection from the HealthVault side (and then connecting from the other record), but that isn’t always optimal, and many users have expressed their expectation that they would do this by going to the application to make changes, not HealthVault’s shell UI. We strongly suggest supporting it from both sides… plus, exposing it from the app allows the application to handle the change gracefully, rather than having to catch Access Denied errors from HealthVault after the user breaks the connection from the HV side.
Anyhow—the functionality to do all this is pretty simple, thankfully. For returning users, you just need to:
1. Read and display the active record name (so users know which record is active, and can decide if they want or need to change the active record)
2. Display basic HTTP links for the switch record and (less important, but also helpful) remove access functions.
a. Those are static links that go to HealthVault and pass in some parameters to tell HV to send the user through the appropriate workflow (using the Shell Redirect feature, the server-side equivalent of the client’s Action URL Redirect—using the AUTH target and the FORCEAPPAUTH parameter).
3. Handle the “SelectedRecordChanged” Action URL target (which can point to an existing target as long as your code handled the record change properly there)
In practice, for those using the .NET SDK, this involves:
1. Editing your web.config and adding a new entry like the following, replacing src.aspx with an appropriate page to handle the SELECTEDRECORDCHANGED target (if your code needs custom logic to grab the new PersonID/RecordID and save it to a local DB, for example… native apps can likely just use their normal default page):
a. <add key="WCPage_ActionSelectedRecordChanged" value="src.aspx"/>
2. Handling the “Change User” or “Switch Record” button/link with the following code:
this.RedirectToShellUrl("AUTH", "appid=" + this.ApplicationId.ToString() + "&forceappauth=true", "passthroughParam=optional");
For non .NET SDK apps, or those who prefer a static link, you just need to add a hyperlink of the following form:
As well as handling the SELECTEDRECORDCHANGED target on your Action URL redirect handler.
I’ll include one example here to illustrate a bit. If you go to the (free) American Heart Association Heart 360 app (https://www.heart360.org), the first page lets you get started, which has the user sign in, and authorize the app if that hasn’t already happened. If it has, then the user just signs in to an online session. If the user has an account with multiple records, and has already authorized one of the records, the next time they go back and sign in, that previous record is automatically selected.
The next page includes a “Welcome back, <FIRST NAME>” string in the upper right that is using the HealthVault selected/active record name, and to the right of that has a “Change User” link. The “Change User” link uses the HealthVault Shell URL redirect with the AUTH target and the FORCEAPPAUTH=true parameter in order to allow the user to either connect and use an additional record, or just to switch the current record.
And, for reference, the record select screen you should see on the HealthVault side looks like:
