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.
The following table contains all columns supported by Survey123. These columns are included on the survey worksheet in the Advanced template and are listed in this table in the order that they appear in the worksheet.
| Column | Description |
|---|---|
| type | Select a question type from the provided list. Enter a valid list name if using a select_one or select_multiple question. |
| name | The field name in the feature layer. |
| label | The question label displayed in your survey. |
| hint | Information that can help to answer the survey question. |
| guidance_hint | Additional information, only displayed after pressing an icon. |
| appearance | Select the appearance of this field in your survey. |
| required | Select yes to require a value in this field before completing the survey. |
| required_message | When a required field has no response, the message in this column will appear to prompt for an answer. |
| readonly | Select yes to set the values in this field to read-only. These values cannot be edited in the survey. |
| default | Set the default value for this field. This will prepopulate the survey with the default value. This can be used to save time by either supplying a commonly used answer or showing the type of answer choice that is expected. |
| calculation | Perform calculations using the values of preceding questions (for example, ${number} * 100). Reference the calculate field to display the result (for example, The answer is ${calc}). |
| constraint | Limit the range of numbers that can be entered (for example, .>0 and .<100). It can be used with all question types. |
| constraint_message | When constraint conditions are not met, this message will appear to prompt a valid answer. |
| relevant | This allows you to skip questions or make additional questions appear based on the response to a previous question. A question is made visible by meeting the conditions in the relevant column (for example, ${name} = 'value'). A question hidden by this column submits only null values. |
| choice_filter | When using cascading selects, this field holds the expression to match the additional attribute columns on the choices tab (for example, attribute = ${value}). |
| repeat_count | This value specifies the number of records available in a repeat. Once the repeat count has been specified, records cannot be added to or deleted from the repeat. |
| media::audio | Copy an audio file to the media subfolder for your project and type the name of your audio file (for example, audio.mp3) to present audio with your question. |
| media::image | Copy an image file to the media subfolder for your project and type the name of your image file (for example, image.jpg) to display an image with your question. |
| bind::type | A field type that overwrites the default field type for the question. |
| bind::esri:fieldType | Define the target field type in the feature layer. This can be used to overwrite the default field type (for example, calculate and select_one fields are strings by default. To save the values in the feature layer as integers, select esriFieldTypeInteger). |
| bind::esri:fieldLength | Define the target field length in the feature layer. You can use this to overwrite the default field length. |
| bind::esri:fieldAlias | Provide values for the field alias in the feature layer. You can use this to overwrite the default field alias values, which are derived from the question label. |
| body::esri:style | Provide expressions to define the style and behavior of a question (for example, the background color for groups and repeats). |
| bind::esri:parameters | Provide parameters for a question that are specific to Survey123 (for example, parameters to control the behavior of repeats when editing your survey). |
| bind::esri:workflow | Provides parameters to enable a survey to be available to a rangefinder measurement mode. |
| parameters | Provide standard XLSForm parameters for a question (for example, the start, end, and step parameters for a range question). |
| body::accept | Set file types accepted for the file question. Accepts file extensions, with multiple file extensions separated by commas (for example, .jpg, .png). |
| body::esri:visible | This allows you to skip questions or make additional questions appear based on the response to a previous question. A question is made visible by meeting the conditions in the body::esri:visible column (for example, ${name} = 'value'). A question hidden by this column still contains and submits values. |
| body::esri:inputMask | Provide an expression to use an input mask to provide a set format for data entry using characters and symbols. |
| label::language (xx) | Provide translations for your question labels. The language must be specified by its name and code (for example, label::Español (es)). Add a new column for each language. The list of languages will appear in a drop-down menu in the survey. |
| hint::language (xx) | Provide translations for your question hints. The language must be specified by its name and code (for example, hint::Español (es)). Add a new column for each language. The list of languages will appear in a drop-down menu in the survey. |
| guidance_hint::language (xx) | Provide translations for your guidance hints. You must specify the language by its name and code (for example, guidance_hint::Español (es)). Add a new column for each language. The list of languages will appear in a drop-down menu in the survey. |
| required_message::language (xx) | Provide translations for the message that appears if a required question is not answered. The language must be specified by its name and code (for example, required_message::Español (es)). Add a new column for each language. The list of languages will appear in a drop-down menu in the survey. |
| body::accuracyThreshold | Provide a numeric value for the threshold (in meters) above which position values will not be accepted. Applies to geopoint and the vertices of geoshape and geotrace questions. |
| bind::esri:warning | Apply an expression that displays warnings if conditions are not met. |
| bind::esri:warning_message | The message that displays if the bind::esri:warning conditions are not met. |
| bind::saveIncomplete | Set to true if the app is to automatically save the response after the question. |
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_name1 | 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 |
| username2 | 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 |
| email2 | 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 |
| file1 | Upload a file to the device. | Attachment |
1—File and rank question types are currently only supported in the Survey123 field app.
2—A more flexible option is to use the pulldata("@property") function to retrieve values. See Device, user, and survey properties.
In Survey123 Connect, try the Question Types sample to see a form that includes all question types supported by Survey123. Refer to the Question types reference for how these question types are represented in the Survey123 web designer.
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:
Note:
Hints are not supported for begin repeat and begin group questions.
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 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:
Placeholder text is not supported in the Survey123 web app.
Update template
Note:
This section describes functionality that is only available in Survey123 Connect. This functionality is not available in Survey123 Studio.
The Advanced Template includes all XLSForm features supported in the Survey123 field app and is available on 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 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.
Special characters
Question names and choice names should not contain special characters, such as spaces, commas, hyphens, parentheses, brackets, or characters such as $, %, and #. It is important that choice names for select_multiple questions do not contain spaces or commas.