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 typeDescriptionSupported in Survey123 field appSupported 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 Scale, 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 username.

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

Survey worksheet columns

The following table contains all columns supported by Survey123. These columns are available on the survey worksheet in the Advanced template.

ColumnDescription

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 enter the name of your audio file here (for example, audio.mp3) to present audio with your question.

media::image

Copy an image file to the media subfolder for your project and enter 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).

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 geopoint results will not be accepted. This only applies to geopoint 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.

Appearances

You can enter the following values into the appearance column for specific types of questions to alter how they appear or behave. For more information on each, see Appearance.

AppearanceApplicable question typeDescriptionSupported in Survey123 field appSupported in Survey123 web app

minimal

select_one, select_multiple, barcode, begin repeat

Presents multiple responses (select_one, select_multiple), multiple questions (repeats), and a text box (barcode) in a hidden or minimized style.

Yes

Yes

minimal compact

begin repeat

Presents questions inside a repeat as both collapsed (compact) and hidden (minimal).

Yes

Yes

compact

select_one, select_multiple, begin group, begin repeat

For select_one and select_multiple questions, presents choices horizontally in a space-efficient manner. For groups and repeats, presents questions in a collapsed state at startup, which can be expanded by the user.

Yes

Yes

compact-n

select_one, select_multiple

Presents choices horizontally in a space-efficient manner, with a maximum amount of columns specified by n. For example, compact-3 limits the question to a maximum of three columns.

Yes

Yes

horizontal

select_one, select_multiple

Displays answer choices horizontally and in columns.

Yes

Yes

horizontal-compact

select_one, select_multiple

Same as compact appearance.

Yes

Yes

image-map

select_one, select_multiple

Displays an attached SVG image with selectable regions.

Yes

No

autocomplete

select_one

Answer choices appear in a pull-down menu with text input to narrow options.

Yes

Yes

likert

select_one

Makes the answer choices appear as a Likert scale.

Yes

Yes

multiline

text, image, file

Presents a text question as a multiline text box. It allows multiple attachments for an image or file question.

Yes

Yes

predictivetext

text

Enables predictive text for mobile devices.

Yes

No

nopredictivetext

text

Disables predictive text for mobile devices.

Yes

No

year

date

Selects only a year for the date.

Yes

Yes

month-year

date

Selects only a month and year for the date.

Yes

Yes

week-number

date

Selects a week number.

Yes

No

distress

integer

Displays the question as a colored sliding scale.

Yes

No

spinner

integer, decimal

Adds buttons to increase and decrease value.

Yes

No

numbers

integer, decimal

Displays a custom numerical keyboard for this question.

Yes

No

calculator

integer, decimal

Displays a custom calculator widget for this question.

Yes

No

thousands-sep

decimal

Displays answers with thousands separators. It applies to prepopulated answers only.

Yes

No

no-ticks

range

Displays the range slider without positions, minimum values, or maximum values.

Yes

No

draw

image

Allows the user to open a canvas window on which to sketch.

Yes

Yes

annotate

image

Allows the user to open a canvas window on which to sketch that also supports annotation on images.

Yes

Yes

signature

image

Presents a UI for signature capture. The signature is added to the feature as an attachment.

Yes

Yes

new-rear

image

Limits the question to only taking a photo, using the rear-facing camera as the default.

Yes

No

new-front

image

Limits the question to only taking a photo, using the front-facing camera as the default.

Yes

No

hidden

All

Hides the question from view while still accepting defaults and calculations.

Yes

Yes

field-list

begin group, begin repeat

Displays the group of questions on a separate page when the survey style is set to pages.

Yes

Yes

table-list

begin group

Presents a set of select_one questions inside a group with a common choice list in a table format.

Yes

Yes

geocode

text

Search for and submit a geocoded address.

Yes

Yes

hide-input

geopoint

Collapses the coordinate entry section when the survey is opened in the web app.

No

Yes

press-to-locate

geopoint, geotrace, geoshape

