HealthJibe Connect makes integrating your consumer health information service to a variety of consumer selected health management services as easy as connecting an eCommerce application to the payment card networks.
Here’s how it works (Click here for an overview diagram):
- Implement an OAUTH Consumer capability that adheres to the OAUTH core authorization protocol as described here.
- Display a Connect with HealthJibe button on your website or application that invokes the OAUTH process
- After completing the OAUTH process and receiving an Access Token:
- Your website redirects the user to the HealthJibe CONFIGURATION endpoint URL (https://www.healthjibe.net/jibe/configure) where the user is able to choose one or more destination health management services for the health data sent from your service. This request must contain a callback URL parameter (raz_callback) that HealthJibe will use to redirect the user back to your website. This request can also contain a user parameter (user) that is a unique ID created by the calling application to identify a specific user. The user parameter can be used to identify a specific user by applications that allow multiple users under a single account.
- HealthJibe redirects the user back to your website at the completion of the configuration process, providing a seamless user experience for the user. In addition to the oauth_token query string parameter and the oauth_verifier parameter, HealthJibe will append a query string parameter to the callback request (raz_notification_status) that indicates if health information should continue to be sent for this user (false = no longer send health information).
- The health data is sent in the body of a SOURCENOTIFICATION request as a parameter (her) and is formatted as a Continuity of Care (CCR) XML document, or as a string of Open Mobile Health Exchange (OMHE) commands. The content type of the POST request must be set to: “application/x-www-form-urlencoded”. The SOURCENOTIFICATION can also contain a “user” parameter to identify the specific user that the health information is intended for. When a “user” parameter is provided, health information is transferred to each HMS connection maintained by that user. If the “user” parameter is missing the health information is sent to all connections linked to the HealthJibe account. The user parameter is created by the calling application to track user connections (maximum 50 characters).
- The gateway will include a status parameter in the Result stream (raz_notification_status) that indicates if future device notifications should continue to be sent for this user/device (false = no longer send notifications).
- The gateway will include an ACK parameter -– set to Success or Failure and indicates whether the operation was successful or not
- On error conditions the gateway will include an error message parameter in the Result stream (errormsg) to further explain the error condition for debugging purposes.
Your service can also read data from any health management service the user linked to your service. Because the user may have multiple HMS connections, this is a two-step process:
- Your application or website sends a signed OAUTH request to the HMSLIST endpoint (URL: https://www.razcode.net/gateway/hmslist) using the access token for the user. The HMSLIST operation can contain a “user” parameter to identify the specific user that the calling application is reading information for.
- HealthJibe will return an ACK parameter (set to Success or Failure) and a “list” parameter which is a JSON array containing the names for each HMS linked to your service (e.g. ["hms1","hms2","hms3"]). An errormsg parameter is also included when ACK is set to Failure.
- Your application or website must display this list to the user in order for he or she to select the HMS they would like to read via your service.
- Your application or website makes a signed OAUTH request to the HMSREAD endpoint on the RAZCODE Gateway (URL: https://www.razcode.net/gateway/hmsread) with a required query string parameter (hms) set to the name of the HMS selected by the user (e.g. hms=hms1). In addition there are two optional parameters, startdate (format: mmddyyyy) and enddate (format: mmddyyyy) that allows the user to read data within a specific time period (note: your application was prompt the user for the start and end dates). If both startdate and enddate are missing or empty, all data is retrieved.
- HealthJibe will return an ACK parameter (set to Success or Failure) and a “her” parameter which is an URL Encoded XML document formatted according to the Continuity-of-Care Record (CCR) in the body of the response. An errormsg parameter is also included when ACK is set to Failure.
Your website or application can redirect the user to the HealthJibe CONFIGURATION endpoint URL whenever the user wishes to modify the source configuration from your website. This OAUTH signed request must contain a callback URL query string parameter (raz_callback) so that the user can be returned to your website at the completion of the configuration process.
- Please remember that you do not implement the entire OAUTH authorization process as described above on subsequent calls to the Configuration endpoint. The OAUTH authorization process is completed only once. Subsequent calls to the Configuration endpoint are used to allow the user to modify the connections he or she has made between your service and HealthJibe. Simply use the access token you have stored for this user to make the OAUTH request.
- In addition to the oauth_token query string parameter and the oauth_verifier parameter, HealthJibe will append a query string parameter to the callback request (raz_notification_status) that indicates if future device notifications should continue to be sent for this user/device (false = no longer send notifications).
