Smart Connect: Locating & Managing Connections

This workflow demonstrates how to enable b.well's Smart Connect feature to locate health records across healthcare networks, establish connections for data retrieval through Individual Access Service (IAS), and manage your connections once established. An end-to-end integration diagram can be accessed here: Smart Connect Flow Diagram

Prerequisites

• health.network enabled for access to b.well network connections (QHIN / TEFCA workflows).
• Identity Verification (IAL2) - Verification at IAL2 (Identity Assurance Level 2) must be completed
• Initialize and Authenticate - SDK must be initialized and user authenticated
• Account Creation and Consent - User account creation and consent must be completed

Workflow Steps

Step 1: Enable Smart Connect

Enable Smart Connect by creating a Consent that triggers the network record locator service (RLS). This consent initiates a query to designated QHINs to locate the user's health records across participating organizations.

TypeScript SDK Example:

import { CreateConsentRequest } from "@icanbwell/bwell-sdk-ts";

const result = await sdk.user.createConsent(
  new CreateConsentRequest({
    status: "active",
    provision: "permit",
    category: "IAS_IMPORT_RECORDS",
  }),
);

if (result.failure()) {
  // Implement error handling
}

const consent = result.data();

Step 2: Check Network Search & Data Retrieval Status (Optional)

After enabling Smart Connect consent, the platform will run in the background to locate records and/or retrieve data. You can optionally poll tasks to determine readiness/completion before proceeding.

TypeScript SDK Example:

import { GetTasksRequest } from "@icanbwell/bwell-sdk-ts";

const tasksResult = await sdk.activity.getTasks(
  new GetTasksRequest({
    code: {
      value: {
        code: "network-data-retrieval",
      },
    },
  }),
);

if (tasksResult.hasError()) {
  console.error("Failed to fetch tasks", tasksResult.error);
} else {
  const tasks = tasksResult.data();
}

📘

Returned IAS connections will be one of two types depending on the data source:

1. Connections that are automatically established on the user’s behalf using the IAL2 token (viewable in getMemberConnections, additional documentation found in the Establishing and Managing Connections workflow guide)
2. Connections that require the user to authenticate (viewable in getCareTeams, see documentation below)

Step 3: Retrieve Recommended Connections Requiring User Action (OAuth)

Use the getCareTeams method to retrieve data sources found by the network record locator service that require additional user authentication.

Note: Records located that meet one of the following criteria will have connections established automatically without additional user intervention. These connections will be available in the getMemberConnections response and will NOT appear in the careTeams response:

1. The data source has already been connected through Patient Right of Access (PROA)
2. The data source accepts an IAL2 token without additional user authentication

TypeScript SDK Example:

import { CareTeamsRequest } from "@icanbwell/bwell-sdk-ts";

export async function getCareTeams(sdk: any) {
  const careTeamsResult = await sdk.health.getCareTeams(
    new CareTeamsRequest({
      page: 0,
      pageSize: 50,
      code: {
        value: {
          code: "recommended-connections",
        },
      },
    }),
  );
}

Step 4: Retrieve the OAuth authorization URL

Use the participant.member.alias from the getCareTeams response (ex. epic_on_fhir_sandbox) as the connectionId in the getOauthUrl method to retrieve the OAuth URL.

Step 5: Launch Authentication Flow

Direct the user to the redirectUrl returned by getOauthUrl. This URL initiates the OAuth authentication flow where the user securely logs into the healthcare provider's portal and authorizes b.well to access their health records.

Once the user completes the OAuth flow, they will be redirected back to your application, and the connection will be established for automatic data retrieval.

Re-Connect a Disconnected or Deleted IAS connection

Connections with a status such as EXPIRED, DISCONNECTED, or DELETED may be re-established depending on their integrationType.

Method A: OAuth Re-Authentication (OAuth/indirect IAS connections)

If the connection has an integrationType of PROA or INDIRECT_IAS, generate a new OAuth URL passing the connectionId from the getMemberConnections response in the getOauthUrl method and redirect again.

Method B: Direct Activation (direct IAS connections)

If the connection has an integrationType of DIRECT_IAS, pass the connectionId from the getMemberConnections response in the activateDirectConnection method.

Revoke & Re-enable IAS Consent

To revoke IAS consent, create/update consent with provision set to deny. To re-enable, set provision to permit again.

ℹ️

Revoking IAS consent will update IAS connections to ACCESS_ENDED. Re-enabling will automatically restore ACCESS_ENDED connections. Connections explicitly disconnected by the user may remain DISCONNECTED.

TypeScript SDK Example (revoke):

import { CreateConsentRequest } from "@icanbwell/bwell-sdk-ts";

const revokeResult = await sdk.user.createConsent(
  new CreateConsentRequest({
    status: "active",
    provision: "deny",
    category: "IAS_IMPORT_RECORDS",
  }),
);