For geopoint questions, only accepts a location after the user interacts with the question. For geotrace and geoshape, it centers the user's location without capturing a point when first interacting with the question.

Only for geopoint

Yes

spike

image

Requires a Spike device and Spike app. It uses Spike integration to measure distance and location in a photo.

Yes

No

spike-full-measure

image

Requires a Spike device and Spike app. It uses Spike integration to measure distance, location, area, and lengths in a photo.

Yes

No

spike-point-to-point

image

Requires a Spike device and Spike app. It uses Spike integration to measure distance between two photographed points.

Yes

No

Parameters

Some question types in XLSForm have additional parameters that allow you to control the style or behavior of questions in a survey. In some cases, these parameters complement the appearances that a question type supports. For an overview of the parameters supported by each question type, see XLSForm parameters.

Data validation

Entering yes as a value in the required column causes the survey question to require that the question contain a value before the form can be completed.

Default values

Entering today() into the default column of a date question sets the default value to today's date.

Responses to a select_multiple question type work differently than others, with each checked answer entered in the order it was selected, separated by commas. To define several values as defaults in a select_multiple question, separate them with commas, for example, item1,item2,item3.

Formula operators

The operators listed in the following table can be used in the constraint, calculation, and relevant columns, although many may not be usable in all of them.

For more information about calculations and constraints, see Formulas, and for more about the use of the relevant column, see Form expressions.

OperatorDescriptionExample

.

The current answer

.=1

+

Addition

${question_one} + 4

-

Subtraction

${question_one} - 4

*

Multiplication

${question_one} * 4

div

Division

${question_one} div 4

=

Equal

${price}=9.80

!=

Not equal

${price}!=9.80

<

Less than

${price}<9.80

<=

Less than or equal to

${price}<=9.80

>

Greater than

${price}>9.80

>=

Greater than or equal to

${price}>=9.80

or

Or

${price}=9.80 or ${price}=9.70

and

And

${price}>9.00 and ${price}<9.90

mod

Modulus (division remainder)

${question_one} mod ${question_two}

The following nonmathematical functions can also be used:

FunctionDescriptionExample

selected(question, value)

Checks whether answer is selected. Used for select_one and select_multiple questions.

selected(${question_one}, 'a')

count-selected(question)

Returns the number of selected answers for select_one and select_multiple questions. Also returns the number of attached files for image, audio, and file questions using the multiline appearance.

count-selected(${question_one})

string-length(question, expression, or value)

Returns the length of a nonempty string.

string-length(${question_one})

substr(question, start, end)

Returns the substring beginning at the specified start and extends to the character at index end -1, where start and end begin at 0.

substr(${question_one}, 1, 2)

not(expression)

Returns a false value if the expression would return true, and a true value if the expression would return false.

not(selected(., 'yes'))

if(condition, a, b)

If the condition evaluates to true, returns a; otherwise, returns b.

if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')

true()

True

true()

false()

False

false()

uuid()

Returns a random UUID string.

uuid()

random()

Returns a random value between 0 (inclusive) and 1 (exclusive).

random()

today()

Returns today's date, internally stored as local midday. Used in date questions.

today()

now()

Returns a time stamp for this instant. Used in time and dateTime questions. Behaves the same as today() in date questions.

now()

once()

If a question already has a value, returns the existing value. Useful when using random() or uuid() in a repeated question to ensure the value doesn't change when you browse through the repeat records in the form.

once(uuid())

boolean(question, expression, or value)

Returns true if the value provided is not null.

It's recommended that you use boolean-from-string() instead.

Caution:

This function will always return true in the Survey123 web app. For alternatives, see Empty values.

boolean(${question_one})

number(question, expression, or value)

Converts to number. Conversion varies depending on data type.

Note:

If this function is empty, it will return NaN and the question will remain empty.

number(${question_one})

int(question, expression, or value)

Converts to integer. Conversion varies depending on data type.

Note:

If this function is empty, it will return NaN and the question will remain empty.

