Cht-core: Add support for death reporting workflow

[sglangevin]

This issue adds support for a death reporting and confirmation workflow involving CHWs and managers. We need to support reporting death as well as reversing a death.

The basic workflow for reporting a death is as follows:

• CHW reports a death in the community via SMS or an app form
• This death report triggers a task for the manager in the app OR sends her an SMS notification
• This task opens a second form (death confirmation) that the manager fills out and submits OR the manager submits a death confirmation form via SMS
• If the manager confirms the death, the person's profile updates to show that they are deceased
• NOTE: The manager can also fill in the death confirmation form directly (in app or via SMS) and the person's profile updates to show that they are deceased

The basic workflow for reversing a death is as follows:

• CHW requests a correction via SMS or an app form
• This request correction form triggers a task for the manager in the app OR sends her an SMS notification
• This task opens an undo death form that the manager submits OR the manager submits an undo death form via SMS
• If the manager confirms that the death should be reversed, the person's profile updates to show that they are alive
• NOTE: The manager can also directly undo the death (in app or via SMS), which should update the profile to show that the person is alive

Design spec is here

Summary of UI changes (these are applied once a death is confirmed). See the design spec for more info:

• [x] person's icon changes from pink to gray (screenshot 1)
• [x] the word "Deceased" is added either next to or immediately below the person's name on their profile (screenshot 1 & 2 are mobile view, on desktop the word "Deceased" should be immediately next to the person's name, see screenshots 6 & 7)
• [x] on the family page, a new row appears at the end of the list of family members that says "View deceased" (screenshot 3)
• [x] when you click on "View deceased", you are taken to a detail page that lists the deceased family members. These are the same as the content rows on the family page except that they show the age at the time of death and have a relative date of death on the right, e.g. "Died 3 years ago" (screenshot 4)
• [x] in search, deceased people should have gray icons and show up at the bottom of the list (screenshot 5)

Screenshot 1

Screenshot 2

Screenshot 3

Screenshot 4

Screenshot 5

Screenshot 6

Screenshot 7

[garethbowen]

Code review please @SCdF

[garethbowen]

Configuration

1. Create forms for death reporting, confirmation, rejection, and undo.
2. Configure tasks and/or responses to prompt for confirmation/rejection.
3. Configure the contact summary to show the death card. The date the death was recorded is available on the patient as date_of_death.
4. Update app_settings to have a death_reporting property with mark_deceased_forms and (optionally) undo_deceased_forms arrays. The arrays must contain a list of strings for all form types that should trigger that action.
5. Enable the death_reporting transition.
6. When a report of one of the mark types is received then the transition looks the patient up using the patient_id in the report's fields and mark them as deceased. The undo types mark the patient as alive.

Example app settings

{
  "transitions": {
     "death_reporting": true
  },
  "death_reporting": {
    "mark_deceased_forms": [ "dc", "death-confirm" ],
    "undo_deceased_forms": [ "uc" ]
  }
}

[ngaruko]

A couple of questions came up as I was testing this feature: @sglangevin

1. According to the workflow, the 'report death' is only available to CHW's not to managers, it this meant to be a configuration thing ?

2. Not just for this but other forms/reports as well, should we hide submit report or particular reports/forms when the user (like manager in this case) cannot submit that report?
   

[garethbowen]

The enketo forms are configurable. We don't have a concept of permissions for sms forms. @sglangevin Is this required? It could be done generically so all forms could have a permission/role required?

[sglangevin]

No, that's not required for this feature. There are actually 3 scenarios here: CHW & supervisor on Medic app, CHW on SMS and supervisor on Medic app, and CHW & supervisor on SMS. The only case where we wouldn't be fully controlling this would be the 3rd one, and I think we'd just train each set of users on the appropriate set of forms. We can come back to the issue of permissions/roles for SMS forms in the future.

[sglangevin]

Sorry for the delay here - Bede had asked me to AT a while ago and I haven't gotten to it. So I think this actually fails AT because it requires the patient to have a Medic ID. We have many projects where we aren't using Sentinel and therefore don't have Medic IDs for every patient. In those cases, we need to be able to list the UUID and have the patient's profile updated based on their UUID as opposed to the Medic ID. @garethbowen I'm assigning this back to you. Sorry it's been so long since you worked on it.

[sglangevin]

One other small point of feedback. According to the mock-up, death confirmation reports should show up on the place page for the clinic level place the person belongs to.

@amandacilek @diannakane what should happen to other past reports about deceased people? Should those show up on the place page? Or only the death confirmation?

[garethbowen]

@vimemo Code review please. This is a change to a sentinel transition to allow it to work with UUIDs (used in xforms) or patient shortcodes (used in sms forms). Let me know if it doesn't make sense!

[garethbowen]

Thanks @vimemo - I've fixed and merged that PR. Now I have another one for you! This one is about the reports of deceased children showing up in the households reports list.

[garethbowen]

The death_reporting transition now accepts UUIDs as well as shortcode IDs. This value must be in the patient_id field. Place contacts show reports for deceased children as well as live children.

Returning to AT.

[ngaruko]

Do we need closed before 2.14 release @sglangevin ?

[sglangevin]

No - this is scheduled for 2.15 so it needs to be tested before the release of 2.15.

[sglangevin]

LGTM. Working well!