Repeats

An XLSForm can repeat a group of questions multiple times. Examples of how repeats are used include the following:

• Capture multiple answers to the same question in one survey.
• Capture separate, smaller collections of records, such as the name, age, and gender of every person in a household.
• Capture multiple map questions in one survey.

When you publish a survey that includes repeats, each repeat is created as a related table in the feature layer or a related layer if the repeat contains a geopoint, geotrace, or geoshape question.

Use repeats

To repeat a group of questions in Survey123 to capture multiple responses, complete the following steps on the survey tab of the spreadsheet:

1. In the row where you want to begin the repeat, type begin repeat in the type column.
2. Provide a name for the repeat in the name column.
3. In the rows below this entry, enter the questions you want to include in the repeat.
4. Immediately after the questions, type end repeat in the type column.

A group of questions is created in the survey that you can add repeatedly to the survey results. By default, there is no restriction on the number of times you can repeat the questions.

Point locations from the first geopoint question in a repeat can be displayed on any map in the survey. For more information, see Point overlays on maps.

Restrict the number of repeat records

To define the number of repeats in Survey123, set a repeat count by completing the following steps:

1. In the row where you want to begin the repeat, type begin repeat in the type column of the survey tab.
2. 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.
3. Provide a name for the repeat in the name column.
4. In the rows below this entry, enter the questions you want to include in the repeat.
5. In the last row, type end repeat in the type column.

When a user opens the survey, the number of repeats set in the repeat_count column are already created. Users cannot create or delete repeats.

The user must navigate through all repeats defined by the repeat_count value before the survey response is submitted; otherwise, not all repeat records will be submitted. To ensure that all repeats are submitted, you can make questions required in the repeats. Be aware though that questions in repeats that have a relevant or conditionally required statement applied are not evaluated on submission.

Note:

The behavior of a repeat with a changing repeat count is different depending on whether the user is creating a survey response or editing one that was previously submitted.

When creating a survey response, the repeat count for a repeat being reduced has a button at the top of a repeat to delete all records above the new repeat count that have data in them; blank records are deleted automatically. Regardless of whether this button is pressed, submitting the survey response does 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 cannot submit an edited response with fewer than the original number of repeat records. Additional new repeat records are only accepted if allowAdds is set to true in the bind::esri:parameters column. If allowAdds is set to false, the user cannot enter more than the original number of repeat records.

Aggregate functions

You can use aggregate functions to return values derived from responses across repeats. To do this, a question in a repeat is referenced by a question outside of the repeat. For example, the following formula counts the responses to a single question across repeats:

count(${repeated_question})

You can use the following functions to aggregate responses:

• count
• sum
• min
• max
• join

These functions only apply to the current survey response. They don't take into account other records in the feature layer. You can also include questions using sum and count in the repeat. However, while sum and count values are calculated for each new record added to the repeat, the calculations on previous entries in the repeat are not automatically updated. You can refresh these calculations manually using the Refresh button next to the question. The use of min and max is only supported outside of the repeat.

Note:

When used in the Survey123 field app, sum, count, and join functions can be placed inside or outside of the repeat. If sum, count, and join are to be used in the Survey123 web app, they must be placed outside of the repeat. A sum, count, or join value from outside the repeat can be referenced in a calculation inside the repeat.

You can use the join function to concatenate questions that return a string. You can also use the sum function to connect geopoint questions in the repeat as a geotrace or geoshape question outside of the repeat.

For information on how to use these functions, see Formulas.

Return the index of a repeat record

You can use the position(..) function to return an integer reflecting the index of the repeat record in a repeat. For example, the first record in a repeat will return 1, the second will return 2, and so on. In the following example, the position(..) function is used in a hidden integer question in a repeat:

Caution:

The position(..) function always returns 0 in the Survey123 field app or 1 in the Survey123 web app when used outside of a repeat or in a group that's in a repeat.

You can also use the position(..) function in an expression. In the following example, the selected-at() function uses position(..) to return the choice that was selected in the select_multiple question at the same position as the current repeat record and display the choice in the repeat as a note. The selected-at() function starts counting choices from zero, so one is subtracted from position(..) to ensure that the indexes match.

selected-at(${issues}, position(..)-1)

You can use the position(..) function in combination with indexed-repeat() to extract question values from specific repeat records.

Use values from indexed repeats

You can use the indexed-repeat() function to return the value from a specific question in a repeat record. This requires the question name, repeat name, and repeat's index number, in that order. The following example returns the answer to the question room_no for the third record in the repeat floor:

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

You can use the indexed-repeat() function for repeats within repeats. When used in this way, it will only receive values accessible from the currently visible parent repeat.

Caution:

The indexed-repeat() function cannot be used in the repeat that it references, as this will cause a circular reference. For example, the following expression cannot be used for a calculation in the repeat named defects:

indexed-repeat(${defect_type}, ${defects}, 3)

Known limitations

The following are known limitations and unexpected behaviors when using repeats in Survey123:

• If a survey contains an empty repeat with no questions between begin repeat and end repeat, all survey responses will fail to submit.
• If a survey contains multiple repeats, and one of the repeats has a geopoint, geotrace, or geoshape question, relationship naming may publish out of order.
• Nested repeats only support one-to-many relationships, and each child can have only one parent.
• Nested repeats with both an expression in the relevant column and an expression in the repeat_count column clear all existing saved data in the first repeat record. To avoid this, incorporate the relevant expression into the repeat_count expression so that no repeat records are created when the repeat isn't relevant.