Use foreach steps to iterate over arrays in parallel - CloudFlow - Alibaba Cloud - CloudFlow

A foreach step iterates over an array in its input and runs the same sequence of steps in parallel for each element in the array. Each iteration keeps its own local variable, and an output mapping combines the results of all iterations into the output of the foreach step.

How a foreach step works

A foreach step iterates over an input array parameter and runs the steps that are defined in its steps field for each element in the array. A foreach step works like foreach in a programming language, except that the iterations run in parallel instead of one after another.

When a foreach step runs, the following sequence occurs:

The foreach step starts one iteration for each element in the array and runs the iterations concurrently.
Each iteration has its own local variable. The steps in an iteration modify only the local variable of that iteration.
After all branches finish, the local variables of all iterations form the $local variable of the foreach step. This variable is an array in which each element is a JSON object that records the result of one iteration.
The output mapping of the foreach step converts the array of iteration local variables into the output of the foreach step.

Limits

A foreach step runs a maximum of 100 iterations concurrently.

Properties

A foreach step supports the following properties.

Property	Required	Description
`type`	Yes	The type of the step. Set the value to `foreach`.
`name`	Yes	The name of the step.
`iterationMapping`	Yes	The iteration mapping of the foreach step. The fields of `iterationMapping` are described in the following table.
`steps`	Yes	The steps that run in each iteration.
`end`	No	Specifies whether to continue running the steps that are defined after the foreach step when the foreach step ends.
`inputMappings`	No	The input mapping of the foreach step. If a step does not define an input mapping, the step inherits the input of its parent step or of the flow.
`outputMappings`	No	The output mapping of the foreach step. If you do not specify an output mapping, the output of the foreach step is empty by default.

The iterationMapping property of a foreach step contains the following fields.

Field	Required	Description
`collection`	Yes	Specifies which parameter in the input is used as the collection for the loop.
`item`	Yes	Specifies the name under which the current element is merged into the iteration input.
`index`	No	Specifies the name under which the current position is merged into the iteration input.

Example

The following flow definition contains a foreach step named myforeach. For each element in the names array, the foreach step runs one task step named toUpperCase.

version: v1
type: flow
steps:
  - type: foreach
    name: myforeach
    iterationMapping:
      collection: $.names
      item: name
    steps:
      - type: task
        name: toUpperCase
        resourceArn: acs:fc:{region}:{account}:services/fnf_test/functions/toUpperCase
    outputMappings:
      - target: names
        source: $local[*].name

Replace {region} and {account} in resourceArn with your own values.

Data flow in the example

The following stages show how data moves through the myforeach step and which field drives each transformation.

1. Flow input. The myforeach step does not define an input mapping, so the input of myforeach is the same as the input of the flow:

{
  "names": ["a", "b", "c"]
}

2. Iteration input. The toUpperCase step does not define an input mapping either, so it inherits the input of its parent step. Each time an iteration runs, iterationMapping merges the current element into that input as the value, with name as the key. The three iterations therefore receive the following inputs.

Input of the iteration for a:

{
  "name": "a",
  "names":["a","b","c"]
}

Input of the iteration for b:

{
  "name": "b",
  "names":["a","b","c"]
}

Input of the iteration for c:

{
  "name": "c",
  "names":["a","b","c"]
}

3. Iteration output. toUpperCase runs three times, once per element, and returns the following outputs.

Output of the iteration for a:

{
  "name": "A"
}

Output of the iteration for b:

{
  "name": "B"
}

Output of the iteration for c:

{
  "name": "C"
}

4. Local variable of the foreach step. The local variable of myforeach is an array that holds the result of each iteration:

[
  {
    "name": "A"
  },
  {
    "name": "B"
  },
  {
    "name": "C"
  }
]

5. Step output and flow output. The outputMappings property of myforeach maps $local[*].name to names, which produces the following output for the step. Because the flow does not define an output mapping or a result mapping, this output is also the output of the final flow execution.

{
  "names": ["A", "B", "C"]
}