Skip to content

Questionnaire Guide

Jump to bottom
amplifi edited this page Jun 29, 2017 · 1 revision

Required Fields

These fields must be included in your questionnaire. If they are not included the questionnaire will fail on submission.

The names listed here must match. using respondent_name instead of party_name will not be accepted.

You don't have to include all choices, but adding new choices is currently not supported.

Some comments that we need to consider when creating a form:

  • Right now we need to establish a default value for the select_one fields. Otherwise it'd not work (it will be fixed).
  • We cannot include blank rows in the Settings tab

party_type

survey:

type                    name          required
select_one respondent   party_type    yes

choices:

list_name       name    label
respondent	GR	Group
respondent	IN	Individual
respondent	CO	Corporation

party_name

survey:

type   name          required
text   party_name    yes

location_geometry

You can choose between geoshape, geotrace, and geopoint with the label location_geometry.

survey:

type      name               required
geotrace  location_geometry  yes
(geoshape)
(geopoint)

If you would like to add that choice to the survey, you would add a relevance option and use location_geoshape and location_geotrace. NOTE: This does not work for geopoint:

survey:

type                 name               required   relevant
select_one geo_type  geo_type           yes
geotrace             location_geotrace  yes        ${geo_type}='geotrace'
geoshape             location_geoshape  yes        ${geo_type}='geoshape'

choices:

list_name	name	        label								
geo_type	geoshape	Geoshape
geo_type	geotrace	Geotrace

location_type

survey:

type                    name           required
select_one land_type    location_type  yes

choices:

list_name       name    label
land_type	PA	Parcel
land_type	CB	Community Boundary
land_type	BU	Building
land_type	AP	Apartment
land_type	PX	Project Extent
land_type	RW	Right-of-way
land_type	NP	National Park Boundary
land_type	MI	Miscellaneous

tenure_type

survey:

type                    name          required
select_one tenure_type  tenure_type   yes

choices:

list_name       name    label
tenure_type	AL	All Types
tenure_type	CR	Carbon Rights
tenure_type	CO	Concessionary Rights
tenure_type	CU	Customary Rights
tenure_type	EA	Easement
tenure_type	ES	Equitable Servitude
tenure_type	FH	Freehold
tenure_type	GR	Grazing Rights
tenure_type	HR	Hunting/Fishing/Harvest Rights
tenure_type	IN	Indigenous Land Rights
tenure_type	JT	Joint Tenancy
tenure_type	LH	Leasehold
tenure_type	LL	Longterm leasehold
tenure_type	MR	Mineral Rights
tenure_type	OC	Occupancy (No Documented Rights)
tenure_type	TN	Tenancy (Documented Sub-lease)
tenure_type	TC	Tenancy in Common
tenure_type	UC	Undivided Co-ownership
tenure_type	WR	Water Rights

Non-required, but recommended fields

If you would like your photos to be automatically tied to the location or party you're collecting, label them as: party_photo location_photo

Update Resource Information (AVAILABLE NEXT RELEASE)

If you would like to attach resources to a party, location, or tenure relationship, begin the name of that field with one of the following:

party_resource_{}
location_resource_{}
tenure_resource_{}

and replace the {} with whatever label you would like. Ex: party_resource_photo

These fields should be place outside of attribute groups.

Custom Fields

Custom fields must go in attribute groups.

If you place additional questions outside of attribute groups, they will not be saved.

Attribute groups

There are only three possible beginnings for attribute groups:

party_attributes

location_attributes

tenure_relationship_attributes

