Establishing and Managing Connections

This guide demonstrates how to manage existing data connections. The workflow provides operations to disconnect or delete specific data connections associated with a user's account and re-establish data connections that were disconnected or may have expired.

Prerequisites

• Completed Authentication and Account Creation

Summary of Available Operations

1. Establish Connections
2. View Established Connections
3. Disconnect Connection
4. Re-Establish Connection
5. Delete Connection

1. Establish Connections

OAuth Connections

The getOauthUrl method in the b.well SDK is designed to retrieve an OAuth URL for a specific data source, facilitating the OAuth authentication flow for that connection.

1. Provide Connection ID:

   • Specify the connectionId corresponding to the connection for which the OAuth flow is to be initiated.

2. Retrieve URL:

   • The method returns a user-specific, absolute URL that initiates the OAuth authentication process with the specified data source.
   • This URL can be opened in a webview within your client application to guide the user through the authentication flow.

3. Security Considerations:

   • Handle the retrieved OAuth URL securely, as it is unique to the authenticated user and critical to the security of the authentication process.
   • Do not share or log the URL, as it may contain sensitive authentication tokens.

Additional Connection Methods

Direct Connections

Some data sources support direct connections that do not require user credentials or an OAuth flow. These connections use the integrationType of DIRECT.

Use createConnection with integrationType set to DIRECT to establish a direct connection. No username or password is needed.

await sdk.connection.createConnection(                                            
   new ConnectionRequest({
     connectionId: 'labcorp-123',                                              
     integrationType: 'DIRECT',                                              
   })
  );

Basic Connections

For credential-based connections (non-DIRECT), provide username, password, and optionally integrationType:

await sdk.connection.createConnection(                                     
   new ConnectionRequest({
     connectionId: 'epic-123',       
     username: 'user',                                             
     password: 'pass',                                             
     integrationType: 'PROA',                                              
   })                                        
  );

When integrationType is not specified, both username and password are required.

2. View Established Connections

Use getMemberConnections to retrieve all connection records associated with a user. This list includes the connection status, data sync status, and sync errors for each connection.

3. Disconnect Connection

Use disconnectConnection to disconnect a specific existing data connection for a user. This will prevent future retrieval from the specific connection but existing data remains on the account.

4. Re-Establish Connection

The getMemberConnections response returns a list of connections and the corresponding connection statuses. For any connection in the list with a status of EXPIRED or DISCONNECTED, the id can be used as the connectionId in getOauthUrlto allow the user to authenticate and re-establish the connection.

5. Delete Connection

Use deleteConnection to delete a specific existing connection. This will asynchronously delete existing data and prevent future retrieval from the specific connection (unless the user re-establishes the connection).

For complete request and response schema, see ConnectionManager documentation.