Event Management on FHIR Core

[dubdabasoduba]

Introduction

This discussion is to highlight the different event types and the different functions that need to the performed before or after each event.

Event Types

• Questionnaire Open & Closure
• Remote sync start & completion
• P2P sync start & completion
• Login & Logout

Event functions

• Redirecting to different parts of the app.
• Update different resources in the local database.
• Notify users of any changes
  • On-screen through different pages
  • Using Snack or Toast messages
• Refresh/Invalidate cache.
• Start/Stop Background jobs

Event Types & functions use cases.

1. Questionnaire Open & Closure

Update different resources in the local database.

Use Case 1: Child patient age update

• We have a child workflow that generates a child routine & child immunization CarePlan and Tasks. These should only be active when the Patient is < 5yrs old.
• If a user updates a patient's age to > 5yrs then the above CarePlans and Tasks should be canceled. This means the patient is now eligible for the CarePlan and subsequent Tasks.
• All this should be triggered from the family/patient registration questionnaires.

Use Case 2: ANC patient with a Pregnancy Outcome

• An ANC patient will have a pregnancy outcome form. When this form is submitted with a pregnancy outcome of any type the ANC CarePlan and Tasks should be canceled since the patient will move to a different workflow with a different CarePlan.

Use Case 3: Removing a patient or family

• If a patient/family is removed through the family or patient removal forms then all the CarePlans and Tasks for the patient/family should be marked as canceled.

Redirecting to different parts of the Application

Use Case 1: Redirecting to different screens

• After a patient/family member creation we would want to redirect to the Register or Profile. We need to make such interactions configurable since most of the deployments would want either of the 2 in different areas fo the Application.

Refresh/Invalidate cache.

Use Case 1: Removing a patient or family.

• Since we currently cache the registers and profiles data we need to refresh/invalidate the cache every time a patient or family is removed from the app.
• This is to make sure the UI shows the correct data at all times.
• The profile and registers to be refreshed have to be defined through the configs.

User Case 2: Tasks generation or cancellation.

• Tasks are generated when patients, practitioners, or families are enrolled in different workflows. The registers or profiles cache show be refreshed/invalidated every time this happens.

2. Remote / P2P sync start & completion

Notify users of any changes

Use Case 1: Updating the sync setting page and sync timestamps.

• every time Remote/P2P sync is completed we need to correctly update the sync settings page. This page is proposed so we haven't built it yet.
• It is proposed to show statistics like the number of resources synced, and the number of failed resources. Date and time of sync.

Use Case 2: Showing the users the snack bars after the sync is complete.

• We need to notify the users via the Android Snack Bars of sync start and completion. The sync completion Snack Bar should only be shown when the sync is complete i.e success or failure of sync.
• Correctly update the sync timestamps on the navigation drawer after sync.

Start/Stop Background jobs

Use Case 1: Reruning the report generation background jobs on sync completion.

• The report generation background service should be rerun after the sync (maybe only after P2P sync). This should configurable to allow re-running or disabling it.

Refresh/Invalidate cache.

User Case 1: Refreshing/Invalidating the registers and profile cache on sync completion.

• After running sync we need to refresh/invalidate the registers and profiles cache.
  • We refresh/invalidate all the registers and profiles cache or specific ones via a config. I would say we refresh all.

[f-odhiambo]

Some comments

1. Some use cases here seem like they can be triggered via a background task based on an Encounter type e.g moving from ANC to PNC, On Sync complete etc.
2. Most of the scenarios here look like updates to the already existing resources are there cases where we need to create new resources e.g Encounter => moving from ANC to PNC
3. What should occur in this event -> Login & Logout
4. How do we queue different notifications if they occur simultaneously?

[pld]

On Refresh/Invalidate Cache

• do we also need to do this when we add a patient/family?
• do we cache the content in the register? if so, then we'd need to change whenever content changes, b/c of a direct patient edit or because of a change in a task, or because of a change in data that affects rendering of the row -- hopefully none of that's cached, but want to confirm

Remote/p2p

• We don't update the settings page directly, we want to update the data stored related to settings, that data then gets pulled into the settings page -- same reasoning also applies to the timestamps shown in the drawer
• Snackbar must be controlled by user, not sure what default should be, but the user should be able to turn these specific notifications off

