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.
...
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
We do not need to deliver these workflows within the same Reveal APK. We can deliver a different NTD application that focuses on distribution point workflows.
...
A single plan will not include a combination of NTD workflow with other intervention types (FI, IRS, MDA)
...
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.
There Below are a few key core decisions that we need support from the developers. First, we need to figure out exactly how we want to represent a distribution point in the geographic hierarchy. Craig’s perspective is to treat them as a structure with a specific type of “distribution point” These can be created in the Android client or in the web server. Second, we need to figure out if we should represent all clients registered in a single all clients list that was recently built for Malawi and transitioned into Wellness Pass. Craig expects this is a good move for Reveal, but we need Sam G to weigh in on this. Third, we need to figure out if we want to implement modules within the existing Reveal application or if we need to implement plans and tasks in another application that we have built for OpenSRPdrive 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:
...
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
...
The OpenSRP server will need to be improved so that we can import a CSV and generate clients server side. The functional requirements includes a template of fields that they believe need to be included. We need to make a few decisions on this import. First, does the import template make sense from the developer’s perspective. For example, can the mapping be done appropriately in the server and can we create a complete client with the information presented? Second, can we create and sync clients from the server to the Android client, or do we do we need to create events for each row in the import? Third, can we make the client generator generic by design so that we could configure how we want to structure the import to be able to create multiple types of clients in OpenSRP as a generic feature? Fourth, how will we handle mistakes when a user uploads information that they don’t want to be there. What’s the lifecycle we should create to remove the likelihood of duplicates? Fifth, we need to make a decision on whether we assign each imported client to a particular distribution point in the system, the operational area, or both.
Below are a few items that we need to develop in the OpenSRP server:
...
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.
This also needs to be supported in the CSV upload.
See the subsection labeled CSV Upload to Client Event Generator
We need to be able to generate clients by using a CSV upload. Each row will present an event
Outstanding questions or 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
The OpenSRP web UI will need to support uploading CSVs to create clients int he system. Additionally, we will need to make distribution points available in the IRS map based planning. Finally, we will need to update the manage plans form to support the MDA and NTD additional plans.
Upload CSVs to create entities in the system
Adjust the map based planning to include schools (points on the map)
Adjust the manage plans and add new plan view to include MDA plan types and NTD plans
Add reporting for NTDs based on the inputs from Akros (Isabel Shaw , we need details to be included here)
CSV Upload →
...
Event Generator
We need to develop a server side client generator that generates clients server side for each row that’s available in the import. We aim to make the CSV entity generator generic so that we can import different types of entities into OpenSRP in the future. We need to pass in the event template with the CSV that shows field mapping of the CSV to event objects or make it so that system administrators can configure these entities and evolve their generation over time.
...
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
...