Retrieve a User's Data Connections

Retrieving User Connection Records

Overview

The getMemberConnections method in the b.well SDK is designed to fetch all connection records associated with a user. This function is key for accessing a comprehensive list of the user's data connections.

Method Signature

suspend fun getMemberConnections(request: MemberConnectionsRequest? = null) : BWellResult<Connection>

BWellResult<Connection>: Returns an object containing a collection of Connection objects, FHIR OperationOutcome, and paging information.

The Connection object includes:

id: string
name: string
category: ConnectionCategory (BASIC, OAUTH, IDENTITY)
type: ConnectionType (PRACTITIONER, CLINICAL, INSURANCE, LAB, PHARMACY)
integrationType: IntegrationType? (DIRECT_IAS, INDIRECT_IAS, PROA)
status: ConnectionStatus? (CONNECTED, DISCONNECTED, EXPIRED, DELETED, ACCESS_ENDED)
syncStatus: SyncStatus? (PENDING, RETRIEVING, RETRIEVED, ERROR, DATA_DELETED, DELETING)
syncErrors: List<Coding>? (PERSON_MATCHING_ERROR, CONNECTION_ERROR, MAPPING_ERROR, ENRICHMENT_ERROR)
statusUpdated: Date
lastSynced: Date
created: Date
isDirect: boolean

Example Usage

When invoked, this method retrieves all the connections linked to the user's account. These connections can include various healthcare entities such as providers, clinics, health systems, hospitals, or labs.

The MemberConnectionsRequest can be filtered by integrationType and/or status

integrationType: The type of connection. Possible values are: INDIRECT_IAS, DIRECT_IAS, PROA
status: Status of connection. Possible values are: CONNECTED, DISCONNECTED, EXPIRED, DELETED, ACCESS_ENDED

val memberConnectionsRequest = MemberConnectionsRequest.Builder()
  .integrationType(listOf(IntegrationType.DIRECT_IAS, IntegrationType.INDIRECT_IAS))
  .status(listOf(ConnectionStatus.CONNECTED, ConnectionStatus.DISCONNECTED))
  .build()

Note: The MemberConnectionsRequest is optional. Default behavior is to not return DATA_DELETED connections. Connections withsyncStatus: DATA_DELETED can only be retrieved when any filters are provided.

Understanding `syncErrors`

The syncErrors attribute is a list that can contain multiple Coding objects. Each Coding object represents a specific error encountered during the data synchronization process. The fields within a Coding object include:

code: A string identifier for the type of error.
display: A user-friendly description of the error.

Error Codes and Displays

Each code in the Coding object corresponds to a particular synchronization issue, described as follows:

PERSON_MATCHING_ERROR: This error occurs when the system fails to match the incoming data to a b.well person record. As a result, all of the health data from the given connection will be unavailable for retrieval through the health data methods in the SDK.
CONNECTION_ERROR: This error is reported when there is a failure in establishing or maintaining a connection either to the data source or internal servers. As a result, some or all of the health data from the given connection may be unavailable for retrieval through the health data methods in the SDK.
MAPPING_ERROR: This error arises during the process of mapping source data to standardized R4 FHIR formats. As a result, some or all of the health data from the given connection may be unavailable for retrieval through the health data methods in the SDK.
ENRICHMENT_ERROR: This occurs when there is a failure in executing the intelligence layer which is responsible for enriching the data. As a result, some or all of the health data from the given connection may be unavailable for retrieval through the health data methods in the SDK.

Each display provides a human-readable explanation aligned with its respective code:

PERSON_MATCHING_ERROR: "Failure to match to a b.well person."
CONNECTION_ERROR: "Failure in connecting to source or internal servers."
MAPPING_ERROR: "Failure to map source data to R4 FHIR."
ENRICHMENT_ERROR: "Failure to run intelligence layer."

Best Practices

Monitor Connection Objects: Regularly check the syncStatus and syncErrors fields in your Connection objects to understand the current state and any issues.
Paging Information: Utilize the provided paging information to effectively navigate through a large number of connections.
Understanding OperationOutcome: Familiarize yourself with the FHIR OperationOutcome for insights into the success or any issues encountered during the fetch operation.

Please review the [Connection State Diagram](As a result, some or all of the health data from the given connection may be unavailable for retrieval through the health data methods in the SDK.) for further understanding of the various connection and data retrieval statuses.