This is a mapping file that is written for every form which maps the fields within the form to Dristhi OpenSRP database. An example Now we would look into how a sample form_definition.json is belowfor this model.xml would look like (keep in mind we would be using the entity_relationship.json as mentioned earlier as the entity relationship in this case):
| Code Block | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
{ "form_data_definition_version": "1", "form": { "default_bind_path": "/model/instance/hh_reg", "bind_type": "household", "fields": [ "entity", { "name": "id", "shouldLoadValue": true }, { "default_bind_path "name": "HH_ID", "bind": "/model/instance/hh_reg/HH_ID" }, { "name": "HH_Name", "bind": "/model/instance/formhh_idreg/", HH_Name" } ], "fieldssub_forms": [ { {"name": "ec_repeat", "bind_type": "eligible_couple", "namedefault_bind_path": "field1/model/instance/hh_reg/ec_repeat", "fields": [ "source": "entity.value1", { "name": "id", "shouldLoadValue": true }, { "name": "woman_name", "bind": "/model/instance/hh_reg/formec_idrepeat/field1", woman_name" }, { "name": "husband_name", "shouldLoadValue": true "bind": "/model/instance/hh_reg/ec_repeat/husband_name" }, { "value "name": "value1" EC_HH_ID", "bind": "/model/instance/hh_reg/ec_repeat/EC_HH_ID" }, { { "name": "EC_HH_Name", "name "bind": "field2",/model/instance/hh_reg/ec_repeat/EC_HH_Name" }, { "sourcename": "entity.value2note", "bind": "/model/instance/hh_reg/formec_idrepeat/field2",note" }, { "valuename": "value2raihan_text", "bind": "/model/instance/hh_reg/ec_repeat/raihan_text" } ] } ] ] } } |
Explanation for the same below:
"form_data_definition_version
This defines ": "1", denotes the version of the form definition. Every Every time the form definition changes, this version must be incremented. This will be useful when handling the form. bind_type
This defines the entity for which the form is being filled. As of now, the possible values for this are eligible_couple, mother or child.
default_bind_path
This is the default value for bind path in case it is not specified in the field.
fields
This has all the fields that we have to map between Dristht DB and Forms.
name
This is the name of the field.
source
This specifies the mapping path for a field in Dristhi DB. For example, if the value for this is entity.value1 then the field value is loaded from or saved onto value1 field of entity when the entity is saved or updated. If no value is specified for this, the value is inferred as [bind_type].[name]
bind
This specifies the mapping path for a field in model.xml (Enketo form field). For
The form starts from: “form”: part in the above json.
"default_bind_path": "/model/instance/hh_reg", is the reference to the model to which this particular form is bound to. ‘hh_reg’ is the form name in this case.
“bind_type”: Bind type is an important aspect and it refers to the initial bind type in the entity relationship model we had shown. In this case we are keeping the bind_type as household however these could be household, eligible_couple, mother and child.
“fields”: is the part which links the names we want in form submission to the tags/name of questions in form.
Before we move onto a typical field , we should look into a special kind of field that each “fields”: array should start with if its an initiation of a bind type (i.e. not a follow up but when you first create an entity of a certain bindtype).
{
"name": "id",
"shouldLoadValue": true
},
This tells the form to create a system generated id for a household (ie. the bindtype). This would populate the id column of the household table in the database in the opensrp client. Just remember to put this as a default first field when you expect an entity to be created.
Moving on a typical field would look like :
{
"name": "HH_ID",
"bind": "/model/instance/hh_reg/HH_ID"
},
Here the name field is the name of the field we want to see it as in form submission as well as the name by which it would be stored as in the client database. The bind refers to the tag in the model.xml (i.e the name of question in the xls form) from which the field pulls its value, for example, if the value for this is /model/instance/form_id/field1 then control that corresponds to this XPath will be pre-populated with the corresponding value. If no value is specified for this, the value is inferred as [default_bind_path]/[name]
shouldLoadValue
This field tells Ziggy that the field should be pre-populated with the corresponding value.
value
This is the value for the field. When .
Form submission for this particular field would look like :
{
"name": "HH_ID",
"bind": "/model/instance/hh_reg/HH_ID",
"source": "household.HH_ID",
"value": "256"
}
source: This specifies the mapping path for a field in OpenSRP DB. For example, if the value for this is entity.value1 then the field value is loaded from or saved onto value1 field of entity when the entity is saved or updated. If no value is specified for this, the value is inferred as [bind_type].[name]
Value: is the value the user entered in the form which is ‘256’. When the form opens if value is specified then Enketo pre-populated the field with the specified on the form.
ShouldLoadValue: 'true' field denotes that the field is auto-generated & is also used to show that a previous value shall be loaded and the source tells it where it should be saved
Moving on we have sub_forms . Sub forms are repeating groups. They are like exactly a form but would appear as a child of a form. Here the sub form has attributes exactly like the form but the bindtype is different. We can see here the bindtype is an eligible_couple which has a child relationship with household. Also the default bind path refers to the repeat group start tag of the form.
As this is initiating an eligible_couple for the first time,the id we put as a default starting should also be there. If we go back and look at the entity relationship we would see something like this :
"from": "household.id",
"to": "eligible_couple.relationalid"
This would mean each eligible_couple we create would by default have a relationalid which would be same in value of the household.id it is a child of.