Repeats

An XLSForm can repeat a collection 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 collection of questions 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 collection 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.

Appearance

By setting the appearance column of a begin repeat question to minimal, the collection of questions is not visible on startup. The user must click the add button to see the questions in the repeat. This is useful when repeated questions don't need to be completed in a survey. This appearance is defined in the begin repeat question.

If a repeat is set to minimal and has a repeat count of zero, the repeat controls and their label are not visible.

By setting the appearance of a begin repeat question to compact, the repeat appears in a collapsed state on startup, which can be expanded by the user. This is useful for large surveys that may be difficult for the user to read and navigate. This appearance is defined in the begin repeat question.

Unlike other appearances, a repeat can use both minimal and compact at the same time by setting the appearance to minimal compact. This presents the questions in a repeat in both a collapsed (compact) and a hidden (minimal) manner.

By setting the appearance of a begin repeat question to tabular, the questions in the repeat are presented as a table. For more information, see Tabular repeats.

Note:

In Survey123 Connect, you can also set the following appearances for repeats in surveys used with the Survey123 field app or Survey123 web app:

• By setting the style column on the settings sheet to pages and the appearance of each begin repeat question to field-list, each repeatable collection of questions displays on a separate page of the survey. This behavior is the same as for a group.
• By setting the style column on the settings sheet to fixed-grid or dynamic-grid, repeats in your survey can be set to display the contained questions in a grid layout. This behavior is the same as for a group.

Tabular repeats

Note:

This section describes functionality that is only available in Survey123 Studio and Survey123 Mobile.

In Survey123 Connect, the Survey123 field app, and the Survey123 web app, the tabular appearance and its associated XLSForm parameters are ignored.

By setting the appearance of a begin repeat question to tabular, the questions in the repeat are presented as a table. In the tabular view, records in the repeat are presented as rows, and questions in the repeat are presented as columns. The tabular view allows you to edit data directly in its cells and sort and navigate records in the repeat.

The tabular view is shown in the following image:

The callouts in the image above are detailed as follows:

1. Tap the menu button for each row to access the Edit in form view, Copy to new record, and Delete options.
2. The read-only icon indicates that a question (column) cannot be edited in the tabular view.
3. Tap a column header to sort the tabular view in ascending order and, optionally, do the following:
   • Tap the column header again to sort in descending order.
   • Tap the column header a third time to turn off sorting (reverts to the original row order). Alternatively, tap another column header to sort on that column.
4. Tap in a cell to edit its value. Only some question types can be edited in the tabular view.
5. Tap the clear button in a cell to delete its value.

You can also edit individual records in the form view. The form view presents individual repeat records in a separate, fully featured survey form.

The tabular appearance can be used in conjunction with the minimal and compact appearances.

To get started with tabular repeats, complete the following steps in Survey123 Studio:

1. Set the appearance to tabular for the begin repeat question.

   The tabular view remains empty until you add questions to it.

2. Add one or more questions to the tabular view by typing showInTabularView=true in the body::esri:style column for each question.
3. Configure the tabular view with optional parameters.

Add questions to the tabular view

You can add questions to the tabular view by typing showInTabularView=true in the body::esri:style column for questions in the repeat. You can edit the following question types in the tabular view:

• text
• integer
• decimal
• date
• time
• dateTime

All other question types are displayed as read-only columns in the tabular view.

Caution:

Consider the following when adding questions to the tabular view:

• Questions in the repeat that have an expression (including yes) in the readonly column cannot be edited in the tabular view.
• Questions in the repeat that have an expression in the body::esri:visible column or that have the hidden appearance are not shown in the tabular view.
• Questions in the repeat that have an expression in the relevant column are not shown in the tabular view.
• Questions in the repeat that have an expression (including yes) in the required column or an expression in the constraint column are shown in the tabular view. When one or more required or constraint conditions are not met, a general warning is displayed above the tabular view with a warning icon alongside each record (row) that has errors. You cannot submit the survey until these issues are addressed. You can edit records in the form view to see the constraint and required warning messages for individual questions. When the repeat has errors, the Edit in form view option is available, even when the editInFormView parameter in the body::esri:style column is set to false.

Tabular view options

You can configure options related to the records (rows) in the tabular view by specifying parameters in the body::esri:style column for a begin repeat question. These optional parameters are described in the table below. You can add multiple parameters by separating them with spaces. The following is an example:

addRecordMode=form copyToNewRecord=false

When you set the appearance of a begin repeat question to tabular and don't specify any parameters in the body::esri:style column for this question, the Edit in form view, Copy to new record, and Delete options are available in the tabular view by default.

Parameter	Description
addRecordMode	Specify the mode for the Add record button and the Copy to new record option in the tabular view. The default is row. When the value is row, the new record is appended to the tabular view. When the value is form, the new record is opened in the form view. Values: row | form Example: addRecordMode=form
editInFormView	Show or hide the Edit in form view option in the tabular view. The default is true. Note: When the repeat has errors, the Edit in form view option is enabled even when the editInFormView parameter is set to false. Values: true | false Example: editInFormView=false
copyToNewRecord	Show or hide the Copy to new record option in the tabular view. This option allows users to duplicate a record in the repeat. The default is true. The addRecordMode parameter determines how the duplicate record is added. Values: true | false Example: copyToNewRecord=true
editInTabularView	Enable or disable editing in the tabular view. The default is true. When the value is false, all cells in the tabular view are read-only. Values: true | false Example: editInTabularView=false

Limitations when using tabular repeats

The following limitations apply to tabular repeats:

• The tabular appearance is not supported for nested repeats.
• The Copy to new record option does not copy attachments or nested repeats to the new record. This is consistent with the behavior when copying survey records to a new record from the Sent folder or Inbox.
• When the tabular view is sorted, it is recommended that you don't edit values in the column that has sorting applied, because the sorting updates immediately on each keystroke.
• When a tabular repeat is inside a group that has a relevant expression, its tabular view will be empty when the group is made relevant.
• In right-to-left languages, the sequence of columns in the tabular view does not reverse, and the column headers aren't always aligned to the right.

Specify the number of repeat records

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 specify the number of repeat records in a repeat, 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.

   Optionally, 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.

Users must navigate to all repeat records defined by the repeat_count value before submitting the survey response. Otherwise, not all repeat records will be submitted because expressions and defaults cannot be applied to repeats until users navigate to the record. To ensure that all repeats are submitted, you can make questions required in the repeats. 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 as follows:

• When creating a survey response, the field app displays a button at the top of the 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 sends all records except empty records.
• When editing an existing survey response, the field app displays a message at the top of the repeat to indicate that the number of records does not match the repeat count. New repeat records can only be added if allowAdds is set to true in the bind::esri:parameters column. Records in excess of the repeat count cannot be deleted because the field app does not support deleting existing repeat records. Edited survey responses can be submitted even when the number of repeat records does not match the repeat count.

Aggregate functions

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.

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 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 for 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 the repeat.

Note:

When used in the Survey123 field app, the sum, count, and join functions can be placed inside or outside the repeat. If sum, count, and join are to be used in the Survey123 web app, they must be placed outside 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 the repeat.

For information about 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 Survey123 Mobile and 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 as follows:

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

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.

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 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.
• Editing individual responses in the Survey123 web app or on the Survey123 website is not supported for surveys that contain nested repeats.