Quick reference

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.
• CAPTCHA—A CAPTCHA is a test displayed at the end of the form that users must solve before submitting a response. Users solve the CAPTCHA by typing the characters shown in the image. You can modify the text that appears above the CAPTCHA by clicking on it in the form preview. CAPTCHAs can be enabled when using https://survey123.arcgis.com/ and is supported in the Survey123 web app. CAPTCHAs cannot be configured when the Survey123 website is installed on your infrastructure, and are not supported in the Survey123 field app.

Click an element in the form preview to customize it on the Edit tab.

Question types

The following table describes the question types that are available across Survey123 Connect, the Survey123 field app, the Survey123 web designer, and the Survey123 web app. In some questions, there are differences in behavior and implementation across platforms; for the differences, refer to the notes after the table.

Survey123 Connect question type	Survey123 web designer question type	Description	Supported in Survey123 field app	Supported in Survey123 web app
audio⁴	Audio⁴ ⁶	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 barcode or QR code.	Yes	No
begin group	Group, Page	Begins a group of questions.	Yes	Yes
begin repeat	N/A	Begins a set of repeating questions.	Yes	Yes
calculate	N/A	Performs a calculation on values in the form. The calculate field contains the outcome of the calculation.	Yes	Yes
decimal¹	Number¹ ⁶	Decimal input.	Yes	Yes
date	Date⁶	Date input.	Yes	Yes
dateTime	Date and time⁶	Date and time input.	Yes	Yes
deviceid	N/A	UUID representing the specific device on which the survey was taken.	Yes	No
email²	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	Group⁶, Page⁶	Ends a group of questions.	Yes	Yes
end repeat	N/A	Ends a set of repeating questions.	Yes	Yes
file	File upload	Accepts a file on the device.	Yes	Yes
geopoint³	Map³ ⁶	Collects a given GPS coordinate. This defaults to current location.	Yes	Yes
geoshape³		Collects a polygon on a map.	Yes	Yes
geotrace³		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¹	Number¹ ⁶	Whole number input.	Yes	Yes
image	Image, Signature	Accepts either an image from the device's files or a directly taken photo.	Yes	Yes
note	Note⁶	Displays text on the screen. Note can also handle hidden calculations.	Yes	Yes
range	Slider⁶	Input for a given range of numbers.	Yes	Yes
rank list_name	Ranking⁶	Ranking question; orders a list of choices. Replace list_name with the name of your choice list.	Yes	Yes
select_one list_name	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
select_one_from_file file_name.csv	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
select_multiple list_name	Multiple select⁶	Multiple choice question; multiple answers can be selected. Replace list_name with the name of your choice list.	Yes	Yes
select_multiple_from_file file_name.csv	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	Address⁶, Email⁶, Multiline text⁵ ⁶, Singleline text⁶, Website⁶	Free text response. A regular expression is applied to Email and Website. The geocode appearance is applied to Address.	Yes	Yes
time	Time⁶	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

¹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. These include 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 Audio, 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

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.

When choices lists are long, change often, or are reliant on other sources of data, you may choose to create the list from a layer instead of entering them manually on the Edit tab. Select Edit and choose From layer, to select a feature layer or table, the choice label field to display in the choice list, and filtering options for that layer. The choice list can be filtered by location, by value, or both. When filtering by location, choice list values can be returned based on either a drawn area on a map question (map question must be of type area), or a nominated distance from the geometry on a map or address question. When filtering by value, choice list values can be returned by matching a nominated value or the answer from another question in the survey.

Note:

Creating a list from a layer can only be done in dropdown questions, not other choice question types.

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 formatted text, hyperlinks, and 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

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.