The BA project requires the ability to generate referrals in the CHW application and have those synchronized to the health facility application.

Assumptions

• The CHW application already synchronizes patient information to the parent health facility
• CHWs will be assigned to push all referrals to a particular facility. We will not ask which facility a CHW is referring to.
• We do not need a plan at this time because the referrals only have one action

Outstanding Questions on this Scoping Document

• How will we get the tasks back to the CHW once the status has been updated?
  • This really as to do with understanding how information synchronizes between the CHW and the facility
• Do we need to support peer-to-peer sync?
• Do we need to be able to assign tasks to a particular user in the health facility?
• Do we need the ability to cancel tasks in the event there was a mistake?
• What's the process for archiving tasks? (This doesn't need to be determined this week)
• The mock-up at the bottom of this document includes a "Referral Problem Child" we need to define this.
• Do we need visual indicators in the task list view that show a task was expired or add an expiration date?

Definitions

• Client/Entity - The OpenSRP system stores information as clients or entities in the database. These tables are generated in the Android client and OpenSRP server. Clients can be defined using any structure that's needed for the project and are updated by events.
• Event/Form - Events or Forms are the core unit of data collection and updates in OpenSRP. Users create, view and edit forms to collect actions.
• Location - The BA project uses locations for role based access controls. Locations in this project represent facilities and CHW catchment areas. (This is different than Reveal)
• Post Form Save Action - A post form save action is a method that is executed every time a form is saved in the OpenSRP Android client. This allows us to update entities in the system, create tasks and execute business logic based on information collected in the system.
• Task - A task is a unit of work that's assigned to a particular user or team. Tasks are linked to events, entities and locations in the OpenSRP system

High Level Workflow

This section defines the high level workflow for generating referrals in the CHW application, syncing and to the server, viewing the task in the Facility application and closing the loop.Additional details and mock-ups have been created by the BA team.

Constraints

• Referrals can be made from any family member profile
• Issue a referral for sick child, pregnancy confirmation, ANC/PNC danger signs, Postpartum FP, FP initiation, and malarial confirmation 
• Referral form content is based on TZ forms which are linked in each data dictionary
• Referrals time out after 7 days and are deprioritized in the referral list view as defined in the referral data dictionary 

Steps:

• CHW decides that they need to refer a patient to a health facility
• The CHW opens the referral form for that patient, completes it and clicks save
• Post Save Action
  • We generate a task in the CHW application
  • The task is added to the referrals task list in the CHW app
• The CHW app automatically synchronizes 15 minutes
• The task and referral form are sent to the server and added to the queue of forms to download at that health facility
• The Facility app synchronizes and downloads the referral and task
• The task is added to the task list in the facility app
• A visual indicator also shows up next to patient in the appropriate register
• The user taps the task from the task list to open it
• The referral information is displayed and the user can navigate away or they can mark the referral as done
• Post Save Action
  • The task status changes to Complete if the referral is marked as done
• Navigate Back Action
  • The task has now been read, so we need to update the task status to "In Progress"
• The Facility app synchronizes after 15 minutes and updates the task in the server
• The CHW app synchronizes, identifies there is an updated task and updates the task locally to show the status as complete

Task, Event, Location and Entity Relationships

The core of this innovation is a relationship between events, tasks and entities in the Android client. These relationships are important in both the Android client and OpenSRP server. Note that Reveal includes a location component that's not critical in this case, so the implementation may be slightly different. (Reference the definitions above for more information) This section defines the relationship and impact of each component of the data model.

• Tasks
  • Tasks are linked to a health facility location where they are assigned (location)
  • Tasks are linked to the patient (entity)
  • Tasks are linked to the referral form that was used to generate them so a user can view the event (event)
  •  Actions
    • Create - Tasks are created when:
      • In the CHW application by a referral event → status = Ready and businessStatus = Referred
    • Update - Tasks are updated when:
      • A health facility user opens the referral in the application → The status changes to in-progress and businessStatus changes to in-progress
      • A health facility user taps "Mark as Done" → status = Complete and businessStatus = Complete
      • On a regular schedule, the health facility app queries all tasks in their facility and changes the status and businessStatus for expired tasks → status = Failed and businessStatus = Expired
• Events
  • Events are used to create tasks
  • Events are performed at locations
  • Events update entities in the system
• Locations
  • Locations are used to group and filter
    • Tasks
    • Events
    • Entities
  • Locations are used for synchronizing to identify the events, tasks and entities that should synchronize

Task State Machine

The Reveal team implemented a task state machine in the Android client. We need to implement the same in OpenSRP for the BA project. Below is a representation of that state machine, which is a number of processes that update the state of tasks. We don't need to implement all states in the Android client for this project.

Task Statuses

