XLSForm essentials

XLSForm is an open standard that simplifies the authoring of forms. Authoring is done in a human-readable format using a spreadsheet. For information about XLSForm, visit https://xlsform.org/. Survey123 supports most (but not all) of the features in the XLSForm standard.

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

To help you author your forms, ArcGIS Survey123 includes the Survey123 Connect desktop tool, which works side by side with your XLSForm authoring tool to create XLS files. Survey123 Connect allows you to preview your XLSForm files as you author or edit them, publish your forms to ArcGIS Online and ArcGIS Enterprise, and create feature layers based on your form specification for data collection. ArcGIS Survey123 Connect 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 ArcGIS Survey123 Connect and Microsoft Excel to author your forms.

Each Excel workbook usually has two worksheets: survey and choices. A third worksheet, 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 additional 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. 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 either label or hint.

  • 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 layer 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 and hint columns contain the text for your questions. This is the text you'll see in the form. A question requires at least one label or hint; providing a label is recommended to avoid warning messages. Spaces and special characters are allowed in these columns. Alternatively, translation columns can be used. Labels and hints also support variables that will be replaced in your survey with the response from another question, and limited HTML code. For more information, see 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 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 allows you to group 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. 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.

When authoring forms in Excel, 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, and a unique version identifier for your survey, among others. For more information, see Settings.

Supplementary worksheets

The Survey123 templates include worksheets that contain the properties, operators, and functions that can be used in your form. These worksheets are also used to populate the drop-down lists and other data validation rules in the survey and settings worksheets. To ensure data validation works as expected it is recommended that you do not modify the contents of the supplementary worksheets.

Question types

XLSForm supports a number of question types. The following table lists the questions you can enter in the type column of your XLSForm, what input is accepted for the question, and the field type that is created in the associated ArcGIS feature layer for that question when the form is published. The field type can be changed by the survey author for many of these question types. Question types whose field type cannot be changed are identified in the table below. For more information about field types, see Esri custom columns.

Question typeAnswer inputDefault field type

integer

Whole number input.

esriFieldTypeInteger

decimal

Decimal input.

esriFieldTypeDouble

range

Input for a given range of numbers.

esriFieldTypeInteger

text

Free text response.

esriFieldTypeString

select_one list_name

Multiple choice question; only one answer can be selected. Replace list_name with the name of your choice list. Field type can be changed; however, the choice name is always treated as a string in the field app when used in expressions.

esriFieldTypeString

select_multiple list_name

Multiple choice question; multiple answers can be selected. Replace list_name with the name of your choice list. Field type cannot be changed and the choice name is always treated as a string in the field app when used in expressions.

esriFieldTypeString

rank list_name

Ranking question; rank a list of choices in order. Replace list_name with the name of your choice list. Field type cannot be changed and the choice name is always treated as a string in the field app when used in expressions.

esriFieldTypeString

note

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

esriFieldTypeString

geopoint

Collect single GPS coordinates. Field type cannot be changed.

esriFieldTypeGeometry

geotrace

Collect a line on a map. Field type cannot be changed.

esriFieldTypeGeometry

geoshape

Collect a polygon on a map. Field type cannot be changed.

esriFieldTypeGeometry

date

Date input.

esriFieldTypeDate

time

Time input.

esriFieldTypeString

dateTime

Accept a date and a time input.

esriFieldTypeDate

image

Take a photo.

Attachment

begin group

Begin a group of questions.

Not applicable

end group

End a group of questions.

Not applicable

begin repeat

Begin a set of repeating questions.

Not applicable

end repeat

End a set of repeating questions.

Not applicable

calculate

Perform a calculation on values in the form. This question type is hidden and does not appear on the form.

esriFieldTypeString

username

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 does not appear on the form.

esriFieldTypeString

email

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 does not appear on the form.

esriFieldTypeString

hidden

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

esriFieldTypeString

barcode

Scan a bar code.

esriFieldTypeString

start

Start date and time of the survey.

esriFieldTypeDate

end

End date and time of the survey.

esriFieldTypeDate

deviceid

Unique ID generated by Survey123 representing the specific device on which the survey was taken. This is distinct from a mobile device's International Mobile Equipment Identity (IMEI), as Survey123 runs on devices that may not have an IMEI.

esriFieldTypeString

audio

Record an audio sample.

Attachment

file

Upload a file to the device.

Attachment

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 ArcGIS Survey123. You can also refer to the quick reference to see how these question types are represented in the Survey123 web designer and web app.

Multiple choice questions

XLSForm supports select_one (select only one answer), select_multiple (select multiple answers), and rank (order a list of choices) 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 yes_no in the survey worksheet must match 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 to geodatabase domains for your ArcGIS feature layer.

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

By default, these choices appear in the order provided in the choices worksheet. You can instead randomize the order in which these choices appear by entering randomize=true in the parameters column.

Caution:

All values collected in a select_multiple or rank 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 and rank questions only send the name of a choice to the feature layer, rather than the name and label submitted by select_one questions.

The value for a rank question will remain empty until the choice order is modified by the user. If a default value has been set, the default order will be applied unless the choice order is modified by the user.

An individual answer for a select_multiple question can be returned using the selected-at function. The following returns 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 the option to choose other when an answer choice is not listed. Then the respondent is usually asked to specify the other option. This is possible in XLSForm by including or_other after the answer choice list name in the survey worksheet. The choices worksheet remains the same. See the following:

Select multiple or other question in a form

External choice lists

Choice lists for select_one and select_multiple questions can be stored in an external CSV file. This is ideal for very large choice lists, as well as choice lists that are managed outside of Survey123. The CSV file must contain name and label columns and be stored in the survey's media folder. To include a question with an external choice list, enter the question type, select_one_from_file or select_multiple_from_file, followed by the name of the CSV file, for example, select_one_from_file CoverType.csv. CSV file names are case sensitive and do not allow spaces.

External choice lists are not to be confused with external selects, where choices must be listed in an additional worksheet.

Metadata

XLSForm has the following data type options for metadata collection:

Metadata typeDescription

start

Start date and time of the survey.

end

End date and time of the survey.

username

Record the user name of the current user signed in to ArcGIS Online or ArcGIS Enterprise. This data type takes no input.

email

Record the email address of the current user signed in to ArcGIS Online or ArcGIS Enterprise. This data type takes no input.

deviceid

Unique ID generated by Survey123 representing the specific device on which the survey was taken. This is distinct from a mobile device's IMEI, as Survey123 runs on devices that may not have an IMEI.

Note:

These XLSForm metadata elements are not supported: 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 ArcGIS Survey123. 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 type, ArcGIS Survey123 will automatically time enable the feature layer for your survey. In this manner, you can filter the content of your survey based on the date the data was submitted. Adding the start and end entries is also useful if you want to know exactly how much time elapsed between the time the form was opened and when it was flagged as done.

Hints

Sometimes you want to add a 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. You can add hints to questions in XLSForm. Add a hint column and add your hint message. See the following for an example:

Hints on questions in a form
Note:

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