MVP drafting feature

[joyce-x-chen]

Describe the feature request

A few clients, including SID, Columbia, and PAHO have expressed interest in being able to save a draft of a form that is in progress.

Currently, there are two possible outcomes with a form:

1. Save and submit
2. Discard (all entered data is lost)

The scope of an MVP feature could be:

• Addition of a "Save as draft" option
  • We need the Design team's input on where to place this in the UI, but ideally it would be in both places
    • (1) on the final page of the form so there are 3 options (back, save as draft, and submit).
      • NB: some apps use the label "SAVE" instead of "SUBMIT." We'd want to consistently use "SUBMIT" to distinguish from "SAVE"
    • (2) if you press back in the form. there would be 3 options: cancel, save as draft, and discard
      • There is a partial implementation worked on by Allan here
        • The partial implementation replaced "cancel" with "save as draft," but it's valuable for a user to be able to cancel to return to the form without saving
• UI update to indicate forms that are in progress
  • e.g. yellow task
• Only relevant to forms that are unique and only expected to be filled out once- i.e. exclude those such as "register client" or "register household"
  • This includes forms that are filled out once per client
  • For the MVP, only consider forms that are in the profile view - e.g. tasks (exclude those that are launched from the side navigation menu and the profile overflow menu)

Not in scope of the MVP

• A register of draft forms in progress (across clients)
• A register of draft forms in progress (per client) in the overflow menu
• Notifications or task reminders to complete draft forms in progress
• Expiry period after which draft forms are deleted
• Auto-submit period after which draft forms are automatically submitted

Example use cases

• A counseling session cannot be completed in one sitting, so the counselor would like to save the incomplete session and continue it in the next session
• A health care worker does not have the answer to a mandatory question (e.g. lab results) and cannot submit the form until it is answered; they also do not want to discard the data they have already entered
• A patient meets with multiple providers during a clinic visit. They would like the ability for the form to be started by one worker and completed by another worker
• A health care worker is doing a child visit and the mother goes to get the child's health card to update the immunization history. Meanwhile, the health care worker wants to proceed to measure the child's MUAC (which is collected in a different form)
• A health care worker is doing a household visit and providing care to multiple household members. They want the ability to start a workflow and switch to another workflow without losing their data
• A health care worker is required to collect data in both the app and on paper. They start a form in the app, but are under time pressure, so they fill out the paper form and plan to enter the data in the app later

Acceptance criteria

• The user is able to save a form as a draft
• The user is able to see that a form is in progress (UI difference from due, overdue, and completed tasks) in the patient profile (task view)
• The user is able to resume a draft form by launching the form. Previously entered data is loaded in the form
  • After launching the draft form, the form starts from the beginning (not where the user left off)
• After completing the form, the user can submit the form or discard it as usual
• A form can be saved as a draft unlimited times
• Forms "saved as a draft" are synced to the server as an "in progress" QR
• "In progress" QRs are downsynced to other users who should have access to that data (i.e. allow the incomplete form to be "passed" from one practitioner to another)
• Forms "saved as a draft" do not appear in the past encounters view

Implementation plan (For Engineers)

• Update QuestionnaireViewModel.searchQuestionnaireResponse to filter Questionnaireresponse search using the status = in-progress
• Update AlertDialogue.showCancelAlert to handle 3 buttons
• Update the QuestionnaireActivity.handleBackPress to open an alert dialog with buttons and text indicated in this figma design

[pld]

this looks like a good mvp, some questions:

1. for "UI update to indicate forms that are in progress", since we exclude register... forms we don't have to worry about those, a form that we launch the form from the hamburger menu on a profile can be configured to only show once, like an "end ANC form", "record patient death" form or similar. Would we show a UI change for the menu items or would we exclude this drafts from forms opened from a drop down menu and only include those from a profile page, like task-related forms?
2. If I save a draft, then open a draft, then exit the draft and choose "cancel", does this delete the draft?

[joyce-x-chen]

1. for "UI update to indicate forms that are in progress", since we exclude register... forms we don't have to worry about those, a form that we launch the form from the hamburger menu on a profile can be configured to only show once, like an "end ANC form", "record patient death" form or similar. Would we show a UI change for the menu items or would we exclude this drafts from forms opened from a drop down menu and only include those from a profile page, like task-related forms?

