Foreach

Iterate all elements of a container object.

Foreach loop or iteration is common task in programming, to go over and handle all elements inside a container object. Foreach shape is used for that exact purpose in Frends as well.

What is Foreach?

To perform iteration in Frends Processes, you can use Foreach shape to loop through a container's elements one by one. The shape will take care that all elements in the container object are handled, and provides the current element as a variable within the Scope.

Much like in general programming, Foreach iteration cannot be used to add or remove elements from the iterated object, but modifying the contents of the current element is possible.

Foreach can be used to iterate through a container object's elements.

Usage

To use a Foreach shape in your Process, add a Foreach shape to your Process Editor, and connect it as part of your Process between a Trigger and a Return or Throw shape. Foreach shapes are always one sequence flow in, one out.

After adding the shape to your Process, you can provide the Foreach shape a name, which can be used to reference its result later in the Process. You then then need to define the name of iterator variable and iterated container object for the Foreach iteration.

Once the Foreach has been added to your Process and parameters defined, you need to fill in the Process flow inside the Foreach as well. Like Processes in general, the execution inside a Foreach starts with a Trigger shape, and ends to a Return or Throw shape, with various different shapes possibly between them. Unlike Processes or Subprocesses, the Trigger shape within a Foreach does not have any parameters assigned to it.

There can be only and exactly one Trigger shape within the Foreach. There can however be as many Return or Throw shapes within the Foreach shape as needed, as well as other Scope shapes within other Scope shapes.

Configuration

To set up a Foreach shape, add the shape to Process canvas and connect it as part of your Process. After that, you can configure the parameters for the shape.

The following configuration parameters are available for Foreach.

Display name

Shapes can be given a display name in Frends Processes to distinquish them from each other. Shape's display name has no technical purpose and is only for documentational and visual purposes only. For shapes returning a #result reference value, the display name can be used to specify which result is meant.

Display name is given to the shape by double-clicking it on the canvas or through its configuration parameters.

Variable

Name of the iterator variable inside the Foreach shape. The variable will accessible as #var.MyVariable reference value inside the shape, if the name of the variable is MyVariable.

Expression

C# code expression that creates, specifies or results in the container object to be iterated through. Can be an Array, JArray, List or any other C# iterable object.

Skip logging result and parameters

Toggle option to select if the values of this shape should be included in logging or not. Default is false. If set to true, Process Instance logs will show the result and parameter values of this shape as << Omitted >>.

Type

Text input field to specify the type of data for the iterator variable. Any valid C# primitive type or class from included libraries can be given here to enforce the data type and simplify the variable's usage.

Alternatively the field can be left empty, resulting in dynamically typed variable, of which data type will be deducted at runtime.

Dispose at the end of the scope

Toggle option to select if the result and other memory allocations should be released after the containing scope exits. The containing scope can be the Process execution itself, Scope shape, or a single iteration of Foreach or While Scope shape.

Can be useful if the shape results in a large amount of data, allowing its early release from memory if it's not needed later in the Process.

Reference Values

Foreach shape provides a #result reference value, which contains its internal operation's result value, defined within its Return shape. The result values for each iteration are returned as a single value, which are then combined to an array object for the actual result value.

Foreach shape will always return an array object that has as many elements as the container object being iterated.

#result

#result reference value can be used to access earlier shape's return value. For Scope shapes, the value is specified using Return shape, while for Task's the #result is populated directly by the Task.

Result reference value used to return the Task's result as response from the Process.

When Return shape is used to end Foreach or While shapes, the expression or HTTP content values in Return shape are available through #result reference value as an array of values for each iteration.

#result reference value by default references the last Task's or Scope shape's return value. Instead of unnamed #result reference, you can also use named #result reference value.

Named #result

Named #result reference value is used with square brackets, much like dictionary's or object's fields would be used, such as #result[Handle elements] or #result[HTTP Request]. This way it can be specified which shape's result you are using.

When using named #result reference value with Scope shapes and Return shapes, it should be noted that the #result reference value is named by the Scope shape and not by the Return shape, although the value is specified in the Return shape. Thus, when using the named #result value, such as #result[Handle elements], the Scope shape's name should be used.