HealthVault FAQ

Certificate loading problem or Error loading certificate in IIS 7 and later versions

Madan kamuju — Mon, 21 Feb 2011 12:15:00 GMT

This document describes how to install a HealthVault certificate in the Windows certificate store and running the corresponding HealthVault application in Windows 7 and Windows Server 2008. If the certificate is not installed correctly in the local computer...(read more)

How to share data with a physician

Aneesh D1 — Mon, 14 Feb 2011 22:55:00 GMT

A common scenario we‘ve seen in hospital-based applications is the persistent need for a patient to share medical information with a doctor or group of doctors. In cases like this, both privacy concerns around medical information and requirements for ease of data use will influence the solution used.

Scenario

Consider a situation where a user has uploaded all their data, either through a device or through another application (including the HealthVault Shell), into his or her HealthVault record. The user now wants to consult a physician based on information that they’ve uploaded, and wants to provide all the necessary and relevant data at their consultation.

How can we achieve this using HealthVault?

1. Accessing data by building a HealthVault application

The last section will show you clearly that the Shell was not designed for sharing a patient’s HealthVault record with doctors. How is an application a better method to exchange information? Let’s consider both the online and offline application architectures. The online applications require the user to be present when the physician’s system accesses their HealthVault record. An online application also requires the user to sign in to HealthVault each time the physician system needs fresh access to the data. These two reasons make the online scenario unacceptable for a patient who wants to give their doctor ongoing access. If we consider the offline architecture, both of these requirements are removed. The user can grant the data permissions to the application just once, and then the application can directly handle the data without any user interaction. This makes it easy for the physician to retrieve the data whenever they want once the access is authorized with the application. Thus, the offline architecture is the best option for an application to allow the patient to provide their data in this scenario.

A sample workflow for this scenario looks like this: The hospital has a HealthVault-integrated offline application in which registered patients can log in and allow exchange of health information with HealthVault. The application will also have a login window where physicians can log in to access patient data. After registering at the hospital, the patient will go to the application and log in using the credentials they acquired during registration. The patient then links their HealthVault record to the hospital application through an authorization process. When a physician wants to see data for a particular patient, they log into the application and then choose the particular patient using a unique patient ID. The application will pull the data from the corresponding HealthVault record and render it to the physician. The application can manage which data types are shown to the logged-in physician, the level of access, and how to show the data; for example by plotting it as a graph or just showing the raw data.

Advantages and Disadvantages

The physician’s login and access rights can be created when they join the hospital. The application can be designed to present any forms desired for patient notice or consent. And the physician can easily choose whose data to view in the application. As the application renders the data in the expected way, the physician can better focus on data analysis rather than data formatting.

Now, let’s look at this scenario from the patient’s perspective. A user authorizes access by the application broadly. This is acceptable for most scenarios, but what if the user wants more control over their data? What if they want to share this information with only a specific physician, or they want to share only a specific set of relevant data? These scenarios cannot be addressed in this solution.

As the application is using the offline architecture, both the Person ID and Record ID of the user need to be stored in a secured local database. This adds an additional overhead. In addition, the application must implement a method to let the physician log in to the system and link their own login information to the patient’s information.

2. Accessing filtered data through a HealthVault application

This application flow mimics the one above for most of this scenario. The difference arises when the user logs in to the application. The user will be shown a list of physicians from which they can select the names of those they’d like to share their data with. Users will have been given the physician’s name during the registration process itself, or by contacting the hospital prior to their appointment. Similar scenarios occur for the physician login. Instead of being shown all available patients, the physician’s access can be limited to only those patients who have given them permission to see their data. A sophisticated system can let the user choose a date range and a set of data types to be accessed. Please note that this flow is different only in the way an application uses the data and it is not related to the HealthVault platform in any way. The Privacy and Term of Use statements of the application should specify these conditions appropriately.

Advantages and Disadvantages

Allowing users to choose how their data will be exposed by the application may be the best option in many cases. This puts users at ease when working with the application, as they know that the application only provides access to those they have selected.

Like the second scenario, this method requires the storage of the user’s login information in a database and the implementation of a login mechanism for physicians. Additionally, this method adds extra complexity to the application logic by which the physician’s information is linked to the patient’s information. When the user logs in and chooses doctors they want to access their data, a mapping of the user’s data with the physician’s information should be created by the application. One way to do this is to use another column to store the mapping information in the DB table in which the user’s information is stored. When a doctor chooses a user, the application should first validate this request with the already-created user mapping information. If the request is valid, i.e., the user has given the physician permission to view the patient data, then a dynamic linking of the physician’s information with the user’s data will occur. This adds an additional complexity to the application design.

Now let us compare the above two approaches.

Feature \ Method	Through HealthVault App	HealthVault App with filtering
Security and Privacy Concerns	Addressed by the App	Addressed by the App
Physician need a HealthVault account	No	No
Additional record sharing step is needed	No	No
Data sharing level	Decided by the App	Decided by the App
Easy for Physician to choose the patient	Yes	Yes
Patients can choose Physicians	No	Yes
Need for local database	Yes	Yes

Can we use the Shell Sharing feature?

