Added doc for repeatable step with items. Unified expressions to use ###XXX

Author: mnocon

code_samples/data_migration/examples/repeatable_step.yaml

@@ -13,7 +13,7 @@
             fields:
                 -   fieldDefIdentifier: name
                     languageCode: eng-GB
-                    value: 'Folder ###SSS i SSS###'
+                    value: 'Folder ###XXX i XXX###'
                 -   fieldDefIdentifier: short_name
                     languageCode: eng-GB
                     value: '### faker().name() ###'

code_samples/data_migration/examples/repeatable_step_with_items.yaml

@@ -0,0 +1,13 @@
+-   type: repeatable
+    mode: create
+    steps:
+        -   type: language
+            mode: create
+            metadata:
+                languageCode: '###XXX code XXX###'
+                name: '###XXX name XXX###'
+                enabled: true
+    items:
+        - { code: afr-AF, name: Afrikaans }
+        - { code: alb-SQ, name: Albanian }
+        - { code: ara-AR, name: Arabic }

code_samples/data_migration/examples/repeatable_step_with_items_counter.yaml

@@ -0,0 +1,20 @@
+-   type: repeatable
+    mode: create
+    iteration_counter_name: index
+    steps:
+        -   type: content
+            mode: create
+            metadata:
+                contentType: folder
+                mainTranslation: eng-GB
+                remoteId: 'migration_folder_###XXX index XXX###'
+            location:
+                parentLocationId: 2
+            fields:
+                -   fieldDefIdentifier: name
+                    languageCode: eng-GB
+                    value: '###XXX title XXX###'
+    items:
+        - { title: 'Getting Started' }
+        - { title: 'Advanced Configuration' }
+        - { title: 'API Reference' }

docs/content_management/data_migration/importing_data.md

@@ -86,32 +86,59 @@ Additionally, the following special migration types are available:
 
 You can run a set of one or more similar migration steps multiple times by using the special `repeatable` migration type.
 
-A repeatable migration performs the defined migration steps as many times as the `iterations` setting declares.
+A repeatable migration performs the defined migration steps as many times as specified:
 
-``` yaml hl_lines="4"
-[[= include_file('code_samples/data_migration/examples/repeatable_step.yaml', 0, 5) =]]
-```
+- with an [interation counter](#repeatable-steps-with-iteration-counter), mimicking the behavior of a [`for` loop](https://www.php.net/manual/en/control-structures.for.php)
+- with a [list of items](#repeatable-steps-with-items), mimicking the behavior of a [`foreach` loop](https://www.php.net/manual/en/control-structures.foreach.php)
 
 !!! tip
 
     You can use repeatable migration steps, for example, to quickly generate large numbers of content items for testing purposes.
 
+#### Repeatable steps with iteration counter
+
 You can vary the operations using the iteration counter.
 
 For example, to create five Folders, with names ranging from "Folder 0" to "Folder 4", you can run the following migration using the iteration counter `i`:
 
-``` yaml hl_lines="16"
-[[= include_file('code_samples/data_migration/examples/repeatable_step.yaml', 0, 16) =]]
+``` yaml hl_lines="4 16"
+[[= include_code('code_samples/data_migration/examples/repeatable_step.yaml', end_line=16) =]]
 ```
 
 To vary the content name, the migration above uses [Symfony expression syntax](#expression-syntax).
 
-In the example above, the expression is enclosed in `###` and the repeated string `SSS`.
+In the example above, the expression is enclosed in `###` and the repeated string `XXX`.
 
 !!! note
 
     Iteration counter is assigned to `i` by default, but you can modify it in the `iteration_counter_name` setting.
 
+#### Repeatable steps with items
+
+By using the `items` key, you can provide an array of items to the `repeatable` step:
+
+``` yaml hl_lines="10-13"
+[[= include_file('code_samples/data_migration/examples/repeatable_step_with_items.yaml') =]]
+```
+
+In the example above, the step runs for each entry declared in `items`.
+On each run, the values of `code` and `name` keys are available as variables.
+
+The iteration counter variable (named `i` by default) is also available and holds the zero-based index of the current item.
+You can rename it with the `iteration_counter_name` setting and combine it with item properties as in the following example:
+
+``` yaml hl_lines="3 10 16"
+[[= include_code('code_samples/data_migration/examples/repeatable_step_with_items_counter.yaml') =]]
+```
+
+This migration results in three new content items:
+
+| Content item name      | Remote location ID    |
+| ---------------------- | --------------------- |
+| Getting started        | `migration_article_0` |
+| Advanced Configuration | `migration_article_1` |
+| API Reference          | `migration_article_2` |
+
 #### Generating fake data
 
 You can also generate fake data with the help of [`FakerPHP`](https://fakerphp.org/).