HealthVault

August Data Type SDK Release (PB6-DT1)

We are happy to announce a new data type release. The SDK can be found in the usual place on the MSDN site.

This release contains the following:

• The source code for the .NET library. Look in the Source directory of the SDK.
  
• An update to the Medication type.
  
• Types to support health assessment questions, answers, and conclusions (HealthAssessment and QuestionAnswer)
  
• A type to store information about body composition.
  
• A type to round out the group membership scenario
  
• Types for pulse oximetry devices (BloodOxygenSaturation and HeartRate)
  
• A type to store CDA documents.

There will be detailed guides for the new data types on the data type blog.

CDA document type

This type provides general-purpose storage for CDA documents. CCD documents (which target a specific scenario) should be stored using the CCD types – all other CDA document types should be stored using this new types. If there are other specializations of CDA that you think the platform should store separately, please contact the HealthVault team.

HealthVault Solutions Conference Videos are available...

After a false start or two, the videos are now online. They show the speaker rather than the slides/demos, which works well for some of the talks but may not be quite as effective for the others.

We hope to provide the content that doensn't work well in this format in some other format.

View your HealthVault account contents with X-Ray

Get Real Consulting has released a very nice utility named X-Ray. I'm happy about this for two reasons.

First, I can cross off the "write a useful type and vocabulary utility" of my list of things to do, where it's been languishing for quite some time (I was going to say that it was languishing near the bottom, but frankly any item near the bottom has gone beyond languishing and is now decomposing).

Second, they've done a much nicer job than I would have done.

It can only look at information on records on the development servers, for reasons that I think will be obvious to most people.

Thanks to Get Real for doing this...

Application Configuration Center Refresh!

We have refreshed the application configuration center. This tool along with Application Manager lets you easily create and self-configure your applications.

Here are some of the changes we made:

• Refreshed the Data type creation and editing interface. The new UI is cleaner and lets you create the data access rules for your application succinctly and add multiple data types to the same rule.
  
• Cleaned and simplified the "methods" tab and added support for applications to automatically be updated with new methods as and when they are added in the corresponding method category by HealthVault platform.
  
• "Submit Go-Live request"  link on home page now tries to validate the application before letting you send an email to start the going to production mode process.
  

We are working on re-wording the MSDN Go-Live page appropriately.

HealthVault Solutions Conference videos now available...

