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 barcode. | 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. This question type is hidden and does not appear on the form. | 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.
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 taps 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.