Input data available in forms

Data accessible from within CHT forms

CHT forms have access to varying amounts of input data depending on the type of form and its source.

contact forms

Available data:

Initial contact data in contact forms

Create forms

Forms for adding contacts have access to a small group of fields contained in a top-level group that is named for the contact_type id of the contact being added (so person, clinic, etc). (This is the same group used to create the contact document when the form is completed.)

typenamelabelhint
begin grouppersonNO_LABEL
hiddenparentParent IdContains the doc id for the new contact’s parent contact doc.
hiddencontact_typeContact TypeThe contact_type id of the contact.
end group

Edit forms

Forms for editing contacts have access to all the contact’s current data. These fields are contained in a top-level group that is named for the contact_type id of the contact being added (so person, clinic, etc). If fields in the top-level group are edited by the form, these changes will be saved to the contact’s doc.

In addition, the contact’s parent data is hydrated so that the form has access to the data stored on the parent contact doc in the parent group.

typenamelabelhint
begin grouppersonNO_LABEL
begin groupparentParentContains the data for the contact’s parent contact doc.
hiddennameParent nameThe name of the parent contact
end groupparent
end group

app forms

Available data:

Form source

If a form is created from the “People” tab, inputs/source will be set to “contact”. If a form is created from a task, inputs/source will be set to “task”.

inputs data for contact in app forms

app forms with a contact in context have access to that contact’s data in the inputs/contact group.

The contact group contains all the fields from the doc of the contact in context. If a place is in context, the primary person for that place will be hydrated in the inputs/contact/contact group. Alternatively, when a person is in context, the parent place for the person will be hydrated in inputs/contact/parent.

contact-summary data

app forms with a contact in context can access the contact-summary data associated with the contact. This is done by referencing an instance named contact-summary. E.g. instance('contact-summary')/context/${variable}. See the reference documentation for more information.

inputs data from task

app forms created via a task have access to any data supplied by the task in the inputs group.


user data

Both app and contact forms can access the current user’s data at inputs/user. The data provided is simply the CouchDB doc for the user (e.g. org.couchdb.user:username) plus an additional language field that contains the user’s currently selected language code.

Example of saving user data as metadata on a report

typenamelabelcalculation
begin groupinputsNO_LABEL
begin groupuserNO_LABEL
stringcontact_idUser’s contact id
stringfacility_idId for user’s facility
namenameUsername
end group
end group
calculatecreated_byUsername that created report../inputs/user/name
calculatecreated_by_person_uuidUUID that created report../inputs/user/contact_id
calculatecreated_by_place_uuidFacility of user that created report../inputs/user/facility_id

Loading the user’s contact data

While the inputs/user group does not contain the user’s contact data, it does contain the user’s contact_id which can be used to load the contact doc via a contact selector.

Contact selector

Using a contact selector allows you to load data from the selected contact (person or place). The contact’s id can be provided by the form or the user can search for an existing contact.

To select a contact in a form, create a field with the type string and set the appearance to select-contact type-{{contact_type_1}} type-{{contact_type_2}} .... Setting multiple contact_type ids allows the user to search among multiple types of contacts. If no contact type appearance is specified then all contact types will be queried when searching.

Searching for a contact

When a contact selector question is visible in a form, the user can search for a contact by typing in the search box.

A value can be pre-selected for the search box via a calculate expression. By default, the user can change the selected value, but this can be prevented by setting read_only = true.

typenamelabelappearancecalculate
stringperson_idPerson IDselect-contact type-person
stringhousehold_idHousehold IDselect-contact type-clinic../inputs/contact/parent/_id

Loading descendants of the current contact

Use the appearance descendant-of-current-contact to load the current contact’s descendants when opening an app form or contact form from the “People” tab.

typenamelabelappearance
stringhousehold_membersHousehold’s membersselect-contact type-person descendant-of-current-contact

Loading additional contact data

Additional data about the contact can be loaded by adding fields to the same group as the contact selector. The field name must match the name of a field on the contact doc. The data will be loaded when the contact is selected and will overwrite any existing data in the field.

typenamelabelappearance
begin groupselected_personNO_LABEL
stringperson_idPerson IDselect-contact type-person
stringnameName of selected person
end groupselected_person

Loading contact data for use in other expressions

One powerful way to use the contact selector is to automatically load data about an existing contact for usage in various expressions within the form. This can be done with a combination of functionality we have already seen!

In the following example, we are loading the name of the current user from the associated contact doc:

typenamelabelappearancecalculate
begin groupinputsNO_LABEL
begin groupuserNO_LABEL
hiddencontact_idUser’s Contact ID
end groupuser
end groupinputs
begin groupintroNO_LABELfield-list
begin groupcurrent_userNO_LABEL
string_idUser’s Contact IDhidden select-contact type-person${contact_id}
stringnameUser’s namehidden
end groupcurrent_user
calculateuser_nameSupervisor name../current_user/name
notewelcomeWelcome ${user_name}!
end groupintro

Conditionally selecting/loading contact data for the current contact

As noted above, when opening an app form with a contact in context (e.g. when opening the form from the “People” tab), the contact’s data will be available in the inputs/contact group. However, this data is not available when opening the form from the “Reports” tab since there is no contact in context.

A common pattern for enabling consistent form behavior in this case is to use a contact selector in the inputs/contact group and make the inputs group only relevant when the default source value is not overridden (the source field is populated with specific values when the form is opened from the “People” tab or from a task). With this pattern, the contact selector will only be visible when the form is opened from the “Reports” tab and the user can select the contact they want to report on. This will ensure that the inputs/contact data is always available regardless of how the form is opened.

Then, this contact data can be used to link the report created from the form to the person or place in context (or the person selected when opening the form). Getting the values for _id or patient_id and setting them to patient_id or patient_uuid on the final report will link that report to the contact. Then the report will be displayed on the contact’s summary page.

typenamelabelappearancecalculaterelevantdefault
begin groupinputsNO_LABELfield-list./source = ‘user’
hiddensourceSourceuser
begin groupcontactNO_LABEL
string_idPatient IDselect-contact type-person
stringpatient_idMedic IDhidden
end groupcontact
end groupinputs
calculatepatient_uuidPatient UUID../contact/_id
calculatepatient_idPatient ID../contact/patient_id

CHT Applications > Reference > forms/

Forms: All the App forms, Contact forms, and Collect forms

CHT Applications > Reference > contact-summary.templated.js

Contact Pages: Customizing the fields, cards, and actions on profile pages

CHT Applications > Quick Guides > Tasks > Passing Data from Tasks to Forms

Demonstrates how to pass data into an application form via tasks