[Update: We are having technical difficulties with videos (okay, I'll fess up. I left them at home, then I dropped them in the mud, then my dog ate them). We hope to have these difficulties fixed soon] 

The technical track videos can now be watched in streaming format.

I'd like to note that the slowness in my demos during the "Developing a HealthVault application" was purely because I forgot to reconfigure my proxy to work correctly outside the Microsoft effort, and do not indicate the speed of HealthVault as a whole.

Drop off / Pick up

Drop off / Pick up is a new platform feature that helps you schedule service appointments for your light truck.

Actually, it’s a way for an application to drop off a document with HealthVault, give a code to a user, and then have that user pick up that document and add it to their HealthVault record.

This is done without any user authentication of the drop off application, so it’s simpler to do than a standard HealthVault application and you can do it from client applications as well.

Sean wrote a post that goes into more detail…

Problems using the XML API...

If you are using the HealthVault API, you may be running into the following issue:

Summary

HealthVault does not properly handle comments or whitespace between XML elements when a request is made to the XML API.  Because of this, partners using the HealthVault XML API directly, instead of the SDK, may encounter errors.  The HealthVault XML API methods do not return consistent or accurate error messages for this problem.  Partners that receive any unexpected errors should ensure there are no comments or whitespace between elements in the XML request.

We are actively working on a fix for this issue and regret any inconvenience.

Workaround

Remove any comments or whitespace between XML elements in requests to the XML API.

Works with Microsoft HealthVault Logo Program for Devices

We’ve just launched a logo program for HealthVault devices.

PB6 Released

The PB6 release of the platform and SDK are now live on the PPE servers. You can download the SDK from the usual place.

The following are the major features for the release.

Fetch size control

By default HealthVault will only return a certain number of "full" health record items for any query. It then returns the "keys" for the remaining items that matched the query which can then be queried for by ID. HealthRecordItemCollection automatically manages this paging for you. However, if you want further control over the count of full items retrieved on each request, MaxFullItemsReturnedPerRequest can be set to optimize for smaller sets of data. For example, let's say the data being retrieved is being displayed in a GridView and the results are shown 10 items per page. Rather than get the default number of full things, you can request 10 full items per request. Then only if the user clicks to the second page would you need to get the next 10 items.

Versioning

PB6 now allows us to version data types.  HealthRecordItem.IsDownVersioned can be used to determine whether an application is able to update a specific data item.

Patient Connect

The Microsoft.Health.Package.ConnectPackage class is used to support the Patient Connect scenario.

Group Membership Type

The GroupMembership type is used by an organization to indicate that the person described in the record is a member of a specific group. Here’s a scenario:

1. An employee goes to an employee portal and registers to take advantage of a fitness benefit which allows them to use an application to track their progress.
2. The employee authorizes the portal to write to their HealthVault record, and the portal writes a group membership entry where name=”SpecialProgram”, value=”FabrikamFitnessProgram”.
3. The employee runs the fitness application, and authorizes is to see GroupMembership instances. The application queries and finds the FabrikamFitnessProgram instance, and verifies that the instance was created by the employee portal.
4. The application allows the user to use the program, and bills the company for the benefit.

Survey - Proposed API change to make related items easier to work with...

If you've been working with related items, you may have found that it's a bit inconvenient to use right now. Specifically:

• To set up a two-way-link between objects, you need to insert one, insert the second with related items, and then update the first one with a related item link.
  
• You have to physically set up the links for every object (ie add a HealthRecordItemRelationship to CommonData.RelatedItems) - there's no helper to do it, and it's hard for us to write one.
  
• You have to fetch each related item separately

We're having some discussions around how to fix the first one, and, if possible, the other two as well. We had originally thought that we would simply modify the platform NewItems() call to have a way to say "link all of these together using related items", but it turns out that there's no simple way to do that, and the complex ways have architectural implications we don't like.

So, we're considering a different scheme. In this scheme, rather than linking together using the platform-generated key (ie CommonData.Key.Id), we would link together using an application-generated client-id instead. So, to link two items together, you would do the following:

1. Create instance of object a
2. Create instance of object b
3. a.CommonData.ClientId = Guid.NewGuid();
4. b.CommonData.RelatedItems.Add(a.CommonData.ClientId);
5. b.CommonData.ClientId = Guid.NewGuid();
6. a.CommonData.RelatedItems.Add(b.CommonData.ClientId);
7. Call NewItems and pass in both instances

We would likely provide a helper function to do #3 - #6, so you could merely write "MakeThingsRelated(a, b)", and the helper would do all the work of generating the client ids and hooking them up.

We would also modify "GetItem" to retrieve an object either using the Key.Id or the Client id, and the code you would write to fetch the related items would be the same as what you currently write.

There are three disadvantages to this approach that we see:

1. The client id isn't invariant, so it's possible for me to set up a related item and then have another app come along and change the client id, breaking the related item. However, apps can already delete the related item or remove an entry from the related item list, so I don't think it's really any different than our current behavior.
   
2. GetItem() currently takes a instance Id, and in the new world it would take either an instance ID or a client ID. That means that it's a little more confusing to developers to figure out what is going on when they look at code.
   
3. HealthRecordItemRelationship now holds two different kinds of information, and you have to know which is which. I think that with a bit of encapsulation, we can make the impact of this to be small.

We could avoid #2 and #3 by adding a new method to fetch an item by clientId (ie GetItemByClientId()). That would make that api clearer, but would have the unfortunate byproduct of requiring a rewrite of all existing code that uses related items to be able to deal with client-related items (it would need to know whether to call GetItem() or GetItemByClientId()...).

We're leaning towards doing the client-id approach, but would like any thoughts you might have.

Conference presentations now available...

The powerpoint presentations from the conference are now available on the HealthVault Developer Center,

As noted on the page, we have some video and audio that we'll make available in the near future. In addition, for the Developing a HealthVault Application, I'm going to convert that to a tutorial and make my source code available as well, but that will take a bit more time.

Wrap up of TechEd 2008 and the HealthVault Solutions Conference 2008.

HealthVault Application Configuration Center

The second tool that is now available is the HealthVault Application Configuration Center. While in the past you would have had to make requests to make modifications to your configurations on the development servers (ie healthvault-ppe.com), you will now be able to make those changes yourself.

The configuration center uses a HealthVault user account to track who you are, so we suggest that you pick one that is appropriate for your development team (it's probably not the one used by a single person).

Once you've chosen the account, there are two ways to get an application visible.

If you already have an application id on the development servers, you can submit a request to have that application associated with your user account. You do this through the submit form, where you can specify the id and name of the application you want to claim. Note that you also need to send an email so it's easier to match you with your application.

If you don't already have your own app id, you can create a new one in the application manager, and then choose "upload" to upload it to the configuration center. In that case, the application will show up immediately.

Once you have an application registered, you can:

• Change the name, action url, logo, description, and data access reason
• Define what methods the application is allowed to call
• Specify what data types your application is allowed to use, for base and optional auth, and for online and offline access
• Enter the "why" string for each data type, explaining to the user how your program uses that data.
• Update your certificate
• Control miscellaneous application settings

Any changes that you make will show up immediately (or, if not immediately, very soon) in the developer environment.

When you reach the point that you want to deploy your application against the consumer servers (ie "go live"), your application configuration in the developer environment can be used as a template. Going live still requires the same level of review as it did before, and if you keep your data type access as minimal as possible, that process will be simpler and easier for all of us.

HealthVault Application Manager

We know that dealing with certificates and application ids has been a source of pain for our partners. I am happy to accounce the release of two new tools that should improve the situation.

The first of these is HealthVault Application Manager, which is installed along with the SDK. It has the following capabilities:

• Lists all the HealthVault certificates on a machine
• Lets you grant access to the appropriate account so IIS can see the cert (so you don't have to use winhttpcertcfg.exe)
• Allows you to associate a more meaningful application name with a certificate (note that this association is only on this machine)
• Exports the certificate either as a .cer (public key) or .pfx (public and private key)
• Deletes the cert
• Imports certificates using an import dialog or using drag/drop (XP only, not on Vista)
• Creates a new certificate with the proper name and other characteristics to work with HealthVault.

Under Vista, you'll need to launch this as an administrator or it won't work right.

There's also an extra-cool feature, named 'upload certificate'. More on that in the next post.

HealthVault SDK Update - new data types, a few API changes...

We've released a new SDK in the usual place (ie find it via the MSDN site). In it, there are the following changes:

New Data Types:

Concern records a concern that a person has - "worried about my weight", or "having trouble sleeping". This differs from condition in that it is about how a person feels about something.

Contraindication is used to store substances (food or drugs) that interact badly with a condition the person has or a drug the person it taking. For example, patients on drug thinners need be careful with leafy green vegetables.

Encounter has been revised to include a reason for the encounter, and location has been changed to facility, with a new backing type (Organization). The previous encounter type is still available but has been renamed to EncounterOld. Data written with the old type is not readable with the new type.

Family History can be captured in FamilyHistoryPerson and FamilyHistoryCondition.  

LabTestResults has been updated considerably.

All of the new data types are in a new dll named Microsoft.Health.ItemTypes.dll, and you will need to add it to your project to use those types.

In other news...

HealthRecordAccessor.GetPeopleForRecord() provides a way for an application to find out which people have access to a specific record. This is allowed only if the current user is a custodian of the record.