Getting Started | Onegevity Health Intelligence

# Overview

This page presents a high-level overview of what the Onegevity Health Intelligence Service offers as well as general guidance of what is needed and what to expect when planning an integration project.

Specific technical details can be found on our Integration Documentation page.

# Requirements

The Onegevity Health Intelligence Service is a fully-managed, cloud solution that encapsulates much of the complexity of managing and analyzing vast amounts of highly sensitive data and provides many tools to make it easy to harness that information and put it to work in your business domain. However it is not a turn-key solution and does require some technical investment by our clients to securely and safely integrate the service into their existing systems.

While the requirements for working with this service depend upon the integration pattern you seek to employ, a typical set of requirements include:

A functioning web application that you maintain that:
- is secured by TLS/SSL
- implements a login feature to protect customer data from unauthorized access
- you have the technical ability to update to integrate JavaScript-based widgets
Ability to make DNS record changes for the domain where your web application is hosted
Familiarity with using REST APIs
A means of collecting payment from your customers if you are selling access to these services
A means of communicating with your customers when their results are ready

Further considerations of technical and process-oriented requirements are discussed in the Integration Patterns section.

# Definitions

The following are common terms that will appear throughout the documentation.

Term	Definition
Patient	An individual who takes our health tests and/or receives our analysis. Depending on your use case, these are your customers, patients, partners, employees, etc.
Package	A set of testing and analysis services that can be administered to a patient. Packages use lab work and surveys as inputs and generate Recommendations and Reports as outputs
Lab Work	A lab analysis of a biological sample collected by/from a patient.
Survey	A set of questions about health history, symptoms, diet and lifestyle habits, etc. that is filled out by a patient.
Order	A request to administer the testing/analysis of a given package to a specific patient.
Results	Specifically the direct measurements from a health test or computed calculations derived from those direct measurements. For example: HDL Cholesterol and Total Cholesterol are directly measured result, while the Total:HDL Cholesterol Ratio is a calculated result
Recommendation	A set of actions recommended to a patient based on the results of their lab work and survey answers.
Report	A structured representation of the final outputs of a patients order, including results, analysis, and recommendations.
Fulfillment Request	A request to have physical products (for example test kits or recommended products) shipped to a recipient on your behalf.

# Process lifecycle

The following interaction diagram illustrates the typical process lifecycle for a client integrating with the Onegevity Health Intelligence Service. Depending upon your use case and integration methodology some of these steps may be different or excluded altogether.

# Requesting services

The first step in the process is determining when and which services are required for a member of your customer pool. This can vary greatly depending upon your specific needs, but examples include:

A customer purchases analysis services on your e-commerce website
A physician orders a test performed through your EHR system
You direct a client to take a test as part of your consultation services

Limitations on requesting services

There are some limitations and restrictions enforced for requesting services that you should be aware of:

Patients receiving services must be at least 18 years of age
Due to state and local restrictions, not all testing services are available everywhere

# Registering a patient

Once it has been determined that services should be provided for your customer, you must first register them as a patient within the Onegevity service. A minimal amount of demographic information is required along with a unique identifier for this individual that means something to your system. This could be a customer number, patient identifier, or database id. This identifier should not include any personally identifying information. For example, do not use a customer's email address as the unique identifier. A suitable alternative would be to use a one-way hashing function on their email address to provide a unique and opaque identifier.

# Placing an order

Placing an order requests the analysis services of a specific Onegevity package be performed for a given patient. If the package ordered utilizes physicial sample collection kits, you have the option of maintaining your own inventory or you may request the kit be shipped to your patient by our fulfillment partner. In either case, an address must be provided for the patient to establish their primary residence for purposes of following state and local guidelines for requisitioning lab testing services.

# Activating test kit

Activating the test kit is a critically important part of the process as it ties together the physical kit contents with the patient who will be collecting the sample using the kit. Onegevity provides a drop-in web UI library that can be used on your website to provide your users with a kit activation form. Alternatively you may implement your own mechanism for registering which kits are given to which customers.

Activating kits is a crucial step

Avoid delays in processing your patients test results by ensuring that they activate their test kits. Without this step it can be difficult to determine who a collected kit sample belongs to and may delay or preclude the processing of the sample

# Completing survey

Collecting timely and accurate health, lifestyle, behavior information from your patients is an important part of creating the most accurate and tailored analysis of their health. Conditions change over time and, therefore, we recommend patients update their health history by completing the appropriate surveys for the analysis package ordered for them. This provides the Onegevity system with the most up-to-date information for its analysis purposes and provides you with longitudinal data about your patient population as their health and habits change over time.

# Collecting a sample

Depending on the type of analysis package ordered for the patient, this step may involve collecting saliva, urine, stool, or blood using an at-home sample collection kit or it may involve making and attending an appointment to get blood drawn by a phlebotomist. At-home sample collection kits contain detailed instructions and return packaging that your patient uses to ship their sample directly to our lab partner who will process the sample. For in-person blood draws, the phlebotomist handles sending blood samples to the lab for processing.