As shown above, the Shell provides a method for a user to share their record with another person. However, HealthVault accounts are not offered for professional or non-personal use. This is a very good way to let relatives or friends help manage health information, for example a family member who needs to control the health information of a child or aging parent. When sharing the data, the user can specify the access level, which includes read access, the ability to view and modify, and full access as a custodian. Additionally, a user can control which data types will be shared, and whether there is an expiration date on the shared access. The sharing feature does not prevent the user from sending a sharing invitation to anyone they choose, including their doctor. Once the doctor receives the sharing invitation, they would have the ability to accept it, open a personal account, and see the user’s shared data in their own HealthVault account. Though this satisfies the basic data sharing function, it violates HealthVault’s service terms, and this shouldn’t be used as a solution for this scenario. Let us discuss the reasons in the next section.

Problems

Sharing data directly through the HealthVault Shell addresses certain security and privacy concerns for account-holders, as the Shell includes access control features described above.

A deeper look, however, reveals a number of concerns with this method. First, this scenario requires the physician to have a HealthVault account and Live ID of their own and use this account as part of healthcare service. This use case does not fall within HealthVault’s terms of service and is not acceptable for any HealthVault integration. In addition, most healthcare organizations would have other requirements for their information management systems. For example, as a personal service for consumers, Microsoft doesn’t act as a business associate under HIPAA in connection with HealthVault records, and doesn’t include the kind of data management features that a healthcare practice would want to help control its operation.

HealthVault policy regarding HealthVault server IP addresses and partners with IP-based firewalls

Anish Ravindran — Fri, 21 Jan 2011 20:42:22 GMT

There are situations where partners need to know whether they can run their application behind a firewall, which require communicating with HealthVault through their IP based firewalls. We don’t recommend partners to depend on our HealthVault IPs but they don’t have any other way then we can talk that during the HealthVault Go-Live of the application.

ActionURL targets override for Privacy and Terms of Use from HealthVault Application Configuration Center

Anish Ravindran — Fri, 07 Jan 2011 21:58:52 GMT

As mentioned in Chris Tremonte’s blog on ActionUrl, Privacy and Terms of Use, HealthVault Application Configuration Center now supports hardcoded statements for both Privacy and Terms of Use irrespective of the ActionURL specified for the application. The only way previously supported was to show relevant Privacy and Terms of Use to the user is by deriving it from the ActionURL. You can find the appropriate Application Targets in the HealthVault Shell Redirect Interfaces. With the released feature, you can now use HealthVault Application Configuration Center to achieve the same results by specifying the contents for the Privacy Statement and the Terms of Use in the Information Tab.

Figure 1: Information Tab in HealthVault Application Configuration Center

If an ActionURL is not specified for SODA and PatientConnect applications, then both Privacy and Terms of Use statements in the Application Configuration Center must be specified. Suppose you have implemented both ActionURL targets for Privacy/Terms of Use and statements in the Application Configuration Center than the hardcoded statements from the Application Configuration Center will override the derived ActionURL targets.

Table 1: Summary of TOU and Privacy statements use for different types of applications

Note: If the organization is covered under the HIPAA or Clinical Trial, then it is not required for the application to derive the privacy page.

Privacy and Terms of Use statements in the Application Configuration Center are useful for web applications when the ActionURL is behind a firewall. This allows for HealthVault to serve up the Privacy and Terms of Use statements to users directly without requiring an ActionURL to redirect the user to the Privacy or Terms of Use statements. Also note that the Application Configuration Center now accepts only plain text for the Privacy or the Terms of Use statements, which still allows you to use the ActionURL if you are using HTML in either of your statements.

Creating application ID from HeathVault Application Manager in UK environment

Madan kamuju — Mon, 20 Dec 2010 10:27:00 GMT

This Blog Post will help you in creating Application ID from HeathVault Application Manager in UK environment, as partners from UK cannot create Application ID using HeathVault Application Manager unless they modify ApplicationManager.exe.config file...(read more)

Users are unable to create support cases - Fixed

Anish Ravindran — Wed, 15 Dec 2010 01:14:00 GMT

We are currently experiencing a technical issue that is blocking people from submitting a new support requesting using the HealthVault Developer Support offering. Until further notice please utilize the MSDN Forums. We will let everyone know when this issue is resolved. Thank you.

All systems are back up and running.

Mobile phone application development in HealthVault

Aneesh D1 — Tue, 23 Nov 2010 19:20:00 GMT

Considering the wide acceptance, ease of use and large user base, mobile application development is getting more and more popular. As the device always stays close to the user, HealthVault integrated applications on mobile platforms make sense in a variety of scenarios. In this discussion we will consider the different possible architectures that a mobile application can utilize for HealthVault integration.

Below are the main areas that we will have to focus when dealing with a mobile phone application in HealthVault space.

1. Authentication

2. HealthVault API interaction

3. Discovering the application

Let the Mobile App talk to Web Service

Architecture

We have some of our partners like SCP, Withings etc. following this architecture.

The application will have its own server which exposes a set of web service APIs to let the mobile application communicate with HealthVault. Thus the mobile application will not have any direct communication with the HealthVault platform, since the server does that on behalf of the application. The server communicates with HealthVault by creating an application connection object. For this architecture you will have to use the Offline connection for all HealthVault interactions.

This is the recommended architecture for mobile phone applications in HealthVault. We are consistently exploring ways to improve the mobile phone application development easier, so please feel free to give us your feedback. Let us look into a typical scenario which implements this architecture.

1. Authentication

In this scenario the application certificate will be installed in the server which is hosting the Web Service. So no distribution of certificate is needed. But how will the user authorization and authentication happens here? Yes this is one big concern. There are many ways the user authentication can happen. Among them the easiest way is to have a web page hosted for the application through which users can do the authorization. Let us call it registration process.

