Throw

Sometimes things do not go the way they are expected to, and preparing for the unexpected to happen is a requirement to handle errors effectively, before they can cause problems. Throw shape is used to raise an error from a situation where execution should be interrupted and an error handling path should be taken instead.

What is Throw?

Throw shape is used to interrupt Process's usual execution path by raising an error. If the thrown error is not caught within the Process, the whole Process execution will stop there. Subprocess to call on unhandled error can catch and handle the error if set for the Process, but this will be after the Process execution has already ended in error.

Throw is an alternative shape to use to end a Process, like Return shape. Process executions that end with Throw shape will be logged as errors in the Pprocess Instance list.

If used in an HTTP or API process and the error is not caught within the Process, the error message will be sent back to the caller as erroneous response. Like in Return shape, the HTTP response can be configured as required.

If used in a Subprocess and the error is not caught within it, the error will be raised as error in the calling Process as well. Using Subprocess to call on unhandled error will trigger the error handling Subprocess, but will not stop the propagation of the error.

If the thrown error is caught within the Process using Catch shape, Process will continue on its original execution path after processing the error within the Catch scope.

Types of Throw configurations

Being an alternative shape to Return shape, Throw shape has the same types and configuration settings available as the Return shape. You can view the details for type options here.

Usage

Throw shape can be used to end a Process path execution for the whole Process execution, or within a container shape. It is alternative shape to finish a process flow, like Return shape, but the Process execution will be logged as error instead of success. When used within an iteration container shape, like Foreach or While, the iteration will end immediately.

To use Throw shape, add it to your Process canvas where you would like to the usual Process flow to be interrupted. Connect the shape to your Process so that it ends a path in your Process. If the intention is to interrupt the normal Process flow, you can use Exclusive Decision to determine if the error should be thrown, and then have Throw shape connect to the Decision shape. Once added to the Process, you can click on the shape to configure its options.

When Throw shape is used, an error message value can be provided in its configuration options. The value can be either a string value or more complex object, that usually includes the reason why an error was raised.

Architecture

When used to provide a response to HTTP or API caller, if the connection between Frends and the caller is still open, the connection will be closed once the response is sent back. In case the connection has closed before the response could be sent, because of connection error, timeout or through the usage of Intermediate Return shape, the HTTP response cannot be sent back to the caller.

Execution of a Throw shape at the end of a Process will signal the Frends platform that the Process execution has ended, and it ended with error. If the log settings and shape configuration allows it, the result is saved as the Process execution's error details into the logs.

Uncaught errors from Processes and Subprocesses are also logged to Agent's logs as errors.

Configuration

Being an alternative shape to Return shape, Throw shape has the same types and configuration settings available as the Return shape. You can view the details for configuration options here.

Reference values

While Throw shape does not provide direct reference values to use, when used in combination with Catch shape or with Subprocess to call on unhandled errors, the error values provided in Throw shape can be accessed through #var.error reference variable by default.

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.