Export (0) Print
Expand All

HealthVault drop-off and pick-up (DOPU)

HealthVault

Drop-off and pick-up (DOPU) is a way for an application to send health data to a user without requiring a patient-facing user interface. It's a good choice for applications that don't have a user interface and want a one-time push of data to users. For an ongoing relationship with users, see Establishing authorization with a user using Patient Connect.

Last updated: July 2012

This topic contains the following sections.

For example, a lab may support sending results to HealthVault, but it doesn't have a website that allows users to log in and connect via the online web user approach. It's also not interested in establishing a connection with the user and exchanging data on an ongoing basis. In this case it can create a DOPU package containing the lab results and send it to HealthVault for the user to pick up.

A typical DOPU connection is made in the following way:

  1. A patient visits a lab and wants to store her lab results in her HealthVault account.

  2. The lab's application creates a DOPU package in HealthVault containing the patient's results, the patient's ID in the lab's system, a friendly name for the patient, and a secret question. The secret answer is used to encrypt the DOPU package and to later verify the identity of the user.

  3. HealthVault returns an identity code for the DOPU package.

  4. The application then sends the user an email containing the identity code and a link to HealthVault. (Alternatively, the lab could give the patient a print-out with the information.)

  5. Later, the patient goes to the URL provided by the lab and enters the identity code. She will also create an account if she doesn't already have one.

  6. The patient is prompted for the answer to her secret question, and when she enters it correctly, this validates her identity.

  7. The patient then selects the HealthVault record in which the lab results should be stored.

  8. The data from the DOPU package is written to the patient's record.

  9. The patient receives confirmation, which includes the Patient Connect Success message that was configured in the Application Configuration Center (see "Application Configuration" below).

Property

Description

Identity code

The unique code generated by HealthVault that identifies the package.

Users begin the process of picking up connect packages by going to https://shellhostname/redirect.aspx?target=PICKUP and entering their identity code manually into the website. You can also provide the identity code as a query string parameter so users don't have to manually enter it themselves. For example: https://shellhostname/redirect.aspx?target=PICKUP&targetqs=packageid%3dJKYZ-QNMN-VHRX-ZGNR-GZNH. See Shell redirect interface for more details on using the Shell redirect interfaces.

Friendly name

A friendly name that can be presented to the user after the user successfully answers the challenge question. The friendly name should be something that is recognizable and distinguishes one package from another so that the user may choose the expected record for receiving the data.

For example, a mother of two children may want to name her packages after each child so she can distinguish one child's package from the other's.

Secret question

A challenge question posed to the user once the identity code has been successfully entered. We recommend that the question be personal and easy to answer in one word. An empty question is not allowed.

Secret answer

The secret answer provided by the user. This should be used to encrypt the package data, so when the user picks up the package, she will have to enter the answer correctly in order to decrypt the package data and verify her identity. The secret answer is not stored in HealthVault.

External ID

A unique identifier supplied by the application for identifying the package. This value is used to map the patient's information in the application to the package. For example, this could be the patient identifier used to store information in the application's database.

Package data

A Password Protected Package thing containing the data to send to the user. Its data-other must be Base64 encoded and must contain the encrypted data which HealthVault will be able to decrypt with the user's answer to the secret question. The decoded and decrypted data must be a sequence of thing elements as defined by the following schema:

 
<sequence>
<element name="thing" type="wc-thing:Thing" minOccurs="1" maxOccurs="unbounded" />
</sequence>

For more information about each XML request, see the XML Method browser.

Method

Description

CreateConnectPackage

Creates a DOPU package.

AllocatePackageId

Allocates an identity code for a DOPU package. Since sending the package can take a long time, applications can call this method to get an identity code to give to the patient immediately and then later upload the package data by calling CreateConnectPackage with the identity code returned by this method.

UpdateExternalId

Updates the external ID for a DOPU package.

BeginPutConnectPackageBlob

Initiates uploading a blob associated with the DOPU package via the Streaming API. For more information, see Working with Blobs and Streamed Data.

DeletePendingConnectPackage

Deletes a pending DOPU package.

The HealthVault .NET SDK contains classes and methods in the Microsoft.Health.Package namespace for creating and managing DOPU packages.

A DOPU package can be created in two ways:

  1. Call CreateConnectPackage with the package data.

  2. Call AllocatePackageId to get an identity code, and then call CreateConnectPackage with the package data plus the identity code.

The latter approach allows applications to give identity codes to users before actually uploading data to HealthVault. This is useful for large packages that may take a long time to upload.

Multiple packages are allowed for a given external ID, but a package cannot be updated once created.

The data in a DOPU package is an encrypted list of HealthVault items. It is encapsulated in the Password Protected Package type, which consists of metadata about the encryption algorithm and an inline blob that is the encrypted data itself.

The unencrypted data should be a sequence of thing XMLs of any HealthVault data type. Items can also contain inline or streamed blobs, but items with streamed blobs cannot be digitally signed inside a DOPU package.

