Formatting the JSON File
We detailed the process of formatting a JSON file to create a customized questionnaire form for the RTMIS system. The RTMIS system leverages the Akvo React Form Editor for generating initial JSON form structures. We explored the basic structure and components of the form JSON, as documented in the Akvo React Form's README.
Additionally, we introduced specific customizations required for RTMIS, including the addition of submission_types at the form level and three new parameters at the question level: default_value, disabled, and hidden. These custom parameters are defined as objects based on the submission_type, which is specified as an enumeration.
We provided a detailed example of the JSON structure incorporating these customizations and outlined the manual steps needed to add these custom parameters after generating the initial JSON form. By following this process, users can effectively format their JSON files to meet the requirements of RTMIS customized questionnaire forms.
Overview
The RTMIS system uses a JSON file to build a questionnaire form. This JSON file can be generated using an internal library called Akvo React Form Editor. For more information and to access the editor, visit the following link: https://akvo.github.io/akvo-react-form-editor/
In general, all components and formats in the form JSON are documented in the Akvo React Form's README file. You can find the documentation here: https://github.com/akvo/akvo-react-form/blob/main/README.md
However, for this project, we have added customizations at the form-level definition and at the question level. These customizations include the addition of submission_types at the form level, and three additional parameters at the question level: `default_value`, `disabled`, and `hidden`. These parameters are defined as objects and depend on the `submission_type`.
The `submission_type` itself is an enum value and is defined as a constant. You can view the definition here:
https://github.com/akvo/rtmis/blob/main/backend/api/v1/v1_forms/constants.py#L37-L48.
All the customizations will be added manually after the JSON form is generated with the Akvo React Form Editor.
Customization Details
Form Level Customization
At the form level, we introduce a new parameter: `submission_types`. This parameter specifies the different types of submissions allowed for the form. The `submission_types` parameter is defined as an enumeration, providing a set of predefined submission types that the form can handle.
Question Level Customization
At the question level, we introduce three new parameters:
1. default_value: Specifies the default value for the question. This value will be pre-filled when the form is loaded.
2. disabled: A boolean parameter that indicates whether the question should be disabled (i.e., not editable) when the form is displayed.
These parameters are defined as objects and their values depend on the `submission_type`.
Example JSON Structure
Here is an example structure of the JSON file with the added customizations:
{
"id": 123456,
"form": "Community Monitoring Form",
"description": "Community monitoring",
"defaultLanguage": "en",
"languages": ["en"],
"version": 1,
"type": 1,
"translations": null,
"submission_types": [
"registration",
"monitoring",
"verification",
"certification"
],
"question_groups": [
{
"id": 1699354006534,
"order": 1,
"name": "community_primary_data",
"label": "COMMUNITY Primary data",
"description": "COMMUNITY: data",
"repeatable": false,
"translations": null,
"questions": [
{
"id": 1699354006535,
"order": 1,
"name": "new_or_update",
"label": "New Community or Monitoring update?",
"short_label": null,
"type": "option",
"tooltip": {
"text": "Entry of community data in RTMIS (first time) or update of monitoring data (existing community)"
},
"required": true,
"meta": false,
"options": [
{
"order": 1,
"label": "New",
"value": "new"
},
{
"order": 2,
"label": "Update",
"value": "update"
},
{
"order": 3,
"label": "Verification",
"value": "verification"
},
{
"order": 4,
"label": "Certification",
"value": "certification"
}
],
"default_value": {
"submission_type": {
"monitoring": "update",
"registration": "new",
"verification": "verification",
"certification": "certification"
}
}
},
{
"id": 1699951210638,
"order": 2,
"name": "location_community",
"label": "What is the location of the community?",
"short_label": null,
"type": "administration",
"tooltip": {
"text": "This question contains a list of possible household locations, starting with the government area or district, down to the village."
},
"required": true,
"meta": true,
"disabled": {
"submission_type": ["monitoring", "verification", "certification"]
}
},
{
"id": 1716283778,
"order": 33,
"name": "community_households_achieved_required_outcomes",
"label": "Have 100% of households in this community achieved the required outcomes for this grade?",
"short_label": null,
"type": "option",
"required": true,
"meta": false,
"options": [
{
"order": 1,
"label": "Yes",
"value": "yes",
"color": "green"
},
{
"order": 2,
"label": "No",
"value": "no",
"color": "red"
}
],
"hidden": {
"submission_type": ["registration", "monitoring", "certification"]
}
}
]
}
]
}Manual Customization Process
- Generate the JSON Form: Use the Akvo React Form Editor to create and export the initial JSON form structure.
- Add Form Level Customization: Manually add the
submission_typesparameter at the form level. - Add Question Level Customization: For each question, manually add the `default_value`, `disabled`, and `hidden` parameters as needed. Define these parameters as objects, specifying their values based on the `submission_type`.
- Review and Validate: Ensure that the JSON structure follows the correct format and that all customizations are properly defined.
By following these steps, you can successfully format the JSON file to work with RTMIS as a customized questionnaire form.