Configuration Concepts

For any system to work, configuration must exist at some level. We use a configuration model comprised of Tenants, Organizations, Devices, and Behaviors. Each of these elements work in concert to manage and deliver integration based on your specific needs.

Term	Definition
Tenant	Tenants are our highest level concept used to segment the system. Tenants represent our customers, and tenants are used to represent entities with which we have an interoperability-type relationship for exchanging information on behalf of our customers
Organization	Organizations provide a level of subdivision within a tenant. Each tenant has at least one organization that is equal to the tenant itself, but many organizations can be added to represent different entities or facilities/locations which need to be identified separately when performing API calls.
Device	Devices represent different systems within an organization. Each Organization will have at least one device, but many can be added to support organizations which manage multiple systems that each have a unique identity for the patient. API Tokens are issued at the Device level.
Behavior	Behaviors represent the work that the device will perform by making various API calls. Each API call made by the device is equal to a behavior.

The above concepts are the core of our API system. Explained more simply, think about this from the bottom up. A Behavior is a type of exchange (e.g., fhir-query, ihe_document_query). Devices are used to enable the Behaviors for use by an Organization. And finally, Organizations are grouped into Tenants to allow for federation.

To provide a more concrete understanding let's walk through a couple of scenarios:

Customer with parent organization and subsidiaries connects to FHIR

Sample Co is a large national organization with three subsidiaries that operate underneath its umbrella. Sample Co desires to provide FHIR-based data acquisition services to its subsidiaries through the OneRecord API platform.

As Sample Co is the parent company, it is configured as the Tenant within our system, and each of its subsidiaries are configured as Subsidiary A, Subsidiary B, and Subsidiary C as Organizations. Each of these subsidiaries are their own Organization - that is, they each have individual configuration entries in our system.

In order to enable FHIR data retrieval for any of the Organizations we will need to use two Devices: One of these is an organization-specific Device, and the other is a system-wide Device. You can also think of these as a source-device and a target-device.

The first Device we need to configure is the source-device. This is the Device with metadata used by the Organization to connect to the target-device. The metadata in this source-device consists of FHIR data source-specific fields that contain values needed for those connections to happen successfully. For example, we will need to select the desired FHIR version (i.e., R4), or the list of FHIR Resource Types that the subsidiary is interested in and set those as the configuration values.

The second Device we need to configure contains the FHIR-specific Behaviors and knows how to connect to external FHIR endpoints (i.e., a health system's FHIR server where data is being retrieved from). This Device is a system-wide device because it is common to many implementations and available as an out of the box item. To enable an Organization to use FHIR we simply link the source-device to the target-device

Once this configuration is in place a unique API Token is generated for each of the subsidiaries and used in all of the calls that subsidiary makes to the OneRecord API for authentication.

Customer with no subsidiaries connects to CommonWell

Sample Co is a medium size organization operating as a sole entity and desires to access CCDA documents through the CommonWell network to serve its business needs.

Sample Co is configured as the Tenant within our system, and is also configured as the sole Organization that falls under the Tenant. If you recall from above, every Tenant must have at least one Organization and so this configuration meets that requirement.

The configuration and use of Devices and Behaviors is almost completely the same as outlined in the previous scenario, so I won't repeat the unnecessary bits here. The only difference is that this customer will use a different system-wide Device that is setup specifically for registering a patient, and querying for and retrieving documents from the CommonWell target-device.

A unique API Token will also be generated for this customer, but in this case only one API Token will be generated since there is only one Organization attached to the Tenant.

In Summary

The configuration and setup of customers in the OneRecord API can handle a multitude of scenarios. We laid out a couple of scenarios above, but the important thing to remember is that we designed the configuration to meet and exceed your organization's interoperability needs. We can handle interoperability at a "per Device" level - configuring different types of interoperability connections across and between different systems, handling federation of companies where needed, and adapt any of our built-in Device connectivity to meet whatever interoperability needs may exist.

Understanding the API Integrator Service

The Integrator Micro-Service acting in conjunction with the Tenant Service provides a set of Healthcare Interoperability Services for clients to connect to one or many sources of clinical data. Integrator Micro-Services are not just one Service but a definition of a pattern to use Tenant configurations to provide interoperability functionality in the form of Actors on connected devices. The design at a high level uses the following entity set:

The tenant service serves as a mean to retrieve information from a tenant device based on 2 things:

A JWT token that contains the id of the device
A service wired directly into a behavior

Behavior Based Service

A Behavior Based Service is a RESTful service intended to implement one or more Behaviors defined at the Tenant Service. A Behavior is simply a type of functionality, other systems such as CommonWell refer to this as transaction types. We call it Behavior because this is how it is defined in the Actor model. We have Devices that contain Actors each of which implements a particular Behavior.

Retrieving the Device Id from the JWT Token in the Request

Your service must be secured using JWT token authentication. This authentication is performed against the Tenant Service. The JDK provides the functionality needed to call the tenant service but you need to configure it in your application and use it in your code.

Loading a Device from the Tenant Service

Once you have a device id you can then use the tenant service to load all the metadata relevant to that device including its connected devices and actors.

Build a RequestWrapper

The RequestWrapper is a way to encapsulate device metadata and request data to be used by the SDK during execution of behaviors. It is used to find and load ActorServices and maintain transactional information across Actor executions. It’s built with a fluent API to make it simpler for the developer to
use.

Executing Actor Services

Once you have implemented your own RequestWrapper, you can send this into the SDK with a behavior id to let the SDK discover and run all ActorServices in all connected devices that implement the given behavior.

Identifying the Patient to the Data Source

The OneRecord API supports two ways of identifying the patient to the data source in order to retrieve the records for that patient.

DEMOGRAPHICS A set of demographics for the patient are passed through the API to the data source in order to match the patient and facilitate the retrieval of the matching records.
CREDENTIALS The patient's pre-established credentials with the data source are passed to the data source using the OAuth 2.0 protocol to facilitate the retrieval of the matching records.

Each of these methods apply to multiple use cases and types of end users such as providers, patients, and payers. Read more about the various use cases in the User Workflows section.