Health Tasks workflow

[dubdabasoduba]

Defining the flow of Tasks through the different statuses

Tasks status

• Requested -- This status is given to a Task when the executionPeriod.start date is in the future.
• Ready -- This status is given to a Task when the executionPeriod.start date is <= to today and the executionPeriod.end date >= today
• In Progress -- This status is given to a Task when the QuestionnaireResponse it acts on is marked as draft
• Completed -- This status is given to a Task when the QuestionnaireResponse it acts on is marked as completed
• Overdue -- Is status is not assigned to the Task resource. This status is inferred from the following logic. A Ready / In Progress task that the executionPeriod.end date < today
• Expired -- This status will be represented by the cancelled status on the Task resource. This is a Task that has been Overdue for a while and therefore it can't be performed anymore.

Tasks Color Coding

• The following designs and colour codes should be used for the different Task statuses.
  • Requested -- This should have a light gray background with Gray font & + sign. Here is a sample
    
  • Ready -- This should have a light blue background with Blue font & + sign. Here is a sample
    
  • In-Progress -- This should have a light orange background with an Orange font & loading sign. Here is a sample
    
  • Completed -- This should have a light grey background with Gray font & a tick sign. Here is a sample
    
  • Overdue -- This should have a light red background with Red font & + sign. Here is a sample
    
  • Expired -- Design TBD cc: @HenryRae

Current Workflow.

• We currently, have a process to generate Tasks & CarePlans via PlanDefinitions & StructureMap Extraction.
• We have the Tasks linked to Questionnaires as the actions to be performed during the tasks.
• We currently generate all Tasks for a certain CarePlan all at once. Then enable the actions based on the Tasks executionPeriod.end date.
• Currently, all the Task linked Questionnaires that required PlanDefinition extraction don't work as required. This is because the Questionnaires aren't linked to the PlanDefinitions to define any extra schedules required.
  • Examples of these extra schedules can be the referral schedules.
• We also don't have a way to mark QuestionnaireResponses as draft
• We currently, don't allow editing on complete tasks.

Proposed workflow

Tasks generation changes

• Generate Tasks on demand instead of generating all the Tasks at once. This means a new task is generated when the current one is completed [Quest] Updating the Tasks generation to on demand instead of all at once #1696
  • We however want to make this configurable since some items would want the Tasks generated all at once. e.g If we choose to visualize the child immunization schedules using tasks then we would all the tasks for the schedule to be generated at once.
  • We will stop the generation of the tasks once the executionPeriod.end is >= to the CarePlan period.end date.
  • We will always generate the first on the day of CarePlan creation/generation.
• Allow the completion of Overdue Tasks. This means these Tasks will be clickable and the users could fill up the Questionnaires tied to them. [Quest] Allow completion of Overdue Tasks #1697
  • We will need to update the Task executionPeriod.end date to the date the Questionnaire is completed.
  • We would then need to generate the next Task on the schedule i.e if we had a 3-month schedule with 3 tasks each to be completed each month. An overdue month 1 task completed in month 2 will mean we generate the month 3 task instead of the month 2 task.
• Add the functionality to mark Tasks as Expired [Quest] Write a service to mark Tasks as expired.  #1703
  • Write a service to identify the Tasks that are way past the overdue dates. The service will then update the status to cancelled.
  • We will use the restriction.period to hold the allowed lifespan of the Tasks
    • Start Date -- This will be equal to the executionPeriod.start. It's the DateTime the task is supposed to start.
    • End Date -- This is the last date that the Tasks can be completed.
• We will need to reference the PlanDefitions the Questionnaires on Tasks need to extra any extra schedules based on the QuestionnaireResponses values. #1699
  • We can use the Task.input.valueReference property on the Task. This accepts different kinds of data types one of them being a Resource Reference.
  • https://www.hl7.org/fhir/task-definitions.html#Task.input.valueReference
  • We will then update FHIRCore to check whether the Tasks have a PlanDefinition tied to them and then trigger extraction just like the program enrolment Questionnaires right now. E.g how we extract the ANC and PNC schedules.
• Extraction of any kind can only be triggered if the QuestionnaireResponse QuestionnaireResponse.status property is set to Complete [Quest] Update Extraction triggering to only happen for QuestionnaireResponses with the status == Completed #1700
• NB: - The old way of generating all tasks might still be needed for some use cases e.g child immunization-related tasks.

Tasks state machine changes

• Write a service to identify the Overdue Tasks. This service can be run every time the Tasks are loaded on each page.
  • We can have it run periodically but it might not make sense since we are not changing the status on the Task Resource.
  • NB: - We also need to review how this will affect measure-reports since we might have indicators around the number of expired/overdue Tasks
• Write a service to identify the Expired (status cancelled) tasks. This service can be run periodically.
  • The service will then update the Tasks status to cancelled.
• Write a service to identify the Ready Tasks. This service can run in 2 different ways [Quest] Add the ability to mark Tasks are Ready.  #1701
  • It can run periodically. The Proposal is to have it run after every 1 hour. This time should however be configurable. Some projects might want more/less frequent.
  • The service can also be run every time a patient profile is open (not recommended). This however has some flaws since the Tasks will not be updated unless the user explicitly opens the subject's profile.
  • The service should do the following: -
    • Find all the Tasks with a executionPeriod.start date == to today then change the Task.status property to ready
