XLSForm supports select_one (select only one answer), select_multiple (select multiple answers), and rank (order a list of choices) questions. Writing a multiple choice question requires adding a choices worksheet to your Excel workbook. The following is an example of a select_one question:
Note that yes_no in the survey worksheet must match yes_no in the list name column 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.
When you modify the choices for select_one questions and republish the survey, Survey123 Connect displays a summary of the changes and allows you to decide whether these changes should be applied to the domains in the feature layer. For more information, see Update a survey.
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.
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}')
Specify other
For multiple choice questions, surveys may 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 this method, Survey123 Connect automatically creates 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 Connect automatically creates 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:
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 may be included in the .csv file, but translated choices will only display in Survey123 Connect 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
To link a .csv file from ArcGIS content to a survey, do the following:
- Ensure the .csv file is hosted in ArcGIS Online or ArcGIS Enterprise and has the same sharing permissions as the survey.
- Ensure 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
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, complete 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