Scope

Scoping your process is important for resource and error management.

To encapsulate a part of your Process to be handled as a whole, like curly brackets would be used in general programming, Scope shape can be used. It allows providing a name for that section of a Process, and error handling can be attached to it to catch any errors from the inner Process flow.

What is Scope?

Scope shape can be used to surround and encapsulate a part of your Process, most commonly to logically divide your Process into sections, as well as for error handling purposes. It can also be used to define and name a specific operation within your Process, that returns a value afterwards.

If execution of a Scope is interrupted by an error, the execution will exit the Scope immediately, much like a Process's execution will stop to an error. With Scope shape, you can attach a Catch shape to it to avoid the error propagating and interrupting the whole Process execution, giving you a chance to recover from the error within the Process, or handle it more gracefully.

Example showing Scope shape being used for error handling in a Process.
Scope shape is commonly used to perform error handling in Frends Processes.

Usage

To use a Scope in your Process, simply add a Scope shape to your Process Editor, and connect it as part of your Process between a Trigger and a Return or Throw shape. Scopes are always one sequence flow in, one out, with optionally a Catch shape connected to them in addition.

After adding the shape to your Process, you can provide the Scope a name, which can be used to reference its result later in the Process. It's also quite important for documentational purposes to have a name for each Scope, to understand what is happening within it.

Once the Scope has been added to your Process, you need to fill in the Process flow inside the Scope as well. Like Processes in general, the execution inside a Scope starts with a Trigger or Start 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 Scope does not have any parameters assigned to it.

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

Architecture

Scopes, in combination with Catch shapes, can be used to avoid errors propagating from the Process to reaching the logging and ending the Process prematurely. When multiple Scope shapes have been nested together, errors inside the scopes will propagate towards the outernmost Scope, exiting the Scopes in inside out order, until caught by a Catch shape or having the Process end in failure state.

Configuration

To set up a Scope 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 Scope.

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.

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

Scope shape provides a #result reference value, which contains its internal operation's result value, defined within its Return shape.

#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.

Example of result reference value being used to return a value from Process.
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.

Last updated

Was this helpful?