From 550e3aed85f85f493bc56fbaeab7664fb7f60096 Mon Sep 17 00:00:00 2001
From: Faithful Adeda <93828448+Adematics@users.noreply.github.com>
Date: Wed, 4 Dec 2024 19:23:22 +0100
Subject: [PATCH] Feats docs(loops) : updated loop over a list of values
 (#1888)

* Update loop.md

* fix: eachsequential -> foreach

---------

Co-authored-by: Will Russell <will@wrussell.co.uk>
---
 content/docs/15.how-to-guides/loop.md | 51 ++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/content/docs/15.how-to-guides/loop.md b/content/docs/15.how-to-guides/loop.md
index ff0d4c22f2..0865ff6e36 100644
--- a/content/docs/15.how-to-guides/loop.md
+++ b/content/docs/15.how-to-guides/loop.md
@@ -8,7 +8,18 @@ topics:
 
 How to iterate over a list of values in your flow.
 
-In this example, we can use `EachSequential` to iterate over a list of values.
+In this guide, you will learn how to iterate over a list of values using the `ForEach` task. This task enables you to loop through a list of values and execute specific tasks for each value in the list. This approach is useful for scenarios where multiple similar tasks need to be run for different inputs.
+
+## Prerequisites
+
+Before you begin:
+
+- Deploy [Kestra](../02.installation/index.md) in your preferred development environment.
+- Ensure you have a [basic understanding of how to run Kestra flows.](../01.getting-started/03.tutorial.md)
+  
+## Loop Over Nested Lists of Values
+
+This example demonstrates how to use `ForEach` to loop over a list of strings and then loop through a nested list for each string. To see the flow in action, define the `each_nested` flow as shown below:
 
 ```yaml
 id: each_nested
@@ -16,15 +27,15 @@ namespace: company.team
 
 tasks:
   - id: 1_each
-    type: io.kestra.plugin.core.flow.EachSequential
-    value: '["s1", "s2", "s3"]'
+    type: io.kestra.plugin.core.flow.ForEach
+    values: '["s1", "s2", "s3"]'
     tasks:
       - id: 1-1_return
         type: io.kestra.plugin.core.debug.Return
         format: "{{task.id}} > {{taskrun.value}} > {{taskrun.startDate}}"
       - id: 1-2_each
-        type: io.kestra.plugin.core.flow.EachSequential
-        value: '["a a", "b b"]'
+        type: io.kestra.plugin.core.flow.ForEach
+        values: '["a a", "b b"]'
         tasks:
           - id: 1-2-1_return
             type: io.kestra.plugin.core.debug.Return
@@ -40,3 +51,33 @@ tasks:
     format: "{{task.id}} > {{outputs['1-2-1_return'].s1['a a'].value}}"
 ```
 
+Save and execute the `each_nested` flow.
+
+The above flow, when executed, iterates over a nested list of values, logging messages at each level of iteration to track the processing of both the outer and inner list items.
+
+Within the flow:
+
+- `1_each`: Uses the `ForEach` task to iterate over the list `["s1", "s2", "s3"]`. For each value, it runs the nested tasks defined within.
+  
+  - `1-1_return`: Logs the task ID, the current list value, and the task run start time.
+  
+  - `1-2_each`: Iterates over a second list `["a a", "b b"]` and runs a set of tasks for each value in this nested list.
+    
+    - `1-2-1_return`: Logs the task ID, the nested list value, and the start time of the task run.
+    
+    - `1-2-2_return`: Logs a custom output from `1-2-1_return`, which shows how to access outputs from previous iterations within the nested loop.
+
+  - `1-3_return`: Logs the output from `1-1_return` after the inner loop is completed and displays the corresponding value processed in the outer loop.
+
+- `2_return`: Fetches the output from the nested loop (`1-2-1_return` for the value `a a`) and logs it.
+
+
+## Next Steps
+
+Now that you've seen how to loop over a list of values using `ForEach`, you can apply this technique to any scenario where multiple iterations of similar tasks are needed. You can further extend this flow by:
+- Adding more complex nested loops.
+- Using dynamic input values instead of hardcoded lists.
+- Logging or processing additional data from each iteration.
+
+For more advanced use cases, refer to Kestra’s official [ForEach](https://kestra.io/plugins/core/tasks/flow/io.kestra.plugin.core.flow.foreach) task documentation.
+