Survey123 for ArcGIS 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 currently only available in one or the other, and some are available in both.
Question types
| Question type | Description | Available in Survey123 Connect | Available in Survey123 web designer | Visible in Survey123 field app | Visible in Survey123 web app |
|---|---|---|---|---|---|
integer | Whole number input. | Yes | Yes | Yes | Yes |
decimal | Decimal input. | Yes | Yes | Yes | Yes |
text | Free text response. | Yes | Yes | Yes | Yes |
| Multiple choice question; only one answer can be selected. Replace [list_name] to reference the correct answer list. | Yes | Yes | Yes | Yes | |
Multiple choice question; multiple answers can be selected. Replace [list_name] to reference the correct answer list. | Yes | Yes | Yes | Yes | |
Displays text on the screen. Can also handle hidden calculations. | Yes | Yes | Yes | Yes | |
Collects a given GPS coordinate. Defaults to current location. | Yes | Yes | Yes | Yes | |
Date input. | Yes | Yes | Yes | Yes | |
Time input. | Yes | Yes | Yes | Yes | |
Date and time input. | Yes | No | Yes | Yes | |
Accepts either an image from the device's files or a directly taken photo. | Yes | Yes | Yes | Yes | |
begin group | Begins a group of questions. | Yes | No | Yes | Yes |
end group | Ends a group of questions. | Yes | No | Yes | Yes |
Begins a set of repeating questions. | Yes | No | Yes | Yes | |
end repeat | Ends a set of repeating questions. | Yes | No | Yes | Yes |
Performs a calculation on values in the form. The calculate field contains the outcome of the calculation. | Yes | No | Yes | Yes | |
When signed in with an organizational account, this question is automatically populated with the account user name. | Yes | No | Yes | Yes | |
When signed in with an organizational account, this question is automatically populated with the account email address. | Yes | No | Yes | Yes | |
hidden | Creates a field in your feature service 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 | No | Yes | Yes |
barcode | Scans a bar code or QR code. | Yes | No | Yes | No |
start | Start date and time of the survey. | Yes | No | Yes | Yes |
end | End date and time of the survey. | Yes | No | Yes | Yes |
deviceid | UUID representing the specific device they survey was taken on. | Yes | No | Yes | No |
Accepts a recorded audio sample. | Yes | No | 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 version provided in Survey123 Connect automatically populates with the email address of the organizational account the user is signed in to. The version provided in the Survey123 web designer is instead a text field that only accepts formatting matching an email address.
- Geopoint questions have location averaging in the Survey123 field app, which is not available in the web app.
- 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.
XLSForm columns
The following table contains all columns supported by Survey123. These columns are available in the Advanced template.
| 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 resulting database. |
label | The question label displayed in your survey. |
hint | Additional information that can help to answer the survey question. |
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. |
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. |
appearance | Select the appearance of this field in your 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. |
readonly | Select yes to set the values in this field to read-only. These values cannot be edited in the survey. |
relevant | This gives you the ability to skip questions or make additional questions appear based on the response to a previous question. A question is made relevant by meeting the conditions in the relevant field (for example, ${name} = 'value'). |
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}). |
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. |
label::language1 | Provide translations for your survey questions here. Include any further translations by creating a new column (for example, label::Español (es)). The list of languages will appear in a drop-down menu in the survey. |
hint::language1 | Provide translations for your survey question hints here. Include any further translations by creating a new column (for example, hint::Español (es)). The list of languages will appear in a drop-down menu in the survey. |
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. |
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:fieldType | Define the target field type in the feature service. 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 service as integers, select esriFieldTypeInteger). |
bind::esri:fieldLength | Define the target field length in the feature service. This can be used to overwrite the default field length. |
bind::esri:fieldAlias | Provide values for the field alias in your feature service. This can be used to overwrite the default field alias values, which are derived from the question label. |
body::esri:inputMask | Provide an expression to use an input mask to provide a set format for data entry using characters and symbols. |
bind::esri:parameters | Provide expressions that will be used to define behavior of a question (for example, the behavior of repeats when editing your survey). |
bind::saveIncomplete | Set to true if the app is to automatically save the response after the question. |
bind::type | A field type that overwrites the default field type for the question. |
bind::esri:warning | Apply an expression that displays warnings if conditions are not met. |
bind::esri:warning_message | The message displays if the bind::esri:warning conditions are not met. |
Appearance values
The following values can be entered into the appearance column for specific types of questions to alter how they appear or behave. For more information on each, see Appearance.
| Appearance value | Applicable question type | Description |
|---|---|---|
signature | image | Presents a UI for signature capture. The signature is added to the feature as an attachment. |
draw | image | Allows the user to open a canvas window on which to sketch. |
annotate | image | Allows the user to open a canvas window on which to sketch that also supports annotation on images. |
minimal | select_one, select_multiple, barcode, repeats | Presents multiple responses (select_one, select_multiple), multiple questions (repeats), and a text box (barcode) in a hidden or minimized style. |
multiline | text | Makes the text box multiple lines long. |
likert | select_one | Makes the answer choices appear as a Likert scale. |
month-year | date | Selects only a month and year for the date. |
year | date | Selects only a year for the date. |
week-number | date | Selects a week number. |
distress | integer | Displays the question as a colored sliding scale. |
calculator | integer, decimal | Displays a custom calculator widget for this question. |
numbers | integer, decimal | Displays a custom numerical keyboard for this question. |
spinner | integer, decimal | Adds buttons to increase and decrease value. |
horizontal | select_one, select_multiple | Displays answer choices horizontally and in columns. |
horizontal-compact | select_one, select_multiple | Displays answer choices horizontally. |
autocomplete | select_one | Answer choices appear in a pull-down menu with text input to narrow options. |
compact | groups, repeats | Presents questions in a collapsed state at startup, which can be expanded by the user. |
minimal compact | repeats | Presents questions inside a repeat as both collapsed (compact) and hidden (minimal). |
field-list | groups, repeats | Displays the group of questions on a separate page when the survey style is set to pages. |
symbol | geopoint | Set a custom marker to replace the default on map view. |
hide-input | geopoint | Collapses the coordinate entry section when the survey is opened in the web form. It has no effect in the field app. |
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 Relevant expressions.
| Operator | Description | Example |
|---|---|---|
. | The current answer | .=1 |
| | Computes two node-sets | //book | //cd |
+ | Addition | 6 + 4 |
- | Subtraction | 6 - 4 |
* | Multiplication | 6 * 4 |
div | Division | 8 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) | 5 mod 2 |
The following nonmathematical functions can also be used:
| Function | Description | Example |
|---|---|---|
selected(question, value) | Checks if answer is selected. Used for select_one and select_multiple questions. | selected(${question_one}, 'a') |
count-selected(question) | Returns the number of selected answers. Used for select_multiple questions. | count-selected(${question_one}) |
string-length(question) | 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 value if the expression is not evaluated. | not(selected(., 'yes')) |
if(condition, a, b) | If 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. Used in date questions. | today() |
now() | Returns a time stamp for this instant. Used in time and dateTime 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 or value) | Returns true if the value provided is not null. It's recommended to use boolean-from-string() instead. | boolean(${question_one}) |
number(question or value) | Converts to number. Conversion varies depending on data type. | number(${question_one}) |
int(question or value) | Converts to integer. Conversion varies depending on data type. | int(${question_one}) |
string(question or value) | Converts to string. Conversion varies depending on data type. | string({$question_one}) |
date() | Converts a number or string to a date object, without preserving time. | date('2017-05-28T04:39:02+10:00') |
date-time() | Converts a number or string to a date object. | date-time('2017-05-28T04:39:02+10:00') |
Converts a date object into a decimal date-time number. | decimal-date-time(${date_question}) | |
decimal-time() | Converts a time object into a number representing a fractional day in the device's timezone. | decimal-time(${time_question}) |
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}) |
Returns the declared device or user property. | property('username') | |
pulldata() | Returns information saved in an external CSV, or in the properties of an answer. | 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; for example, '2' will return the second selected choice. | selected-at(${question_one}, 2) |
jr:choice-name(choice, 'question') | Used for select_one and select_multiple questions. Returns the label associated with the name of the choice in the given question. Be aware the question must be defined inside quotes. | jr:choice-name(maybe, '${question_one}') |
join(separator, question) | Concatenates all answers to a given question in a repeat, separated by the given separator. | join(',', ${question_in_repeat}) |
Mathematical functions
The following mathematical functions can be used in the calculation column of your survey:
| Function | Description | Example |
|---|---|---|
pi() | Returns pi. | pi() |
acos(value) | Returns the arccosine of the value. | acos(${question_one}) |
asin(value) | Returns the arcsine of the value. | asin(${question_one}) |
atan(value) | Returns the arctangent of the value. | atan(${question_one}) |
cos(value) | Returns the cosine of the value. | cos(${question_one}) |
sin(value) | Returns the sine of the value. | sin(${question_one}) |
tan(value) | Returns the tangent of the value as degrees of an angle. | 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 arctangent 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 field to alter the appearance of the text displayed as described in the following table:
| Format type | HTML | Result |
|---|---|---|
Font color | <font color="red"></font> | Text is in red. |
Hyperlink | <a href="http://www.esri.com"></a> | Text is link to website. |
Bold | <b></b> | Text is bold. |
Italics | <i></i> | Text is in italics. |
H1 | <H1></H1> | First heading format. |
H2 | <H2></H2> | Second heading format. |
Paragraph | <p> | Line break. |
Center | <center></center> | Text is centered. |
Blockquote | <blockquote></blockquote> | Text is indented blockquote. |
Underlined | <u></u> | Text is underlined. |
Typewrite | <tt></tt> | Text is in typewrite font. |
Strikethrough | <s></s> | Text is in strikethrough font. |
Unordered list | <ul><li></li></ul> | Text appears as points in an unordered list. |
Telephone number | <a href="tel:555-555-5555">555-555-5555</a> | Text is link to telephone number. |
Email address | <a mailto="someone@somewhere.com">someone@somewhere.com</a> | Text is link to email address. |
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.
| Subexpression | Match |
|---|---|
^ | 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 value | Result |
|---|---|
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 character | Name |
|---|---|
Space | |
, | Comma |
; | Semicolon |
- | Hyphen |
/ | Forward slash |
$ | Dollar sign |
. | Dot |
( | Opening parenthesis |
) | Closing parenthesis |