The user goes to the above page and login (with his HealthVault account for Online + Offline applications or through the PatientConnect way). Here the application should have enough Offline permissions set because after the registration all the HealthVault data upload and retrieval will happen through Offline Connection. Once the authorization is done the site will store the Person ID and the Record ID in a data store accessible to the Web Service. Then the site will give the user a confirmation ID which will be used to find out the corresponding Person ID and Record ID from the data store in future.

While the user is using the application for the first time user will be prompted to enter the confirmation ID, along with the right help if the user doesn’t have a confirmation ID yet. This confirmation ID will be stored in the mobile device’s persistent storage to avoid the user entering it again.

2. HealthVault API interaction

All the HealthVault API interactions happen here from the Web Service and none from the mobile application. For any data that the mobile application needs to deal with will be passed to or read from the Web Service using the APIs exposed by the Web Service. Here the Web Service will have to expose some wrapper classes for the HealthVault data types and some interfaces for the mobile application.

With each request send from the mobile application the encrypted confirmation ID will have to be passed to the Web Service. Web Service will use this confirmation ID to look up the Person ID and the Record ID and create an OfflineWebApplicationConnection using it.

3. Discovering the application

Yes, the application is built to be discovered! Once the Go-Live process is completed for the application we will help you to get the application listed in our Application Directory. Another good place to showcase the application will be to have them listed in the corresponding mobile application stores. We will be happy to help you in case if you have any concerns on this.

4. Analysis

Scenario

Advantage

Disadvantage

Authentication

As all the HealthVault authorization and authentication process is done outside the mobile application and the whole HealthVault interaction code is inside the web services the mobile application will be lighter than any other architecture. Mobile application developer can concentrate more on the business logic.

As the authentication cannot be done directly in the mobile application this requires an additional step and user facing site (mostly a registration site) where users will be registering to use the application. As the architecture requires an Offline access scenario the Record ID and the Person ID will be retrieved in this step and then stored on the server for later use.

The retrieved Record ID and Person IDs will have to be stored and maintained in a secure location.

Deployment

Deployment of the application becomes easy as the application does not have to be concerned about the platform changes to HealthVault.

The communication between the server and the mobile application requires a secure way for data transfer as the data being transferred is sensitive, adding to the maintenance and the longer execution time.

Certificate Handling

In this architecture there is no need for distributing or maintaining the certificate with the application since it will be always kept inside the server.

This architecture adds additional overhead for maintaining the web services in the server.

SDK support

The HealthVault interaction code, as it is developed outside the mobile platform, can utilize the existing HealthVault SDKs (.Net SDK, Java SDK, PHP SDK or Ruby SDK). Additionally the mobile application can use any program language that is allowed on the mobile device.

As the application does not directly communicate with the HealthVault platform each of the HealthVault interactions takes more time than is necessary.

Let’s try the Rich Client (SODA) architecture

Architecture

Software on Device Authentication (SODA) architecture is the relatively new architecture for HealthVault which helps you to develop rich client applications on any platform or any application architecture (Console application, Form application, etc.).

This architecture was developed to support rich client application running on Windows platforms to talk directly to HealthVault. A good example of the same is HealthVault Connection Center. Interesting parts of this approach could be used in mobile context.

In this architecture the application will also directly communicate with the HealthVault platform without requiring any extra web services. SODA allows each instance of the application to have its own application certificate, allowing each instance to be sandboxed from all other instances. This significantly lessens the risk if an application certificate becomes compromised.

In the application, a GUID will be used to identify the application instance thus differentiating it from any other existing installations of the application. The HealthVault .Net SDK's SODA APIs that are used to create the Child application automatically create a new public and private key and add it to the current user’s certificate store without requiring the user to understand this process. The user can then authorize the Child application to communicate with the platform using an Offline connection. In this MSDN post the complete steps of creating a SODA application using the HealthVault .Net SDK is listed.

1. Authentication

From an end user perspective the authorization process will look the same as any other HealthVault application. The only difference will be, as the application lacks an Action URL the user will not be directly taken back to the application after the authorization. Application will have to implement some polling mechanism or track the URLs to see whether the record authorization is done.

2. HealthVault API interaction

SODA clients use OfflineWebApplicationConnection to communicate with HealthVault. The interaction happens directly from the mobile device using the certificate created by the application itself.

3. Discovering the application

The story of application discoverability goes the same for this also. The HealthVault Application Directory and the mobile application stores will be the best place to showcase the application.

4. Analysis

Scenario

Advantage

Disadvantage

Authentication

Authorization steps are done on the mobile device itself so that user does not have to leave the application for it.

During authorization the user will be directly taken to the HealthVault authorization page which is not highly friendly for a mobile device, especially those which doesn’t have a zoom option, so you will have to make sure that this is in line with your user interface requirements. This is definitely an area where we are looking to improve ourselves soon.
The HealthVault application authorization workflow in the HealthVault shell provides a redirect interface that can send the user to a web app after authorization, but getting this to work cleanly for a thick client app requires a few tricks. Look at a blog post entitled “Rich Client Options” in the HealthVault FAQ blog for more information. The current address of this post is: http://blogs.msdn.com/b/healthvaultfaq/archive/2010/02/24/rich-client-options.

Deployment

As each client application or application instance will have its own unique client ID each application instance is treated as a separate application by the platform.
Directly communicating with the HealthVault platform improves the response time and stability of the application.

This approach may have technical difficulties on most of the mobile platforms and some intermediate web services might be needed to make this work.

Certificate Handling

This avoids the requirement of distributing the certificates as the application will create the certificate and store in the local certificate store.

