The HealthVault data model allows applications to create data that is read-only. Read-only things cannot be edited by users or applications. Data can be deleted, provided the user or application has the necessary permissions. Read-only data is appropriate for use by any application adding data to a HealthVault record that should never be edited, for example, clinical applications that store clinical test results and measurements.
This article provides an overview of the HealthVault read-only data feature and the APIs used to store and interact with read-only data. This article assumes the reader is familiar with the basics of querying and writing data to HealthVault.
Read-only vs. immutable data types
HealthVault has long supported immutable data types like CCDs and CCRs. Read-only data is different because it can be applied to instances of any data type.
Creating read-only data
Creating data in HealthVault is done via a PutThings request. To specify that an item should be read-only, set the read-only flag. A flag is a numeric value on a thing that describes its attributes. The read-only flag has a decimal value of 16. For more information about flags, see the Flags section of the thing type schema.
A thing can be marked read-only when it is created in HealthVault for the first time. An existing item that is not read-only cannot be updated to be read-only. Attempting to do this will result in a CannotSetReadOnlyFlag (161) error. For more information about error codes, see Status Codes.
Updating read-only data
Once an item has been stored in HealthVault as read-only, it cannot be updated and the read-only restriction cannot be removed. The read-only restriction applies to the data-xml element, which holds the type specific structured information, and the blobs element, which holds the type specific unstructured information. Some fields outside of these sections can be updated for read-only things. These are:
The updated-end-date field
Attempts to update any other fields on a read-only thing will result in one of the following errors. For more information about error codes, see Status Codes.
It is not possible to update a thing instance that has been specified as read-only.
It is not possible to remove the read-only restriction from a thing instance.
Deleting read-only data
Any application or user with delete permissions can delete read-only items. Deleting data can be done via a RemoveThings request.
Querying read-only data
Querying data from HealthVault is done via a GetThings request. To query for the read-only status of an item, your request must include the Core or Effective Permissions sections.
The following example shows a GetThings request that includes the Core section.
<!-- ... -->
<group name="height things">
It is not possible to use a filter to query for things that are read-only.
Data types that support read-only instances
Most HealthVault data types support read-only instances, though there are a few that do not. The AllowReadOnly property of the data type indicates if the type supports read-only instances. The data type definition can be viewed at the Thing types and sample data browser or through a GetThingType request. At this time, the following types do not allow read-only instances:
Basic Demographic Information
Personal Contact Information
Personal Demographic Information
An attempt to specify the read-only flag for a type that does not support it will result in a CannotCreateReadOnlyThing (155) error. For more information about error codes, see Status Codes.
Updated end date handling
When data is read-only, applications may still want to provide a way for a user to update the end date status of an item. To support this, all HealthVault data types now include an updated-end-date field that is always writable, even if the item is read-only. This is useful for example for a Medication thing instance when the user wants to indicate they are no longer taking the medication, or for a Condition thing instance when the user wants to indicate they no longer have the condition. The updated-end-date field is the recommended place to store end date information on all data types. For more information, see HealthVault item status.
The HealthVault data model supports relating items to one another via Related Items. Related items are stored within the common element within the data-xml element, so they cannot be edited for a read-only item.
There are two approaches that can be used for relating items where some of the items are read-only.
Use a Client ID to define your own IDs for each item, and store the Client IDs via the Related Items mechanism when creating the items in HealthVault. The relationships need to be defined at the time the read-only things are created in HealthVault.
Related Items can be used to specify relationships FROM a non-read-only thing TO a read-only thing. The reverse is not allowed. The following table describes the possible relationships between things.
From thing A (read-only) to thing B
This is not allowed, as the Related Items section of thing A cannot be edited.
From thing B to thing A (read only))
This is allowed, as the Related Items section of thing B can be updated with the thing-id or client thing id of thing A.
From thing A (read-only) to thing B (read-only))
This is not allowed. Once a thing is stored as read-only, the Related Items section cannot be updated.
Reconciliation is the process by which clinical documents such as Continuity of Care Record (CCR) and Continuity of Care Document (CCD) documents in HealthVault can be used to create HealthVault items based on the data they contain. For more information, see Using CCR Data in HealthVault.
By default, the individual items reconciled from a clinical document are not read-only. To specify that the reconciled items should be read-only, set the read-only flag on the clinical document thing when creating it in HealthVault. All items reconciled from the document will be read-only.
When using the HealthVault .NET SDK for querying and writing data, use the HealthRecordAccessor class.
To specify that a thing instance should be read-only when creating data, set the HealthRecordItem..::..IsReadOnly property to true.
To determine if a thing instance is read-only when reading data, check the value of the IsReadOnly property. Note that you must query for the Core or Effective Permissions section to retrieve the value of the IsReadOnly property.
.NET SDK code samples
The following example stores a read-only thing instance.
// Create a read-only Medication thing
Medication med = new Medication(new CodableValue("My read-only medication"));
med.IsReadOnly = true;
The following example edits the Updated End Date field on a read-only thing.
// Edit updated end date on a read-only thing to the current time. This
// indicates the user considers the medication inactive as of the current time.
// In this example, "9b3ef8ad-dd4a-484c-aa05-66f967470e0f" is the thing id
// for an existing Medication instance that is read-only.
HealthRecordItem med =
med.UpdatedEndDate = DateTime.Now;
The following example specifies that items from a CCD should be reconciled as read-only.
// Specifies that a CCD document's items should be reconciled as read-only
XmlDocument ccdDocument = new XmlDocument();
// ExampleCCD.xml is located in the HealthVault SDK at
// \Microsoft HealthVault\SDK\DotNet\WebSamples\ccr_ccd_example\website\ExampleCCD.xml
HealthRecordItem ccd = new HealthRecordItem(CCD.TypeId, ccdDocument);
ccd.IsReadOnly = true;