This post describes a feature which exists in JHU Collect, which was forked from ODK Collect some time ago. At the time of this writing, JHU Collect is 95 commits ahead and 2013 commits behind ODK Collect. The goal would be to get this feature into ODK collect.
What is the general goal of the feature?
The goal of this feature is to allow forms that are related to each other to be "linked". The most important feature of this "linking" is that some data should be shareable between them.
What are some example use cases for this feature?
A common use case is a household questionnaire that would be connected to one or more household member questionnaires.
What can you contribute to making this feature a reality?
JHU Collect is used by PMA2020. Myself and @jpringle are frequent users. However, I do not know what our capacity is / will be in the near future for contributing towards this. We are currently transitioning to a new grant. I believe we will know more in the coming months about what our capacity for this under the new grant would be.
Technical description and further details
In the source file there is a
save_instance binding. The corresponding fields exist in the source XlsForm.
A standard use case is the following:
- The parent form is a used to fill in a household roster to identify people for further follow-up.
- Children forms are generated for those who are identified, and certain data is pre-populated in the children forms.
PMA2020 uses this scheme to interview a household (household questionnaire) and identify eligible females for later questioning (female questionnaire) on topics like reproductive health. The household questionnaire might have the following fields:
hidden stringtype (similar to a
calculate), with the value of
save_formfield of the XlsForm. The value "fq-v1" represents the
form_idin the settings worksheet of the child form. In this case, it would be short for "female questionnaire, version 1".
- 1+ fields (I believe any
typeis possible), with values of the structure
save_instancefield of the XlsForm. The "XML_ROOT" would be found in the
xml_rootfield of the settings worksheet of the child form. If, for example, my "XML_ROOT" was "FQ" (female questionnaire), and I had a question with the name
first_namein a group called
confirm_info, the following value would be entered in
Given this setup, we would expect the following behavior in JHU Collect:
- An interviewer would enter a household roster in the household questionnaire. Upon saving it, she would receive a toast notification saying that the form had been saved, and 1+ other forms were created.
- The interviewer would navigate to the new forms or edit forms section. There, she would see a single item that she could select which, in ODK Collect, would simply be the name of the form, which she would press her finger on to enter the form. In JHU Collect, tapping this option would expand into a list of the parent form (household questionnaire) and any child forms (female questionnaire(s)).
- She opens a child form.
- When navigating to the questions for which the path to that question was designated in the
save_instancein the parent form, the question would be pre-populated with whatever the value was in the parent form (household questionnaire).
- If she changed that information in the child form (female questionnaire), the change would be synced with the corresponding value in the parent form.
- Once completing all of these linked forms (parent form and all child forms), she would be able to submit to the server.
Some features of form linking are the following:
- The parent form may contain eligibility logic to create the child form. If in the parent form, answers are changed such an existing child form is no longer eligible, the child form is deleted.
- The child form may contain eligibility logic such that if further information shows ineligibility, the child form will be deleted.
- The parent form determines the instance name of the generated forms upon creation.
- Example: PMA2020 uses this so that in the instance chooser list, the instance name shows the age and name of the eligible female.
- The parent form may send values to the child form. These values are linked, so that an update in one form triggers an update in the other form.
- Example: PMA2020 uses this so that name and age can be updated in the female form.
- In the instance chooser lists for "edit saved form," "send finalized form," "view sent form," and "delete saved form," linked instances are shown together.
- In "send finalized form," linked instances are sent to the server together.
- In "delete saved form," deleting a parent instance deletes all child forms
We at PMA2020 have used the form linking functionality only in the context of repeat groups. If a single repeat group has an associated child form and the repeat group is deleted, then the child form is deleted.
In the future, it may be useful to allow different child forms with different eligibility and to allow form linking outside of repeat groups.