• Draft - The task is not yet ready to be acted upon.
• Ready - Task is ready to be performed, but no action has yet been taken. Used in place of requested/received/accepted/rejected when request assignment and acceptance is a given.
• In-Progress - Task has been started but is not yet complete.
• Cancelled - The task was not completed.
• Completed - The task has been completed.
• Failed - The task was attempted but could not be completed due to some error.
• Archived - The task is invalid, a duplicate or is no longer required for reporting purposes.

Task Business Statuses

• Referred - The referral was sent
• In-Progress - The referral was opened by the facility worker
• Complete - The task was marked as done
• Expired - The task expired before it was done

Task Template and Data Dictionary

{
  "identifier": "UUID()",
  "planIdentifier": "",
  "groupIdentifier": "healthFacilityLocation",
  "status": "Ready",
  "businessStatus": "Not Visited",
  "priority": 3,
  "code": "referralType",
  "description": "referralDescription",
  "focus": "",
  "for": "patientBaseEntityId",
  "executionStartDate": "now()",
  "executionEndDate": "now() + 7 days",
  "reasonReference": "referralFormEventId",
  "owner": "username",
  "note": null,
  "serverVersion": 0
}

Plan Definition

We need to create a plan in the system to be able to link tasks to particular actions within the plan.

{
    "identifier": "${UUID()}",
    "version": "1",
    "name": "baCatchAllReferral Plan",
    "title": "BA Catch All Referral Plan",
    "status": "active",
    "date": "2019-08-06",
    "effectivePeriod": {
      "start": "2019-08-07",
      "end": "2020-08-06"
    },
    "jurisdiction": [
      {
        "code": "UUID_OF_FACILITY_1"
      },
      {
        "code": "UUID_OF_FACILITY_2"
      },
      {
        "code": "UUID_OF_FACILITY_3"
      },
      {
        "code": "UUID_OF_FACILITY_4"
      },
      {
        "code": "UUID_OF_FACILITY_5"
      }
    ],
    "serverVersion": 0,
    "goal": [
      {
        "id": "sickChildReferralGoal",
        "description": "Sick Child Referral Goal",
        "priority": "medium-priority",
        "target": [
          {
            "measure": "Percent of referrals closed",
            "detail": {
              "detailQuantity": {
                "value": 80,
                "comparator": ">=",
                "unit": "Percent"
              }
            },
            "due": "2020-08-06"
          }
        ]
      },
	  {
        "id": "suspectedMalariaReferralGoal",
        "description": "Suspected Malaria Referral Goal",
        "priority": "medium-priority",
        "target": [
          {
            "measure": "Percent of referrals closed",
            "detail": {
              "detailQuantity": {
                "value": 80,
                "comparator": ">=",
                "unit": "Percent"
              }
            },
            "due": "2020-08-06"
          }
        ]
      },
	  {
        "id": "pregnancyTestReferralGoal",
        "description": "Pregnancy Test Referral Goal",
        "priority": "medium-priority",
        "target": [
          {
            "measure": "Percent of referrals closed",
            "detail": {
              "detailQuantity": {
                "value": 80,
                "comparator": ">=",
                "unit": "Percent"
              }
            },
            "due": "2020-08-06"
          }
        ]
      },
	  {
        "id": "ancDangerSignsReferralGoal",
        "description": "ANC Danger Signs Referral Goal",
        "priority": "medium-priority",
        "target": [
          {
            "measure": "Percent of referrals closed",
            "detail": {
              "detailQuantity": {
                "value": 80,
                "comparator": ">=",
                "unit": "Percent"
              }
            },
            "due": "2020-08-06"
          }
        ]
      },
	  {
        "id": "pncDangerSignsReferralGoal",
        "description": "PNC Danger Signs Referral Goal",
        "priority": "medium-priority",
        "target": [
          {
            "measure": "Percent of referrals closed",
            "detail": {
              "detailQuantity": {
                "value": 80,
                "comparator": ">=",
                "unit": "Percent"
              }
            },
            "due": "2020-08-06"
          }
        ]
      },
	  {
        "id": "fpInitiationReferralGoal",
        "description": "Family Planning Referral Goal",
        "priority": "medium-priority",
        "target": [
          {
            "measure": "Percent of referrals closed",
            "detail": {
              "detailQuantity": {
                "value": 80,
                "comparator": ">=",
                "unit": "Percent"
              }
            },
            "due": "2020-08-06"
          }
        ]
      }
    ],
    "action": [
      {
        "identifier": "${UUID()}",
        "prefix": 1,
        "title": "Sick Child Referral",
        "description": "Receive referral, perform patient action and close it",
        "code": "Referral",
        "timingPeriod": {
          "start": "2019-08-07",
          "end": "2020-08-06"
        },
        "reason": "Sick Child",
        "goalId": "sickChildReferralGoal",
        "subjectCodableConcept": {
          "text": "Referral"
        },
        "taskTemplate": "Referral"
      },
	  {
        "identifier": "${UUID()}",
        "prefix": 2,
        "title": "Suspected Malaria Referral",
        "description": "Receive referral, perform patient action and close it",
        "code": "Referral",
        "timingPeriod": {
          "start": "2019-08-07",
          "end": "2020-08-06"
        },
        "reason": "Suspected Malaria",
        "goalId": "suspectedMalariaReferralGoal",
        "subjectCodableConcept": {
          "text": "Referral"
        },
        "taskTemplate": "Referral"
      },
	  {
        "identifier": "${UUID()}",
        "prefix": 3,
        "title": "Pregnancy Test or Confirmation Referral",
        "description": "Receive referral, perform patient action and close it",
        "code": "Referral",
        "timingPeriod": {
          "start": "2019-08-07",
          "end": "2020-08-06"
        },
        "reason": "Pregnancy Test",
        "goalId": "pregnancyTestReferralGoal",
        "subjectCodableConcept": {
          "text": "Referral"
        },
        "taskTemplate": "Referral"
      },
	  {
        "identifier": "${UUID()}",
        "prefix": 4,
        "title": "ANC Danger Signs Referral",
        "description": "Receive referral, perform patient action and close it",
        "code": "Referral",
        "timingPeriod": {
          "start": "2019-08-07",
          "end": "2020-08-06"
        },
        "reason": "ANC Danger Signs",
        "goalId": "ancDangerSignsReferralGoal",
        "subjectCodableConcept": {
          "text": "Referral"
        },
        "taskTemplate": "Referral"
      },
	  {
        "identifier": "${UUID()}",
        "prefix": 5,
        "title": "PNC Danger Signs Referral",
        "description": "Receive referral, perform patient action and close it",
        "code": "Referral",
        "timingPeriod": {
          "start": "2019-08-07",
          "end": "2020-08-06"
        },
        "reason": "PNC Danger Signs",
        "goalId": "pncDangerSignsReferralGoal",
        "subjectCodableConcept": {
          "text": "Referral"
        },
        "taskTemplate": "Referral"
      },
	  {
        "identifier": "${UUID()}",
        "prefix": 6,
        "title": "Family Planning Initiation Referral",
        "description": "Receive referral, perform patient action and close it",
        "code": "Referral",
        "timingPeriod": {
          "start": "2019-08-07",
          "end": "2020-08-06"
        },
        "reason": "Family Planning Initiation",
        "goalId": "fpInitiationReferralGoal",
        "subjectCodableConcept": {
          "text": "Referral"
        },
        "taskTemplate": "Referral"
      }
    ]
  }