For example:

 
<thing>
<type-id>3d34d87e-7fc1-4153-800f-f56592cb0d17</type-id>
<data-xml>
<weight>
  <when>
    <date>
      <y>2006</y>
      <m>12</m>
      <d>22</d>
    </date>
  </when>
  <value>
    <kg>125</kg>
    <display units="lb" units-code="lb">275.5625</display>
  </value>
</weight>
</data-xml>
</thing>
<thing>
<type-id>3d34d87e-7fc1-4153-800f-f56592cb0d17</type-id>
<data-xml>
<weight>
  <when>
    <date>
      <y>2006</y>
      <m>12</m>
      <d>22</d>
    </date>
  </when>
  <value>
    <kg>114</kg>
    <display units="lb" units-code="lb">251.313</display>
  </value>
</weight>
</data-xml>
</thing>

Adding blobs to package data items is very similar to adding blobs to regular items – the only difference is that you need to call BeginPutConnectPackageBlob instead of BeginPutBlob when initiating a streamed blob for DOPU packages. Using the blob URL returned by BeginPutConnectPackageBlob, you stream the blob data to HealthVault and add the blob metadata to the thing XML as with regular items.

To preserve the confidentiality of the DOPU package, the data should be encrypted based on the user's secret answer before uploading to HealthVault. The encryption key should be derived using the user's secret answer and a salt and iteration count specified by the app. (See the IETF RFC 2892 as a reference.) To ensure case-insensitivity, HealthVault converts the secret answer to lowercase when attempting to decrypt the package, so the answer should be converted to lowercase when encrypting the package as well. The .NET SDK does this automatically. In addition, the unencrypted data should include a Hash-based Message Authentication Code (HMAC) based on the same salt as the encryption key in order for HealthVault to confirm the integrity of the data when the package is picked up.

Supported encryption algorithms:

Algorithm

Block size (bits)

Key size (bits))

IV size (bytes)

Rijndael

256

256

32

3DES

64

192

8

You need to provide the following information as part of the Password Protected Package type when creating the DOPU package:

Property

Description

Encryption algorithm name

Allowed values:

hmac-sha256-aes256: Encrypted using the hmac-sha2 pseudorandom and the Rijndael encryption function. This is the recommended encryption algorithm.

hmac-sha1-3des: Encrypted using the hmac-sha1 pseudorandom and the 3DES encryption function. This algorithm is not recommended. It is currently supported for backwards compatibility but may be removed in the future.

Salt

Salt used when hashing the value. This is application dependent, but to support consistency we suggest that the salt be a base64-encoded series of bytes matching the length requirement of the algorithm. For instance, 64 bytes for sha1 and sha256.

Iteration count

The number of iterations used when hashing the data.

Key length

The key length in bits used. This depends on the encryption algorithm. Currently the supported values are 192 for hmac-sha1-3des and 256 for hmac-sha256-aes256.

The user has a limited amount of time to pick up the package (currently four weeks); after that the package will expire and no longer be available. If the user attempts and fails to answer the question correctly several times (currently after three chances), she will not be able to use the package code anymore. In either case, the user will have to contact the application to resend the package.

The package can be picked up only once. If the user selects the wrong record, she will have to request that the application resend the package.

Unlike Patient Connect requests, there is no way to determine if a user has picked up a DOPU package. This is a one-time-only transfer of data, so the application isn't authorized to continue exchanging data with the record.

To use DOPU, you must select the "ConnectPackage" methods when configuring your application in the HealthVault Application Configuration Center (ACC). This set of methods is not available for mobile apps.

You do not need an action URL, terms of use, or privacy statement if your application only does DOPU. You can set a custom message for the user upon successfully picking up the package:

DOPU success message

Creating a DOPU package:

 
private static void CreateDopuPackage(
string friendlyName,
string secretQuestion,
string secretAnswer,
string patientId,
double weight,
double height,
string imagePath)
{
// Create an offline connection
OfflineWebApplicationConnection connection = new OfflineWebApplicationConnection(
    ApplicationId,
    HealthServiceUrl,
    Guid.Empty /* offlinePersonId */);

// Create package parameters
ConnectPackageCreationParameters parameters = new ConnectPackageCreationParameters(
    connection,
    friendlyName,
    secretQuestion,
    secretAnswer,
    patientId);

// Create items
Weight weightItem = new Weight(
    new HealthServiceDateTime(DateTime.Now), new WeightValue(weight));
Height heightItem = new Height(height);

// Stream a blob
BlobStore blobStore = heightItem.GetBlobStore(parameters);
using (IO.FileStream stream = new IO.FileStream(imagePath, IO.FileMode.Open))
{
    blobStore.Write("attachment", "image\\jpg", stream);
}

// Create the package
string code = ConnectPackage.Create(
    parameters,
    new List<HealthRecordItem>() { weightItem, heightItem });

// Email the URL and code to the user
SendConnectPackageMail(patientId, code);
}
Show:
© 2014 Microsoft