While
Iterate while condition is true.
Intro here. Replace XYZ with the shape's name in titles.
What is While?
Instead of iterating for a specified number of times or for the length of a container object, While shape can be used to loop over and over again, until the condition no longer holds true. While the condition can also use incrementing number to execute specified amount of times, it can be more dynamic to allow execution as many times as needed, regardless of the actual number of iterations.
Because the condition is not directly connected to a container object's element count, it can be used to also add or remove elements from an object. The While shape can also be used to perform an API call until it succeeds, or wait and poll a system for a long running execution elsewhere.
To avoid situations where the condition will not ever change to false, called infinite loops, While shape includes a mandatory parameter to limit the number of iterations to a maximum value, making sure that the iteration will end eventually, if the condition does not change.
Usage
To use a While shape in your Process, add a While shape to your Process Editor, and connect it as part of your Process between a Trigger and a Return or Throw shape. While shapes are always one sequence flow in, one out.
After adding the shape to your Process, you can provide the While shape a name, which can be used to reference its result later in the Process. You then then need to define the condition which defines how long to continue iteration, and optionally change the maximum iteration count if needed.
Once the While has been added to your Process and parameters defined, you need to fill in the Process flow inside the While shape as well. Like Processes in general, the execution inside a While 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 While does not have any parameters assigned to it.
There can be only and exactly one Trigger shape within the While shape. There can however be as many Return or Throw shapes within the While shape as needed, as well as other Scope shapes within other Scope shapes.
Configuration
To set up a While 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 While.
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.
Expression
Condition that determines whether to continue iteration or stop it. Written in C# code as an expression that results in a boolean value. Condition must evaluate to True in order to perform iteration, while False value will stop the iteration.
Max iterations
Upper limit of iterations to make in the While shape. If reached, the While shape will throw an error that needs to be handled, otherwise the execution of the Process will end in failure. Acts as a safeguard against infinite looping.
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 >>.
Reference Values
While shape provides a #result reference value, which contains its internal operation's result value, defined within its Return shape. The result value will be the result of last iteration done in the While shape, defined in the executed Return shape.
Unlike Foreach shape, While shape will always return only the single value from the last iteration, instead of all result values from all iterations.
#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.
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.
Last updated
Was this helpful?