Pull

Josh Mandel edited this page Dec 27, 2013 · 10 revisions
Clone this wiki locally

Demo: http://growth-pull.bluebuttonpl.us/

Source: https://github.com/jmandel/bb-tutorial-growthtastic/tree/step-2-pull

Why Pull when there's Push?!

BlueButton+ Push specifications build on the Direct specification for secure e-mail. The strong advantage of Push for developers is that EHR vendors have already begun to implement the provider side of the interface. This means you can start building real BB+ Push apps today. But there are strong limitations to an e-mail based workflow, including:

  • Complex sign-up workflow (patients need to leave the app & remember a Direct address)
  • Architecture requires an always-on server (can't build a self-contained tablet app)
  • No on-demand data access (messages sent when the provider fires a trigger)

This portion of the BB+ tutorial demonstrates how the forthcoming BB+ Pull spec addresses these limitations.

Overall user interaction

BB+ Pull: Sharing patient records with REST + OAuth2

The BlueButton+ Pull Working Group has developed a draft specification for RESTful OAuth2-protected patient data endpoints. To briefly summarize the architecture, there are three main components:

  • BB+ Patient-facing Apps (Web, mobile, native -- whatever)
  • BB+ Data Providers (hospitals, clinics, or others serving patient-level data)
  • BB+ Registries (allows apps and providers to discover one another)

In this tutorial, we'll show a sequence of steps to obtain a C-CDA for a patient. You'll see that the entire sequence can run client-side, with no need for server-side logic.

  1. Discover a list of BB+ Data Providers from a Registry
  2. Allow the user to select a Data Provider
  3. Register the app with the patient's Provider as an OAuth2 client
  4. Ask the patient to authorize access (obtaining an OAuth2 access token)
  5. Retrieve a summary document via OAuth2-protected RESTful endpoint

0. JavaScript client library

We'll take advantage of BBClient, a simple JS client library for BlueButton+ Pull. This library uses jQuery under the hood. To include these dependenncies, we add script tags to our main view as well as index.html:

<script src="/static/growth_charts/lib/jquery.js"></script>
<script src="/static/growth_charts/bb/bluebutton-pull-client.js"></script>

We'll also set up a two configuration variables straght away: OAuth2 client details, and a list of trusted registries (in this case, just one -- a testing registry):

var client = {
  "client_name": "Growth-tastic",
  "client_uri": "http://growth.bluebuttonpl.us",
  "logo_uri": "http://growth.bluebuttonpl.us/static/growth_charts/img/icon.png",
  "contacts": [ "info@growth.bluebuttonpl.us" ],
  "redirect_uris": [ "http://growth.bluebuttonpl.us/static/growth_charts/" ],
  "response_types": ["token"],
  "grant_types": ["implicit"],
  "token_endpoint_auth_method": "none",
  "scope":  "summary"
};

var registries = ["https://pilots.fhir.me"];

1. Discover a list of BB+ Data Providers from a Registry

We'll augment the main page's UI with a list of providers (initially empty):

<h4>Connect Growth-tastic to your your health record</h4>
<ul type='text' id='provider-select'></ul>

And then we call BBClient.providers to query our trusted Registries for available providers. This obtains a JSON array of Providers, where each provider has basic metadata including a name, URL, and a set of OAuth endpoints -- full details about the format are available here.

For each provider we append a clickable item to our list:

BBClient.providers(registries, function(providers){
  $.each(providers, function(i,v){

    var p = $("<li><a href='"+v.oauth2.authorize_uri+"'> " +
              v.name+"</a> " + 
              "<em>"+v.description+"</em></li>");
    p.click(choose(v));
    $('#provider-select').append(p);
  });
});


2. Allow the user to select a Data Provider

When the user clicks on a provider, we'll ask BBClient to kick off an authorization process so the user can approve Growth-tastic to access her medical record:

  function choose(p){
    return function(event){
      event.preventDefault();
      BBClient.authorize({
        client: client,
        provider:p
      });
    };
  };

3. (Automatic) Register the app with the patient's Provider as an OAuth2 client

Since we're using the BBClient, registration happens automatically under the hood. This gives us an OAuth2 client_id (informing the data provider of Growth-tastic's name, logo, and redirect URI) -- which we'll need in order to request authorization in the next step.

4. (Automatic) Ask the patient to authorize access (obtaining an OAuth2 access token)

BBClient redirects the user to her data provider for authorization. At her provider's portal, the user will log in and see an authorization screen. If she accepts, she'll be redirected back to http://growth.bluebuttonpl.us/static/growth_charts/, Growth-tastic's redirect_uri.

5. Retrieve a summary document via OAuth2-protected RESTful endpoint

Finally, we'll modify our GC.get_data function in bluebutton-loader.js, to take advantage of BB+ Pull access. Assuming the user has approved access, all we need to do is call:

  BBClient.summary()
  .fail(fail)
  .success(extractVitals);

This will call extractVitals with the C-CDA summary XML file as a string argument, just the way we did with BB+ Push. For a refresher, see our tutorial on working with the data in attached C-CDA files.