Retrieve Individual Access Connections & Status

Retrieving a User's Individual Access Records

Overview

The b.well SDK will fetch all Individual Access Service (IAS) connection records associated with a user once the user is IAL2 verified and has provided the appropriate consent.

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

• Connections that are automatically established on the user’s behalf using the IAL2 token (viewable in getMemberConnections, additional documentation found in the Retrieve a User's Data Connections method guide)
• Connections that require the user to authenticate (viewable in getCareTeams, see documentation below)

Method Signature

suspend fun getCareTeams(request: CareTeamsRequest?): BWellResult<CareTeam>

• request: Defines the category within the CareTeam object for fetching the desired resources.
• BWellResult<CareTeam>: Returns an object containing a list of CareTeam objects.
• The CareTeam object includes:

id: string
name: string
meta: Meta
identifier: List<Identifier>
category: List<CodeableConcept>
participant: List<CareTeamParticipant>

Sample Code

Here's an example demonstrating how to use the getCareTeams method:

val careTeamsRequest = CareTeamsRequest.Builder()
    .category("recommended-connections")
    .page(0)
    .pageSize(10)
    .build()

getCareTeams(careTeamsRequest)

Detailed Explanation

1. CareTeamsRequest Builder:
   • A builder pattern is used to construct a CareTeamsRequest object, allowing for easy setting of various CareTeam properties:
     • category: Use the category property shown in the sample code above to filter the response to only include recommended-connections. This will return a list of connections found by the network record location service that need user authentication to establish the connection.
2. Handling Indirect Connections:
   • The method getCareTeams returns a CareTeam object. The participant property can be used to compile the list of recommended (indirect) IAS connections:
     • participant.member.alias contains the datasourceId that can be used to Retrieve an OAuth URL.
3. Handling Direct Connections:
   • Direct connections returned within getMemberConnections have successfully retrieved data and the status will automatically be set to Retrieved so that the connection can be shown as "active" or "connected".

Best Practices

• Validating Input: Ensure that the fields set in CareTeamsRequest are validated for correctness before calling the getCareTeams method.
• Error Handling: Implement robust error handling to manage potential failures, such as invalid data or network issues.
• Pre-Requisites for Successful Retrieval: The user must have been IAL2 verified and then have granted Consent:
  • Use the IAS_IMPORT_RECORDS ConsentCategory like this example code

val createConsentRequest = ConsentCreateRequest.Builder()
  .category(ConsentCategoryCode.IAS_IMPORT_RECORDS)
  .provision(ConsentProvisionType.PERMIT)
  .status(ConsentStatus.ACTIVE)
  .build()

• See the Individual Access Service Flow diagram for full flow details

Retrieving User Individual Access Status

Overview

The b.well SDK provides a mechanism to fetch the status of IAS network request for the user. This uses the same underlying Task infrastructure that powers Insights.

Method Signature

suspend fun getTasks(request: TasksRequest): BWellResult<Task>

• request: A TasksRequest object containing search criteria.
• BWellResult<Task>: Returns a collection of FHIR Task resources, FHIR OperationOutcome, and paging information.

See Retrieve Tasks for a User for full details of this method.

Sample Code

To retrieve the status of the IAS Network request, filter the Tasks by network-data-retrieval as seen in this sample code:

val taskRequest = TasksRequest.Builder()
  .activityType(listOf("network-data-retrieval"))
  .performerType(listOf("system"))
  .build()
getTasks(taskRequest)

The Task status represents the current state of IAS Network request:

• READY: Data pull not started but consent has been granted
• IN_PROGRESS: Data pull in progress
• COMPLETED: Data pull completed successfully
• FAILED: Data pull encountered an issue
• REJECTED: User has revoked consent, no further data pulls will occur

Best Practices

• Note: These tasks are distinct from the Insights a user sees in the UI. enrichContent is not supported.
• Pre-Requisites: There will not be a Task created until a Consent is granted