Skip to main content

Terra Integration

Schema

Involved Parts​

Terra-service​

  • A new service, exposed to the open internet, implementing payload validation according to Terra documentation.
  • Connects to a distinct database per tenant.

Krane-base-app​

  • Coordinates the flow initialization.
  • Authorizes Terra into the patient wearable app.
  • For wearables without a cloud API, Terra SDK will use Terra API on its own.

Tenant-service​

  • Terra service should use a new database to store wearables payloads, with a distinct database per tenant.

Krane-base-app​

The basic idea is to:

  • Connect Terra with the wearable cloud.
  • Authorize Terra with the wearable cloud.
  • Store and process the data via a webhook which Terra interacts with each time there is a new data batch.
  • For those wearable providers which do not have cloud, Terra SDK will interact with Terra.
  • Terra SDK is also used to authorize Terra against providers.

Terra provides SDKs for native Android (Java), iOS, and React Native. The decision on which one to use has to be made later.

No implementation has been done yet. According to the documentation, a connection widget can be used as follows:

terra
    .generateWidgetSession({
      referenceID: "userid",
      providers: ["CRONOMETER", "OURA"],
      authSuccessRedirectUrl: "https://success.com",
      authFailureRedirectUrl: "https://failure.com",
  		language: 'en'
    })
    .then((s) => {
      console.log(s);
    });

In the interaction with Terra, the referenceID plays a crucial role. It must uniquely combine a user identifier with the tenant name. This requirement stems from Terra's lack of tenant-specific functionalities, obligating terra-service to determine the appropriate database based on the provided payload.

Combining the Auth0 sub with organization metadata could serve as an effective identifier.

This process generates a one-time URL, facilitating authentication with specific wearable providers. Notably, certain providers like Apple and Samsung lack dedicated cloud services. In these cases, TerraSDK independently manages interactions with Terra, though specific prerequisites must be met as outlined in Terra's documentation for React Native projects.

Tenant-service​

A new role dedicated to Atlas management is proposed, to be assigned to terra-service. This role enables autonomous creation and access to its databases. To ensure synchronization between terra-service and tenant-service, the utilization of a Pulsar topic is recommended. Initial efforts in this direction have been documented in a GitHub pull request, though its efficacy remains unverified.

Terra-service​

Terra-service is designed as the primary endpoint for Terra's push notifications, employing a post method with a predefined payload. Key features of the service include:

  • Exposure to the open internet without the use of traditional authentication methods. Instead, payload signing is proposed for authentication purposes, with a 403 error response in cases of malformed or unintended actions.
  • Storage of data in tenant-specific databases, determined by parsing the referenceID from Terra's payloads. The referenceId itself is a custom composite of a user's sub and the tenant name.

Initial boilerplate work for terra-service has been undertaken, as seen in this GitHub pull request, with additional guidelines on receiving webhooks from Terra.