Loop Node

The Loop Node allows for iterating over values on your payload, or for performing a certain operation a set number of times.

Configuration

Loop Source

Loop Source Path is the payload path to the item over which to iterate. Depending on the type of value found at this path, the Loop Node will behave slightly differently …

• For arrays, the Loop Node will run one iteration for each value in the array.
• For objects, the Loop Node will iterate over the object’s top-level keys. (Note: Order of the object keys is not guaranteed while iterating.)
• For numbers, the loop will run the number of times specified by the absolute value of the number rounded up to the nearest integer.
• For strings, the Loop Node will iterate over each character in the value.
• For all over value types, the Loop Node will not execute any iterations and will simply pass through to the next node(s).

Current Value Path

Current Item Path is the path on the payload where info on the current iteration should be stored. This value will be overwritten with each iteration. At this path will be stored an object with these properties…

• value: The value for this iteration.
• index: The iteration counter (starting at 0).
• first: A boolean indicating if this is the first iteration of the loop.
• last: A boolean indicating if this is the last iteration of the loop.
• key: If iterating over an object, the name of the property associated with the current iteration value.

Loop Mode

Specify whether this loop should run in Serial Mode or in Parallel Mode. Each has its own advantages, and each produces a much different result.

Edge Workflows running a Gateway Edge Agent with version below 1.21.0, as well as Embedded Workflows, will only run the Loop Node in serial mode.

Run loop iterations serially

• Iterations run one at a time.
• Each iteration can mutate the original payload.
• Loop can “break” (end early) if desired.

Run loop iterations in parallel

• Multiple (up to 5) loop iterations occur at one time, leading to faster execution.
• Mutations to the original payload are discarded after each iteration.
• All iterations will complete; loop cannot be stopped early.

Results

Loop Results Path is an optional path to return an array of results from the execution of this loop. Each item in the array will be the value found at the payload path in your Next / Return / Break Nodes.

Edge Workflows running with a Gateway Edge Agent with version below 1.21.0, as well as Embedded Workflows, will not have this configuration option.

Viewing Loop Contents

The Loop Node differs in behavior from other nodes within the workflow engine, in that it represents a group of sub-nodes that are run per iteration. To view or edit nodes within the iteration process, double-click the node on the canvas, or click the “View Group Contents” button in the node’s editor panel.

This will change the view of the workflow stage, indicating you are now viewing the contents of the Loop Node’s iteration. All of your workflow’s top-level nodes and connectors will no longer be visible, and in their place will be a new stage where nodes can be added to the iteration process and connected together. You may add, edit and connect nodes within the loop just like within the root level of your workflow. Think of your loop’s contents as just another workflow within your main workflow.

The entire palette of workflow nodes is available when editing a group (including more Loop Nodes) except for workflow triggers. A workflow may only be triggered from the root level of the workflow.

Sub-Node Errors

If any of your loop’s sub-nodes has configuration errors, the Loop Node at the root level will indicate an error exists within the group, and you will not be able to deploy the workflow until the errors are resolved.

Debug Output

While viewing a loop’s contents, debug messages will continue to stream into the debug panel from the workflow, regardless of if the node that triggered the message is part of the currently viewed group. However, hovering over a debug message, or viewing a live stream of debug content, will only highlight workflow runs whose corresponding Debug Node is currently visible.

Returning to the Top Level

To back out of the loop and return to the top level, double-click a blank area on the workflow stage, or click the breadcrumb in the top left corner of the stage.

Loop-Specific Nodes

There are three special nodes that exist only within a loop’s contents.

Loop Trigger

The Loop Trigger represents the starting point of each loop iteration. Its appearance mimics that of a workflow trigger. It takes no configuration of its own; however, the properties of the loop itself (the Loop Source Path and Current Item Path) may be edited when it is selected.

The node may be moved around the canvas and connected to other nodes like any other trigger; however, this node may not be deleted.

Next Node

The Next Node sets the payload that will be used on the loop’s next iteration. This is required if your loop is modifying the payload and you’d like to retain the modifications between each iteration and after the loop completes.

If the Next Node is not used, any changes to the payload will be lost at the end of each iteration.

The Next Node is similar to the continue statement in a JavaScript loop.

The Next Node has a configuration option to set the Iteration Result Path. Optionally, specify a payload path for a value to return when this node is invoked. If a “Loop Result Path” is set in the main Loop Node, the value at the “Iteration Result Path” path will be placed in the array of results. If no “Iteration Result Path” is specified, the node will default to the value at your “Current Item Path”.

The Next Node is only available in Serial Loop Mode.

Return Node

The Return Node does not set the payload that will be used on the loop’s next iteration. Any changes to the payload when running in parallel are discarded at the end of the iteration.

The Return Node has a configuration option to set the Iteration Result Path. Optionally, specify a payload path for a value to return when this node is invoked. If a “Loop Result Path” is set in the main Loop Node, the value at the “Iteration Result Path” path will be placed in the array of results. If no “Iteration Result Path” is specified, the node will default to the value at your “Current Item Path”.

The Return Node is only available in Parallel Loop Mode.

Break Node

The Break Node stops the iteration process after the current iteration completes. No iterations will occur after the Break Node is reached, and the workflow will continue with any nodes that come after the loop sub-process (if applicable). The payload for any subsequent nodes will match the (potentially mutated) payload at the time the Break Node was reached.

The Break Node’s functionality is similar to that of the break statement in a JavaScript loop.

The Break Node has a configuration option to set the Iteration Result Path. Optionally, specify a payload path for a value to return when this node is invoked. If a “Loop Result Path” is set in the main Loop Node, the value at the “Iteration Result Path” path will be placed in the array of results. If no “Iteration Result Path” is specified, the node will default to the value at your “Current Item Path”.

The Break Node is only available in Serial Loop Mode. Existing Break Nodes in Serial Mode will be converted to Return Nodes when the Loop Mode is toggled to Parallel Mode.

Loop Race Conditions

If your loop contains branches to different node paths, and two or more of those branches ends with a Return or Break Node, the payload for the rest of the workflow’s execution will match the payload at whichever node was reached first. For this reason, you should take special care with constructing your loop workflows to avoid race conditions.

If a Break Node is reached before a Return Node, the iteration process will stop with that iteration; similarly, if a Return Node is reached before a Break Node, the iteration process will continue and the Break Node will be ignored. But the loop’s next iteration, or the workflow’s nodes following the Loop Node, will not fire until the other branches have completed execution.

Take the screenshot above as an example. For each iteration in the loop, we are making three simultaneous HTTP requests, and the responses are put on the payload at data.responseA, data.responseB and data.responseC, respectively. Those responses are then pushed to an array, and we connect that to a Return Node so we have the value for the next iteration.

However, the workflow will not wait for all three responses to be added to the array before executing the Return Node and continuing the loop. Instead, whichever request completes first will have its response added to the array, and the response from the other two requests will be ignored for the continuing execution of the workflow. Furthermore, if Request B completes first and it does not have an OK response, the loop will break without adding any additional response values to the array. (The other two HTTP requests will still complete, though their responses will not be added to the payload.)

To avoid this particular race condition we could reconstruct this loop so the requests happen in sequence (seen above). The danger here is that if we are iterating over a large number of items, or our HTTP requests take a significant amount of time, our workflow could time out before completing execution.