Blue Button+ Implementation Guide

February 4, 2013 - Developer Preview | Help edit this site

Receiving Health Data Using Direct

This section describes the use of the Direct Project specification to receive health data securely from a data holder on behalf of a patient or their authorized representative. The ability to receive health data securely enables an ecosystem to be built on patient health data.

Receive Diagram

1. Using the Direct Protocol to Receive Data

Direct Project offers a specification for how existing standards can be used to securely transport health information over the Internet. Direct uses SMTP, S/MIME, and X.509 certificates to achieve security, privacy, data integrity, and authentication of sender and receiver sufficient to meet the data transport needs of health information exchange.

Your application will need to integrate with a component that can accept Direct messages and their payloads. This component is called a Security/Trust Agent (STA). A STA uses SMTP and S/MIME to ensure messages and their payload are delivered securely. A STA can be a component internal to your system, or hosted externally.

When an STA is hosted externally, it is usually by a Health Information Services Provider (HISP).

For Blue Button+, your Direct STA must be able to:

Your application must be able to:

Sample code: .NET Reference Implementation, and Java Reference Implementation.

Learn more: Direct Project’s Documentation Library and Direct Project’s Applicability Statement for Secure Health Transport

Detailed Flow Diagram

The following diagram depicts a successful transmission. See it full-size.

Direct Transmit Flow Diagram

2. Blue Button+ Format and Payload

Once your application has received the message and payload, it needs to process it. It needs to understand what files have been included. It also needs to handle cases in which it receives multiple updates from the same user, over a period of time.

As with all Direct messages, Blue Button+ messages that your application receives from the STA/HISP will be Internet-format Messages following RFC 5322 and Multipart MIME. Blue Button+ provides additional guidance on the contents of these messages to support a higher level of semantic exchange.

Blue Button+ messages will contain:

Anatomy of Request.txt

In addition to the friendly message in the body, you may receive a request.txt. This is a simple way, much like robots.txt works to provide some semi-structured context to machines.

Destination: [Direct Address]
Patient: [Patient Name]
Data-holder: [Data Holder Name]
Recurring: [Yes / No]

An example of what a request.txt would look like:

Patient: Ellen Ross
Data-holder: Ashby Medical Center
Recurring: Yes

3. Frequency

For a given address, there is the likelihood that your application will receive multiple documents over a period of time. This will be especially so if the consumer sets up an “automated” transmission when ever their health data changes.

This is beneficial for your application, because it will be getting an up-to-date stream of data. However, your application may need to handle the merging of these transmissions. The means of this merge is up to you as the receiver and not part of Blue Button+ guidelines.

4. Blue Button+ Patient Trust Bundle

You need to submit the trust anchor for your application to the Blue Button+ Trust Bundle in order for a data holder participating in the Blue Button+ ecosystem to send messages to Direct addresses issued by your application. Follow these steps:

  1. Visit
  2. Register your application
  3. Demonstrate that your application is secured via SSL/HTTPS
  4. Provide a link to the Model Privacy Notice on your website or in your application

Once your application’s trust anchor is in the system, it will take 24-48 hours for data holders to sync your certificate.