More about data type versioning

  • Article

This is a supplement to Eric's blog post on Data Type Versioning in HealthVault. 

The HealthVault platform is capable of converting V2 items into the V1 schema and vice versa.  In order to simplify things for app developers, the platform will convert all versions of a type into versions that it believes this app understands.  It makes this assessment by looking at the base authz that has been configured for the app.  If the app asks the user to authorize V1 then the platform will convert all instances to V1.  Replace "V1" with "V2" or "both versions" in that previous sentence at it remains true. 

Note that what the app asks for in its auth rules may sometimes differ from what the user has granted, especially in the case where you have changed your auth rules from including Type-V1 to Type-V2.  If a user has already authorized Type-V1 and you change your auth rules to use Type-V2 then the platform will recognize that your app now uses Type-V2 and the user will not be prompted to re-authorize.

So if you change your code to deal with V2 instead of V1 but don't change your authorization rules then the platform will continue converting the elements into V1s.  A typecast error will occur when you try to load these V1 instances into a V2 object.

The platform treats different versions of a single type a bit differently than it treats different types.  When you query the platform for instances of a versioned type, the platform's default behavior is to treat this as a request for all versions of the type and to ignore the fact that your request implicitly specified a version.  You can override this behavior by using the TypeVersionFormat property of the View property of your HealthRecordFilter when you search, i.e.

filter.View.TypeVersionFormat.Add(Encounter.TypeId);

If you are searching across multiple types then this TypeVersionFormat collection can contain multiple elements, each of which will only be applied when relevant. 

So if you are moving from an older version to a newer version of one or more data types then you have two options to choose from:

1. Change your authorization rules such that the new versions are requested.  The platform will see this at run-time and will therefore convert instances into the version that you want.

-OR-

2. Add one or more types to your HealthRecordFilter.View.TypeVersionFormat collection.

If you fail to do either of these options then you will get a typecast error at run time.