This document defines the software requirements for the distribution point features for Reveal. A distribution point is a centralized location where individuals meet to receive care. The primary workflows are funded under a grant for Neglected Tropical Diseases (NTDs) which focuses on distributing medication among children who are attending schools in Eswatini. The functional requirements are outlined on NTD School Workflow and the data dictionary. This document applies those functional requirements into the Reveal technical architecture.
Themes
There are a few themes that make the distribution point workflow different from the existing Reveal workflows:
Individuals gather at the distribution point instead of healthcare workers going door-to-door at a community
We are using the term distribution point so it can be more generic than school-based workflows. We believe that the workflows defined by the NTD School Workflow project are able to be run regardless of whether at a school or other distribution setup by project partners.
The NTD workflows, as scoped, assume no longitudinal health record. We will utilize existing features in Reveal to ensure each client has a longitudinal health record that can be improved upon at each health encounter.
Assumptions
A single plan will not include a combination of NTD workflow with other intervention types (FI, IRS, MDA)
Summary of Core Features
This section summarizes the core features required for delivering the workflows outlined in the functional requirements document.
Android Client
The Android client needs to be able to receive clients that have been loaded in to the distribution point into a single register view that supports sorting and filtering. This register view needs to display all clients registered at the distribution point whether they have a task or not. If they have a task, the task will allow users to collect information against the client and add that the client’s longitudinal health record. Each client has these metadata tags that allow them to be filtered. These are represented in the mock-ups and data dictionaries. We want to make them generic tags that we can repurpose for other workflows in the application, allowing for greater flexibility when filtering any client list in the future.
Below are core decisions that drive the Android client:
Distribution points will be loaded in to Reveal as locations that are not jurisdictions. These will have a tag of distribution point. Users will be able to assign plans to distribution points.
We will represent all clients in a single all clients register utilizing the family module that’s already in Reveal. There isn’t a hard constraint on having a family registered for children.
We will build all of this on top of the Reveal APK.
UI mock-ups are available at:
Below is a list of features we need to build in the Android client:
Register view of all clients registered to receive care at that distribution point
Add, Update, and Archive client registration information
This includes assignment of up to three metadata tags (class, grade, etc) that need to be defined server side.
Generate tasks in the Android client:
When a client is registered
When a form is saved
View of all tasks assigned to all clients in the system
Update the hamburger menu to display the additional step in the geographic hierarchy so that users can select a distribution point.
Individual client view that displays all tasks assigned and their status with the ability to edit the underlying form (as seen in the mock-ups)
Search, Sort, and Filter the all clients view
Search
Client First and last name
By school identifier
By system identifier
Filter
By task type
By task status
List clients who do not have a task assigned
By metadata point 1, 2 and 3
OpenSRP Server
The OpenSRP server will need to be improved so that we can import a CSV and generate events that create “register client” events in the OpenSRP server for each row. These events will then be allocated to the correct jurisdiction and synced down to the appropriate devices.
User Workflow: (Note that this needs to go through a UX review with Roger)
(Outside of the system) The user updates a template based on the structure that’s defined for the project
User logs into the system
User chooses a plan (draft or active)
User chooses a jurisdiction that they want to upload the CSV
User clicks a button to find the file on their computer
User clicks the upload button and the CSV is uploaded to the server
Details are passed in with the CSV to show what types of entities to generate and the mapping of the template.
CSV is parsed server side and validated (See CSV Validator section)
An error is returned to the user if the CSV is invalid or it doesn’t pass a security check
An event is created for each row in the OpenSRP server
Each event is tagged to the plan and location
A task is created for each even that’s uploaded if the plan is active. Otherwise, tasks are created when the plan becomes active.
(Existing functionality) A client is created in the Android client for each event when it’s received
The OpenSRP server needs to be enhanced in the following ways in order to deliver this workflow:
We need to build a REST API in the OpenSRP server that can receive the CSV file and perform the event generation
We need to build the foundation for a server side task generator in OpenSRP that can generate tasks as a service when the CSV is uploaded. This task generator will be improved upon in the coming months so that we can move the Nifi flows that generate tasks for Focus Investigation, IRS and MDA to Java server code so that the task generation system functions better.
Note that this will involve engaging the queuing software in OpenSRP so that we don’t overwhelm the server with a spike of activity.
We need to build an import template pattern that is configurable for OpenSRP. This would allow us to create a server side configuration that validates the template that was received and create the events. Ultimately, this will be able to be used generically to import events and, optionally, tag them to the appropriate jurisdiction and plan.
We need to be able to define settings that map the event/client metadata tags to the labels in the CSV template, sync them down to the Android client and make them available for display and filter in the Android client. We have three points that need to be dynamically assigned in the app. We need to “tag” each client in the register view to up to 3 of those points so they can be searched against.
See the subsection labeled CSV Upload to Event Generator
We need to be able to generate clients by using a CSV upload. Each row will present an event
Outstanding questions on this section:
How do we roll back these items in the event someone messes up?
We need to define the logic behind generating
(Business question) Users don’t have a view into all of the entities that are registered to a distribution point. Therefore, they have no idea if their list was uploaded correctly. How should we mitigate this?
In other words, how will we handle mistakes when a user uploads information that they don’t want to be there. What’s the life cycle we should create to remove the likelihood of duplicates?
OpenSRP Web UI
We need to develop the following features in the OpenSRP Web UI in order to deliver the features above.
UI for uploading CSV files to send to the OpenSRP server’s REST API
Change the manage plans form so that users can either select jurisdictions or distribution points
Adjust the manage plans and add new plan view to include MDA plan types and NTD plans
Web UI Reporting Needs
The reporting needs are defined in the data dictionary from Akros. This will require changes to the Canopy flow to make sure the data is available to the data warehouse and Superset.
[This section needs to be enhanced by showing the reporting needs and differentiating the current reporting process so the development is straightforward. Isabel Shaw will do this.]
CSV Upload → Event Generator
We need to develop a server side event generator that generates events server side for each row that’s available in the import. We aim to make the CSV event generator generic so that we can import different types of entities into OpenSRP in the future. We need to reference the event template with the CSV so that we can identify which fields should be mapped to which events when they are created. This template should be defined within the OpenSRP server so that it’s CSV to event objects or make it so that system administrators can configure these entities and evolve their generation over time.
[This section needs to be enhanced by showing the business logic that’s executed when the CSV is uploaded. Craig Appl will do this]
CSV Validator
CSVs need to go through a validation process that can generate an event that will sufficiently generate a client when the event is loaded in the Android device. This section defines the details of the CSV Validator.
Perform a security validation to reduce risks on import (see the Security section below)
Validate the structure of each field in the template
(Stretch) identify if there is an existing client in the system with the same information. Provide feedback to the user.
[This section needs to be improved by identifying how we will address duplicates. Craig Appl will update this.]
Plan Definition and Task changes
This section defines the changes to the plan generation and task process for NTDs. The most simple solution is to slightly modify the plan definition template for NTD distribution point workflows. In the long run, we need to accommodate NTDs in the dynamic tasking workflows that are scheduled to be developed in June.
Plan Definition Sample
We will add the following attributes to a plan definition. All core task sections are defined in The All Events Data Dictionary
[Craig needs to complete this section]
Outstanding Items on the Plan Definition and Task Changes
The current Task paradigm in Reveal generates all tasks when the plan is changed to active. We have a work item to persist entities in the Android client by the end of June as well as support dynamic tasking client side. Craig has a hunch that there is a core redesign in how and when we generate tasks in Reveal. We went through a lot of pain in the past because we only allowed tasks to be generated once instead of doing it on a rolling basis while events happened in the system. We need to look at the whole picture of what needs to be delivered in June and figure out if we can work on that as part of this work. This section focuses on those changes so we can make a clear decision.
[This section needs more thought and research from Craig based on the long term timelines for Reveal.]
We need to rethink when tasks are generated server side.
Prior workflows generated tasks at one time when the plan was transitioned from draft to active
We have the dynamic tasking feature which may overlap
We need to
Task Data Elements
Security
This section defines security requirements for these features.
Users should not have the capability to download large lists that contain personally identifiable information about the clients.
Access to download rosters will, at maximum, provide identifiers that can be linked to people registered in the system.
All uploads need to be validated to include the following:
Valid CSV architecture with UTF-8 encoding
Individual fields are parsed and validated to remove exposure to SQL injection threats
Individual fields are parsed and validated to remove exposure to cross-site scripting threats
(We probably need to add more here)
Things to be discussed from scoping so far
We need to validate the assumption that we will support importing rosters against active plans.
Do we only import rosters against active plans?
Should we support importing rosters against plans in draft state?
Should we generate tasks when a plan is shifted to active like we currently do?
Out of Scope
Linking people who were registered in the distribution point workflows to families or structures