Mobile device should have the support for the certificate handling

SDK support

No mobile HealthVault SDK is available so far.

Running a HealthVault Application in IIS without installing a certificate in the certificate store

Anish Ravindran — Wed, 10 Nov 2010 19:03:00 GMT

Starting with the HealthVault 0908 SDK release, HealthVault applications can run with an application’s certificate stored in a file store instead of in a certificate store by setting the ApplicationCertificateFileName key and its value in the web.config file. We often noticed that the developers facing issues in Windows Server 2008 R2 and Windows 7 machines while hosting HealthVault applications in IIS 7.5 and getting errors like ‘Error loading certificate. Is password specified using ApplicationCertificatePassword?’

This issue is caused by the IIS Worker Process which runs under a Windows Identity account that doesn’t have enough Code Access Security to call the security APIs. This is due to the DefaultAppPool setting that is used in IIS 7.5, which is the default, running under the ‘ApplicationPoolIdentity’ account. Switching this account to the 'NetworkService' account allows you to run the HealthVault application in IIS without installing the certificate in certificate store. You can find detailed steps on how to switch a Windows Identity account here, http://learn.iis.net/page.aspx/624/application-pool-identities/.

We highly recommend using the certificate store because keeping the private key of an application intact and private is very important due to security reasons. If your configuration doesn't allow using a certificate store and you must use the file based certificate store then please ensure that a password is set for the certificate and keep it in a non-web accessible directory.

Meet the Upgraded HealthVault Developer Center

Lowell Meyer — Mon, 24 May 2010 22:52:02 GMT

We are happy to announce the make-over of HealthVault Developer Center. The HealthVault Developer Center is an online site meant to complement the MSDN HealthVault Developer Center, Application Configuration Center and GetReal developed X-Ray for HealthVault tool. This site itself is a HealthVault application, and contains useful online tools to view raw user data, add editable sample data to a record and view methods & data-types schema documentation.

Fig 1. HealthVault Developer Center

In this upgrade of HealthVault Developer Center in addition to new look and feel, we have added following features -

Ability to add samples for data types

Developers can now add sample data to their development account directly through HealthVault DataType explorer.

Fig 2. Ability to add samples for HealthVault data types

Ability to edit samples

We adding controls to edit the existing sample data. Most of these controls are auto-generated and the individual fields are also hooked up to auto-complete if the schema recommends a preferred vocabulary for the field.

Fig 3. Show-casing Allergy Episode Sample

Fig 4. Control enabling editing of Allergy Episode Sample.

Rich and Brows-able documentation for each data-type

We have added rich brows-able documentation for each data-type.

Fig 5. Brows-able documentation for Medication Type

Each type now shows the version associated with it

Fig 6. Type Versions for Medication Type in HealthVault DataType Explorer.

Ability to look at the content of GetServiceDefinition

Developers can now directly read the HealthVault Service Definition through the Methods Browser.

Tell us what you think..

Please feel free to comment on features you would like or report on bugs in this tool. We are planning to do a bug-fix update shortly.

Accessing your application configuration

Chris Tremonte — Tue, 09 Mar 2010 18:03:35 GMT

The HealthVault Application Configuration Center is available at https://config.healthvault-ppe.com. You login to this tool with a HealthVault-PPE account and it will show you a list of ApplicationIds for which you have admin rights. Generally you will see zero or one ApplicationIds in this list. Here is the home screen that I see with one of my Microsoft accounts:

There are three ways for an application to get onto your list:

Create AppId in Application Manager client: when Application Manager uploads your ApplicationId information to the HealthVault-PPE platform, you will be prompted to login to the Application Configuration Center. The account with which you login will become the admin account for this AppId.
Create AppId in Application Configuration Center: there is a “Create a new application” link in the screenshot above. If you use that link to create an AppId then the currently-logged-in account will be the admin for that AppId.
Submit a request: if you don’t remember which account is your admin account, if you lost credentials to an admin account or if your ApplicationId was created before the existence of the Application Configuration Center then you can “reclaim” admin rights to your AppId by clicking the “submit a request” link on this page. You will see the dialog box below. Enter the AppId that you want to reclaim and the email address where you would like to receive the reclaim invitation. A Microsoft person will review your request and verify that it is coming from a company that is associated with the application, then they will send the invitation mail to the specified email address.

Rich client options

Chris Tremonte — Wed, 24 Feb 2010 22:52:00 GMT

Most of our HealthVault documentation on samples focuses on building web applications but you can also use HealthVault with your rich client application. We support two high-level approaches to doing this:

Intermediate web app

With this approach, your rich client application communicates with a web service that you develop. That web service, in turn, communicates with HealthVault. You install a private certificate on your web server and this server performs app authentication with the HealthVault service like any other web app.

The application authorization process can happen via a page that you host or via HealthVault PatientConnect. Either way, make sure to request Offline Access in your application configuration.

Software on Device Authentication

Software on Device Authentication (or SODA) is a new option that we added in our 0908 release in September 2009. With SODA the end user authorizes a device (or client) to communicate directly with HealthVault. A private certificate gets installed on the user’s PC or phone or other device, and then that device can perform the application authentication step with HealthVault. The device can then use Offline connections to communicate with HealthVault. Note that SODA applications will not have a user token and therefore cannot use OnlineConnections.

Each installed instance of a SODA application will have its own unique ApplicationId. This ApplicationId is used by the application instance for all future offline sessions.

