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.

Question types

Survey123 Connect question typeSurvey123 web designer question typeDescriptionFunctional in Survey123 field appFunctional in Survey123 web app

integer

Number

Whole number input.

Yes

Yes

decimal

Decimal input.

Yes

Yes

range

N/A

Input for a given range of numbers.

Yes

No

text

Singleline text, Multiline text, Email, Website, Address

Free text response. A regular expression is applied to Email and Website. The geocode appearance is applied to Address.

Yes

Yes

select_one list_name

Single choice, Single choice grid, Dropdown, Likert, Rating

Multiple choice question; only one answer can be selected. Replace list_name with the name of your choice list.

Yes

Yes

select_multiple list_name

Multiple choice

Multiple choice question; multiple answers can be selected. Replace list_name with the name of your choice list.

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

note

Note

Displays text on the screen. Can also handle hidden calculations.

Yes

Yes

geopoint

Map

Collects a given GPS coordinate. Defaults to current location.

Yes

Yes

geotrace

Collects a line on a map.

Yes

Yes

geoshape

Collects a polygon on a map.

Yes

Yes

date

Date

Date input.

Yes

Yes

time

Time

Time input.

Yes

Yes

dateTime

Date and Time

Date and time input.

Yes

Yes

image

Image, Signature

Accepts either an image from the device's files or a directly taken photo.

Yes

Yes

begin group

Group, Page

Begins a group of questions.

Yes

Yes

end group

Group, Page

Ends a group of questions.

Yes

Yes

begin repeat

N/A

Begins a set of repeating questions.

Yes

Yes

end repeat

N/A

Ends 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

username

N/A

When signed in with an organizational account, this question is automatically populated with the account user name.

Yes

Yes

email

N/A

When signed in with an organizational account, this question is automatically populated with the account email address.

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

barcode

N/A

Scans a bar code or QR code.

Yes

No

start

N/A

Start date and time of the survey.

Yes

Yes

end

N/A

End date and time of the survey.

Yes

Yes

deviceid

N/A

UUID representing the specific device on which the survey was taken.

Yes

No

audio

N/A

Records an audio clip in the field app. Accepts an audio file in the web app.

Yes

Yes

file

File upload

Accepts a file on the device.

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 recording in the Survey123 web app. Instead, they allow the user to browse to and attach an existing audio file from their device.
  • Several appearance types available in Survey123 Connect are instead available as separate question types in the Survey123 web designer. This includes Multiline Text, Dropdown, and Likert.
  • 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

These characters can't be used in the name of a question. Some of these may also prompt warnings when used in choice lists but can be generated and used successfully, with the exception of spaces in a choice list used by a select_multiple question, which will fail.

Special characterName

Space

,

Comma

:

Colon

;

Semicolon

-

Hyphen

/

Forward slash

$

Dollar sign

.

Dot

(

Opening parenthesis

)

Closing parenthesis

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.

Multiline text

Multiline text provides the user with a single, simple text box. It has no text limit, wrapping to a new line and potentially introducing a scroll bar if the text is long enough. This 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.

Single choice

Single choice provides a list of potential answers from which the user selects only 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 choice 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 choice grid

Single choice 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.

This question type behaves in the same way as a group of select_one questions with a table-list appearance in Survey123 Connect.

Multiple choice

Multiple choice 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.

Dropdown

Dropdown provides a list of potential answers from which the user selects only 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 into the field that limits the list to only answers that contain that text. This question type functions similarly to the single choice 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 choice 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.

Rating

Rating provides a list of potential answers from which the user selects only one; you can set one as the default on the Edit tab. This functions identically to the single choice 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 choice 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.

Likert

Likert provides a list of potential answers from which the user selects only one; you can set one as the default on the Edit tab. This functions identically to the single choice 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 choice 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 Likert 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.

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.

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 either a specified time, or the time of the survey was loaded.

This question type behaves in the same way as a time question in Survey123 Connect.

Date and time

Date and time provides both 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.

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. The maximum possible size of this image is 10 MB. 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 the 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 using the pulldata("@exif") function. 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.

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 the one question response, up to a maximum of 99.

This question type behaves in the same way as a file 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 declare it a required question.

This question type behaves in the same way as an image question with a signature appearance in Survey123 Connect.

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 defined by your organization, by default the ArcGIS World Geocoding Service. You can set this question to either 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 either 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 change once published, however, the drawing style can be changed at any time. The Map and extent settings allow you to select which online basemap and default map extent the user will see for this 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.

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.

Email

Email provides a limited text field that will automatically reject any 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.

Website

Website provides a limited text field that will automatically reject any 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.

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.

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.

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.