int(${question_one})

string(question, expression, or value)

Converts to string. Conversion varies depending on data type.

string(${question_one})

date(question, expression, or value)

Converts a number or string to a date object, without preserving time.

date('2017-05-28T04:39:02+10:00')

date-time(question, expression, or string)

Converts a number or string to a date object.

date-time('2017-05-28T04:39:02+10:00')

decimal-date-time(question, expression, or string)

Converts a date object into a decimal date-time number.

decimal-date-time(${date_question})

decimal-time(question, expression, or string)

Converts a time object into a number representing a fractional day in the device's time zone.

decimal-time(${time_question})

format-date()

Fits an existing date or time value to a defined format.

format-date(${previous_time}, '%H:%M')

coalesce(value1, value2)

Returns the first nonempty value. Supports only two values.

coalesce(${question_one}, ${question_two})

concat(value1, value2, …)

Returns the concatenation of the string values.

concat(${question_one}, ' and ', ${question_two})

max(value1, value2, ...)

Returns the maximum value in a given range, or to a single question across repeats.

max(${question_one}, ${question_two})

min(value1, value2, ...)

Returns the minimum value in a given range, or to a single question across repeats.

min(${question_one}, ${question_two})

sum(repeat)

Returns the sum of all responses to a given question across repeats.

sum(${question})

count(repeat)

Returns the amount of responses to a given question across repeats.

count(${question})

pulldata()

Returns information saved in an external CSV file, or in the properties of an answer. For more information, see Work with external content.

pulldata('info', 'email', 'name', ${previous_question})

version()

Returns the version of the survey defined in the settings worksheet.

version()

boolean-from-string()

Returns true if the string provided is 'true' or '1'. Otherwise, returns false.

boolean-from-string(${question_one})

contains(string, substring)

Returns true if the given string contains the substring.

contains(${question_one}, 'red')

starts-with(string, substring)

Returns true if the given string starts with the substring.

starts-with(${question_one}, 'The')

ends-with(string, substring)

Returns true if the given string ends with the substring.

ends-with(${question_one}, 'hand.')

selected-at(question, number)

Used for select_multiple questions. Returns the name of the choice selected for the given number, counted starting from zero; for example, '2' will return the third selected choice.

selected-at(${question_one}, 2)

jr:choice-name(choice_name, 'question')

Used for select_one questions. Returns the label associated with the name of the choice in the given question. Be aware that the question must be defined inside quotes.

jr:choice-name(${select_one}, '${select_one}')

Used for select_multiple questions. Returns the label associated with the name of the choice in the given question. The selected-at() function must be used to extract the label for individual answers. Be aware that the question must be defined inside quotes.

jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')

join(separator, question)

Concatenates all answers to a given question in a repeat, separated by the given separator.

join(',', ${question_in_repeat})

regex()

Applies a regular expression to the question's input. For more information, see Regular expressions.

regex(., '^\d{5}$')

position(..)

Returns the index of the current record in a repeat. For more information, see Repeats.

position(..)

indexed-repeat(question, repeat, index number)

Returns the value from a specific question in a repeat record. For more information, see Repeats.

indexed-repeat(${room_no}, ${floor}, 3)

Mathematical functions

The following mathematical functions can be used in the calculation column of your survey:

FunctionDescriptionExample

pi()

Returns pi.

pi()

acos(value)

Returns the arc cosine of the value.

acos(${question_one})

asin(value)

Returns the arc sine of the value.

asin(${question_one})

atan(value)

Returns the arc tangent of the value.

atan(${question_one})

cos(value)

Returns the cosine of the value as an angle in radians.

cos(${question_one})

sin(value)

Returns the sine of the value as an angle in radians.

sin(${question_one})

tan(value)

Returns the tangent of the value as an angle in radians.

tan(${question_one})

exp(value)

Returns the natural exponent of the value.

exp(${question_one})

exp10(value)

Returns 10 to the power of the value.

exp10(${question_one})

log(value)