The application authorization process includes a few steps that are unique to SODA applications. Your rich client application must redirect into the HealthVault Shell so that end users can authorize access, but the Shell generally can’t redirect back to your rich client application using ActionUrl because client applications don’t generally host a web component. This means that you have a few options for getting the user back into your application after application authorization:

The simplest approach is to display instructions within your client application that include telling the user to manually return to the application after app authorization is done. The last screen that the user will see in the Shell looks like this:
Build a protocol handler for your client app and register this as your ActionUrl. HealthVault Connection Center uses this approach so that the Shell can redirect to HVCC after App Auth.
After you redirect to the Shell for app auth, have your application poll the HealthVault service until it sees that app authorization has been completed. At this point your client app can move on to its post-authorization setup steps.
If you already have a web presence, build a web app which hosts an ActionUrl that gives specific/custom instructions and guidance to your SODA end users. You can then also customize the other ActionUrl targets described here.

If you do not specify an ActionUrl for your SODA app (which we expect to be the mainline case) then you can upload your Terms of Use and Privacy Statement to the HealthVault platform and the HealthVault shell will be able to display these to end users during the application authorization process. Note that the HealthVualt shell only uses these statements if the ActionUrl is null/empty. See this post for more details – we expect to change/improve this behavior by mid-2010.

SODA leverages the HealthVault Master-Child application feature, so each instance of a particular SODA application is a child application of a master AppId which you (the developer) control. In the case of a security issue, Microsoft is able to shut off an entire family of SODA applications with one flip of a switch.

We published a guide to creating your own SODA application here on MSDN.

ActionUrl, Privacy and Terms of Use

Chris Tremonte — Fri, 19 Feb 2010 21:47:59 GMT

As many of you know, the HealthVault platform asks each application to register a single ActionUrl that understands a variety of redirect targets. These redirects are generally used in scenarios where the application first redirects to the HealthVault Shell in order to accomplish some platformy task like App AuthZ or Record Picker and then the Shell wants to redirect back into the application once this task has been completed by the user. We require that this URL is specified in advance rather than at run-time for security reasons – the HealthVault Shell will only redirect to URLs that have been reviewed by our HealthVault Go-Live Team.

Some HealthVault applications do not have a web server upon which to host there ActionUrl. For example,

PatientConnect applications tend not to have any UI of their own
SODA applications run on fat clients, not on the web

But the HealthVault Application Authorization process for these (and all) types of applications must include a way for the user to read the relevant Privacy Statement and Terms of Use before authorizing data sharing. This is part of Microsoft’s Privacy Promise to our end users. So for these types of applications, we allow the developer to load the entire body of each legal statement into their HealthVault Application Configuration and then the HealthVault platform can display this statement directly to the user when needed.

Our Application Configuration Center does not currently make this part clear, but the platform only uses these hardcoded statements if no ActionUrl is specified in the application configuration. If a non-empty ActionUrl is in the config then the HealthVault platform will ignore the statement fields.

Note that we plan to change this behavior in our 1003 release, currently scheduled for March 2010. After 1003 the platform will use the hardcoded statement in situations where both a statement and an ActionUrl are available.

We apologize for any confusion that this state of affairs is causing. If you have questions on this topic, please ask on our Developer Forum or use the Comments below.

EDIT: You can learn more about the HealthVault Shell Redirect Interfaces in this article on MSDN.

Absolute URLs for NonProductionActionUrlRedirectOverride

Chris Tremonte — Wed, 17 Feb 2010 22:48:51 GMT

Our sample HealthVault applications in our HealthVault SDK all use relative paths for their NonProductionActionUrlRedirectOverride, but we have added support for absolute paths as well. The “redirect” parameter in web.config now supports either a relative path or an absolute path.

Just like with relative URLs, this is only supported in non-Production environments.

Creating your own ApplicationId and certificates

Chris Tremonte — Thu, 11 Feb 2010 23:01:00 GMT

The Microsoft HealthVault SDK comes with a few sample applications and ApplicationIds which you can use in order to explore the platform and even to get started on your own application. But at some point in your application development process, you will want to customize your ApplicationName and Logo. You may also want to use additional data types or methods that the sample ApplicationIds cannot use.

The application configuration for these sample ApplicationIds is controlled by Microsoft and we want to keep these configurations in a known-good state for other developers, so you cannot modify these configurations. Luckily it is easy to create your own ApplicationId that you can then configure as you see fit. There are two options for how to do this:

Easiest way: If you have access to a computer running Microsoft Windows then you can use the HealthVault Application Manager client.

Start the Application Manager, which comes with the HealthVault SDK (it will be located in the install location “Microsoft HealthVault\SDK\Tools”).
Click on the Create New Application button to create the new application.
In the latest SDK it will give you a check-box to create a new Visual Studio website. Uncheck this option if you already have a project.
Click on the button “Create and Register Application”. This will create your application ID, register it in the Application Configuration Center and bring up the Application Configuration Center UI. You will need to log in with your LiveId/HealthVault account. The account with which you login now will be given administrator rights for this ApplicationId. There is a request form in the Application Configuration Center that you can use to invite other administrators.
Once you are in configuration center, you can define the Online and Offline rules that are needed. Please choose only those data types and permissions that are needed for the application.
Once the configuration is done, right click on the application ID in Application Manager and select Copy Application ID to Clipboard.
Then paste the ID in the appSettings section in the Web.config file. Test your application to make sure it works as expected.