Software Development Required

This section defines the software that needs to be developed to realize this feature. I have broken this down into a set of features that need to be implemented in the CHW app, the health facility app and the OpenSRP server. This section does not include reporting.

Out of Scope for the MVP

• Reporting
• Different business logic based on task type.
• Cancelling tasks

Decisions

• Do we need plans to make this easier to deliver because tasks are so tightly coupled with plans in Reveal?
• Do we need to use the Reveal locations in the OpenSRP server or are OpenMRS locations enough?
• Should we try to extract the Reveal task/plan processes into an independent library?
  • Comment - This is nearly complete
• Implementation details:
  • How will we translate user facing task elements into Swahili?
  • How should the task list view be sorted?

Core

We need to develop the following core features.

• Extract the task process from Reveal and make that available as a library
  • List view
  • Domain objects and Repository
  • Task based Activities and utilities
• Implement the task domain model from opensrp-server-core in the BA project and expose the API

CHW App

• Add all referral forms as defined in the data dictionary in both English and Swahili
• Add referrals to the FAB in the profile views of the app
• Add post save actions on each of these referral forms to generate tasks
• Add task list view called "Referral View"
• Add the ability to view (and edit?) referral forms from the task list (https://docs.google.com/presentation/d/1TJ_dstW4Ap4Hvxst4tYTT-vyPrE0isLakgocdWPb7_M/edit#slide=id.g50d639d270_1_140)
• Refresh the task list view when an update is received on the task from the server (i.e. change the task status)

Health Facility App

• Add a task list view that shows referrals
• Add a the ability to view the referral form and mark it as done
• Add the ability to change the task status and businessStatus when a user opens a referral from the task list view
• Add a referral to the patient's profile in each section of the health facility app
• Add the ability to change the task status and businessStatus when a user opens a referral from the patient profile view

Both Apps

• DONE Add the ability to sync tasks from the Android client to the server
• DONE Add the ability to sync referral forms from the Android client to the server

View Descriptions

This section defines the views that are impacted and the core data elements that define these views.

Card Structure

Row 1: (Given Name) (Family Name), (Age) (DateTime)
Row 2: (Referral Reason)
Row 3: Referred by CHW (CHW Username)