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 you can use 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.
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.
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. You can omit optional columns and leave any number of rows 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 will appear in the form. Each row usually represents one question; however, there are more 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 field in the feature layer in which responses to the question will be stored. No spaces or special characters are allowed in this column. Names must be unique for all questions in each layer.
- 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, you can use translation columns. Labels and hints also support limited HTML code and variables that will be replaced in your survey with the response from another question. For more information, see Notes.
For an overview of the columns in the survey worksheet, see Survey worksheet columns.
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 or 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 are presented as the set of answers for a question.
- The name column specifies the value that is persisted in ArcGIS. Values in the name column do not accept special characters. It is not recommended to include duplicate choice names in a choice list. For more information on duplicate choice names, see Multiple choice questions.
- The label column shows the answer choice exactly as you want it to appear on the form. Alternatively, you can use label translation columns.
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 is 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 you can use 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. For example, to collect the name and location of a store, write the following:
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 survey author can change the field type for many of these question types. For more information about field types, see Esri custom columns.
| Question type | Answer input | Default 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 in which the user can only select one answer. Replace list_name with the name of your choice list. You can change the field type; 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 in which the user can select multiple answers. Replace list_name with the name of your choice list. You cannot change the field type, 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. You cannot change the field type, 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. You cannot change the field type. | esriFieldTypeGeometry |
| geotrace | Collect a line on a map. You cannot change the field type. | esriFieldTypeGeometry |
| geoshape | Collect a polygon on a map. You cannot change the field type. | 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 username. 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 |
¹A more flexible option is to use the pulldata("@property") function to retrieve values. See Device and user properties.
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:
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.
By default, when a survey is published the choices in select_one questions are added to the survey's feature layer as coded value domains. You can disable the creation of domains during the publishing process. For more information, see Publish options.
When you modify the choices for select_one questions and republish the survey, Survey123 Connect displays a summary of the changes and allows you to decide whether these changes should be applied to the domains in the feature layer. For more information, see Update a survey.
Caution:
The following are limitations when using a choice list with duplicate choice names:
- Duplicate choice names are not supported for select_multiple questions.
- Duplicate choice names are not supported for multilingual surveys.
- The jr:choice-name() function returns the label of the first duplicate choice in the list.
- When opened from the Inbox, Drafts, Outbox, Sent, or Overview folders, select_one questions revert to the first duplicate choice in the list.
You can also add multiple choice questions that allow multiple answers to be selected, such as the following:
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 remains empty until the choice order is modified by the user. If a default value has been set, the default order is 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 may include the option to choose other when the desired choice is not listed. The respondent can then be asked to specify the other option. You can do this in XLSForm using either the manual method or the built-in method. The built-in method is quicker and easier to configure than the manual method but has several limitations.
Manual method
The manual method is recommended because it allows you to specify the name and label of the other choice and the name and label of the text question that collects the other response. You can provide translations for these names and labels. You can also apply constraints and appearances to the text question and make it required.
First, add an other choice to the choice list for the question on the choices worksheet. Specify a name and label for this choice as you would for any other choice in the list. In the following example, the color choice list has a choice named other.
On the survey worksheet, add a text question to collect the other response. Add a relevant expression so that the text question is relevant only when the other choice is selected. In the following example, the other_color question is relevant when the answer to the select_one question is other.
For multilingual surveys, the questions and choices can be translated. In the following example, French and Greek translations are provided on the survey worksheet for both the select_one question and the text question.
Translations are also provided on the choices worksheet, including for the other choice.
Built-in method
With this method Survey123 Connect automatically creates the other choice and the question to collect the other response. To use this method, type or_other after the choice list name in the type column in the survey worksheet. An Other choice is displayed in the list of choices for the question. When the Other choice is selected, a Specify other question is shown allowing users to provide their own answer. To store this answer, Survey123 Connect automatically creates an additional field in the feature layer using the name of your multiple choice question followed by _other, for example, favorite_toppings_other. See the following:
Caution:
The label for the Specify other question will not display in languages other than English.
If creating a survey from an existing feature layer, the field for the Specify other question will not be automatically created, and the survey will not be published. You must create the field for the Specify other question manually in the feature layer, with the name of your multiple choice question followed by _other, for example, favorite_toppings_other.
External choice lists
You can store choice lists for select_one and select_multiple questions 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. There are two ways to include a .csv file: manually place the file in the survey's media folder or link to a .csv file hosted in ArcGIS.
To include a question with an external choice list, enter the question type, select_one_from_file or select_multiple_from_file, and the name of the .csv file, for example, select_one_from_file CoverType.csv. File names are case-sensitive and do not allow spaces.
External choice lists are not to be confused with external selects, in which choices must be listed in an additional worksheet.
Link a .csv file
To link a .csv file to a survey, do the following:
- Ensure the .csv file is hosted in ArcGIS Online or ArcGIS Enterprise and has the same sharing permissions as the survey.
- Ensure the survey is published to ArcGIS before attempting to link content.
- In Survey123 Connect, browse to the Linked Content tab of the survey and click the Link content button. Choose CSV and browse to and select the .csv file to link.
To use the .csv file in Survey123 Connect, on the Linked Content tab, you can choose to download the file with the download button 
. This places a copy of the .csv file in the survey's media folder. Linked files are automatically downloaded with the survey in the Survey123 field app.
If you manually place the .csv file in the survey's media folder, and at a later time upload a .csv file of the same name to ArcGIS and link it to the survey, the .csv file in the survey is updated from the linked content (if newer).
Note:
If the .csv file lacks a column header, or has a trailing comma at the end of the file's rows, the file fails to import into the survey.
For best results, encode the .csv file using UTF-8 character encoding. If you're using Microsoft Excel to create your .csv file, save it as CSV UTF-8.
Metadata
XLSForm has the following data type options for metadata collection:
| Metadata type | Description |
|---|---|
| start | Start date and time of the survey. |
| end | End date and time of the survey. |
| username | Record the username of the current user signed in to ArcGIS Online or ArcGIS Enterprise. This data type takes no input. |
| | 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:
The metadata entries described above are automatically captured by ArcGIS Survey123. They are not 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 automatically time enables 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:
You can also add guidance hints to a question using the guidance_hint column. Guidance hints further instruct the user in how to answer a question but are hidden until the user clicks the guidance hint button that appears to the side of the hint. Guidance hints can only be used if there is already a hint for the question.
Placeholder text
You can also provide placeholder text for questions that accept a typed input (such as text, integer, and decimal questions, and select_one questions with autocomplete appearance) by setting the placeholderText parameter in the body::esri:style column. With placeholderText=@[hint] or placeholderText=@[guidance_hint], the hint or guidance hint is hidden and the hint text is instead placed inside the question's input area. Placeholder text appears in the input area when the question is empty.
Note:
Hints are not supported for begin repeat and begin group questions.
Placeholder text is not supported in the Survey123 web app.
Update template
The Advanced Template includes all XLSForm features supported in Survey123 and is available in the New Survey dialog box in Survey123 Connect. This template is updated regularly to add new functionality and enhance the survey authoring experience. While you can continue to use previous versions of the template without issue, you may want to update your existing surveys to the latest XLSForm template to take advantage of the latest changes.
The Update XLSForm template tool updates the existing XLSForm for a survey to the latest version of the advanced template. It does this by copying the contents of the survey, choices, and settings worksheets to their respective rows and columns in the new template. Any columns that you have added are also copied to the new template, as well as the external_choices worksheet if you are using external selects.
To run the tool, you must configure a Python environment in Survey123 Connect. For more information, see Configure Python.
In Survey123 Connect, open the survey you want to update. Click Tools and then click Update XLSForm template. A dialog box displays messages as the tool is running. When the process is complete, the .xlsx file in the survey folder is updated to the latest template and the form preview in Survey123 Connect is reloaded. If an error is encountered while the tool is running, the existing XLSForm is preserved.
Note:
The survey's XLSForm must be an .xlsx file. The Update XLSForm template tool cannot be run on .xls files.
It is recommended that you verify that the columns, data validation, cell formatting, and font styles from the original XLSForm are present in the updated XLSForm. The tool creates a backup of the existing XLSForm and a log file in C:\Users\<username>\ArcGIS\My Survey Designs\<surveyName>\debug\template_updater. To reinstate a survey from a backup, copy the .xlsx file from the template_updater folder to the survey's root folder. Delete the existing XLSForm and rename the backup to match the original.
Note:
The fill color for the cell in the first column of each row is applied to the whole row in the updated template.
For multilingual surveys, the default language columns, such as label::language (xx) and hint::language (xx), will be excluded from the updated template.