What is an XLSForm?

XLSForm is a form standard created to help simplify the authoring of forms in Excel.
Authoring is done in a human readable format using a familiar tool that almost
everyone knows - Excel. XLSForms provide a practical standard for sharing and
collaborating on authoring forms. They are simple to get started with but allow for the
authoring of complex forms by someone familiar with the syntax described below.

The XLSForm is then converted to an ODK XForm, a popular open form standard,
that allows you to author a form with complex functionality like skip logic in a
consistent way across a number of web and mobile data collection platforms.

Basic format
Each Excel workbook usually has two worksheets: survey and choices. A third
optional worksheet called settings can add additional specifications to your form and
is described below.

The survey worksheet

This worksheet gives your form its overall structure and contains most of the content
of the form. It contains the full list of questions and information about how they should
appear in the form. Each row usually represents one question; however, there are
certain other features described below that you can add to the form to improve the
user experience.

The choices worksheet

This worksheet is used to specify the answer choices for multiple choice questions.
Each row represents an answer choice. Answer choices with the same list name are
considered part of a related set of choices and will appear together for a question.
This also allows a set of choices to be reused for multiple questions (for example,
yes/no questions).

Both of these worksheets have a set of mandatory columns that must be present for
the form to work. Additionally, each worksheet has a set of optional columns that
allow further control over the behavior of each entry in the form, but are not essential
to have. Every entry must have values for each of the mandatory columns, but the
optional columns may be left blank.

 The survey worksheet has 3 mandatory columns: type, name, and label.

o The type column specifies the type of entry you are adding.
o The name column specifies the unique variable name for that entry.
No two entries can have the same name. Names have to start with a letter or an
 underscore. Names can only contain letters, digits, hyphens, underscores, and
periods. Names are case-sensitive.
o The label column contains the actual text you see in the form.
Alternatively, label translation columns can be used.
type name label
today today  
select_one gende
Respondent's gender?
gender r
integer age Respondent's age?
surveychoicessettings
 The choices worksheet has 3 mandatory columns as well: list name, name,
and label.
o The list name column lets you group together a set of related answer
choices, i.e., answer choices that should appear together under a question.
o The name column specifies the unique variable name for that answer
choice.
o The label column shows the answer choice exactly as you want it to
appear on the form. Alternatively, label translation columns can be used.
list_nam
name label
e
transgende
gender Transgender
r
gender female Female
gender male Male
gender other Other
surveychoicessettings

The columns you add to your Excel workbook, whether they are mandatory or
optional, may appear in any order. Optional columns may be left out completely. Any
number of rows may be left blank. All .xls file formatting is ignored, so you can use
dividing lines, shading, and other font formatting to make the form more readable.

One thing to keep in mind when authoring forms in Excel is that the syntax you use
must be precise. For example, if you write Choices or choice instead of choices,
the form won't work.

Question types
XLSForm supports a number of question types. These are just some of the options
you can enter in the type column in the survey worksheet in your XLSForm:

Question type Answer input

integer Integer (i.e., whole number) input.
decimal Decimal input.
range Range input (including rating)
text Free text response.
 Question type Answer input
select_one [options] Multiple choice question; only one answer can be selected.
select_multiple [options] Multiple choice question; multiple answers can be selected.
select_one_from_file [file] Multiple choice from file; only one answer can be selected.
select_multiple_from_file
Multiple choice from file; multiple answers can be selected.
[file]
rank [options] Rank question; order a list.
Display a note on the screen, takes no input. Shorthand for
note
type=text with readonly=true.
geopoint Collect a single GPS coordinate.
geotrace Record a line of two or more GPS coordinates.
Record a polygon of multiple GPS coordinates; the last
geoshape
point is the same as the first point.
date Date input.
time Time input.
dateTime Accepts a date and a time input.
image Take a picture or upload an image file.
audio Take an audio recording or upload an audio file.
background-audio Audio is recorded in the background while filling the form.
video Take a video recording or upload a video file.
file Generic file input (txt, pdf, xls, xlsx, doc, docx, rtf, zip)
Scan a barcode, requires the barcode scanner app to be
barcode
installed.
calculate Perform a calculation; see the Calculation section below.
acknowledge Acknowledge prompt that sets value to "OK" if selected.
A field with no associated UI element which can be used to
hidden
store a constant
xml-external Adds a reference to an external XML data file

GPS
For example, to collect the name and GPS coordinates of a store, you would write
the following:

type name label

store_nam
text What is the name of this store?
e
geopoin
store_gps Collect the GPS coordinates of this store.
t
surveychoicessettings

To collect a line or shape of GPS coordinates, you can use one of the following:
 nam
type label hint
e
Please walk along the pipeline and record the coordinates
geotrace pipe Pipeline
of each corner point
geoshap Please walk along the border and record the coordinates
border Border
e of each corner point
surveychoicessettings  

