documentation/manual/en/module_specs/Zend_Gdata_Health.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.health">
   4     <title>Using Google Health</title>
   5
   6     <para>
   7         The Google Health Data <acronym>API</acronym> is designed to enable developers to do two
   8         things:
   9
  10         <itemizedlist>
  11             <listitem>
  12                 <para>
  13                     Read a user's Google Health profile or query for medical records that match
  14                     particular criteria and then use the results to provide personalized
  15                     functionality based on the data.
  16                 </para>
  17             </listitem>
  18
  19             <listitem>
  20                 <para>
  21                     Add new medical records to a user's profile by including CCR data when sending a
  22                     notice to a user's profile. Note: The CCR data is stored as an
  23                     <acronym>XML</acronym> blob within the &lt;atom&gt; entry. The library does not
  24                     provide direct accessors to the object model but it does have helpers for
  25                     extracting specific fields.
  26                 </para>
  27             </listitem>
  28         </itemizedlist>
  29     </para>
  30
  31     <para>
  32         There are three main feeds, each of which requires authentication. Unlike other Google Data
  33         <acronym>API</acronym>s, each Google Health feed has a limited set of
  34         <acronym>HTTP</acronym> operations you can perform on it, depending on which authentication
  35         method you are using (ClientLogin or AuthSub/OAuth). For a list of permitted operations, see
  36         <ulink
  37             url="http://code.google.com/apis/health/reference.html#Authentication">http://code.google.com/apis/health/reference.html#Authentication</ulink>.
  38
  39         <itemizedlist>
  40             <listitem>
  41                 <para>
  42                   <firstterm>Profile Feed</firstterm>
  43                   use the profile feed to query a user's health profile for specific information.
  44                 </para>
  45             </listitem>
  46
  47             <listitem>
  48                 <para>
  49                   <firstterm>Register Feed</firstterm>
  50                   use the register feed to reconcile new CCR data into a profile.
  51                 </para>
  52             </listitem>
  53
  54             <listitem>
  55                 <para>
  56                   <firstterm>Profile List Feed</firstterm> the profile list feed should be used to
  57                   determine which of the user's Health profiles to interact with. This feed is only
  58                   available when using ClientLogin.
  59                 </para>
  60             </listitem>
  61         </itemizedlist>
  62     </para>
  63
  64     <para>
  65         See <ulink
  66             url="http://code.google.com/apis/health/">http://code.google.com/apis/health</ulink>
  67         for more information about the Google Health <acronym>API</acronym>.
  68     </para>
  69
  70     <sect2 id="zend.gdata.health.connect">
  71         <title>Connect To The Health Service</title>
  72
  73         <para>
  74             The Google Health <acronym>API</acronym>, like all Google Data <acronym>API</acronym>s,
  75             is based off of the Atom Publishing Protocol (APP), an <acronym>XML</acronym> based
  76             format for managing web-based resources. Traffic between a client and the Google Health
  77             servers occurs over <acronym>HTTP</acronym> and allows for authenticated connections.
  78         </para>
  79
  80         <para>
  81             Before any transactions can occur, a connection needs to be made. Creating a connection
  82             to the Health servers involves two steps: creating an <acronym>HTTP</acronym> client and
  83             binding a <classname>Zend_Gdata_Health</classname> service instance to that client.
  84         </para>
  85
  86         <sect3 id="zend.gdata.health.connect.authentication">
  87             <title>Authentication</title>
  88
  89             <para>
  90                 The Google Health <acronym>API</acronym> allows programmatic access to a user's
  91                 Health profile. There are three authentication schemes that are supported by Google
  92                 Health:
  93             </para>
  94
  95             <itemizedlist>
  96                 <listitem>
  97                     <para>
  98                         <firstterm>ClientLogin</firstterm> provides direct username/password
  99                         authentication to the Health servers. Since this method requires that users
 100                         provide your application with their password, this authentication scheme is
 101                         only recommended for installed/desktop applications.
 102                     </para>
 103                 </listitem>
 104
 105                 <listitem>
 106                     <para>
 107                         <firstterm>AuthSub</firstterm> allows a user to authorize the sharing of
 108                         their private data. This provides the same level of convenience as
 109                         ClientLogin but without the security risk, making it an ideal choice for
 110                         web-based applications. For Google Health, AuthSub must be used in
 111                         registered and secure mode--meaning that all requests to the
 112                         <acronym>API</acronym> must be digitally signed.
 113                     </para>
 114                 </listitem>
 115
 116                 <listitem>
 117                     <para>
 118                         <firstterm>OAuth</firstterm> is an alternative to AuthSub. Although this
 119                         authentication scheme is not discussed in this document, more information
 120                         can be found in the <ulink
 121                             url="http://code.google.com/apis/health/developers_guide_protocol.html#OAuth">Health
 122                             Data <acronym>API</acronym> Developer's Guide</ulink>.
 123                     </para>
 124                 </listitem>
 125             </itemizedlist>
 126
 127             <para>
 128                 See <ulink
 129                     url="http://code.google.com/apis/gdata/auth.html">Authentication Overview in the
 130                     Google Data <acronym>API</acronym> documentation</ulink> for more
 131                 information on each authentication method.
 132             </para>
 133         </sect3>
 134
 135         <sect3 id="zend.gdata.health.connect.service">
 136             <title>Create A Health Service Instance</title>
 137
 138             <para>
 139                 In order to interact with Google Health, the client library provides the
 140                 <classname>Zend_Gdata_Health</classname> service class. This class provides a common
 141                 interface to the Google Data and Atom Publishing Protocol models and assists in
 142                 marshaling requests to and from the Health <acronym>API</acronym>.
 143             </para>
 144
 145             <para>
 146                 Once you've decided on an authentication scheme, the next step is to create an
 147                 instance of <classname>Zend_Gdata_Health</classname>. This class should be passed an
 148                 instance of <classname>Zend_Gdata_HttpClient</classname>. This provides an interface
 149                 for AuthSub/OAuth and ClientLogin to create a special authenticated
 150                 <acronym>HTTP</acronym> client.
 151             </para>
 152
 153             <para>
 154                 To test against the H9 Developer's (/h9) instead of Google Health (/health), the
 155                 <classname>Zend_Gdata_Health</classname> constructor takes an optional third
 156                 argument for you to specify the H9 service name 'weaver'.
 157             </para>
 158
 159             <para>
 160                 The example below shows how to create a Health service class using ClientLogin
 161                 authentication:
 162             </para>
 163
 164             <programlisting language="php"><![CDATA[
 165 // Parameters for ClientLogin authentication
 166 $healthServiceName = Zend_Gdata_Health::HEALTH_SERVICE_NAME;
 167 //$h9ServiceName = Zend_Gdata_Health::H9_SANDBOX_SERVICE_NAME;
 168 $user = "user@gmail.com";
 169 $pass = "pa$$w0rd";
 170
 171 // Create an authenticated HTTP client
 172 $client = Zend_Gdata_ClientLogin::getHttpClient($user,
 173                                                 $pass,
 174                                                 $healthServiceName);
 175
 176 // Create an instance of the Health service
 177 $service = new Zend_Gdata_Health($client);
 178 ]]></programlisting>
 179
 180             <para>
 181                 A Health service using AuthSub can be created in a similar, though slightly more
 182                 lengthy fashion. AuthSub is the recommend interface to communicate with Google
 183                 Health because each token is directly linked to a specific profile in the user's
 184                 account. Unlike other Google Data <acronym>API</acronym>s, it is required that all
 185                 requests from your application be digitally signed.
 186             </para>
 187
 188             <programlisting language="php"><![CDATA[
 189 /*
 190  * Retrieve the current URL so that the AuthSub server knows where to
 191  * redirect the user after authentication is complete.
 192  */
 193 function getCurrentUrl() {
 194     $phpRequestUri = htmlentities(substr($_SERVER['REQUEST_URI'],
 195                                          0,
 196                                          strcspn($_SERVER['REQUEST_URI'],
 197                                                  "\n\r")),
 198                                   ENT_QUOTES);
 199
 200     if (isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on') {
 201         $protocol = 'https://';
 202     } else {
 203         $protocol = 'http://';
 204     }
 205     $host = $_SERVER['HTTP_HOST'];
 206     if ($_SERVER['SERVER_PORT'] != '' &&
 207        (($protocol == 'http://' && $_SERVER['SERVER_PORT'] != '80') ||
 208        ($protocol == 'https://' && $_SERVER['SERVER_PORT'] != '443'))) {
 209         $port = ':' . $_SERVER['SERVER_PORT'];
 210     } else {
 211         $port = '';
 212     }
 213     return $protocol . $host . $port . $phpRequestUri;
 214 }
 215
 216 /*
 217  * Redirect a user to AuthSub if they do not have a valid session token.
 218  * If they're coming back from AuthSub with a single-use token, instantiate
 219  * a new HTTP client and exchange the token for a long-lived session token
 220  * instead.
 221  */
 222 function setupClient($singleUseToken = null) {
 223     $client = null;
 224
 225     // Fetch a new AuthSub token?
 226     if (!$singleUseToken) {
 227         $next = getCurrentUrl();
 228         $scope = 'https://www.google.com/health/feeds';
 229         $authSubHandler = 'https://www.google.com/health/authsub';
 230         $secure = 1;
 231         $session = 1;
 232         $authSubURL =  Zend_Gdata_AuthSub::getAuthSubTokenUri($next,
 233                                                               $scope,
 234                                                               $secure,
 235                                                               $session,
 236                                                               $authSubHandler);
 237
 238          // 1 - allows posting notices && allows reading profile data
 239         $permission = 1;
 240         $authSubURL .= '&permission=' . $permission;
 241
 242         echo '<a href="' . $authSubURL . '">Your Google Health Account</a>';
 243     } else {
 244         $client = new Zend_Gdata_HttpClient();
 245
 246         // This sets your private key to be used to sign subsequent requests
 247         $client->setAuthSubPrivateKeyFile('/path/to/your/rsa_private_key.pem',
 248                                           null,
 249                                           true);
 250
 251         $sessionToken =
 252             Zend_Gdata_AuthSub::getAuthSubSessionToken(trim($singleUseToken),
 253                                                        $client);
 254
 255         // Set the long-lived session token for subsequent requests
 256         $client->setAuthSubToken($sessionToken);
 257     }
 258     return $client;
 259 }
 260
 261 // -> Script execution begins here <-
 262
 263 session_start();
 264
 265 $client = setupClient(@$_GET['token']);
 266
 267 // Create an instance of the Health service
 268 $userH9Sandbox = false;
 269 $healthService = new Zend_Gdata_Health($client,
 270                                        'googleInc-MyTestAppName-v1.0',
 271                                        $userH9Sandbox);
 272 ]]></programlisting>
 273
 274             <para>
 275                 NOTE: the remainder of this document will assume you are using AuthSub for
 276                 authentication.
 277             </para>
 278         </sect3>
 279     </sect2>
 280
 281     <sect2 id="zend.gdata.health.profilefeed">
 282         <title>Profile Feed</title>
 283
 284         <para>
 285             To query the user's profile feed, make sure your initial AuthSub token was requested
 286             with the <code>permission=1</code> parameter set. The process of extracting data from
 287             the profile requires two steps, sending a query and iterating through the resulting
 288             feed.
 289         </para>
 290
 291         <sect3 id="zend.gdata.health.profilefeed.query">
 292             <title>Send a Structured Query</title>
 293
 294             <para>
 295                 You can send structured queries to retrieve specific records from a user's profile.
 296             </para>
 297
 298             <para>
 299                 When retrieving the profile using the Health <acronym>API</acronym>, specifically
 300                 constructed query <acronym>URL</acronym>s are used to describe what (CCR) data
 301                 should be returned. The <classname>Zend_Gdata_Health_Query</classname> class helps
 302                 simplify this task by automatically constructing a query <acronym>URL</acronym>
 303                 based on the parameters you set.
 304             </para>
 305
 306             <sect4 id="zend.gdata.health.profilefeed.query.construct">
 307                 <title>Query The Feed</title>
 308
 309                 <para>
 310                     To execute a query against the profile feed, invoke a new instance of an
 311                     <classname>Zend_Gdata_Health_Query</classname> and call the service's
 312                     <methodname>getHealthProfileFeed()</methodname> method:
 313                 </para>
 314
 315                 <programlisting language="php"><![CDATA[
 316 $healthService = new Zend_Gdata_Health($client);
 317
 318 // example query for the top 10 medications with 2 items each
 319 $query = new Zend_Gdata_Health_Query();
 320 $query->setDigest("true");
 321 $query->setGrouped("true");
 322 $query->setMaxResultsGroup(10);
 323 $query->setMaxResultsInGroup(2);
 324 $query->setCategory("medication");
 325
 326 $profileFeed = $healthService->getHealthProfileFeed($query);
 327 ]]></programlisting>
 328
 329                 <para>
 330                     Using <methodname>setDigest("true")</methodname> returns all of user's CCR data
 331                     in a single Atom <code>&lt;entry&gt;</code>.
 332                 </para>
 333
 334                 <para>
 335                     The <methodname>setCategory()</methodname> helper can be passed an additional
 336                     parameter to return more specific CCR information. For example, to return just
 337                     the medication Lipitor, use
 338                     <methodname>setCategory("medication", "Lipitor")</methodname>. The same
 339                     methodology can be applied to other categories such as conditions, allergies,
 340                     lab results, etc.
 341                 </para>
 342
 343                 <para>
 344                     A full list of supported query parameters is available in the <ulink
 345                         url="http://code.google.com/apis/health/reference.html#Parameters">query
 346                         parameters section</ulink> of the Health <acronym>API</acronym> Reference
 347                     Guide.
 348                 </para>
 349             </sect4>
 350         </sect3>
 351
 352         <sect3 id="zend.gdata.health.profilefeed.iterate">
 353             <title>Iterate Through The Profile Entries</title>
 354
 355             <para>
 356                 Each Google Health entry contains CCR data, however, using the
 357                 <code>digest=true</code> query parameter will consolidate all of the CCR elements
 358                 (that match your query) into a single Atom <code>&lt;entry&gt;</code>.
 359             </para>
 360
 361             <para>
 362                 To retrieve the full CCR information from an entry, make a call to the
 363                 <classname>Zend_Gdata_Health_ProfileEntry</classname> class's
 364                 <methodname>getCcr()</methodname> method. That returns a
 365                 <classname>Zend_Gdata_Health_Extension_CCR</classname>:
 366             </para>
 367
 368             <programlisting language="php"><![CDATA[
 369 $entries = $profileFeed->getEntries();
 370 foreach ($entries as $entry) {
 371     $medications = $entry->getCcr()->getMedications();
 372     //$conditions = $entry->getCcr()->getConditions();
 373     //$immunizations = $entry->getCcr()->getImmunizations();
 374
 375     // print the CCR xml (this will just be the entry's medications)
 376     foreach ($medications as $med) {
 377         $xmlStr = $med->ownerDocument->saveXML($med);
 378         echo "<pre>" . $xmlStr . "</pre>";
 379     }
 380 }
 381 ]]></programlisting>
 382
 383             <para>
 384                 Here, the <methodname>getCcr()</methodname> method is used in conjunction with a
 385                 magic helper to drill down and extract just the medication data from the entry's
 386                 CCR. The formentioned magic helper takes the form
 387                 <methodname>getCATEGORYNAME()</methodname>, where <constant>CATEGORYNAME</constant>
 388                 is a supported Google Health category. See the <ulink
 389                     url="http://code.google.com/apis/health/reference.html#CatQueries">Google Health
 390                     reference Guide</ulink> for the possible categories.
 391             </para>
 392
 393             <para>
 394                 To be more efficient, you can also use category queries to only return the necessary
 395                 CCR from the Google Health servers. Then, iterate through those results:
 396             </para>
 397
 398             <programlisting language="php"><![CDATA[
 399 $query = new Zend_Gdata_Health_Query();
 400 $query->setDigest("true");
 401 $query->setCategory("condition");
 402 $profileFeed = $healthService->getHealthProfileFeed($query);
 403
 404 // Since the query contained digest=true, only one Atom entry is returned
 405 $entry = $profileFeed->entry[0];
 406 $conditions = $entry->getCcr()->getConditions();
 407
 408 // print the CCR xml (this will just be the profile's conditions)
 409 foreach ($conditions as $cond) {
 410     $xmlStr = $cond->ownerDocument->saveXML($cond);
 411     echo "<pre>" . $xmlStr . "</pre>";
 412 }
 413 ]]></programlisting>
 414         </sect3>
 415     </sect2>
 416
 417     <sect2 id="zend.gdata.health.profilelist">
 418         <title>Profile List Feed</title>
 419
 420         <para>NOTE: This feed is only available when using ClientLogin</para>
 421
 422         <para>
 423             Since ClientLogin requires a profile ID with each of its feeds, applications will likely
 424             want to query this feed first in order to select the appropriate profile. The profile
 425             list feed returns Atom entries corresponding each profile in the user's Google Health
 426             account. The profile ID is returned in the Atom <code>&lt;content&gt;</code> and the
 427             profile name in the <code>&lt;title&gt;</code> element.
 428         </para>
 429
 430         <sect3 id="zend.gdata.health.profilelist.query">
 431             <title>Query The Feed</title>
 432
 433             <para>
 434                 To execute a query against the profile list feed, call the service's
 435                 <methodname>getHealthProfileListFeed()</methodname> method:
 436             </para>
 437
 438             <programlisting language="php"><![CDATA[
 439 $client = Zend_Gdata_ClientLogin::getHttpClient('user@gmail.com',
 440                                                 'pa$$word',
 441                                                 'health');
 442 $healthService = new Zend_Gdata_Health($client);
 443 $feed = $healthService->getHealthProfileListFeed();
 444
 445 // print each profile's name and id
 446 $entries = $feed->getEntries();
 447 foreach ($entries as $entry) {
 448     echo '<p>Profile name: ' . $entry->getProfileName() . '<br>';
 449     echo 'profile ID: ' . $entry->getProfileID() . '</p>';
 450 }
 451 ]]></programlisting>
 452
 453             <para>
 454                 Once you've determined which profile to use, call
 455                 <methodname>setProfileID()</methodname> with the profileID as an argument. This will
 456                 restrict subsequent <acronym>API</acronym> requests to be against that particular
 457                 profile:
 458             </para>
 459
 460             <programlisting language="php"><![CDATA[
 461 // use the first profile
 462 $profileID = $feed->entry[0]->getProfileID();
 463 $healthService->setProfileID($profileID);
 464
 465 $profileFeed = $healthService->getHealthProfileFeed();
 466
 467 $profileID = $healthService->getProfileID();
 468 echo '<p><b>Queried profileID</b>: ' . $profileID . '</p>';
 469 ]]></programlisting>
 470         </sect3>
 471     </sect2>
 472
 473     <sect2 id="zend.gdata.health.notice">
 474         <title>Sending Notices to the Register Feed</title>
 475
 476         <para>
 477             Individual posts to the register feed are known as notices. Notice are sent from
 478             third-party applications to inform the user of a new event. With AuthSub/OAuth, notices
 479             are the single means by which your application can add new CCR information into a user's
 480             profile. Notices can contain plain text (including certain <acronym>XHTML</acronym>
 481             elements), a CCR document, or both. As an example, notices might be sent to remind users
 482             to pick up a prescription, or they might contain lab results in the CCR format.
 483         </para>
 484
 485         <sect3 id="zend.gdata.health.notice.send">
 486             <title>Sending a notice</title>
 487
 488             <para>
 489                 Notices can be sent by using the <methodname>sendHealthNotice()</methodname> method
 490                 for the Health service:
 491             </para>
 492
 493             <programlisting language="php"><![CDATA[
 494 $healthService = new Zend_Gdata_Health($client);
 495
 496 $subject = "Title of your notice goes here";
 497 $body = "Notice body can contain <b>html</b> entities";
 498 $ccr = '<ContinuityOfCareRecord xmlns="urn:astm-org:CCR">
 499   <Body>
 500    <Problems>
 501     <Problem>
 502       <DateTime>
 503         <Type><Text>Start date</Text></Type>
 504         <ExactDateTime>2007-04-04T07:00:00Z</ExactDateTime>
 505       </DateTime>
 506       <Description>
 507         <Text>Aortic valve disorders</Text>
 508         <Code>
 509           <Value>410.10</Value>
 510           <CodingSystem>ICD9</CodingSystem>
 511           <Version>2004</Version>
 512         </Code>
 513       </Description>
 514       <Status><Text>Active</Text></Status>
 515     </Problem>
 516   </Problems>
 517   </Body>
 518 </ContinuityOfCareRecord>';
 519
 520 $responseEntry = $healthService->sendHealthNotice($subject,
 521                                                   $body,
 522                                                   "html",
 523                                                   $ccr);
 524 ]]></programlisting>
 525         </sect3>
 526     </sect2>
 527 </sect1>