Start/stop background jobs

• We have to evaluate this in light of how expensive these background jobs are, like if we're syncing every 15 minutes, it might be too expensive to rerun these jobs on the same schedule

[ellykits]

On Refresh/Invalidate Cache

• do we also need to do this when we add a patient/family?
• do we cache the content in the register? if so, then we'd need to change whenever content changes, b/c of a direct patient edit or because of a change in a task, or because of a change in data that affects rendering of the row -- hopefully none of that's cached, but want to confirm

Yes we update the cache every time a questionnaire is submitted.

[pld]

K, how do we update the cache for changes in the 2nd bullet, or stuff that'd affect not cached?

[ellykits]

Oh, yes your assumption is correct we cache the register data per page. The data is stored in a hashmap with the page number used as the key. We clear the cache whenever sync completes or when a new client is registered. I hope that answers your question.

[ellykits]

Some of the events described here are handled by using Android LiveData and ViewModel e.g. (the events under this section Refresh/Invalidate cache). Is the general objective to of this discussion to implement some sort of a generic event bus to handle all the events?

[ellykits]

We do have a config for referencing plan definitions used in a QuestionnaireConfig. Is there a possibility where we would want to close multiple PlanDefs?

[pld]

Yes good point, we probably need to be able to handle closing any careplans linked to multiple plan definitions, worth building for, doesn't seem that much more complex. I can't think of any use cases, the example use case is a patient gives birth, their ANC CarePlan is now closed, and all the Tasks associated with it are cancelled. There's death, but that's a special case we won't handle with this. @AnnieMungai @dubdabasoduba can you think of use cases where we'd want to close multiple CarePlans on a single event (eg Questionnaire submission)?

[dubdabasoduba]

@ellykits @pld Yes, closing multiple PlanDefs is a possibility. E.g If someone was in ANC & On the ANC referral and they got a pregnancy outcome then. We would have to close both CarePlans.

If we changed the for and under 5 patient who was also on the sick child PlanDef then we would need to close both CarePlans.

I would look at this in two options.

1. Create a config that can accept a CarePlan Code referenced on the Category attribute and some FHIR Path expression to tell the closePlanDefinitionOnSubmit method on when to actually execute.

   • We would then perform a search for the CarePlan with the above code and is tied to the patient.
   • We then update the CarePlan status to revoked.
   • Then update all the linked Tasks to cancelled.

2. After a chat with @pld yesterday, he brought up the idea of using the PlanDef. So this approach would have us giving the id of the PlanDef that generates the CarePlans we want to close. We can also write the FHIR Path expressions to determine when the closePlanDefinitionOnSubmit is triggered in the PlanDef or use an attribute as in the option above.

   • We would then perform a search of CarePlan tied to the patient and linked to the referenced PlanDef.
   • We then update the CarePlan status to revoked.
   • Then update all the linked Tasks to cancelled.

[pld]

Cool, I edited to call the first (1) and the second (2).

In (1), do we store CarePlan categories now? Is this first set in a PlanDefinition that generates the CarePlan and then propagation un running apply/lite? If yes, then both approaches are doing the same thing but using different techniques to track the mapping from PlanDefinition to CarePlan. Then I think I'd prefer (2) because it would remove the need to track that Categories are correctly set, you can link the closure directly to the PlanDefinition.

Although, one interesting feature of (1) is that if we have the same Category for multiple CarePlans, we could close multiple CarePlans by passing a single Category, like it's reasonable for the "ANC" and "ANC Referral" CarePlan to both have the category "ANC".

Still overall, I think the extra indirection and complexity of using the Category with Code isn't worth the trouble.

[Rkareko]

There is a ticket here that handles closing (revoking) CarePlans and associated Tasks using configured plan definitions (option 2 above). we have introduced a CarePlanConfig that contains the conditional fhirplan expression and a Careplan operation which can either be cancel or complete. The question at the moment is whether we have a use case for configuring completion of a careplan cc @f-odhiambo @dubdabasoduba @ellykits

[Rkareko]

The current implementation handles completing a CarePlan only when a task has both expired and is the last task on that careplan
That leaves a gap in situations where all the tasks linked to a careplan have either been completed or cancelled before they expire. This ticket outlines how to go about completing or canceling Careplans depending on status of linked Tasks

