Medications

Note: Medication Module Class Diagram describes the relationships regarding the below Medication Related Resources

Retrieving Medication Groups

Overview

The getMedicationGroups method in the b.well SDK is designed to fetch a list of MedicationGroup resources. It uses a MedicationGroupsRequest object to define specific search criteria for medication groups.

Method Signature

suspend fun getMedicationGroups(request: MedicationGroupsRequest?): BWellResult<MedicationGroup>

request: Specifies the search criteria for retrieving MedicationGroup resources.
BWellResult<MedicationGroup>: Represents the list of Medication Groups retrieved.

Example Usage

val groupsRequest = MedicationGroupsRequest.Builder()
    .page() // Specify the page number
    .pageSize() // Specify the number of results per page
    .build()

suspend fun getMedicationGroupsList() {
    val medicationGroupsResult = BWellSdk.health.getMedicationGroups(groupsRequest)
    // Handle the retrieved Medication Groups
}

This code snippet demonstrates how to build a MedicationGroupsRequest and fetch medication groups based on the specified criteria.

Best Practices

Appropriately set page and pageSize in the request to manage the volume of results.
Handle the response to process the list of Medication Groups effectively.

Retrieving Medication Statements

Overview

The getMedicationStatements method in the b.well SDK is designed to fetch a list of MedicationStatement resources, based on criteria specified in the MedicationStatementsRequest object.

Method Signature

suspend fun getMedicationStatements(request: MedicationStatementsRequest?): BWellResult<MedicationStatement>

request: Object specifying search criteria for Medication Statements.
BWellResult<MedicationStatement>: Represents the list of medication statement records received.

Return Type

BwellResult<> containing list of MedicationStatements. Type of MedicationStatement is described below:

data class MedicationStatement(
    val id: String,
    val meta: Meta?,
    val status: MedicationStatementStatusCode?,
    val medication: CodeableConcept?,
    val reasonCode: List<CodeableConcept>?,
    val authoredOn: Date?,
    val requester: Actor?,
    val effectiveDate: Period?,
    val dosageInstruction: List<Dosage>?,
    val dispenseRequest: DispenseRequest?,
    val source: List<String>?,
    val derivedFrom: List<Reference> <-- When present, contains a Reference to resources from which the MedicationStatement was derived)


enum class MedicationStatementStatus {
    ACTIVE,       // Medication is currently being taken
    COMPLETED,    // Medication has been fully taken as prescribed
    ENTERED_IN_ERROR, // Statement was entered incorrectly
    INTENDED,     // Medication is intended to be taken
    STOPPED,      // Medication has been stopped
    ON_HOLD,      // Medication is temporarily paused
    UNKNOWN,      // Status is not known
    NOT_TAKEN     // Medication was prescribed but not taken
}

Parameters

ids (List<String>): A list of resource IDs to filter the search results.
lastUpdated (SearchDate): Specifies a date filter for retrieving resources updated after a certain date.
groupCode(SearchToken): Filters based on the group code
page (Int): The page number for paginated results
pageSize (Int): The number of results to return per page

Special Features

Medication Filtering: The medicationCode filter allows retrieval of Medication Statements with specific medication codes

Example Usage

The following example retrieves base medication statement resources based on groupCode while also setting the .lastUpdated parameter.

var request = MedicationStatementsRequest.Builder()
    .ids(listOf("medication-statement-id-1", "medication-statement-id-2"))
    .lastUpdated(
        SearchDate.Builder()
            .greaterThan(dateFormat.parse("2024-01-01"))
            .build()
    )
    .medicationCode(listOf(Coding(code = "specific-medication-code")))
    .page(0)
    .pageSize(20)
    .build()
val result = BWellSdk.health.getMedicationStatements(request)

Best Practices

Utilize MedicationStatementsRequest to fetch relevant medication statements.
Handle the response to effectively use the fetched data.

Retrieving Medication Requests

Overview

The getMedicationRequests method allows users to access a consolidated list of MedicationRequest resources. It provides various filtering options that can be employed to specifically retrieve the Medications with certain codes as well.

Method Signature

The function which fetches medication requests records related to a user.

suspend fun getMedicationRequest(request: MedicationRequestRequest?): BWellResult<getMedicationRequests>

request: Specifies the search criteria for retrieving MedicationRequest resources.
BWellResult<MedicationRequests>: Represents the list of Medication Requests retrieved.

Return Type

BwellResult<> containing list of MedicationRequests. Type of MedicationRequest is described below:

data class MedicationRequest(
    val id: String,
    val meta: Meta?,
    val status: MedicationRequestStatusCode,
    val category: List<CodeableConcept>?,
    val identifier: List<Identifier>?,
    val intent: MedicationRequestIntentCode,
    val medicationCodeableConcept: CodeableConcept?,
    val medicationReference: MedicationReference?,
    val text: Narrative?,
    val encounter: Encounter?,
    val authoredOn: Date?,
    val dosageInstruction: List<Dosage>?,
    val dispenseRequest: DispenseRequest?,
    val requester: Practitioner?,
    val recorder: Practitioner?,
    val subject: Patient?
)

