Skip To Content

XLSForm essentials

There are many options for authoring XLSForm-compliant spreadsheets. Microsoft Excel is most commonly used, but other options include 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, macOS, 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. 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 variables that will be replaced in your survey with the response from another question, and 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 special characters.
  • 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


Whole number input.


Decimal input.


Input for a given range of numbers.


Free text response.

select_one [options]

Multiple choice question; only one answer can be selected. Replace [options] with the name of your choice list.

select_multiple [options]

Multiple choice question; multiple answers can be selected. Replace [options] with the name of your choice list.


Display a note on the screen; takes no input. Can also display hidden calculations.


Collect single GPS coordinates.


Collect a line on a map.


Collect a polygon on a map.


Date input.


Time input.


Accepts a date and a time input.


Take a photo.

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.


Performs a calculation on values in the form. This question type is hidden and is not displayed on the form.


When signed in to ArcGIS Online or ArcGIS Enterprise, this field is automatically populated with the account user name. This question type is hidden and is not displayed on the form.


When signed in to ArcGIS Online or ArcGIS Enterprise, this field is automatically populated with the account email address. This question type is hidden and is not displayed on the form.


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


Scan a bar code.


Start date and time of the survey.


End date and time of the survey.


UUID representing the specific device on which the survey was taken.


Record an audio sample.

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

A text and geopoint question in a form

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:

Select one question in a form
Select one choices in a form

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:

Select multiple question in a form
Select multiple choices in a form

All values collected in a select_multiple question are saved as a comma-separated list, so avoid using commas in the name column of your choice list. Also note that select_multiple questions only send the name of a choice to the feature service, rather than the name and label submitted by select_one questions.

An individual answer for a select_multiple question can be returned using the selected-at function. The following will return the name value for the first answer given for a select_multiple question:

selected-at(${species}, 0)

To send the label for an answer, you can use the jr:choice-name function. To get the label value for the second answer given to the same select_multiple question, use the following:

jr:choice-name(selected-at(${species}, 1), '${species}')

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:

Select multiple or other question in a form


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

Metadata typeDescription


Start date and time of the survey.


End date and time of the survey.


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


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


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:

Metadata questions in a form

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.


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:

Hints on questions in a form

Hints are not supported for begin repeat and begin group questions.