Catch
Catching the expected or unexpected errors thrown within the Process.
When preparing for unexpected results within a Process, Catch shape is important to handle the possible errors gracefully. In tandem with Scope shapes and Throw shapes, Catch shape is the link between successful execution and handling possible errors before they can cause havoc.
What is Catch?
Catch shape can be used to catch errors from the connected shape, including Scope shape to handle errors from a part of the Process. The element itself does not do error handling, but instead it is commonly used with Scope shape after the Catch shape to perform error handling actions.
Unlike most other event shapes, Catch shape is not used to end the Process flow path, but instead the flow continues to an alternative path for error handling, before returning the flow back to the original path. It is more alike to a Decision shape, in that the error handling path is executed "if" an error occurs, otherwise the original path is followed.
Usage
To use Catch shape, add the shape to Process canvas, near another shape that you would like to catch errors from. Allowed shapes to catch from are Scope and Task shapes. Connect the Catch shape to the shape you want to catch errors from, and then further connect the catch shape to a shape that will handle the error. Finally, connect the error handling shape back to the original Process path to the next shape from the one you are catching errors from. Once added to the Process, you can click the shape to configure its options.
Connection details
Catch shape has very specific requirements when it comes to connecting it to Processes, unlike most other shapes.
The error handling must be done within one shape after the Catch shape. If more than one shape is required, using Scope shape as the error handling shape allows you to perform more complex logic. Scope shape as the error handler is the most common setup for catching and handling errors.
The error handling path must also join back to the main Process flow right after the shape you are catching errors from. There can be no shapes in between.
As a special note, the shape performing error handling cannot have a second Catch shape directly connected to it, to catch errors from the error handling. However, error handling Scope can contain other shapes with Catch shapes along with other processing logic. Same error handling shape also cannot be used to handle multiple catched errors, all Catch shapes must include their own error handling shape and logic.
In both special cases it is recommended to create a Subprocess to handle errors to avoid repeating the same logic and to clean up more complex error handling logic, to keep the Process itself clean and readable.
Reference value notes
If the #result reference value is required to be used for the shape errors are caught from, the error handling shape and the shape errors are caught from should be of same type, or more accurately they should return same type of result object. Alternatively, more complex logic can be used to check if errors were raised, and if not, then the #result reference can be used. More common usage is thus to catch from and handle errors in Scope shapes, so that the #result reference value is always available to use.
When using named #result reference value for element with Catch shape and error handler, the named #result is always named after the shape the errors are catched from. When an error is caught and handled, the result for that error handling will be available as the result for the shape the error was caught from, regardless of the name and type of the error handling shape.
Architecture
Errors caught with Catch shape are not logged to Process Instance list or Agent logs, and they have no direct effect on how the Process execution appears in the Process Instance list.
Configuration
To set up a Catch shape, add it to your Process canvas and connect it to your Process flow as described in Usage section. After this, you can configure the shape's options.
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
Name of the error variable available to the error handling shape. Defaults to "error", which is useable as #var.error in the error handler shape.
As an example, if the value is changed to "ErrorVariable", the reference value in error handling shape would be used as #var.ErrorVariable.
Reference values
Note that Catch shape includes option to change the name of the error variable, having the #var.error as the default value. Same option is not available when using Subprocess to call on unhandled error, and there the reference value is always #var.error.
#var.error.Message
The error message as a string. Values entered in Throw shape appear in this field.
#var.error.Type
The type of the exception (e.g., System.Exception).
#var.error.StackTrace
The stack trace at the point where the error occurred.
#var.error.InnerException
If the error was caused by another exception, this contains the inner exception details.
#var.error.TaskName
The name of the Task where the error occurred.
#var.error.TaskId
The ID of the Task where the error occurred.
#var.error.StepName
The name of the Process step.
#var.error.StepId
The ID of the Process step.
#var.error.OccurredAt
The timestamp when the error occurred.
#var.error.Input
The input data for the Task at the time of the error.
#var.error.Output
The output data (if any) before the error occurred.
Last updated
Was this helpful?