Start Iteration v1.0.17 Help ​

Starts an iteration to loop over a JavaScript/JSON object or array.

How can I use the Step? ​

The Step lets you iterate through a JavaScript/JSON object or array to perform actions on each element. This can be useful in data aggregation, customer records management, and workflow automation tasks.

How does the Step work? ​

The Step loops over the first dimension of input data and performs one iteration at runtime. It has three main exit conditions:

  • iteration: Triggered for each element in the object or array. Use this exit to define the iteration logic and then include one of the following companion Steps:

    • End Iteration: Indicates the end of the iteration and returns the Flow to the specified Start Iteration Step; can collect iteration data.
    • Break Iteration: Terminates the current iteration loop and jumps to a specified Start Iteration Step within the Flow, bypassing any remaining iterations.

  • iteration end: Triggered when the iteration loop has completed, allowing the Flow to proceed to subsequent Steps.

  • error: Triggered when the data provided for iteration is neither an array nor an object. This exit condition stops the Step, indicating that the iteration data type is invalid.

Handling multidimensional data ​

To handle multidimensional data, add Start Iteration and End Iteration Steps for each dimension level you wish to traverse. It's possible to have multiple branches inside each iteration level, but each branch must end with the End Iteration or Break Iteration Steps. This setup ensures that the logic for each dimension is encapsulated correctly and executed.

Prerequisites ​

  • To use the Step, basic knowledge of JavaScript/JSON is required.

Input data ​

  • For Source, provide the input data for iteration. It must be a JavaScript/JSON object or array. This parameter is required.

Merge field settings ​

The Merge field only holds data for the current iteration and becomes empty once the loop ends. The exception is when the iteration is interrupted by a Break Iteration Step. In this case, the Merge field in the Start Iteration Step becomes available with the current iteration data and the isIterationBroken property set to true.

Caution: If you use the Start Iteration Step multiple times in a Flow, customize the Merge field name for each instance to avoid overwriting data.

To learn more about Merge fields, their types, and how to work with them, follow this link

Output example ​

For each iteration, the output contains essential iteration details like the original data, current index, and value:

json
{
 "iteratedData": ["item0", "item1", "item2"],
 "iteratedItemKey": 0,
 "iteratedItemValue": "item0",
 "iteratedIndex": 0
}
{
 "iteratedData": ["item0", "item1", "item2"],
 "iteratedItemKey": 0,
 "iteratedItemValue": "item0",
 "iteratedIndex": 0
}

The output object can include the following properties:

  • iteratedData: The original data.
  • iteratedItemKey: Current index for arrays or key for objects.
  • iteratedKeys: Array of all iterated keys (only for object data types).
  • iteratedItemValue: Current iterated value.
  • iteratedIndex: Number of the current iteration, starting from 0.
  • isIterationBroken: A flag set to true, indicating that the iteration was interrupted by the Break Iteration Step.

Error handling ​

By default, the Step handles errors using a separate exit. If the source data is neither an array nor an object, the Step throws an error, and the Flow proceeds down the error exit.

For more information on error handling, follow this link.

Reporting ​

The Step automatically generates Reporting events during its execution, allowing for real-time tracking and analysis of its performance and user interactions. To learn more about Reporting events, follow this link.

Service dependencies ​

  • studio v3.71.0
  • bot deployer v2.22.4
  • library v2.18.4

Release notes ​

v1.0.17 ​

  • Rebuild external components with standard UI components
  • Add the ability to break the loop using the Break Iteration Step

v1.0.14 ​

  • Update error handling for invalid iteration data