• Write functionality to check the QuestionnaireResponse QuestionnaireResponse.status property to identify whether the QuestionnaireResponse is In Progress. The functionality then updates the Task Task.status property to In Progress. [Quest] Add the ability to mark Tasks as Complete or In progress #1702
• Update the current functionality that marks Tasks as complete to also check the QuestionnaireResponse QuestionnaireResponse.status property to make sure it's set to Completed before marking a Task as complete. [Questionnaires] Adding the ability to save QuestionnaireResponse as In Progress #1631

**Questionnaire Response Changes -- SDK Related #1631

• Add the ability to mark a QuestionnaireResponse as draft by setting the QuestionnaireResponse QuestionnaireResponse.status property to In Progress.
  • Going back or clicking Exit on the Questionnaire page will show a dialog with 2 options.
    • Save Partially -- Allows the user to save the questionnaire partially by setting the QuestionnaireResponse QuestionnaireResponse.status property to in progress, then redirects to the screen before the questionnaire render.
    • Discard -- This discards all the inputs on the form and closes the Questionnaire render page, then redirects to the screen before the Questionnaire.
    • Cancel -- @HenryRae Do we need a cancel button?

[ellykits]

What's the corresponding FHIR task status for overdue?

[dubdabasoduba]

@ellykits the Overdue task status does not have a corresponding FHIR state. This will be a calculation checking the executionPeriod.end and the current status e.g in progress & ready

[ndegwamartin]

There's an interesting library here from Tinder we can check out https://github.com/Tinder/StateMachine

[pld]

Thanks for the write-up, based on the description, this sounds broader, more about Task Workflow / Management than the state machine specifically, because the state machine is only one sub-component of the different interactions you are describing, like scheduling and loading of specific questionnaires seem key to this but outside the scope of what is normally a state machine.

With $apply getting closer (maybe it won't be ready in time) we should consider if we can use it for the task generation portions, like rerunning it after data changes to generate the updated tasks. Ignoring the question of whether they're embedded in a CarePlan or not, does $apply generate all or only currently applicable tasks?

[dubdabasoduba]

@pld Not very sure whether $apply currently generates the Tasks. I will review it and revert. @f-odhiambo any ideas?

[pld]

Got another update on this today, it is WIP, google/android-fhir#1603

[dubdabasoduba]

@pld @f-odhiambo I will go ahead and create the SDK-related issue for it to be worked on.

[AnnieMungai]

@dubdabasoduba how do we handle expired tasks - these are the tasks that became overdue but were not completed. If they are not completed within a specific period of time, then they become irrelevant to the user thus are termed as expired. They are no longer seen on the client profile. Example is a referral task that was not followed up after when it was supposed to be followed up.

[pld]

cool, followups

1. why both with setting restriction.period.start, is that required? if it's the same as executionPeriod.start I don't see why it's needed

2. On the services, is the importance of identify overdue tasks so that we can officially change their state, and then through that display them correctly in the UI?

3. NB that we need to make firm decisions on how the tasks services are run, the description above lays out the options, but before implementation we need to do the deciding

[dubdabasoduba]

@pld

why both with setting restriction.period.start, is that required? if it's the same as executionPeriod.start I don't see why it's needed

This is one of those things I added for data completeness purposes. It felt weird to have the period with just the end date.

On the services, is the importance of identify overdue tasks so that we can officially change their state, and then through that display them correctly in the UI?

Yes, that the use case for the services.

NB that we need to make firm decisions on how the tasks services are run, the description above lays out the options, but before implementation we need to do the deciding

Agreed,

[HenryRae]

Generate Tasks on demand instead of generating all the Tasks at once. This means a new task is generated when the current one is completed

@dubdabasoduba how can we handle showing upcoming tasks for instance if Health worker has to inform client when the next visit will happen for proper planning...
Are we still not able to show upcoming tasks in the questionares?
cc: @rowo @AnnieMungai

Allow the completion of Overdue Tasks. This means these Tasks will be clickable and the users could fill up the Questionnaires tied to them.
We would then need to generate the next Task on the schedule i.e if we had a 3-month schedule with 3 tasks each to be completed each month. An overdue month 1 task completed in month 2 will mean we generate the month 3 task instead of the month 2 task.

@dubdabasoduba what happens incase you have 3 tasks in 1 month. Does the overdue tasks overshadow the others? don't the 2 other new tasks get generated?

Add the ability to mark a QuestionnaireResponse as draft by setting the QuestionnaireResponse QuestionnaireResponse.status property to In Progress.
Going back or clicking Exit on the Questionnaire page will show a dialog with 2 options.
Cancel -- @HenryRae Do we need a cancel button?

@dubdabasoduba yes we do need cancel button to discard the dialog.

[samkanga]

@pld @dubdabasoduba I would like to add some perspectives on the tasks discussion; while an expired task need not be shown on the task list, on some implementations such as Immunisation, we have been showing the expired tasks on the child's profile. This is usually for the care giver to have a glance at what vaccinations have been administered and those that were never administered(expired). This information is helpful in the longitudinal care of the client.

[pld]

Thanks, that's useful. I think there are two issues here we can separate, 1) is the tasking of vax, 2) is the schedule for a vax in a immunization CarePlan. @dubdabasoduba @f-odhiambo are these the same thing in our model?

I haven't thought about it that hard, but I don't think these can be the same thing unless we're pre-generating all the tasks. Because along the lines of what you said, we usually have views in the app that show all the vaxs for the patient, and if we're using tasks to track that we'd need to pre-gen to see that correctly. But if we're not using tasks, how is that schedule being encoded in the CarePlan?