[Rkareko]

Here are some options for consideration when thinking about building a generic event bus

Livedata
lifecycle-aware data holder class that can stream or share data to attached observers
Because a LiveData object is lifecycle-aware, it can be bound to both Activities and Fragments

• Whenever an observer becomes active, LiveData objects propagate the latest value to these observers.
• Avoid Memory Leaks as they are life-cycle aware
• Device rotation and configuration changes can be handled seamlessly, since once the Activity/Fragment is recreated, its corresponding LiveData objects will become active and resend the latest values
• LiveData.observe() automatically unregisters the consumer when the view goes to the STOPPED state

Flows
In coroutines, a flow is a type that can emit multiple values sequentially, as opposed to suspend functions that return only a single value. For example, you can use a flow to receive live updates from a database.

• Kotlin flows have operators that allow us to sort, filter, and manipulate our data in a variety of ways
• You might not need them if you’re trying to do something more straightforward like grabbing some data and making an update to the UI
• Flows are also not lifecycle dependent
• By default, the producer of a flow builder executes in the CoroutineContext of the coroutine that collects from it
• To change the CoroutineContext of a flow, use the intermediate operator flowOn. flowOn changes the CoroutineContext of the upstream flow, meaning the producer and any intermediate operators applied before (or above) flowOn
• collecting from a StateFlow or any other flow does not stop collecting automatically. To achieve the same behavior,you need to collect the flow from a Lifecycle.repeatOnLifecycle block

StateFlow and SharedFlow
StateFlow and SharedFlow are Flow APIs that enable flows to optimally emit state updates and emit values to multiple consumers. They are designed to be used in cases where state management is required in an asynchronous execution context with Kotlin Coroutines. StateFlow takes a default value through the constructor and emits it immediately when someone starts collecting, while a SharedFlow takes no value and emits nothing by default

StateFlow
StateFlow is a state-holder observable flow that emits the current and new state updates to its collectors
When collecting value from StateFlow, we always get the latest value
A StateFlow is always active and in memory, and it becomes eligible for garbage collection only when there are no other references to it from a garbage collection root

SharedFlow
The shareIn function returns a SharedFlow, a hot flow that emits values to all consumers that collect from it

Channel

• A channel is conceptually similar to a queue. One or more consumer coroutines can read from the same channel
• A channel has a suspending send function and a suspending receive function
• This means that several coroutines can use channels to pass data to each other in a non-blocking fashion.

Resources

• Crash Course Kotlin Flows, Channels and Shared/State Flows
• kotlinx.coroutines 1.4.0: Introducing StateFlow and SharedFlow
• How To Implement The Event Bus Pattern With Kotlin SharedFlow In Your Android App
• Kotlin channels
• Asynchronous Flow
• Shared flows, broadcast channels
• Introduction to Channels in Kotlin
• Kotlin shared flow docs

[Rkareko]

One of the use-cases for event management as outlined above is Redirecting to different screens. An example of this would be redirecting the user to the family register after a family has been removed. The current implementation redirects the user to the household profile.

@ellykits @dubdabasoduba it would be prudent to have a discussion about the different use cases that would need to be handled in addition to how configurability would be approached

[dubdabasoduba]

Event Management | CarePlan and Related resources Closure Update

• After a review of the current work we have identified 2 pieces for enhancement later on.

1. Linking the Event Management CarePlan closure functionality to the background worker that closes CarePlans once all the Tasks are of Task.status == completed/cancelled.
   • This will be used to close all the CarePlans that are time bound e.g PNC which should expire 28days after a LiveBirth
   • Here is a ticket to track this enhancement
2. Updating the Other Resources closure functionality to be configurable.
   • This will allow us to dynamically support the closing of extra related resources
   • Prelimary discussions around this are documented in this and subsequent comments

[dubdabasoduba]

Related tickets

• Event Management - Resource closure failure after sync up #2638
• [Event Management] - Closing Related Resources by the background worker #2421
• [Event Management] Update the CarePlan Closure configs to define the PlanDefs to closure separately.  #2372
• [Event Management] Closing CarePlans and Related resources configuration update #2371
• [Event Management] Updating Resources closure functionality to be configurable. #2978