An XLSForm can repeat a group of questions multiple times. Examples of how repeats are used include the following:
- Capturing multiple answers to the same question in one survey
- Capturing separate, smaller collections of records, such as the name, age, and gender of every person in a household
- Capturing multiple images or geopoints in a single survey
To repeat a group of questions in Survey123 to capture multiple responses, complete the following steps on the survey tab of your spreadsheet:
In the row where you want to begin your repeat, type begin repeat in the type column.
Provide a name for the repeat in the name column.
In the following rows, enter the questions you want to include in your repeat.
Immediately after the questions, type end repeat in the type column.
This will create a group of questions in your survey that can be added repeatedly to your survey results. By default, there is no restriction on the number of times the questions can be repeated.
Restrict the number of repeat records
To define the number of repeats in Survey123, set a repeat count as shown in the following steps:
In the row where you want to begin your repeat, type begin repeat in the type column of the survey tab.
Provide a numeric value for the number of repeats in the repeat_count column. You can also provide a question name or calculation that returns a numeric value.
Provide a name for the repeat in the name column.
In the rows below this entry, enter the questions you want to include in your repeat.
In the last row, type end repeat in the type column.
When a user opens your survey, the repeat will already have created the number of repeats set in the repeat_count column. They will be unable to create new repeats, or delete existing ones.
All repeats defined by the repeat_count value must be navigated through before the survey response is submitted; otherwise, not all repeat records will be submitted. To ensure that all repeats are submitted, consider making questions required in your repeats. However, be aware that questions in repeats that have a relevant or conditionally required statement applied will not be evaluated on submission.
The behavior of a repeat with a changing repeat count is different depending on if the user is creating a new survey response or editing one that was previously submitted.
When creating a new survey response, the repeat count for a repeat being reduced presents a button at the top of a repeat to delete all records above the new repeat count that have data in them; blank records will be deleted automatically. Regardless of whether this button was pressed, submitting the survey response will not send records above the new repeat count.
When editing an existing survey response, the repeat count for a repeat being reduced displays a message at the top of the repeat, warning that the repeat record amount has changed. The user will be unable to submit an edited response with fewer than the original number of repeat records. Adding new repeat records will only be accepted if allowAdds is set to true in the bind::esri:parameters column. If allowAdds is set to false, the user will also be prevented from entering more than the original number of repeat records.
Repeat records and related tables
When you publish a survey that includes repeats, each repeat will be created as a table that is related to your feature service.
Starting with version 2.1 of Survey123, aggregate functions can be used to return values derived from responses across repeats. To do this, a question inside a repeat is referenced by a question outside of the repeat. For example, the following formula will count the responses to a single question across repeats:
The following functions can be used to aggregate responses:
These functions only apply to the current survey response. They don't take into account other records in the feature service. It is also possible to include questions using sum and count within the repeat. However, while sum and count will be calculated for each new record added to the repeat, the calculations on previous entries in the repeat are not automatically updated. These calculations can be refreshed manually using the Refresh button next to the question. The use of min and max is only supported outside of the repeat.
The sum function can also be used to concatenate questions that return a string.
There are some known limitations and unexpected behaviors to using repeats in Survey123:
- If your survey contains an empty repeat, with no questions between begin repeat and end repeat, all survey responses will fail to submit.
- Republishing a survey will cause it to stop responding if you have only added a new question to a repeat. As a workaround, you can add a new question outside of the repeat, and then republish. The new question added outside of the repeat will also need to be deleted from the feature service afterward if not needed.
- If your survey contains multiple repeats, and one of these repeats has a geopoint, relationship naming will often be published out of order.