Hi all,
Based on the discussion we had on this thread: Brief demo video of the DHIS Connector Module - #8 by jesplana and on the last COVID Squad call, I thought of initiate this thread to verify the requirement and the design for implementing functionality to map Org Units in the DHIS Connector module.
Why we need it?
Whenever a user needs to send data to dhis2, the user has to pick the relevant OMRS location and the DHIS2 Org Unit.
Fig. 1. A screenshot from the DHIS Connector Module’s run report view.
The following are the downsides of the above option,
- Users has to select the relevant Org Unit each time they run a report
- Users need to know about the mappings between Org Units and locations. If they select a wrong matching, it might lead to unexpected results in reports.
- Most of the time a dataset has a limited number of assigned Org Units. If a user selects an unassigned Org Unit, it’ll throw an error after sending data (from DHIS2) - which is not good from a UX perspective as well as a performance perspective because it has to run the mapped period indicator report before getting the error.
- If a dataset has multiple Org Units, then the user has to re-run the report by changing the locations one by one. (Ex: If a dataset is mapped with 100 org units, then the user needs to rerun the report 100 times)
- If a dataset has multiple Org Units, and if the user needs to schedule the report, then the user has to schedule automation for each location.
The solution
One of the things we can do is introducing a feature to map the locations. With that, we can introduce a new UI as in Fig. 2 to map the locations with the matching DHIS2 Org Units. This will be a one time task for the user and they would edit it at any time. The mapping will be stored in a module-specific table in the database.
Fig. 2. Proposed UI for the Map locations page
With the above mapping, we no longer need to prompt the user to select the matching OrgUnits when running a report; selecting the location would be enough because the org units are already mapped with the locations. It will solve issues no. 1 and 2.
However, it won’t solve the issues related to the multiple Org Units. As a solution, we can get the assigned Org Units of a dataset. Then we can run the period indicator report for each corresponding location at once and send the data to DHIS2. (We can send multiple 'dataValueSet's with one request payload) Hence the user doesn’t need to worry about locations at all. Fig. 3 reflects the changes proposed to the run report page.
Fig. 3. Proposed changes for the Run Report page.
The Plan
We can divide the development into two iterations.
Iteration 1
Provide a UI that is capable of mapping the OMRS locations with DHIS2 Org Units. The DHIS2 Org Unit picker will be removed from the Run Report page and the automation page. It will list down only the mapped OMRS locations.
Tasks:
- Create a new table to store the location mappings
- Implement a new endpoint to manage mappings
- Implement a new UI to map locations
- Remove the Org unit picker from the run report page. Pick the mapped Org unit of the selected OMRS location from the DB.
Iteration 2
The location selection will be completely removed from the Run reports, and Automation pages. The user doesn’t need to worry about the locations and doesn’t need to run the re-run the report for each location. Just selecting the mapping would be enough.
Tasks:
- Fetch assigned ORG units for a given dataset.
- Run the Period indicator report for each OMRS location and generate the DXF payload that contains multiple
dataValueSets.
Assumptions
- The relationship between OMRS locations and DHIS2 Org units is 1:1
cc: @grace @jennifer @ibacher @dkayiwa @k.joseph @jesplana @bawanthathilan @piumal1999 @anjisvj