Returns the natural logarithm of the value.

log(${question_one})

log10(value)

Returns the base-ten logarithm of the value.

log10(${question_one})

sqrt(value)

Returns the square root of the value.

sqrt(${question_one})

atan2(value1, value2)

Returns the arc tangent of the quotient of the values.

atan2(${question_one}, ${question_two})

round(value, power)

Returns the rounded value.

round(${question_one}, 5)

pow(value, power)

Returns the value to the power specified.

pow(${question_one}, 3)

HTML formatting

HTML can be used in the label or hint field, or the labels of choice lists, to alter the appearance of the text displayed, as described in the following table:

TagAttribute

a

href, style

img

src, width, height, border, alt, style

video¹

autoplay, controls, height, loop, muted, poster, preload, width

audio¹

autoplay, controls, loop, muted, preload

source¹

media, src, type

span

style

table

width, height, cellpadding, cellspacing, border, style

div

style, align

font

size, color, style

figure

style

figcaption

style

dd, dl, dt

style

h1, h2, h3, h4, h5, h6

style

tr

height, valign, align, style

td, th

height, width, valign, align, colspan, rowspan, nowrap, style

p

style

b, strong, i, em, u, ul, ol, li, tbody, br, hr

abbr

title

sub

style

sup

style

¹Only supported in the Survey123 web app.

Tip:

By default, a hyperlink created with HTML formatting that is opened in the Survey123 web app will open the destination in the same tab as the survey. To open this link in a new tab instead, add target="_blank" to the a href tag, for example:

<a href="https://www.esri.com" target="_blank">Link to Esri website</a>

Regular expressions

Regular expressions are sequences of characters that define a search pattern. They can be used in one question to determine its value based on other questions or to constrain data entry. A regular expression can be built from the subexpressions listed in the following table. For more information, see Formulas.

SubexpressionMatch

^

Matches beginning of line.

$

Matches end of line.

.

Matches any single character except newline.

[...]

Matches any single character in brackets.

[^...]

Matches any single character not in brackets.

\A

Beginning of entire string.

\z

End of entire string.

\Z

End of entire string except allowable final line terminator.

re*

Matches 0 or more occurrences of preceding expression.

re+

Matches 1 or more occurrences of preceding expression.

re?

Matches 0 or 1 occurrences of preceding expression.

re{ n}

Matches exact number of occurrences of previous expression defined in place of n.

re{ n,}

Matches n or more occurrences of preceding expression.

re{ n, m}

Matches at least the number of occurrences defined by n and, at most, defined by m in preceding expression.

a| b

Matches either a or b.

(re)

Groups regular expressions and remembers matched text.

(?: re)

Groups regular expressions without remembering matched text.

\w

Matches word characters.

\W

Matches nonword characters.

\s

Matches a whitespace character: tab, line feed, form feed, carriage return, or space.

\S

Matches nonwhitespace.

\d

Matches digits. Equivalent to [0 through 9].

\D

Matches nondigits.

\G

Matches point where last match finished.

\n

Back reference to capture group number n.

\b

Matches word boundaries when outside brackets. Matches backspace (0x08) when inside brackets.

\B

Matches nonword boundaries.

\n, \t, etc.

Matches new lines, carriage returns, tabs, and so on.

\Q

Escape (quote) all characters up to \E.

\E

Ends quoting started with \Q.

For example, the regular expression regex(.,'^[A-Za-z]*$') requires the user to enter only letters, no numbers or special characters, into a string question.

Esri field types

The bind::esri:fieldType column can be used to overwrite the default field type with one of the following values. For more information, see Esri custom columns.

Field valueResult

esriFieldTypeDate

Date

esriFieldTypeDouble

Double-precision floating point numbers

esriFieldTypeInteger

Whole numbers

esriFieldTypeString

A series of alphanumeric symbols

esriFieldTypePointZ

Enables altitude capturing in geopoints

esriFieldTypeGUID

Globally Unique Identifier

null

Null field, does not store values

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