Good question. I would prioritize a UI update for forms that are displayed in the child's profile, e.g. task-related forms. While there are some forms stored in the overflow menu that might need drafting, they are less likely. The types of forms that are typically accessed in the overflow menu are ones that:

• Are repeatable (e.g. adverse events form), so already excluded from the MVP feature
• Are short and have only a couple of questions. It is unlikely you need to save a draft of such a form. Even if you don't have all the information, closing it and re-filling the form is not a big pain point
• Are used infrequently and/or in circumstances where the information is more definitive. As such, the user is less likely to not complete and submit the form (e.g. close ANC, death, adverse event, activate patient)

2. If I save a draft, then open a draft, then exit the draft and choose "cancel", does this delete the draft?

No, if you open a draft form and exit the draft, you get the same 3 options as if you're in a new form: cancel, save as draft, and discard.

• Cancel = go back to the form to continue editing (do not exit)
• Save as draft = save (but do not submit) and leave the form
• Discard = discard and leave the form (next time, start from new)

[pld]

1. sounds good, let's update the scope for the MVP to be only for non-repeatable forms AND forms displayed in the a profile view.

2. Oh sorry, I confused cancel with discard but that's what I was thinking, which means the way to "delete a draft" is to edit a draft then exit it and choose discard.

If you do that, then you sync, is the expected behavior that a draft you discarded also disappears from other devices when they resync their drafts? That seems reasonable. There might be an edge case where User A discards a draft and it's status is set to deleted and User B, completes and submits a draft so it's status is set to completed, we will have to confirm how this is handled by the FHIR API.

[joyce-x-chen]

I had tried to describe non-repeatable forms here, but maybe the wording isn't so clear? I've edited the description to restrict it to those in the profile view. Feel free to edit for further clarity.

Only relevant to forms that are unique and only expected to be filled out once- i.e. exclude those such as "register client" or "register household"
This includes forms that are filled out once per client

Good point on potential conflicts. That's not unique to saving of drafts (can happen due to offline work with new forms and editing of forms too), but we do need to come up with basic rules for how they are handled so it doesn't lead to app crashes or ANRs.

[pld]

Looks good, the wording on non-repeatable was clear, change was to add in profile view, thank you.

[f-odhiambo]

Initial Scoping on Implementation Plan

After initial code review here are my findings

Adding Config

1. Add config - Already exists

{
   "trigger": "ON_CLICK",
   "workflow": "LAUNCH_QUESTIONNAIRE",
   "questionnaire": {
      "id": "2b56ce61-6e33-4d40-8edb-7f273cb358dd",
      "title": "{{ questionnaire.title.anc.profile }}",
      "saveButtonText": "{{ submit }}",
      "setPractitionerDetails": true,
      "setOrganizationDetails": true,
      "saveDraft": true,
      "resourceIdentifier": "@{patientId}"
   }
}

2. If saveDraft is true, then add QuestionnaireResponse status to in-progress

PS. Everything else after this does not exist

Populate

1. Add function to populate form once the user re-opens the form (QuestionnaireRersponse with link to Questionnaire ID & Subject ID) if the last QR link has the status in-progress

UI/UX

1. Message

• If saveDraft config is provided we need to update the message on the alert dialog from Submit/Discard to SaveDraft/Submit
• Add a rule that will be used in the profile or register to update the button text for the submit alert dialog
• We need to override the QuestionnaireView model to override the validate function so that drafts are saved when questions are not validated for required fields/data type

2. Color

• If Draft update the Task icon and color
• Update generateTaskServiceStatus in the rules engine to update the icon and color of the Task.Button in the RulesFactory.kt

Assumptions

1. You will only have 1 draft per question at a time
2. You will not be able to save the practitioner detail until submit is pressed
3. You can track the version history of the resource only on HAPI but not on the app
4. Tracking of which practitioner is doing the edits is not captured in this initial implementation plan

[f-odhiambo]

Open Questions from grooming with @Rkareko

1. UI/UX - Discard/Cancel - Do we have a single button or multiple? Do we show this dialog only on the back press when you want to exit the form?
2. QR Status - in-progress | completed | amended | entered-in-error | stopped - which QR status do we use for the different user journey flows?

[Rkareko]

