For Each Loop task

TheFor Each Loop task lets you make repeated calls to a sub-integration from your current (main) integration. The task iterates over the configured array variable and calls the sub-integration for each element in the array. The number of times the sub-integration is called is equal to the size of the array variable.

TheAPI Trigger ID and theIntegration name identifies the sub-integration you want to run.

The task also lets you collect the response from each sub-integration run and store the value in your current integration for use in downstream tasks. You can use any of the following approach to collect the responses:

• Collate the response of each run in an array variable, where each element of the array has the response from one particular run. To collate the responses, configure theCollect values from sub-integration output(s) property.
• Aggregate the responses of all the runs in a single variable. To aggregate the responses, configure theResponse parameter override mapping property.

• AFor Each Loop task can run a maximum of 8000 iterations.
• The cumulative size of the data collected from each sub-integration run cannot exceed50 MB. If the size exceeds50 MB, the integration fails, and the downstream tasks are not run.
• If an integration in theFor Each Loop task fails, then the entire task fails, and the downstream tasks are not run. To prevent failure of the entire integration you can specify anExecution strategy for the task in itsJoin configuration pane. SeeJoin for more details.

Before you begin

• Ensure that you haveattached a user-managed service account to your integration. If your integration does not have user-managed service account configured, then by default thedefault service account (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) is used for authentication.
• Ensure that your service account has theApplication Integration Invoker IAM role. For information about granting roles to a service account, seeManage access to service accounts.

Configuration properties

The following table describes the configuration properties of theFor Each Loop task.

Examples

The following sections provide detailed examples of how to configure and use theFor Each Loop task for specific scenarios. These examples illustrate the configuration steps for different use cases:

• Iterate and pass each element
• Collect sub-integration outputs
• Aggregate results with response override
• Pass additional inputs

Iterate and pass each element

Assume you have a main integration with an array variable namedproductIds containing values like["P1", "P2", "P3"]. To call a sub-integration namedGetProductDetails for each product ID, configure theFor Each Loop task as follows:

• SetList to iterate toproductIds.
• SetIteration element sub-integration mapping to map the current element ofproductIds to a variable inGetProductDetails, for example,subIntProductId.

Each execution ofGetProductDetails then receives one product ID fromproductIds.

Collect sub-integration outputs

As in the previous example, assumeGetProductDetails returns a JSON object in an output variable calledproductInfo.

To collect allproductInfo outputs from each sub-integration execution and store them as elements in an array variable within the main integration:

• ConfigureCollect values from sub-integration output(s).
• SelectproductInfo fromSub-integration output to collect from.
• Select an array variable in the main integration, for example,allProductDetails, fromIntegration variable to collect into.

After the loop completes,allProductDetails is an array where each element is theproductInfo JSON from one sub-integration execution.

Aggregate results with response override

Assume you have a main integration that calls a sub-integration (for example,GetProductDetails) for each item in a list, and you want to calculate the total price of all items. To sum up a numeric value returned by each sub-integration execution:

• Ensure the sub-integration returns a value in an output variableitemPrice.
• Initialize thetotalPrice variable to0 in the main integration.
• ConfigureResponse parameter override mapping:
  • MapitemPrice (from sub-integration) tototalPrice (in main integration).
• In theMap to additional sub-integration input(s) section:
  • MaptotalPrice (from main integration) to an input variable in the sub-integration, for example,currentTotal.
• In the sub-integration's logic, add the current item's price to thecurrentTotal received from the main integration. Then, return this new sum in the output variable nameditemPrice. This process creates a cumulative aggregation.

Pass additional inputs

If your sub-integrationGetProductDetails needs acurrency code from the main integration, then:

• In theMap to additional sub-integration input(s) section:
  • Map the main integration variablecurrencyCode to the sub-integration input variablesubIntCurrency.
• ThiscurrencyCode is passed to every execution of the sub-integration.

Explore the following sample integrations for practical, step-by-step guides and executable examples of the concepts discussed in the preceding sections:

• Invoke a sub-integration using a For Each Loop task
• Ecommerce sample integration

Best practices

For information about the usage limits that apply to theFor Each Loop task, see Usage limits.

Error handling strategy

An error handling strategy for a task specifies the action to take if the task fails due to atemporary error. For information about how to use an error handling strategy, and to know about the different types of error handling strategies, seeError handling strategies.

Quotas and limits

For information about quotas and limits, seeQuotas and limits.

What's next

• Learn aboutall tasks and triggers.
• Learn how totest and publish an integration.
• Learn abouterror handling.
• Learn aboutintegration execution logs.