ArcGIS Survey123 supports a large amount of the XLSForm specification. This reference guide provides a summary of the XLSForm features that you can use in Survey123. Surveys can be created in either Survey123 Connect or the Survey123 website; some features are only available in one or the other, and some are available in both.
Survey elements
Options on the Add tab in the Survey123 web designer allow you to control the visibility of the following elements:
- Survey header—The header appears at the top of the form and can be text or an image. For an image header, provide the URL for an image hosted online or upload an image file.
- Survey description—The description appears below the header and can contain formatted text, links, and images.
- Survey footer—The footer appears beneath the Submit button as a hyperlink. Provide text and a URL for the hyperlink.
Click an element in the form preview to customize it on the Edit tab.
Question types
| Survey123 Connect question type | Survey123 web designer question type | Description | Supported in Survey123 field app | Supported in Survey123 web app |
|---|---|---|---|---|
| Records an audio clip in the field app. Records an audio clip or accepts an uploaded audio file in the web app. | Yes | Yes | ||
| barcode | N/A | Scans a bar code or QR code. | Yes | No |
| begin group | Begins a group of questions. | Yes | Yes | |
| N/A | Begins a set of repeating questions. | Yes | Yes | |
| N/A | Performs a calculation on values in the form. The calculate field contains the outcome of the calculation. | Yes | Yes | |
| decimal | Decimal input. | Yes | Yes | |
| Date input. | Yes | Yes | ||
| Date and time input. | Yes | Yes | ||
| deviceid | N/A | UUID representing the specific device on which the survey was taken. | Yes | No |
| | N/A | When signed in with an organizational account, this question is automatically populated with the account email address. | Yes | Yes |
| end | N/A | End date and time of the survey. | Yes | Yes |
| end group | Ends a group of questions. | Yes | Yes | |
| end repeat | N/A | Ends a set of repeating questions. | Yes | Yes |
| file | Accepts a file on the device. | Yes | Yes | |
| Collects a given GPS coordinate. This defaults to current location. | Yes | Yes | ||
| Collects a polygon on a map. | Yes | Yes | ||
| Collects a line on a map. | Yes | Yes | ||
| hidden | N/A | Creates a field in your feature layer that is not displayed on the form. Use the bind::esri:fieldType and bind::esri:fieldLength columns to specify the data schema for this field. | Yes | Yes |
| integer | Whole number input. | Yes | Yes | |
| Accepts either an image from the device's files or a directly taken photo. | Yes | Yes | ||
| Displays text on the screen. Note can also handle hidden calculations. | Yes | Yes | ||
| range | N/A | Input for a given range of numbers. | Yes | Yes |
Ranking question; orders a list of choices. Replace list_name with the name of your choice list. | Yes | Yes | ||
| Dropdown, Likert scale, Rating, Single select, Single select grid | Multiple choice question; only one answer can be selected. Replace list_name with the name of your choice list. | Yes | Yes | |
N/A | Multiple choice question; only one answer can be selected. Replace file_name.csv with the name of the file located in the survey's media folder that contains the list of choices. | Yes | Yes | |
| Multiple choice question; multiple answers can be selected. Replace list_name with the name of your choice list. | Yes | Yes | ||
N/A | Multiple choice question; multiple answers can be selected. Replace file_name.csv with the name of the file located in the survey's media folder that contains the list of choices. | Yes | Yes | |
| start | N/A | Start date and time of the survey. | Yes | Yes |
| text | Free text response. A regular expression is applied to Email and Website. The geocode appearance is applied to Address. | Yes | Yes | |
| Time input. | Yes | Yes | ||
| username | N/A | When signed in with an organizational account, this question is automatically populated with the account username. | Yes | Yes |
Question differences between app and web
While the table above describes what question types are available across Survey123 Connect, the Survey123 field app, the Survey123 web designer, and the Survey123 web app, there are differences in their behavior and implementation across platforms.
- The web designer combines integer and decimal questions into a single question type named Number. A check box in the properties of the question allows the survey designer to define which input is required.
- The email question types provided in Survey123 Connect and the Survey123 web designer are implemented differently. The implementation in Survey123 Connect automatically populates with the email address of the organizational account the user is signed in to. The implementation in the Survey123 web designer is instead a text field that only accepts formatting matching an email address.
- Geopoint, geotrace, and geoshape questions have been combined into a single question type named Map. A check box in the properties of the question allows the survey designer to define which input is required. An additional question type named Address allows for submitting geocoded points.
- Audio questions don't allow upload in the Survey123 field app as they do in the web app. To allow upload of audio in the field app, use a File question.
- Several appearances available in Survey123 Connect are instead available as separate question types in the Survey123 web designer. This includes Multiline text, Dropdown, and Likert scale.
- For each question, the web designer provides an option to cache the answer. In the web app, after submitting a survey record, the answer to the question will be cached in the browser and preloaded into the next submission made for this survey on that device. Caching an answer can be set for all question types except Image, File upload, and Signature.
Data validation
Checking This is a required question on the Edit tab causes the survey question to require that the question contain a value before the form can be completed.
Most questions also have functionality to set a minimum and maximum length. This prevents the survey from being submitted unless the response to the question is within the defined limits. This function has the same role as either the constraint or bind::esri:fieldLength column in the Survey123 XLSForm specification.
Default values
Most question types allow you to define a default answer that is automatically used when the survey is loaded. This has the same purpose as the default column in XLSForm.
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 Multiple select questions do not contain spaces or commas.
Date, number, text, and time
The following question types allow users to type answers or select dates and times.
Date
Date provides a calendar to select a date. You can set a default answer for this question as either a specified date or the date of submission for the survey. In the Validation section, you can define a date range from which the user must select.
This question type behaves in the same way as a date question in Survey123 Connect.
Date and time
Date and time provides a calendar to select the date and a field to select a time. These fields behave in the same way as the date and time question types, respectively, and provide the same controls for default values and validation.
This question type behaves in the same way as a dateTime question in Survey123 Connect.
Email provides a limited text field that will automatically reject responses that are not in the format of an email address. The only additional options available for this question type are to specify it as a required question or to cache the answer for future responses.
This question type does not behave in the same way as an email question in Survey123 Connect. Instead, the question type acts as a text question with a regular expression applied.
Multiline text
Multiline text provides the user with a large text box that wraps text to a new line as it's typed. It also accepts carriage returns. This question type is ideal for long-form answers.
This question type behaves in the same way as a text question with a multiline appearance in Survey123 Connect.
Number
Number provides a question that allows the user to use numerical values only. By default, it also permits a single decimal point. In the Validation section, you can use a check box to state whether the value must be an integer. Checking this box will remove the ability to enter a decimal point.
In place of the minimum and maximum character count, number questions have minimum and maximum values that prevent the user from submitting their survey unless their answer is within the given range. This behaves in the same way as the constraint column in XLSForm.
This question type behaves in the same way as either an integer or a decimal question in Survey123 Connect, depending on whether you've defined the value as an integer.
Singleline text
Singleline text provides the user with a single text box. If the text exceeds the size of the text box, it remains the same size and scrolls horizontally without line breaks. This is ideal for short answers. You can also apply an input mask to force the input to adhere to a certain format.
This question type behaves in the same way as a text question in Survey123 Connect.
Time
Time provides a question to select a time in a format of hour:minute AM/PM. A drop-down menu allows the user to select times at 15-minute intervals; the selected times are presented in text fields, allowing users to input a more specific time. You can set a default answer for this question as a specified time or the time the survey was loaded.
This question type behaves in the same way as a time question in Survey123 Connect.
Website
Website provides a limited text field that will automatically reject responses that are not in the format of a website URL. The only additional options available for this question type are to specify it as a required question or to cache the answer for future responses.
This question type acts as a text question with a regular expression applied.
Choice
The following question types allow users to choose an answer from a list of choices. The way the choices are presented varies depending on the question type.
Dropdown
Dropdown provides a list of potential answers from which the user selects one; you can set one as the default on the Edit tab. An Allow "Other" check box allows the user to specify an additional choice not on the list. There is also an option to randomize the order in which the choices appear. The Autocomplete check box will allow the user to enter text in the field that limits the list to only answers that contain that text. This question type functions similarly to the single select question but presents its answers in a drop-down list. This is ideal for a longer list of choices, as the list isn't visible unless one is being chosen.
As with single select questions, dropdown questions have a Set rule button in the design section on the left. Click this button to open a window that allows you to set a visibility rule for any question that comes after it. This function has the same purpose as the relevant column in XLSForm.
This question type behaves in the same way as a select_one question with a minimal appearance in Survey123 Connect.
Likert scale
Likert scale provides a list of potential answers from which the user selects one; you can set one as the default on the Edit tab. This functions identically to the single select question but presents its answers as a Likert scale. By default, this question type presents a range from one to five, but this range can be changed on the Edit tab.
As with single select questions, Likert scale questions have a Set rule button in the design section on the left. Click this button to open a window that allows you to set a visibility rule for any question that comes after it. This function has the same purpose as the relevant column in XLSForm.
This question type behaves in the same way as a select_one question with the likert appearance in Survey123 Connect.
Multiple select
Multiple select provides a list of potential answers from which the user can select any number; you can set some as default on the Edit tab. There is also an Allow "Other" check box, which allows the user to specify an additional choice not on the list. There is also an option to randomize the order in which the choices appear. In the Appearance section, you can choose whether you want your answers to be laid out vertically or horizontally.
This question type behaves in the same way as a select_multiple question in Survey123 Connect.
Ranking
Ranking provides a list of choices for which the user specifies a preferred order. The user can select the choices in any order and then drag choices that have already been selected to reorder them. The user must rank all available choices before the survey response can be submitted. A Reset button is available to clear all rankings. When designing the survey, the designer can also choose whether to randomize the order in which the choices appear.
This question type behaves in the same way as a rank question in Survey123 Connect.
Rating
Rating provides a list of potential answers from which the user selects one; you can set one as the default on the Edit tab. This functions identically to the single select question but presents its answers as a number of icons. By default, this question type presents a range from one to five stars, but this maximum value and provided icon can be changed on the Edit tab.
As with single select questions, rating questions have a Set rule button in the design section on the left. Click this button to open a window that allows you to set a visibility rule for any question that follows it. This function has the same purpose as the relevant column in XLSForm.
This question type behaves in the same way as a select_one question in Survey123 Connect.
Single select
Single select provides a list of potential answers from which the user selects one; you can set one as the default on the Edit tab. There is also an Allow "Other" check box, which allows the user to specify an additional choice not on the list. There is also an option to randomize the order in which the choices appear. In the Appearance section, you can choose whether you want your answers to be laid out vertically or horizontally.
Single select questions have a Set rule button in the design section on the left. Click this button to open a window that allows you to set a visibility rule for any question that comes after it. This function has the same purpose as the relevant column in XLSForm.
This question type behaves in the same way as a select_one question in Survey123 Connect.
Single select grid
Single select grid provides a list of potential answers for a series of questions from which the user selects one; you can set one as the default on the Edit tab. This functions identically to a series of single-choice questions and has no Set rule button.
On mobile devices, if the width of the single select grid is greater than the screen width, the layout adjusts automatically so that the questions appear as a group of single-choice questions instead of as a grid. This ensures that all questions and choices fit on the screen.
This question type behaves in the same way as a group of select_one questions with a table-list appearance in Survey123 Connect.
Location
The following question types allow users to specify a location, either on a map or by typing an address.
Address
Address provides a text box for entering an address. Begin typing an address, and a series of autocomplete options will appear suggesting locations based on the locator service set for the question; if not set, the question will use your organization's chosen locator, which by default is the ArcGIS World Geocoding Service. You can set this question to submit the selected address selected as text or to submit both the selected address as text and its location as a point geometry. If a Map question is already present in the survey, you can only submit the address as text.
This question type behaves in the same way as a text question with a geocode appearance in Survey123 Connect.
Map
Map provides a map interface for the user to specify a point, line, or area. Select the type of geometry and drawing style to be used by the survey. The geometry type used will apply to the underlying feature layer for the survey, and cannot be changed once published; however, the drawing style can be changed at any time. The Map and extent settings allow you to select which online basemap, default map extent, and locator service the question will use. There is also an option to ensure that the user's location will only be captured when first interacting with the question.
Note:
If the Do not submit the answer option is checked for a map question, the geometry type will not be used for the underlying feature layer, and you can change it after publishing.
This question type is equivalent to a geopoint, geotrace, or geoshape question in Survey123 Connect. The following features are supported in the Survey123 field app but not in the web app:
- Offline basemaps.
- Location averaging for geopoint questions.
- Geopoint symbology.
- Location accuracy thresholds and location quality expressions.
- All pulldata("@geopoint") properties. The web app only supports the x, y, z, horizontalAccuracy, verticalAccuracy, speed, and direction properties.
- Calculations on geotrace and geoshape questions, including the sum() function.
- Style options provided for geotrace and geoshape questions.
Media and files
The following question types allow users to capture or upload media and files.
Audio
Audio provides buttons to record or upload an audio file. The Validation section allows the survey designer to define the maximum duration of the audio files recorded or to specify it as a required question.
This question type behaves in the same way as an audio question in Survey123 Connect.
File upload
File upload provides a button to choose a file from the device. The Validation section allows the survey designer to define the allowed file types, first by category (Document, Archive, or a custom selection) and then by either a checklist or a comma-separated list of file name extensions. You can allow the user to submit multiple files in one question response, up to a maximum of 99.
This question type behaves in the same way as a file question in Survey123 Connect.
Image
Image provides a button to choose an image file from the device or take a photo using the device's camera if one is available. You can prevent the user from submitting an image file from the device by selecting Camera only as the image source. You can also allow the user to submit multiple images in one question response, up to a maximum of 99.
Caution:
If an image question contains multiple images, EXIF data cannot be extracted from the images. If you need to extract EXIF data from multiple images submitted to the same question, consider using a repeat.
This question type behaves in the same way as an image question in Survey123 Connect.
Signature
Signature provides a free drawing field to provide a signature. This signature will be saved as an image and added to the survey response as an attachment. The only additional option available for this question type is to specify it as a required question.
This question type behaves in the same way as an image question with a signature appearance in Survey123 Connect.
Display and structure
The following question types allow users to control the layout of the survey form.
Group
A group that questions can be dragged into. This group is collapsible, with the Edit tab providing an option for the group to be collapsed by default.
This question type behaves in the same way as a begin and end group question pair in Survey123 Connect.
Note
Note provides a label to display an extended message. This can include HTML formatting, hyperlinks, or images. There are no additional options available. A field will not be created in the feature layer for a note question.
This question type behaves in the same way as a note question in Survey123 Connect.
Page
Creates a separate page for the survey that can contain separate questions, either created inside of it or dragged into it. The design pane provides the option to duplicate a page or merge with another.
This question type behaves in the same way as a begin and end group question pair using the pages style in Survey123 Connect.