# Receiving labwork results

The Onegevity service handles the complexities of securely interchanging ePHI data with our partner labs and pulls in the lab results as soon as they are released. Once all labwork results have been received the Onegevity system begins its analysis process to generate the final results, recommendations, and reports.

Critical results

In some instances labwork results may report a "critical result" that indicates a patient's levels are significantly out of normal range and could represent an adverse health situation that should be looked into further with their physician. In these cases our lab partner performs patient outreach, typically via phone call, to notify the patient in a timely manner that they should see their doctor for a follow-up consultation.

Onegevity provides a drop-in UI library for surfacing and visualizing the final reports, recommendations, and labwork results within your web application. Alternatively you can access this information programmatically via API and ingest into your own system and provide your own method of sharing the results with your patients.

# Integration Patterns

Onegevity provides capabilities for several different ways of integrating its service to try and meet as many needs as reasonably possible. Which pattern you choose depends on your business needs, your existing technology stack, your ability to securely store and manage ePHI data, as well as your comfort and ability with the technologies used in each. Below is a brief description of the possible integration patterns and the tradeoffs of using each:

# Embedded Onegevity Single Page Application (SPA)

The Onegevity Single Page Application (SPA) approach provides the easiest on-ramp to integrating Onegevity services into your web application by providing all of the functionality you need to place orders for patients, activate kits and collect survey responses, and to surface final reports and recommendations to your end user. The SPA leverages the Onegevity UI-Kit embeddable widgets which means that all communication of ePHI data is done directly from your customer's browser to Onegevity API servers and the sensitive data never passes through your system.

The drawbacks to this approach are that you have no control over the page flows and how the information is presented to the customer, as it is all embedded into a single page application that is hosted on a web page. While you have some ability to customize the presentation by using CSS overrides, the overall structure and presentation of the data is limited to what we provide. Maintaining security in an all-JavaScript environment is not trivial and you will need to do some server-side coding to help establish trust between the customer's browser and the Onegevity API.

# Embedded Onegevity widgets

Using the Onegevity UI-Kit widgets directly provides a degree of freedom in the user page flow by allowing you to place the individual widgets into your own pages and control when they are displayed. For instance you can provide access to filling out surveys on one page using the survey widget and display test results to the user on a separate page using the reports widget. Using these embeddable widgets means that all communication of ePHI data is done directly from your customer's browser to Onegevity API servers and the sensitive data never passes through your system.

The drawbacks to this approach are that you are doing more coding on more pages. While you have some ability to customize the presentation by using CSS overrides, the overall structure and presentation of the data is limited to what we provide. Maintaining security in an all-JavaScript environment is not trivial and you will need to do some server-side coding to help establish trust between the customer's browser and the Onegevity API.

# API with Onegevity UI-Kit frontend library

In some cases you may not be able to or may not wish to use the embedded widget approach and, instead, wish to have your customer's browser communicate only with your server. In this case you implement the communication with the Onegevity API in the backend of your web application and surface the data to your customers however you see fit. Some of the data is straightforward and simple to visualize, but some of it is quite complex. If desired you have the ability to use the Onegevity UI-Kit library just for presentation only, where you provide the data from your own backend but don't have to write any of the code to visualize complex data sets like reports and test results or implement the dynamic behavior of surveys.

The drawbacks to this approach are primarily that ePHI data is now passing through your systems and you will be responsible for securely handling that data. You will also be responsible for implementing the OAuth2 client authorization to our API and will need implement the logic to call our APIs. More information can be found by reading the API Documentation.

# API only

You can also choose to integrate by using only our API. This can be ideal if you do not need to create a visual presentation to your end users or if you wish to integrate the results into your own UI or if you are building a non-web-based application.

You may also find our API-Only Workflow cookbook page helpful.

# Webhooks

The process lifecycle for Onegevity Health Intelligence analysis is a lengthy one with many touch-points involving several systems as well as manual intervention on the part of the end user as well as our fulfillment and lab partners. To provide insight into the process the Onegevity system utilizes webhook technology to keep your system notified as events happen throughout the process lifecycle. Example use cases might be to send an email to your customer when their kit has shipped or to send a push notification when their test results are available.

Making use of webhooks is an additional integration component that complements any of the above integration patterns and is highly recommended in order to provide your systems and users the best possible visibility into the Onegevity process lifecycle.

In order to utilize webhooks you must implement a publicly accessible web endpoint that the Onegevity service can call to notify your system of events. More technical details about webhooks can be found in the Integration Reference.

# Product fulfillment and drop-shipping

The Onegevity Health Intelligence system also provides fulfillment integration with our product manufacturing partner, Thorne, which gives you access to the full Thorne catalog of nutritional supplements and the ability to request drop-shipping of those products to your customers via API. This capability allows you to recommend and sell Thorne products directly to your customer through your own website while leaving the logistics of product inventory and fulfillment to Thorne.

Note

You'll need to register an account on Thorne.com or use an existing account if you wish to take advantage of this capability