Survey123 supports select_one (select only one answer), select_multiple (select multiple answers), and rank (order a list of choices) questions.
Note:
Rank questions are currently only supported in the Survey123 field app and web app.
Writing a multiple choice question requires adding a choices worksheet to your Excel workbook. The following is an example of a select_one question:
The list name in the survey worksheet, yes_no, must match the list name in the choices worksheet. This ensures that the form displays the correct list of answer choices for a particular question.
By default, when a survey is published, the choices in select_one questions are added to the survey's feature layer as coded value domains. You can disable the creation of domains during the publishing process. For more information, see Publish options.
Caution:
The following are limitations when using a choice list with duplicate choice names:
- Duplicate choice names are not supported for select_multiple questions.
- Duplicate choice names are not supported for multilingual surveys.
- The jr:choice-name() function returns the label of the first duplicate choice in the list.
- When opened from the Inbox, Drafts, Outbox, Sent, or Overview folders, select_one questions revert to the first duplicate choice in the list.
For additional considerations when modifying choice lists in existing surveys, see Update a survey.
You can also add multiple choice questions that allow multiple answers to be selected, such as the following:
By default, these choices appear in the order provided in the choices worksheet. You can instead randomize the order in which these choices appear by entering randomize=true in the parameters column.
Caution:
All values collected in a select_multiple or rank question are saved as a comma-separated list, so avoid using commas in the name column of your choice list. Also note that select_multiple and rank questions only send the name of a choice to the feature layer, rather than the name and label submitted by select_one questions.
The value for a rank question remains empty until the choice order is modified by the user. If a default value has been set, the default order is applied unless the choice order is modified by the user.
An individual answer for a select_multiple question can be returned using the selected-at function. The following returns the name value for the first answer given for a select_multiple question:
selected-at(${species}, 0)
To send the label for an answer, you can use the jr:choice-name function. To get the label value for the second answer given to the same select_multiple question, use the following:
jr:choice-name(selected-at(${species}, 1), '${species}')
Appearance
By setting the appearance column to minimal, a select question is presented in a drop-down menu.
By setting appearance to horizontal, the choices for a select question are presented horizontally in columns of equal width.
The compact appearance is similar to the horizontal appearance but uses a different method for determining column widths that may result in the choices taking up less space.
Note:
In Survey123 Connect, you can specify a maximum number of columns for the compact appearance by providing a number separated by a hyphen. For example, compact-3 limits the question to a maximum of three columns for multiple choice questions in surveys used with the field app or web app.
The compact and horizontal-compact appearances are identical. In the Survey123 web app, instead of using columns, these appearances fit the choice labels for a select question side by side in rows without additional spacing.
For a select one question, setting the appearance column to likert presents the choices as a Likert scale. A Likert scale is a rating scale that allows respondents to specify their level of agreement on a symmetric agree-disagree scale of a statement.
By setting appearance to autocomplete, a select question is presented with a text field and a drop-down menu. Entering text in the field limits the drop-down menu to only answers that contain that text. This is useful for very long choice lists.
Note:
The autocomplete appearance for select multiple questions is only supported in Survey123 Mobile. It is not supported in the Survey123 field app or web app.
By setting appearance to search, you can populate the choice list for a select question with values from a CSV table in the survey's media folder, or an existing feature layer or table. For more information, see Create a dynamic choice list using the search appearance.
By setting appearance to image-map, a select question can be presented in the field app as an image with selectable regions as choices using an SVG file. For more information, see Work with SVG files
Create a dynamic choice list using the search appearance
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
Select one and select multiple questions support the search appearance, which can be used to populate the choice list with values from a CSV table in the survey's media folder, or an existing feature layer or table. When using the search appearance, you must still include an entry on the choices worksheet, but instead of listing each of the choices, you will reference the field name from the existing feature layer or table.
In the following example, a choice list named us_states is defined on the choices worksheet and will use the field STATE_NAME for both the choice name and label.
In the following example, this choice list is then referenced on the survey worksheet in the same way as other choice lists, but it includes the search appearance expression that references the existing feature layer from which to retrieve the choices.
The search appearance expression must be structured in the following way, with variables separated by commas:
search(tableName, searchType, searchColumn, searchText, filterColumn, filterText)The tableName parameter accepts either the name of the .csv file in the survey's media folder, for example, airports, or the URL of a feature layer or map service layer, preceded by a name for Survey123 to refer to the table internally. This table name doesn't need to match the name of the hosted layer, but because this is how Survey123 internally refers to your search, it must be different from all other table names and .csv files used in the survey. You can optionally append query request parameters to the REST endpoint of your feature layer or map service layers to configure the search behavior. In the following example, a feature layer URL is appended with the resultRecordCount parameter to populate the choice list with the first 10 query results, with the search being stored internally under the name airports:
"airports?url=https://services1.arcgis.com/e7dVfn25KpfE6dDd/arcgis/rest/services/Airports2/FeatureServer/0&resultRecordCount=10"The choice list can also be filtered using a WHERE
expression. When using the following example as the tableName, the
choice list will be filtered to show only states whose name is not
Alabama or Alaska:"state?url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized_Boundaries/FeatureServer/0&where=STATE_NAME
NOT IN('Alabama', 'Alaska')"
Note:
Search parameters that include special characters must be encoded if the survey will be used in the Survey123 web app. Encoding replaces special characters (such as a wildcard in the expression) with the percent sign (%) followed by their hexadecimal equivalent.
The following additional parameters are optional but can be used to narrow the results provided by the search:
| Parameter | Description |
|---|---|
searchType | Controls what type of search is performed, and accepts different values depending on whether the table being searched is a spatial table within a feature layer or a nonspatial table in a CSV or feature table. For spatial tables, the accepted search types are intersects, contains, crosses, envelope_intersects, index_intercepts, overlaps, touches, and within. To learn more, see Spatial relationships. For a nonspatial table, the supported search types are contains, startswith, endswith, and matches. |
searchColumn | Determines the column that will be searched for the text in the searchText parameter. These columns are taken from the table itself. In addition, a spatial table in a feature layer can search the columns @geopoint, @geotrace, and @geoshape. |
searchText | Contains the text that will be searched for and returned in the searchColumn parameter. |
Additionally, the following filter parameters can be added to the search expression to further refine the choice list values:
| Parameter | Description |
|---|---|
filterColumn | Sets a column to search for matches to the text given in the filterText parameter. The search query will only return results that contain this text. The filterColumn and filterText parameters must be used together. |
filterText | The text being searched for in the column given by the filterColumn parameter. The filterColumn and filterText parameters must be used together. |
The example search expression below includes some of the optional parameters for the search appearance. It populates a choice list with the contents of a .csv file, using a previous question as the search text.
search('csvName', 'matches', 'breed', ${DogQuestion})
Note:
Questions with the search appearance are presented in the Survey123 web app in the same way as select questions with the autocomplete appearance.
Specify other
For multiple choice questions, surveys can include the option to choose other when the desired choice is not listed. The respondent can then be asked to specify the other option. You can do this in XLSForm using either the manual method or the built-in method. The built-in method is quicker and easier to configure than the manual method but has several limitations.
Manual method
The manual method is recommended because it allows you to specify the name and label of the other choice and the name and label of the text question that collects the other response. You can provide translations for these names and labels. You can also apply constraints and appearances to the text question and make it required.
First, add an other choice to the choice list for the question on the choices worksheet. Specify a name and label for this choice as you would for any other choice in the list. In the following example, the color choice list has a choice named other.
On the survey worksheet, add a text question to collect the other response. Add a relevant expression so that the text question is relevant only when the other choice is selected. In the following example, the other_color question is relevant when the answer to the select_one question is other.
For multilingual surveys, the questions and choices can be translated. In the following example, French and Greek translations are provided on the survey worksheet for both the select_one question and the text question.
Translations are also provided on the choices worksheet, including for the other choice.
Built-in method
With the built-in method, Survey123 Studio and Survey123 Connect automatically create the other choice and the question to collect the other response. To use this method, type or_other after the choice list name in the type column in the survey worksheet. An Other choice is displayed in the list of choices for the question. When the Other choice is selected, a Specify other question is shown allowing users to provide their own answer. To store this answer, Survey123 Studio and Survey123 Connect automatically create an additional field in the feature layer using the name of your multiple choice question followed by _other, for example, favorite_toppings_other. See the following example:
Caution:
The label for the Specify other question will not display in languages other than English.
If creating a survey from an existing feature layer, the field for the Specify other question will not be automatically created, and the survey will not be published. You must create the field for the Specify other question manually in the feature layer with the name of your multiple choice question followed by _other, for example, favorite_toppings_other.
External choice lists
You can store choice lists for select_one and select_multiple questions in an external .csv file. This is ideal for very large choice lists, a survey with several choice lists, and choice lists that are managed outside of Survey123. External choice lists are not to be confused with external selects, in which choices must be listed in an additional worksheet.
The .csv file must contain name and label columns.
Note:
If the .csv file lacks a column header, or has a trailing comma at the end of the file's rows, the file fails to import into the survey.
For best results, encode the .csv file using UTF-8 character encoding. If you're using Microsoft Excel to create your .csv file, save it as CSV UTF-8.
Translated label columns can be included in the .csv file, but translated choices will only display in Survey123 Studio, Survey123 Connect, Survey123 Mobile and the Survey123 field app, not the Survey123 web app.
To include a question with an external choice list, enter the question type, select_one_from_file or select_multiple_from_file, and the name of the .csv file, for example, select_one_from_file CoverType.csv. File names are case sensitive and do not allow spaces.
There are two ways to include a .csv file: store the file in the survey's media folder or link to a .csv file hosted in ArcGIS.
Tip:
Run the Convert choice lists to CSV tool to automate migrating choice lists from the choices worksheet to .csv files.
Link a .csv file
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
To link a .csv file from ArcGIS content to a survey, do the following:
- Ensure that the .csv file is hosted in ArcGIS Online or ArcGIS Enterprise and has the same sharing permissions as the survey.
- Ensure that the survey is published to ArcGIS before attempting to link content.
- In Survey123 Connect, open the survey, and click the Linked Content tab. Click the Link content button, choose CSV, and browse to and select the .csv file to link.
For the form preview to show the choices from the linked .csv file, in Survey123 Connect, on the Linked Content tab, click the download button 
. This places a copy of the .csv file in the survey's media folder. Linked files are automatically downloaded with the survey in the Survey123 field app.
If you manually place the .csv file in the survey's media folder, and at a later time upload a .csv file of the same name to ArcGIS and link it to the survey, the .csv file in the survey is updated from the linked content (if newer).
Convert choice lists to CSV
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
Run the Convert choice lists to CSV tool in Survey123 Connect to automatically migrate specified choice lists from the choices worksheet to new .csv files in the media folder. The tool also modifies the corresponding questions in the survey worksheet to use select_one_from_file and select_multiple_from_file question types.
To run the tool, do the following:
- Configure a Python environment in Survey123 Connect so you can run the tool. For more information, see Configure Python.
- Open the survey's XLSForm. In the choices worksheet, add a column named esri_tool_convert_csv. Add a yes value to at least one row for each of the choice lists that you want to convert to external choice lists. Save and close the file.
- In Survey123 Connect, open the survey, click Tools, and choose Convert choice lists to CSV.
When the conversion is complete, a .csv file is saved to the media folder for each migrated choice list. The file name matches the original choice list name value (list_name column). The choices worksheet is updated to only include the remaining lists that weren't migrated. It still includes any custom column headers from the original. In the survey worksheet, applicable select_one and select_multiple questions are changed to select_one_from_file and select_multiple_from_file to reference the new external choice lists. The original choices worksheet is saved to a choices_backup worksheet so you can verify the results or revert. You can keep or delete the backup worksheet.
The tool will not convert choice lists used in rank questions, table-list groups, or questions with the search appearance. None of the questions that use these choice lists are modified in the survey.
If the tool detects unsupported questions, an .xlsx file is created in the debug folder with the affected choice list names. You can find this file in the following folder:
C:\Users\<username>\ArcGIS\My Survey Designs\<surveyName>\debug\convertchoicelists