Harder way: you can also create your certificate using a client application such as MakeCert.exe on Windows systems, and then upload it to Application Configuration Center yourself. The process to create and install your certificate pair is outlined in detail in this article. To actually create the ApplicationId in the HealthVault-PPE environment, look for the create a new application link within the Application Configuration Center.

Managing Ownership of and Access to Your HealthVault Application Config

Lowell Meyer — Tue, 26 Jan 2010 22:34:39 GMT

Have you ever needed or wanted to access or modify your application configuration, but couldn’t… because the developer who has the account to log in to the Application Configuration Center is out sick, not speaking with you, or is taking a permanent vacation to Bermuda? Even if the answer is no, would you like to make sure this doesn’t happen to you in the future? The correct answer is yes, and I’ll explain how to ensure this doesn’t happen to you below.

There are two main things I’d like to quickly cover. The first is to draw everyone’s attention to a new feature we’ve released in the HealthVault Application Configuration Center, the new “Admins” tab; the “Admins” tab allows you to add additional “Application Managers” who can then share access to your application configuration. The second is to remind everyone that HealthVault accounts can actually have multiple IDs associated with them… so even if you only have one account set up to manage your HealthVault Application Configuration, you can have multiple Live IDs for different team members set up to access that single account.

Beyond either of those things, we do recommend that businesses creating HealthVault applications set up IDs (Live ID or OpenID) that aren’t associated with specific individuals for use in managing their applications. Many times individual accounts are used, and this can create problems when people leave organizations.

Let’s work backwards. Previously, you could only have one account set up to manage a particular application configuration. This could be problematic at times, as developers might forget the access credentials, or the developer whose credentials were used may leave the company without transferring access first. There has actually been a way around that, and while you can now add multiple accounts (see below), even with just a single account you can set it up to use multiple Live IDs.

To do this:

Log on to HealthVault.com using the ID associated with the application in the Application Configuration Center.
Click on the account name in the top right corner of the page (it should say “Welcome, <FIRSTNAME LASTNAME>”)
On the following page, you should see an option to “add another Live ID or OpenID”. Click that.
You’ll then be walked through a process to add or remove IDs associated with the HealthVault Account.

All that being said… our new feature makes this process less of a necessary step. You can now add more than one HealthVault account as an “application manager” for a particular application’s configuration. To do this, just log in to the Application Configuration Center, select the application you want to add or remove app managers for, and then click on the Admins tab in the upper right. It’s pretty self-explanatory once you get to that point, just put in the email address and name of anyone you want to add, or you can resend invites or remove managers directly.

Setting these things up properly now will save you time and trouble later when you need to access your application configuration, but the developer with the account is out sick, or otherwise unavailable.

Running HealthVault .NET SDK (1.1.2193.4712) on XP SP2

VaibhavB [MSFT] — Tue, 26 Jan 2010 01:56:36 GMT

We have hardened the security protocols used in our .NET SDK (>= 1.1.2193.4712) to use SHA2 instead of SHA1. If you are running HealthVault 0910 or 1001 SDK (DLL Version 1.1.2193.4712) on an Windows XP SP2 (which doesn’t support FIPS compliant SHA2 natively), please add the following settings in web.config of your application to get the SDK to work for you. In future versions of SDK we will default to appropriate alternatives if the OS doesn’t support them.

Web.Config :

<appSettings>
 <add key="HashAlgorithmName" value="SHA1" />
 <add key="HmacAlgorithmName" value="HMACSHA1" />
</appSettings>

UPDATE: Changed the last line to reflect use of appropriate SHA2 alternatives if OS support is not available.

Authorizing Additional Records or Switching the Active Record

Lowell Meyer — Thu, 07 Jan 2010 01:03:00 GMT

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 4^th record but instead left the default/1^st 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:

https://account.healthvault-ppe.com/redirect.aspx?target=AUTH&targetqs=appid%3D82d47a5a-d435-4246-895a-746c475090d3%26forceappauth%3Dtrue

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 (http://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:

Microsoft.Health.HealthServiceException: The thing type specified in the update, 'bf516a61-5252-4c28-a979-27f45f62f78d', is an older version than the type of the existing instance.

Chris Tremonte — Mon, 21 Dec 2009 23:54:11 GMT

You will see the error above if you try to update an instance of the BasicDemographicInformation HealthRecordItem type that is stored in the v2 type schema from an application that “speaks” the v1 type schema.

In our recent 0910 release we updated the Basic Demographic Information HealthRecordItem type to use Codable Values for State/Province and Country. This helps make the data more consistent across applications, but it means that we had to version the data type.

Eric Gunnerson’s blog post describes how data type versioning is handled within the HealthVault platform and my blog post three months ago elaborates a bit on this topic. But the recent revision of Basic Demographic Info gives me a chance to expand a bit more, discuss some corner cases and give some examples.

Data Type Details

You can see the type details in our HealthRecordItem Type Schema Browser:

bf516a61-5252-4c28-a979-27f45f62f78d is the older version of BasicDemographicInfo.
3b3e6b16-eb69-483c-8d7e-dfe116ae6092 is the newer version of BasicDemographicInfo.

You can also see the type details in our MSDN Library, which always documents our most recent SDK version (as of right now, version 1.1.2193.4712).

Microsoft.Health.ItemTypes.BasicV2 – this is the new type
Microsoft.Health.ItemTypes.Basic – this is the old type
For types that got revised before 0908, we moved the old schemas to the Microsoft.Health.ItemTypes.Old namespace. But in order to ensure binary compatibilty between SDK releases moving forward, we have switched are naming approach as described above. From now on, old versions of data types will retain their current name and namespace and the new type version will be “burdened” with the new name.

How this impacts you

If you have a HealthVault application which is already live and you interact with Basic Demographic Information then you are almost certainly using the older version of the schema. Per the descriptions in Eric’s and my blog posts, if you ask the HealthVault platform for Basic Demographic Information then it will return all of the instances of both v1 and v2 of the data type. Any v2 instances will be downconverted into v1 of the schema. These downconverted instances will be read-only to your application. If you try to update any of these downconverted instances then you will see the error message above.

The HealthVault Shell has been updated to use the new version of Basic, 3b3e6b16-eb69-483c-8d7e-dfe116ae6092. This means that any new account will have its Basic Demographic Information stored in the new schema. It also means that any user who updates their Basic Demographic Info in the Shell will get moved to the new schema.

You have two options in order to avoid this error, and both require a code change:

Stay on the 1.0.2145.4504 and don’t update BasicV2 instances. You can accomplish this by capturing this exception and letting the user know that an update of this item was not possible, but I’d rather not wait until the user tries to save changes. Instead, look at the IsDownversioned property on each instance of basic and tell the user when an instance is read-only using your own UI cues. You should also give the user a workaround for updating this information, such as using the HealthVault Shell.
Move to the 1.1.2193.4712 SDK

Moving Forward

We don’t update data types all that often, and few of our data types are singletons so it is unlikely that you’ll see this issue again in the near future. But you can “future-proof” your application by looking for the IsDownversioned flag on each HealthRecordItem instance before you allow the user to attempt an update.

We are considering some revisions to our approach to data type versioning that may simplify this process for developers. Keep an eye on the HealthVault Developer Blog for announcements about updates to the HealthVault platform.

IP Filtering Config

Chris Tremonte — Tue, 15 Dec 2009 01:07:00 GMT

You may notice that the newest version of the Application Configuration Center contains fields for configuring your IP Filtering settings. This extra security measure is not generally needed for HealthVault applications, except in special cases. If you enter a non-null address range in this field then you will effectively turn on filtering for your application in HealthVault-PPE. If you do this accidentally then you can turn IP filtering off again by clearing out this field.

If you have an application which is live in the production HealthVault environment and are using IP Filtering there, you still need to go through the Microsoft team in order to update your Production settings as the settings in the config tool are for PPE. You can contact Microsoft for these types of updates via the hsg-pn@microsoft.com email alias. Expect the update to take a few business days.

Updating an application configuration in Production

Chris Tremonte — Mon, 09 Nov 2009 22:36:00 GMT

You can create and update your ApplicationId configuration in our Developer/PreProduction environment by accessing https://config.healthvault-ppe.com. The App Manager tool in our HealthVault SDK also connects to this config site.

But this configuration site is only available in non-Production environments. Microsoft reviews the data access for each application before it goes live, in an effort to ensure that the data set is reasonable for the implied intent of the application. Therefore any updates to a Production configuration can only be performed by the Microsoft team. You must make the config changes in PPE first and then test/verify that they work with your app. Then you submit an email request to HvGoLive@microsoft.com so that we can review the changes and then push the changes for you.

If you are making major changes to your configuration and want the config updates to coincide with the deployment of new code, we are generally able to schedule the push of a config update to coincide with your deployment. We ask that you give us a few business days' notice for such a push, or a bit longer if the push will be outside of west-coast US business hours.

Handling HealthServiceCredentialTokenExpiredException in .NET SDK

VaibhavB [MSFT] — Fri, 06 Nov 2009 20:15:02 GMT

Applications are expected to Handle the HealthServiceCredentialTokenExpiredException. The best way to handle this error is to Redirect the user to sign-on again, the best place to implement it in your basepage’s page error handler. Here is some sample code which accomplishes the same, please note this code should be in our basepage or any page deriving from HealthServicePage :

/// <summary>
/// This error block handles the case of an expired user token. User
/// tokens expire after 24 hours or time set by persistent tokens
/// for the "keep me sign-in" feature. These tokens and are stored in the cookie,
/// which has no default timeout. Developers are encouraged to expire cookies 
/// sooner, but this code handles the case where the cookie does not
/// expire and the browser window is left open for over 24 hours.
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
protected void Page_Error(object sender, EventArgs e)
{
    Exception ex = Server.GetLastError();

    if (ex is HealthServiceCredentialTokenExpiredException)
    {
        WebApplicationUtilities.RedirectToLogOn(HttpContext.Current);
    }

    ShowError(ex);
}

Your page will need to implement ShowError method or you comment it and re-throw the un-caught exceptions.

More About Certificate Errors

Chris Tremonte — Thu, 05 Nov 2009 21:18:00 GMT

Here is some help on diagnosing some of the common modes of failure with HealthVault certificate management.

Access denied

The most common cause of this error is that the application can find the certificate but the account running the app does not have the proper permissions to utilize its private key at run-time. See the end of this article for more information on giving permissions manully, or use the App Manager tool in the SDK.

This error can also be triggered by attempting a read/write which the user has not authorized, or a number of other authorization-related errors. You may need to look at the stack trace in order to figure out where your error lies. But if you have never successfully connected to HealthVault from Machine X with AppId Y, the certificate is the best place to start.

Keyset does not exist

I have seen this in two different scenarios:

Application certificate is in the cert store, but that certificate only contains a public key. So the app finds the cert but can't find the keyset that it wants.
Application certificate is in the file system but the application's service account doesn't have permission on this folder or file. Having not run this scenario myself, I would have expected this to be another "access denied" but I learned today that it gives a "keyset does not exist" error.

Certificate Errors

Chris Tremonte — Fri, 23 Oct 2009 00:15:00 GMT

Got a good question today from a long-time HealthVault Developer -- at least they are long-time in terms of the short history of HealthVault.

If your application certificate is not configured correctly, either on your app server or on the HealthVault server, the first time that you will see an error is the first time that your application tries to read or write data to/from the HealthVault platform. This means that your end users (or more likely your test accounts) can successfully go through Application Authorization before they will see this error.

The fact that you get through App AuthZ without seeing any errors may lead you to believe that your certificate must be correct, but that is not the case. If you see an "Access Denies" error the first time that you try to load a page containing health information, then the most likely cause of your issue is an improperly configured application certificate.

See the post linked above for more information on certificate management.

HealthVault Response Paging

Chris Tremonte — Mon, 19 Oct 2009 22:56:00 GMT

There is a parameter on the HealthRecordFilter object called MaxFullItemsReturnedPerRequest and it is set to 240 by default. If your search returns more than MaxFullItemsReturnedPerRequest items then you will get full items for the first max items and then HealthRecordItemIds for the remaining items. You can then retrieve the other items by ID.

If you are using the .NET HealthVault SDK then all of this logic is handled for you. The HealthRecordItemCollection returned by GetMatchingItems will appear to contain all of the items. Attempts to work with the guts of an item that is still on the server will trigger the retrieval of that information.

(update on 10/21/2009: the default for MaxFullItemsReturnedPerRequest is 240. I originally said 30 and that is incorrect.)

Certificate Management

Chris Tremonte — Mon, 19 Oct 2009 22:07:00 GMT

We get a lot of questions about managing your HealthVault application certificate. When your application initiates a connection to HealthVault, it uses its unique private key to encrypt the first handshake message that it sends. HealthVault then uses a public key to verify that the sender of this message is indeed a trusted host. This public key must be registered with HealthVault before such connections can be made.

Generating your key pair and installing your private key

You can generate your key pair in one of two ways:

Use the MakeCert.exe tool which ships with the HealthVault SDK and is available on MSDN. This doc on MSDN has more information on using MakeCert.
Use the Application Manager tool which ships with the HealthVault SDK. Application Manager makes it easy to create a new AppId and certificate pair at the same time. Application Manager does not handle the scenario of creating a new certificate pair for an existing application.

Once you have generated your key pair, you can install it for use by your application in one of three ways:

Cert store, default name. Application Manager gives your certificate the default name, "WildcatApp-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx," and places it in the default location. The HealthVault instructions on using MakeCert also give the cert the default name and place it in the default location.
Cert store, non-default name. To specify your certificate name, specify the full subject name of the cert (CN=) in the <appSettings> section of your web.config file as follows:

</appSettings>

File system. If you choose to take this approach then make sure that the following two things are true:

The IIS worker process has access to read the file
The file is not stored in a location where it is visible on your web site. Don't put it inside your web application path but in a secure file path not visible in IIS.
To store your certificate on the local file system, you must add an additional entry in your web.config to tell the HealthVault SDK code where to look for the certificate, as follows. (This is also added to the <appSettings> section.)

Note: the file path is an absolute local file path; relative path names are not allowed
If you configured your private key to require a password for use, then you can/must specify this password in your web.config by using the ApplicationCertificatePassword parameter

Registering your Public Key

In PPE, you can register your public key in one of two ways:

Use the Application Manager tool in the .NET HealthVault SDK to upload a new ApplicationId and its certificate. Note that this workflow is only for creating new applications. You cannot add a new certificate to an existing application this way.
Login to the Application Configuration Center at https://config.healthvault-ppe.com and click on the "Public Certs" tab. You can upload additional CER files here.

Note that each application in the HealthVault-PPE environment has exactly one HealthVault-PPE account that has been set up with config access. If you need to set up a new account with config access, you can request this access via a link on the App Config Center home page.

In Production, the only way to register your public key is to go through the HealthVault Go-Live process. If your application is already live and you need to update or replace its public key, you can file a request with HealthVault Developer Support here.

Scenario	Advantage	Disadvantage
Authentication	As all the HealthVault authorization and authentication process is done outside the mobile application and the whole HealthVault interaction code is inside the web services the mobile application will be lighter than any other architecture. Mobile application developer can concentrate more on the business logic.	As the authentication cannot be done directly in the mobile application this requires an additional step and user facing site (mostly a registration site) where users will be registering to use the application. As the architecture requires an Offline access scenario the Record ID and the Person ID will be retrieved in this step and then stored on the server for later use. The retrieved Record ID and Person IDs will have to be stored and maintained in a secure location.
Deployment	Deployment of the application becomes easy as the application does not have to be concerned about the platform changes to HealthVault.	The communication between the server and the mobile application requires a secure way for data transfer as the data being transferred is sensitive, adding to the maintenance and the longer execution time.
Certificate Handling	In this architecture there is no need for distributing or maintaining the certificate with the application since it will be always kept inside the server.	This architecture adds additional overhead for maintaining the web services in the server.
SDK support	The HealthVault interaction code, as it is developed outside the mobile platform, can utilize the existing HealthVault SDKs (.Net SDK, Java SDK, PHP SDK or Ruby SDK). Additionally the mobile application can use any program language that is allowed on the mobile device.	As the application does not directly communicate with the HealthVault platform each of the HealthVault interactions takes more time than is necessary.