Skip To Content

XLSForm essentials

There are many options for authoring XLSForm-compliant spreadsheets. Microsoft Excel is most commonly used, but there are other options available, such as Kingsoft Spreadsheets, Google Sheets, or OpenOffice Calc. There are also online XForms builders that export XLSForm spreadsheets that can be used with Survey123 for ArcGIS.

To help you author your forms, Survey123 for ArcGIS includes a desktop tool named Survey123 Connect, which works side by side with your XLSForm authoring tool for creating XLS files. Survey123 Connect lets you preview your XLSForm files as you author or edit them and also publishes your forms to ArcGIS Online and ArcGIS Enterprise and creates feature services based on your form specification for data collection. Survey123 Connect for ArcGIS is available for Windows, OSX, and Ubuntu.

Once your forms have been published to ArcGIS, you can use the Survey123 website to share your forms with members of your ArcGIS organizations. You can also analyze maps and tables for any data collected through the Survey123 field app, as well as export your survey results. If you're not familiar with the workflow between Survey123 Connect and the website, refer to these video tutorials.

For the purpose of this topic, assume that you're using Survey123 Connect for ArcGIS and Microsoft Excel to author your forms.

Each Excel workbook usually has two worksheets: survey and choices. A third worksheet named settings is also described below. The 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. Every entry must have values for each of the mandatory columns, but the optional columns can be left blank. The columns you add to your Excel workbook, whether mandatory or optional, can appear in any order. Optional columns can be omitted entirely. Any number of rows can 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.

Survey worksheet

This worksheet gives your form its overall structure. 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 survey worksheet has three mandatory columns: type, name, and label.

  • The type column specifies the type of XLSForm question you're adding. There is a well-defined list of possible question types for this column.
  • The name column determines the name of the ArcGIS feature service column in which the response to the question will be stored. No spaces or special characters are allowed in this column. No two rows can have the same content.
  • The label column contains the text for your questions. This is the text you'll see in the form. Spaces and special characters are allowed in this column. Alternatively, label translation columns can be used. Labels also support limited HTML code; for more information, refer to Notes.

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).

The choices worksheet has three mandatory columns: list name, name, and label.

  • The list name column lets you group together a set of related answer choices. Choices with the same list name will be presented as the set of answers for a question.
  • The name column specifies the value that will be persisted in ArcGIS when that choice is chosen. Values in the name column do not accept spaces.
  • The label column shows the answer choice exactly as you want it to appear on the form. Alternatively, label translation columns can be used.

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.

Settings worksheet

The settings worksheet is optional and allows you to further customize your form. Available customization includes a title that will be displayed while the form is being edited, an instance name to uniquely identify each completed form, a unique version identifier for your survey, and other functions. For more information, see Settings.

Types worksheet

This worksheet is included in the Survey123 templates to act as a glossary. It can be used as a reference for looking up the definition of different properties and operators that can be used within your form. This worksheet is also used to populate the drop-down lists for supported properties in the templates.

Question types

XLSForm supports a number of question types. The following table lists some of the options you can enter in the type column in the survey worksheet in your XLSForm:

Question typeAnswer input

integer

Whole number input.

decimal

Decimal input.

text

Free text response.

select_one [options]

Multiple choice question; only one answer can be selected.

select_multiple [options]

Multiple choice question; multiple answers can be selected.

note

Display a note on the screen; takes no input.

geopoint

Collect single GPS coordinates.

date

Date input.

time

Time input.

dateTime

Accepts a date and a time input.

image

Take a picture.

begin group

Begin a group of questions.

end group

End a group of questions.

begin repeat

Begin a set of repeating questions.

end repeat

End a set of repeating questions.

calculate

Performs a calculation on values in the form.

username

When signed in to ArcGIS Online or ArcGIS Enterprise, this field is automatically populated with the account user name.

email

When signed in to ArcGIS Online or ArcGIS Enterprise, this field is automatically populated with the account email address.

hidden

A field not displayed on the form. Use bind::esri:fieldType and bind::esri:fieldLength columns to specify data schema.

barcode

Scan a bar code.

start

Start date and time of the survey.

end

End date and time of the survey.

audio

Record an audio sample.

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

survey

type

name

label

text

store_name

What is the name of this store?

geopoint

store_gps

Collect the GPS coordinates of this store.

The Question Types sample form includes all question types supported by Survey123 for ArcGIS.

Multiple choice questions

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. The following is an example of a select_one question:

survey

type

name

label

select_one yes_no

likes_pizza

Do you like pizza?

choices

list name

name

label

yes_no

yes

Yes

yes_no

no

No

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.

When publishing your surveys to ArcGIS with Survey123 Connect, the choices in select_one questions are converted into geodatabase domains for your ArcGIS feature service.

You can also add multiple choice questions that allow multiple answers to be selected, such as the following:

survey

type

name

label

select_multiple pizza_toppings

favorite_toppings

What is your favorite pizza topping?

choices

list name

name

label

pizza_toppings

cheese

Cheese

pizza_toppings

pepperoni

Pepperoni

pizza_toppings

sausage

Sausage

By default, all values collected in a select_multiple question are saved as a comma-separated list.

Specify other

For multiple choice questions, surveys often include an option of marking other when an answer choice is not listed. Then the respondent is 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 the following:

survey

type

name

label

select_multiple pizza_toppings or_other

favorite_toppings

What are your favorite pizza toppings?

choices

list name

name

label

pizza_toppings

cheese

Cheese

pizza_toppings

pepperoni

Pepperoni

pizza_toppings

sausage

Sausage

Metadata

XLSForm has the following data type options available for metadata collection:

Metadata typeDescription

start

Start date and time of the survey.

end

End date and time of the survey.

username

Records the user name of the current user logged in to ArcGIS Online or ArcGIS Enterprise. Takes no input.

email

Records the email address of the current user logged in to ArcGIS Online or ArcGIS Enterprise. Takes no input.

Note:

The following XLSForm metadata elements are not planned to be supported: deviceid, subscriberid, simserial, and phonenumber.

To collect all of this metadata, add the following to the beginning of your survey:

survey

type

name

label

start

start

end

end

username

username

username

email

email

email

The metadata entries described above are automatically captured by Survey123 for ArcGIS. They will not be represented as questions in the form, but you'll see the values once the survey is submitted.

When you add the start or end types, Survey123 for ArcGIS will automatically time-enable the feature service for your survey. In this manner, you'll be able to filter the contents of your survey based on the date when the data was submitted. Adding the start and end entries is also useful if you want to find out exactly how much time elapsed between the moment the form was opened and when it was flagged as done.

Hints

Sometimes you want to add a small hint to a question on your form, instructing the user how to answer the question, but you don’t want the hint to be part of the question itself. It’s easy to add hints to questions in XLSForm. Simply add a hint column and add your hint message. See the following for an example:

survey

type

name

label

hint

text

store_name

What is the name of this store?

Look on the signboard if the store has a signboard.

geopoint

store_gps

Collect the GPS coordinates of this store.