AMR Surveys

AMR Surveys is custom React App used by the Anti Microbial Resistance(AMR) team of WHO to survey countries across the world.

Each Survey corresponds to a Program in DHIS. Either a Tracker Program or an Event Program.

The react app generates a form for each survey by fetching the metadata of the program and creating a react "widget" for each element in the Program. Some point to note about creating a survey form from program in the code:

• Programs can either be Tracker Programs or Event Programs.
• Each Survey is called a Questionnaire in code. Questionnaire structure can be seen at https://github.com/EyeSeeTea/amr-surveys/blob/1119f145710ef03429904d5a6c159b564e765319/src/domain/entities/Questionnaire/Questionnaire.ts#L54
• Each Questionnaire has multiple stages, sections, rules. Questionnaires corresponding to Tracker Programs also have entity (which corresponds to TEA in DHIS) and subLevelDetails(which stores the enrollmentid)
• The TEAs stage is called "Profile" stage across all surveys.
• Each Stage can be repeatable. If the stage is repeatable, then a new stage can be added using Add new button. The repeatable code logic can be found at : https://github.com/EyeSeeTea/amr-surveys/blob/1119f145710ef03429904d5a6c159b564e765319/src/domain/entities/Questionnaire/Questionnaire.ts#L327
• Each Questionnaire has multiple rules that correspond to program rules in DHIS. The code handles program rules and

Program Rule Parsing

Program rules created in DHIS for each program, need to applied in the corresponding Survey Form.

• In the code, we fetch the rules associated with a program when a form is opened
• We apply all the program rules on initial load of the form : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/Questionnaire.ts#L144
• Then, on each question(field) update - we filter the applicable rules, and apply them with the updated value of the question : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/Questionnaire.ts#L255
• Program rule has 2 main parts - condition and action.

Program rule condition parsing

To parse the condition in the program rule, earlier we had custom logic which had lot of issues/bugs. In Nov 24 we changed the code to use DHIS package for expression parsing : https://github.com/dhis2/expression-parser This is a lot more reliable and has no known bugs so far. The wrapper code to use this package can be found at https://github.com/EyeSeeTea/amr-surveys/blob/development/src/data/entities/D2ExpressionParser.ts The expression parser takes as input the condition and the values for the variables for the condition and returns a true or false value.

Program rule action

Program rules have actions like : hide field, hide section, show error, show warn, set mandatory etc.(Check DHIS for complete list) Currently in AMR Survey code we support :

• HIDEFIELD : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/QuestionnaireQuestion.ts#L282
• HIDESECTION : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/QuestionnaireSection.ts#L102
• SHOWERROR : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/QuestionnaireQuestion.ts#L313
• SHOWWARNING : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/QuestionnaireQuestion.ts#L313

Recursive program rule application

If one question is updated, there could be side-effects for that question. And each of those side effect questions, could cause a another side effect. So the program rules need to be recursively applied to all questions that are effected by that update. In Nov 2024, we have added the code for recursive handling of program rules : https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/domain/entities/Questionnaire/QuestionnaireQuestion.ts#L162 Arnau has context on this. Please contact him if any issues around this area that are not solvable within the team.

Custom Survey Rules

There are many survey rules - which are customised app specific logic that have been handled. They are a niche scenario and applicable only to certain surveys in certain cases. They are related to Antibiotic Black listing, AST Guidelines, hiding specific sections/field only in specific instances of surveys. All of these configuration details are stored in datastore. Please contact Miquel for details on custom survey rules - the conditions are complex but the code is fairly simple.

#PPS There are 5 forms corresponding to PPS where each form is the child of the previous :

• Parent : PPSSurveyForm

• PPSCountryQuestionnaire

• PPSHospitalForm

• PPSWardRegister

• PPSPatientRegister - This is the only form in PPS that is fetched and displayed in a paginated manner. This is the only survey that has search functionality.

• When listing each child should be filtered by its parent

• The topmost parent is saved at saved at Global level.

• Country Surveys are stored at country level. The country is chosen in the UI by the user.

• Hospital Surveys are stored at hospital level - 6,7,8. The hospital is chosen in the UI by the user.

• Ward Surveys and Patient Surveys are stored at parents hospital level - 6,7,8.

Prevalence

There are 5 forms corresponding to PPS where each form is the child of the previous :

• Parent : PrevalenceSurveyForm

• PrevalenceFacilityLevelForm

• PrevalenceCaseReportForm - This form and its children in Prevalence are fetched and displayed in a paginated manner. This is the only survey that has search functionality.

• PrevalenceSampleShipTrackForm, PrevalenceCentralRefLabForm, PrevalencePathogenIsolatesLog, PrevalencePathogenIsolatesLog, PrevalenceSupranationalRefLabForm, PrevalenceD28FollowUp, PrevalenceDischarge, PrevalenceCohortEnrolment

• When listing each child should be filtered by its parent

• The topmost parent is saved at saved at country level. The country is chosen in the UI by the user.

• Facility Surveys are stored at hospital level - 6,7,8. The hospital is chosen in the UI by the user.

• All other surveys are stored at parents hospital level - 6,7,8.

• Only PrevalenceCaseReportForm has multiple children, and so the child count logic is different for it. This code is a little convoluted and needs to be improved.

Access/Permissions

• User needs to have AMR Surveys PPS data capture, AMR Surveys PPS admin or AMR Surveys PPS data visualizer user groups assigned to be able to see PPS module in menu
• User needs to have AMR Surveys Prevalence data capture, AMR Surveys Prevalence admin or AMR Surveys Prevalence data visualizer user groups assigned to be able to see Prevalence module in menu
• The following key needs to be adde din datastore under amr-surveys/modules

amr-surveys-modules.json

• All programs should have appropriate user groups access and org unit access for user to be able to list and create surveys in app:

Notes

• Each child survey has a data element/TEA with its parent's(and root parent's, if applicable) id. This is how the parent-child relationships are saved. the code automatically populates this field and it is disabled so that user cannot change it.
• Recently PPSPatientRegister was changed from event program to tracker program with repeatable stages.
• Sort order - the metadata endpoint of DHIS returns the data elements/TEAs in sorted order in only one of the objects in the response. https://github.com/EyeSeeTea/amr-surveys/blob/41bdbc087dd217fe2200a97a702c46a1f4c77df8/src/data/repositories/SurveyFormD2Repository.ts#L62

To Do:

• Contexts are not saved to browser local storage, so reloads behave weirdly (not filtered).
• Child count logic needs to be improved.