See the question_types XLSForm for a look at each question type being used in a

form.

GPS with accuracyThreshold

When recording GPS coordinates in ODK Collect, ODK collect automatically collects
the gps when an accuracy level of 5 meters or less is reached. You can change this
default behaviour by specifying an accuracyThreshold; this could be less than 5m
or more than 5m. You will need to add a column with
heading body::accuracyThreshold on the survey sheet of your XLSForm. Then
specify your preferred accuracy threshold value for this column on your geopoint
question, as in the example shown below:

type name label body::accuracyThreshold

geopoin store_gp Collect the GPS coordinates of this
1.5
t s store.
surveychoicessettings  

See gps_accuracy_threshold form for an example that uses this attribute.

Multiple choice
XLSForm supports both select_one (select only one answer)
and select_multiple (select multiple answers) questions. Writing a multiple choice
question requires adding a choices worksheet to your Excel workbook. Here is an
example of a select_one question:

type name label

select_one
likes_pizza Do you like pizza?
yes_no
surveychoicessettings

list
name label
name
yes_no yes Yes
yes_no no No
surveychoicessettings
Note that the yes_no in the survey worksheet must match the yes_no in the list
name column in the choices worksheet. This ensures that the form displays the
correct list of answer choices for a particular question.

We can also add multiple choice questions that allow multiple answers to be
selected, like so:

type name label

select_multiple What are your favorite pizza
favorite_toppings
pizza_toppings toppings?
surveychoicessettings

list name name label

pizza_topping
cheese Cheese
s
pizza_topping
pepperoni Pepperoni
s
pizza_topping
sausage Sausage
s
surveychoicessettings

Choice names
The name column of the choices sheet defines the values that will be saved when
each choice is selected during data collection. Choice names
for select_multiple must not contain spaces because spaces are used as a
separator when an answer with multiple selected choices is saved. Choice names
for select_one questions may contain spaces. However, we recommend avoiding
them to make analysis easier. Additionally, this makes it possible to convert the
question to a select_multiple in a future form version.

In general, choice names should be unique within a single choice list. If two choices
from the same list have the same name, they will be impossible to tell apart in
analysis. If you have duplicate choice names, you will get an error and your form will
not be converted. However, it may sometimes be appropriate to have duplicate
choice names. An example would be if you use a cascading select and the choices
with the same name are differentiated by a preceding question. If you do need to use
duplicate choice names, you can suppress the error by using
the allow_choice_duplicates setting:

allow_choice_duplicates
yes
surveychoicessettings

Specify other
For multiple choice questions, surveys often include an option of marking other when
their answer choice is not listed. Then they are usually asked to specify the other
option. This is possible through XLSForm by including or_other after the answer
choice list name in the survey worksheet. The choices worksheet stays the same.
See below:

type name label

select_multiple pizza_toppings favorite_toppin What are your favorite pizza
or_other g toppings?
surveychoicessettings

list name name label

list name name label
pizza_topping
cheese Cheese
s
pizza_topping
pepperoni Pepperoni
s
pizza_topping
sausage Sausage
s
surveychoicessettings

Click on the link to look at the complete pizza_questionnaire.

Caveat
When you export data using this or_other option, in the favorite_topping column,
you will see a value other. A separate column will have the answer for the questions
in which the user selected other. This makes data analysis more cumbersome, so
we do not recommend the or_other construct for large scale data collection efforts.
See the Relevant section below for an alternative method more appropriate for large
scale projects.

Multiple choice from file

The options in a multiple choice question can also be taken from a separate file
instead of the choices sheet. This is particularly useful if the options are dynamic or if
the list of options is used in multiple surveys. Two types of files are supported: CSV
and XML files. See usage examples below:

type name label choice_filter

select_multiple_from_file In which countries did you
liv  
country.csv live?
select_one_from_file In which country do you live
cou  
countries.xml now?
select_one_from_file
cit What is the closest city? name=${cou}
countries.xml
select_one_from_file
hh Select household number  
households.csv
surveychoicessettings  
The files require a specific format. A CSV file requires a name and label column
which represent the value and label of the options. An XML file requires a structure
as shown below:

<root>

<item>

<name/>

<label/>

...

</item>

</root>

Both CSV and XML files may have additional columns and XML nodes as long as the
above-mentioned basic requirements are met.

Note that this question type is generally the preferred way of building select
questions from external data as it is the most versatile and works across applications.
However, if your external data file consists of many thousands of lines, please test
carefully whether the performance is satisfactory on the lowest spec device you
intend to use. If it is too slow, consider using External Selects or Dynamic selects
from preloaded data if your data collection application supports it.

Rank
The rank widget can be used to let respondents order a list of option