Repeats

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 map questions in a single survey
Repeat to provide multiple responses to a single question

When you publish a survey that includes repeats, each repeat is created as a related table in your feature layer or a related layer if your 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 your spreadsheet:

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

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

Restrict the number of repeat records

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

  1. In the row where you want to begin your 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 your repeat.
  5. 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 cannot to 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, 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.

Note:

The behavior of a repeat with a changing repeat count is different depending on whether 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 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 will be deleted automatically. Regardless of whether this button is 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.

Aggregate functions

You can use aggregate functions 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 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 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. 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.

You can use the join function to concatenate questions that return a string. You can also use the sum function to connect geopoint questions within 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:

Example of the position(..) function in XLSForm
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 inside a group that's inside 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 the indexes match.

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

Example of the position(..) and selected-at() functions in XLSForm

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.

Known limitations

There are some known limitations and unexpected behaviors when 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.
  • If your survey contains multiple repeats, and one of these repeats has a geopoint, geotrace, or geoshape question, relationship naming will often be published out of order.
  • Nested repeats only support one-to-many relationships, and each child can have only one parent.