1. UI/UX - Discard/Cancel - Do we have a single button or multiple? Do we show this dialog only on the back press when you want to exit the form?

@f-odhiambo A suggested approach for this using a HouseHold registration form as an example would be to do the following :

1. The form would have a single button. Add House Hold for this case.
   
2. When the Add Household button is called, the SDC would perform validation and if any errors exist the validation error dialog would be displayed. This is the normal flow.
   
3. When the validation errors are fixed or if they don't exist and we have configured our questionnaire to have saveDraft as true then the following dialog would be displayed.
   

[joyce-x-chen]

Please note that discard and cancel have 2 different functions. Discard = discard the draft. Cancel = go back to the form to continue editing.

[f-odhiambo]

Hi @joyce-x-chen unfortunately we can not have an alert dialog with more than 3 buttons to accommodate adding a cancel I wanted to let you know that we’re currently focusing on the heavy lifting of the code for the button. Once that’s done, we’ll revisit the button press functions and make sure everything aligns with your design preferences. We’ll also keep your concerns in mind and try to avoid any changes to the SDK to minimize any potential impact on the overall implementation. Thanks for your patience! 😊

PS. Cancel also introduces a new scope that may get a life of its own. @Rkareko Check if we can be able to add a cancellable property to the alert dialog to take care of the cancel scenario

CC @HenryRae @rowo

[f-odhiambo]

@Rkareko
Based on the convo we had we need to maintain the QR top and status for the workflows to populate the correct state of data post-submission

1. Edit - Latest QR + status = completed
2. Draft - Latest QR + status = in-progress

We need to update the docs to show a clear distinction on how draft vs edit works

[HenryRae]

@joyce-x-chen @f-odhiambo we have designs here on how we would like the feature to work. We will definitely need all 3 CTAs.

1. Save draft - to save users input as a draft
2. Discard changes - dismisses user's input, and closes the form without saving the draft.
3. Cancel - dismisses the dialog so user can continue with the form
   Cc: @rowo

[joyce-x-chen]

Thanks so much @f-odhiambo @Rkareko @HenryRae.

@HenryRae

Discard changes - dismisses user's input, and closes the form without saving the draft.

To clarify - I was suggesting "discard" to mean discard the entire (draft) form. I do see the value of a "discard changes" option (which would return the draft to the state it was in before the person opened the in-progress form), but then we'd have to find another way to provide the user with the option to discard the entire form. Since we don't want to create a register of in-progress forms for the MVP, there's no "delete" option elsewhere at the moment. If we have to choose between "discard changes" and "discard form", and "discard changes" and "cancel", I think discard form is more valuable. Alternatively, could we add an X button to represent cancel (go back to form to resume editing - no discarding of newly input data)?

Good point though on clarifying whichever we settle on. The label needs to be more specific - i.e. "discard form" or "discard changes" rather than simply "discard."

@f-odhiambo

PS. Cancel also introduces a new scope that may get a life of its own. @Rkareko Check if we can be able to add a cancellable property to the alert dialog to take care of the cancel scenario

I thought cancel is an existing functionality in OpenSRP apps if you try to back out of a form. The current options are "Cancel" and "Discard." The new one would be "Save draft." Here is a screenshot from PATH EIR:

[joyce-x-chen]

Oh never mind @HenryRae I see you've gone above and beyond and suggested more functionalities within the task button! I wasn't even considering this for an MVP implementation. But if there is another way to delete draft, then I like the option of "discard changes" when pressing the back button for an in-progress form. Just not sure how much LOE this adds from an engineering perspective 🙂

[f-odhiambo]

SubTasks

• Open Draft - scoped
• Delete Draft - We don't have purge so this will need to be discussed
• Cancel - scoped

CC @Rkareko

[HenryRae]

These 3 are a must have, for users that are trying to leave an open form.

1. Save draft
2. Discard form
3. Cancel

The options while opening a saved draft i.e open draft, delete draft and cancel, it's fine to drop all them. This means, when someone clicks on a saved draft, we open the draft directly without showing the dialog. When they try to leave the form without submitting, we resurface the same options when saving draft i.e save draft, discard form, cancel.
Cc: @joyce-x-chen @f-odhiambo @Rkareko

[f-odhiambo]