class MedicationRequestStatusCode(override val code: MedicationRequestStatus?, override val display: String?) :
    Code<MedicationRequestStatus>
    
enum class MedicationRequestStatus {
    ACTIVE,
    ON_HOLD,
    CANCELLED,
    COMPLETED,
    ENTERED_IN_ERROR,
    STOPPED,
    DRAFT,
    UNKNOWN;
}

Parameters

ids (List<String>): A list of resource IDs to filter the search results.
lastUpdated (SearchDate): Specifies a date filter for retrieving resources updated after a certain date.
sort(List<String>): A list of sorting criteria for the search results
page (Int): The page number for paginated results
pageSize (Int): The number of results to return per page
medicationCode (SearchToken): Filters based on the medication code

Special Features

Medication Filtering: The medicationCode filter allows retrieval of Medication Statements with specific codes. RxNorm or NDC are preferred, but other systems are supported.

Example Usage

var request = MedicationRequestRequest.Builder() 
.ids(listOf("medication-request-id-1", "medication-request-id-2")) 
.lastUpdated(
    SearchDate.Builder()
            .greaterThan(dateFormat.parse("2024-01-01"))
            .build()
)
.groupCode(listOf(Coding(code = "209459"))) 
.page(0)
.pageSize(20)
.build()
val result = BWellSdk.health.getMedicationRequest(request)

Retrieving Medication Dispense

Overview

The getMedicationDispense method allows users to access a consolidated list of MedicationDispense resources. It provides various filtering options that can be employed to specifically retrieve medication dispense records with certain characteristics.

Method Signature

The function which fetches medication dispense records related to a user

suspend fun getMedicationDispense(request: MedicationDispenseRequest?): BWellResult.ResourceCollection<MedicationDispense>

request: Specifies the search criteria for retrieving MedicationDispense resources.
BWellResult<MedicationRequests>: Represents the list of Medication Requests retrieved.

Return Type

BwellResult<> containing list of MedicationDispense. Type of MedicationDispense is described below:

data class MedicationDispense(
    val id: String,
    val meta: Meta?,
    val status: MedicationDispenseStatusCode,
    val identifier: List<Identifier>?,
    val medicationCodeableConcept: CodeableConcept?,
    val medicationReference: MedicationReference?,
    val context: Encounter?,
    val performer: List<Performer?>?,
    val location: Location?,
    val type: CodeableConcept?,
    val quantity: Quantity?,
    val whenPrepared: Date?,
    val whenHandedOver: Date?,
    val dosageInstruction: List<Dosage>?
)

class MedicationDispenseStatusCode(
    override val code: MedicationDispenseStatus?, 
    override val display: String?
) : Code<MedicationDispenseStatus>

enum class MedicationDispenseStatus {
    PREPARATION,    
    IN_PROGRESS,    
    CANCELLED,      
    ON_HOLD,        
    COMPLETED,      
    ENTERED_IN_ERROR, 
    STOPPED,        
    DECLINED,       
    UNKNOWN         
}

Parameters

ids (List<String>): A list of resource IDs to filter the search results.
lastUpdated (SearchDate): Specifies a date filter for retrieving resources updated after a certain date.
sort(List<String>): A list of sorting criteria for the search results
page (Int): The page number for paginated results
pageSize (Int): The number of results to return per page
prescription (String): The id of the MedicationRequest for which to get MedicationDispenses.

Example Usage

var request = MedicationDispenseRequest.Builder()
    .ids(listOf("medication-dispense-id-1", "medication-dispense-id-2"))
    .lastUpdated(
        SearchDate.Builder()
            .greaterThan(dateFormat.parse("2024-01-01"))
            .build()
    )
    .page(0)
    .pageSize(20)
    .build()
val result = BWellSdk.health.getMedicationDispense(request)

Example Workflows

Fetching Source Data for a Derived MedicationStatement

If MedicationStatement.derivedFrom[n], then that MedicationStatement was derivedFrom another resource.

val result = BWellSdk.health.geMedicationStatements(request)
val medicationStatement = result.data?.firstOrNull()

// Assumming derivedFrom is present.
val reference = medicationStatement.derivedFrom.first().reference

//Assuming that the reference is "MedicationRequest/medication-request-id"
var request = MedicationRequestRequest.Builder() 
.ids(listOf("medication-request-id")) 
.build()
val result = BWellSdk.health.getMedicationRequest(request)

Fetching MedicationRequest History for a Medication

The user’s history of taking a certain medication.

val result = BWellSdk.health.geMedicationStatements(request)
val medicationStatement = result.data?.firstOrNull()

// Assumming derivedFrom is present.
val result = medicationStatement.derivedFrom?.filter {
	it.type?.startsWith("MedicationRequest")
}?.map { it.reference } ?: emptyList()

//Assuming that the reference is "MedicationRequest/medication-request-id"
var request = MedicationRequestRequest.Builder()
	.ids(result)
	.build()
val result = BWellSdk.health.getMedicationRequest(request)