Patient

Retrieving Patient Resources

Overview

The getPatients method in the b.well SDK fetches a list of Patient resources linked to the authenticated user's Person record. A single Person can have multiple Patient records (e.g., from different health systems). It utilizes the PatientRequest object to define search criteria.

Method Signature

suspend fun getPatients(request: PatientRequest?): BWellResult<Patient>

• request: An optional object defining the search criteria for Patient resources. If null, defaults are applied (page=0, pageSize=20, sort="-meta.lastUpdated").
• BWellResult<Patient>: Represents the list of Patients retrieved.

Data Class: Patient

• id: Unique identifier of the Patient.
• resourceType: The FHIR resource type (always "Patient").
• meta: Metadata about the Patient, including security tags identifying the owning health system.
• identifier: List of identifiers, each with a system and value.
• name: Name(s) of the Patient.
• telecom: Contact details for the Patient.
• gender: Administrative gender.
• birthDate: Date of birth.
• address: Physical addresses.
• communication: Preferred language(s).

Example Usage

The following example retrieves patient resources with pagination.

val patientRequest = PatientRequest.Builder()
    .page(0) // Specify the page number
    .pageSize(20) // Specify the number of results per page
    .build()

val patientsResult = BWellSdk.user.getPatients(patientRequest) as BWellResult.ResourceCollection
// Process retrieved Patient records

The following example retrieves patients updated within the last 30 days.

val thirtyDaysAgo = Calendar.getInstance().apply {
    add(Calendar.DAY_OF_YEAR, -30)
}.time

val patientRequest = PatientRequest.Builder()
    .lastUpdated(
        SearchDate.Builder()
            .greaterThan(thirtyDaysAgo)
            .build()
    )
    .build()

val patientsResult = BWellSdk.user.getPatients(patientRequest)
// Process retrieved Patient records

The following example finds a patient by health system and accesses their identifier.

val result = BWellSdk.user.getPatients(null) as BWellResult.ResourceCollection

// Find patient from Memorial Hospital using meta.security tags
val memorialPatient = result.data?.find { patient ->
    patient.meta?.security?.any { security ->
        security.system == "https://www.icanbwell.com/owner" &&
        security.code == "memorial_health"
    } == true
}

// Access the patient's identifier using the known system URI
val mrn = memorialPatient?.identifier?.find { identifier ->
    identifier.system == "http://memorial-health.example.org/mrn"
}?.value

Best Practices

• Utilize the PatientRequest to tailor the search to specific needs, including filtering by ids or lastUpdated.
• Use meta.security tags to identify which health system a Patient record belongs to (e.g., system = "https://www.icanbwell.com/owner").
• Use identifier.system to distinguish between identifiers from different health systems.
• Handle the response to process the list of Patient records effectively.