If you want to have attributes based on a conditional value (ex. the type of party, location, or tenure relationship), you can do with the following steps:

  1. Add another identifier to the end of the label (i.d. {model}_attribute_{identifier}:

party_attributes_default, party_attributes_individual, party_attributes_group

  1. Create a conditional value for that row in the questionnaire:
type            name                            label                         relevant
begin group	party_attributes_default	Default Party Attributes
...
end group

begin group	party_attributes_individual	Individual Party Attributes   ${party_type}='IN'
...
end group

begin group	party_attributes_group  	Individual Party Attributes   ${party_type}='GR'
...
end group

Currently the only types of questions supported are:

  • boolean
  • text
  • date
  • dateTime
  • time
  • integer
  • decimal
  • email
  • url
  • select_one
  • select_multiple (very recently added, still not in platform site)
  • foreign_key (will be used in the future to connect models)

Groups nested inside attribute groups are not supported.

Repeat blocks nested inside attribute groups are not supported.

Putting media inside an attribute is not supported (which is why it is placed outside).

Media Fields

The only thing that goes outside an attribute group is any additional media you'd like to collect, which will be saved as resources. The following file types are supported:

  • pdf
  • doc
  • docx
  • xls
  • xlsx
  • jpg
  • png
  • gif
  • tiff

Audio:

  • 1d-interleaved-parityfec
  • interleaved-parityfec
  • 32kadpcm
  • 3gpp
  • 3gpp2
  • ac3
  • aac
  • aacp
  • amr
  • amr-wb
  • amr-wb+
  • aptx
  • asc
  • ATRAC-ADVANCED-LOSSESS
  • ATRAC-X
  • ATRAC3
  • basic
  • BV16
  • BV32
  • clearmode
  • CN
  • DAT12
  • dls
  • dsr-es201108
  • dsr-es202050
  • dsr-es202211
  • dsr-es202212
  • DV
  • DV14
  • eac3
  • encaprtp
  • EVRC
  • EVRC-QCP
  • EVRC0
  • EVRC1
  • EVRCB
  • EVRCB0
  • EVRCB1
  • EVRCNW
  • EVRCNW0
  • EVRCNW1
  • EVRCWB
  • EVRCWB0
  • EVRCWB1
  • EVS
  • example
  • fwdred
  • G711-0
  • G719
  • G7221
  • G722
  • G723
  • G726-16
  • G726-24
  • G726-32
  • G726-40
  • G728
  • G729
  • G7291
  • G729D
  • G729E
  • GSM
  • GSM-EFR
  • GSM-HR-08
  • iLBC
  • ip-mr_v2.5
  • L8
  • L16
  • L20
  • L24
  • LPC
  • mobile-xmf
  • MPA
  • MP4A-LATM
  • mpa-robust
  • m4a
  • midi
  • mpeg1
  • MPA2
  • mpa-robust3
  • mpeg3
  • mpeg
  • mp3
  • mp4
  • mpeg4-generic
  • ogg
  • opus
  • parityfec
  • PCMA
  • PCMA-WB
  • PCMU
  • PCMU-WB
  • QCELP
  • raptorfec
  • RED
  • rtp-enc-aescm128
  • rtploopback
  • rtp-midi
  • rtx
  • SMV
  • SMV0
  • SMV-QCP
  • sp-midi
  • speex
  • t140c
  • t38
  • telephone-event
  • tone
  • UEMCLIP
  • ulpfec
  • VDVI
  • VMR-WB
  • vorbis
  • vorbis-config
  • wav
  • wave
  • x-flac
  • x-mpeg-3
  • x-midi

Repeats

  1. (For now) You only have two options for repeat group: party_repeat and location_repeat. They must be named as such.
  2. If you are repeating something, everything associated with that needs to go inside the same repeat. So if you’re repeating parties, ALL party information goes inside the same repeat (required fields, resources, attribute groups, everything). Otherwise it won’t know what’s connected and chaos ensues.
  3. For each survey you must have either party or location outside of the repeat. This creates one object for all other objects to be tied to.

Flow chart for the objects created using the repeat structure.

You have four options when constructing xlsforms with repeats.

One Location. Repeat Parties and Tenure.

Party and Tenure questions are inside the repeat Standard Questionnaire Multiple Party

One Party. Repeat Locations and Tenure.

Location and Tenure questions are inside the repeat Standard Questionnaire Multiple Location

One Location and One Tenure*. Repeat Parties.

  • This form still creates multiple tenure relationship objects, but it assumes all information for each tenure relationship will be exactly the same for each party.

Party is inside the repeat, Tenure is outside Standard Questionnaire Multiple Party Minus Tenure

One Party and One Tenure*. Repeat Locations.

  • This form still creates multiple tenure relationship objects, but it assumes all information for each tenure relationship will be exactly the same for each location.

Location is inside the repeat, Tenure is outside Standard Questionnaire Multiple Location Minus Tenure

Multi-lingual questionnaires

Support for multi-lingual questionnaires diverges slightly from the XLSForms standard, mostly to ensure that languages are specified unambiguously.

Language codes

Languages within multi-lingual XLSForms will be identified using ISO 639 language codes. The code used will be the two-letter ISO 639-1 code where the language in question has one (e.g. en for English, fr for French, te for Telugu), and otherwise will be the three-letter ISO 639-2 code (e.g. fil for Filipino). (This is the main difference from the XLSForms standard, which doesn't specify how languages are identified.)

Rationale: Using ISO 639 codes identifies languages unambiguously. It also allows for language names to be rendered as autoglossonyms in the platform UI and in ODK, instead of using English names for languages.

Default language

A multi-lingual XLSForm must define a default language in the settings sheet, using the default_language setting. The language must be specified using its ISO 639 code. (So, for a form whose default language is English, you would have default_language = en.)

Rationale: Without a default_language setting, there is no way of identifying the language used for the default label columns in the survey and choices sheets. This isn't a problem in a single language form, but it makes accurate handling of multi-lingual forms impossible.

Migrations: existing forms with multi-lingual labels but without a default_language setting will need to be migrated somehow, either by re-uploading a corrected form, or by manually editing the database.

Multi-lingual labels

In the survey and choices sheet of a multi-lingual form, multi-lingual labels can be specified by giving label values in the default language in a label column, and labels in other languages in columns of the form label::<iso-639-code>, e.g. label::en, label::de, label::fil.

Rationale: This follows the XLSForms standard, except for using ISO 639 codes to identify languages. (The XLSForms standard does not explicitly specify how to identify languages.)

Restrictions

  1. If a form contains multi-lingual labels and does not contain a default_language setting, then the form is not parseable and will be rejected.
  2. If a form contains multi-lingual labels in the survey or choices sheet but not in both, then the form will be accepted, but entries from the non-translated sheet will appear in the UI and ODK only in the default language. Note: this may be VERY confusing for users, so it is strongly suggested that multi-lingual forms should contain label columns for all languages in use on both the survey and choices sheets.
  3. If a form contains multi-lingual labels in the survey or choices sheets and the set of languages used in the two sheets does not match, then the "missing" entries on each sheet will fall back on the default language. Note: this is a more general case of point #2, and it just as confusing for users.

Rationale: It would probably be better to have strict checking of language coverage, so that the survey and choices sheets are required to have the same set of multi-lingual label columns, but it appears that this might break some existing forms, so the more lax restrictions listed here are used instead.

Visit our User Documentation to learn more about using the Cadasta Platform.

If you'd like to contribute to the Cadasta Platform, start with our Contributing Guidelines.

Cadasta Wiki Home | Developer Setup Guide

Cadasta.org | About Cadasta | YouTube | Twitter | Facebook

Development

Design

Documentation Needs

  • Quick Start Guide
  • Glossary
  • Questionnaire Guide
Clone this wiki locally