1. The SDK supports purge
   The question is whether the purge can be propagated to the server and back down to other devices

  suspend fun purge(resource: Resource, forcePurge: Boolean) {
    try {
      fhirEngine.purge(resource.resourceType, resource.logicalId, forcePurge)
    } catch (resourceNotFoundException: ResourceNotFoundException) {
      Timber.e(
        "Purge failed -> Resource with ID ${resource.logicalId} does not exist",
        resourceNotFoundException,
      )
    }
  }

2. This may have a negligible impact on storage over time but TBD

CC @joyce-x-chen @HenryRae

[FikriMilano]

I'm not sure if this is supposed to be a bug or we should not do this use case in the first place.

Re-open a completed form, do some changes, and then save as draft; is not working:

1. Form has been submitted
2. Open the form again
3. Pre-fill works ok
4. Change some answer
5. Then for some reason tap the back button
6. Save as draft
7. Open the form again
8. No prefill

See this recording (the bug starts at 0:26)
https://drive.google.com/file/d/1qSL40LE1obTROEjzM2xfPoMg1DHA3ffx/view?usp=sharing

[joyce-x-chen]

Thanks @FikriMilano. That appears to be a bug, because you should not be able to open a completed form (that would be editing, not drafting). You should only be able to open and edit forms that have been saved as a draft.

However, I observed a missing UI change - after the draft is submitted the first time (as well as any subsequent time), the task should appear as yellow with the in-progress icon as in Henry's designs here cc: @Rkareko @f-odhiambo. Do we need a separate issue for the UI changes?

[joyce-x-chen]

Next steps from the Engage project standup:

• Fikri will disable editing
• Fikri will update the configs to see if the UI implementation is applied

[joyce-x-chen]

@HenryRae would you be ok with us maintaining the + sign for the " in progress" task status (represented by yellow) instead of using the circular progress icon?

Most of the time, the circular progress icon isn't an action button and it's more straightforward to maintain the + button (SDK default). Thank you cc: @rowo

[joyce-x-chen]

Hi @Rkareko @f-odhiambo

We are testing this in Engage and it's looking really good! @FikriMilano pointed out that we will need a small code change to update the task status to draft (Task.IN_PROGRESS).

We wanted to clarify the implementation approach chosen, as there had been 2 options discussed:

• Advanced option: have 2 discard choices - i.e. "discard changes" when leaving the form and "discard form" from the profile/task view
• Basic option: only have 1 discard choice - i.e. "discard form" when leaving the form

Henry approved the basic option

These 3 are a must have, for users that are trying to leave an open form.

1. Save draft
2. Discard form
3. Cancel

The options while opening a saved draft i.e open draft, delete draft and cancel, it's fine to drop all them. This means, when someone clicks on a saved draft, we open the draft directly without showing the dialog. When they try to leave the form without submitting, we resurface the same options when saving draft i.e save draft, discard form, cancel. Cc: @joyce-x-chen @f-odhiambo @Rkareko

From @madrinekariuki's thorough testing,, it appears as though perhaps we have implemented only "discard changes" when leaving the form. This means there is no way to discard a draft. Was this intended?

[Rkareko]

From @madrinekariuki's thorough testing,, it appears as though perhaps we have implemented only "discard changes" when leaving the form. This means there is no way to discard a draft. Was this intended?

@joyce-x-chen cc @f-odhiambo discard a draft functionality is being tracked on this github ticket. There is a new pop up dialog with Open draft, Delete draft and Cancel options. The discard changes will still be available when leaving the form.

The current implementation on FHIR core main implements the Basic option: only have 1 discard choice - i.e. "discard changes" when leaving the form .

[joyce-x-chen]

Thanks for the clarification @Rkareko. I didn't realize we are going with the Advanced option!

Right now, the option for leaving a form is "discard changes" and not "discard form." But that is ok if we are going to add "discard form" from the profile view later. cc: @MargaretNjenga

[HenryRae]

@HenryRae would you be ok with us maintaining the + sign for the " in progress" task status (represented by yellow) instead of using the circular progress icon?

Most of the time, the circular progress icon isn't an action button and it's more straightforward to maintain the + button (SDK default). Thank you cc: @rowo

@joyce-x-chen can we use the edit icon instead? Link to icon
Icon color: #D2760D

[joyce-x-chen]

Great idea @HenryRae! @FikriMilano could we use this icon for in-progress?