New PB3 Feature - Related Items

This release provides a new way to manage relationships between instances.

Each data instance now supports a collection of relationships, stored in CommonData.RelatedItems. The items in this collection are of type HealthRecordItemRelationship, which stores the following information:

• A HealthRecordItemKey that contains the ID of the related item, and optionally, the VersionStamp
• An optional string RelationshipType that the application may use to store the type of the relationship

If, for example, I had a procedure object and wanted to add a related annotation, I could write the following:

    Procedure procedure = ... // fetch existing item...

    Annotation annotation = new Annotation();
    annotation.Content = "Annotation text goes here";
    PersonInfo.SelectedRecord.NewItem(annotation);

    HealthRecordItemRelationship relationship = new HealthRecordItemRelationship(annotation.Key);
    procedure.CommonData.RelatedItems.Add(relationship);
    PersonInfo.SelectedRecord.UpdateItem(procedure);

Now, when I fetch the procedure, I can see that there is a related item, and I can go fetch that item to find the annotation.

That establishes the relationship from the procedure to the annotation. If I wanted a back-link as well, I'd have to add a few lines...

    Procedure procedure = ... // fetch existing item...

    Annotation annotation = new Annotation();
    annotation.Content = "Annotation text goes here";
    HealthRecordItemRelationship backRelationship = new HealthRecordItemRelationship(procedure.Key);
annotation.CommonDate.RelatedItems.Add(backRelationship);
    PersonInfo.SelectedRecord.NewItem(annotation);

    HealthRecordItemRelationship relationship = new HealthRecordItemRelationship(annotation.Key);
    procedure.CommonData.RelatedItems.Add(relationship);
    PersonInfo.SelectedRecord.UpdateItem(procedure);

As you may have noticed, to establish links in both directions with two new objects requires that the first object be added, the second object be added with a relationship to the first, and then the first object updated with a relationship to the second. We are considering providing a way to have the platform do this hook-up when the objects are added in the future. This would allow you to call NewItems() with several objects and have the system automatically relate all of them to each other.

The HealthVault platform does not enforce the integrity of related items - you can add references to items that don't exist or have a related item that has been deleted.