Error handling

Content [ Hide ]

When everything works out smoothly, each action completes normally and the workflow is successful. Unfortunately, errors may always happen occassionally, such as when the internet connection is not working, when the server does not have any empty memory left, or when an external service is not available. When you designer a workflow, you should always consider which errors may happen and how you wish to proceed in case they do happen.

This help page explains what happens when an error occurs in the workflow and how you can react to errors.

Error types

The info windows shows a list of all possible errors that may occur when the action is executed.

With very few exceptions, every action can result in an error. Each action can result in different kind of errors. If you want to learn which error can occur, click on the icon to the top right of an action. This open an info window which shows all possible kinds of errors. Errors are categorized into two different types:

  • Hard errors, which are displayed in red. A hard error usually indicates a technical issue, such as a missing internet connection.
  • Soft errors, which are displayed in orange. A soft error usually indicates an issue in the business logic, such as when you access a non-required upload field, but no file was uploaded for that upload field.

For each error, the info window shows the corresponding error code. Hover over the error code to view a short explanation when that error may occur. Later in the workflow, you can use variables to check which kind of error occurred.

In addition to the error codes specific to each action, the following error codes also exist:

GENERAL
This error code is used when an unexpected error occurred during an action, which was not converted into a custom error code by the action itself. This may indicate a programming error, bad data or a severe server issue.
HANDLER_NOT_FOUND
This error is used when the processing logic of an action could not be found. Usually this happens when the workflow contains an action provided by a plugin; and that plugin was either uninstalled or is currently deactivated.

When an error did occur, additional data may be provided by the action with further details regarding the error. Which data is provided depends on the action and the error code. Refer to the info window, which shows all data items for each error code. For example, the HTTP request action lets you access the response code and response message when an error with the code SERVER_ERROR or CLIENT_ERROR occurred.

Error case behavior

Handling errors with an error block. Here, an email is sent to an administrator and the state of the form record is set to Error.

Handling errors with an error event. Here, an email is sent to an administrator and the state of the form record is set to Error.

Handling soft errors with a condition. Here, we check whether a soft error with the code CLIENT_ERROR occurred. If it did, an email is sent to an administrator and the state of the form record is set to Error.

It is important to understand what happens when an error occurred in the workflow. You need to distinguish between soft and hart errors. The following section briefly explains the behavior of the workflow in case of an error.

Hard errors

When an action ends abruptly with a hard error, the action is aborted and a protocol entry with the result Error is created. The protocol entry contains the error code as well as additional info regarding the error. If you did not explicitly set up an error handler, the entire processing chain of the current event is aborted and no more actions are executed. All queued events that would have been executed after the current event are aborted as well; and the entire workflow execution ends in an error. If the workflow was started in response to a user submitting a form, the user is shown the generic error page template. If this is not the desired behavior, you can react to an error in one of the following two ways:

First of all, you can add an error handler block to the workflow. The error block catches all errors that did occur in one of the actions inside the default section on the left-hand side of the error block. Then, if an error did occur, the error block runs the actions in the error branch on the right-hand side of the error block. This way, you can prevent the workflow from getting aborted. Once you have handled an error with an error block, the workflow proceeds with the next action after the error block. Note that in case one of the actions in the error branch of the error block should end in an error, the workflow will be aborted. You can nest error block in case you need to handle errors in the error branch of an error block. Error blocks are useful when you wish to handle a specific error of a certain action, such as when a HTTP requests results in a client error.

Secondly, you can also handle errors via a so-called error event. An error event occurs when a processing chain ends in an unhandled error that would result in the workflow getting aborted. In particular, this means that an error event does not occur when you have already handled an error by means of an error block. Once the processing chain of an error event was processed successfully, the workflow as a whole is considered to have been successful. When a workflow contains more than one error event, each processing chain is processed in order, from left to right. In case the processing chain of an error block ends in an unhandled error, the workflow is aborted and no more error events are processed. Error events are useful when you wish to run a general action in case of an error, such as sending an email to an administrator.

Soft errors

When a soft error occurs, the action is still treated as having been completed successfully. The workflow proceeds with the next action, as if no error had occured. In particular, this means that error block and error events are not processed when a soft error occurs.

In this sense, you can also think of soft errors as warnings that may inform about potential issues about an action. Note that an action can produce more than one soft errror. When an action produces at least one soft error, a protocol entry with the result Warning is created that contains the error code of each soft error, as well as further informtation about each soft error. You can use the variable [%$ActionName.HAS_SOFT_ERROR] to check whether any soft errors did occur. Alternatively, you can use the variable [%$ActionName.SUCCESS] if you are only interested whether a hard of soft error occured.

Variables

You can use of the available variables to check which error occured. The following list contains all error-related variables.

[%$ActionName.SUCCESS%]
Either true or false. Indicates whether an action was successful, i.e. whether neither a hard nor a soft error occured. Usually this variable should suffice, but in case you need to distinguish between soft and hard errors, you can use one of the following variables:
[%$ActionName.HAS_HARD_ERROR%]
Evaluates to true when the action resulted in a hard error; or false otherwise. Hard errors need to be handled explicitly, such as with an error block or error event, and will result in the workflow getting aborted in case they are not handled.
[%$ActionName.HAS_SOFT_ERROR%]
Evaluates to true when the action produced one or more soft error; and false otherwise. A soft error is similar to a warning, the workflow proceeds as normal even if a soft error occurs.
[%$ActionName.SOFT_ERRORS%]
A list with all soft errors that were produced by an action. [%$Aktionsname.SOFT_ERRORS[0]%] is the first soft error, [%$Aktionsname.SOFT_ERRORS[1]%] is the second soft error, and so on. For each soft error, you can access its code (error code), its message (error message) and its data (additional errror data). For example, [%$Aktionsname.SOFT_ERRORS[2].message%] evaluates to the error message of the third soft error, if there are at least three soft errors. To access the number of soft errors, use [%$Aktionsname.SOFT_ERRORS.length()%].
[%$ActionName.ERROR_CODE%]
Evaluates to the error code, in case an action ended in a hard or soft error. When more that one error was produced by an action, evalutes to the error code of the first soft error. For example, the HTTP request action may result in the error codes CLIENT_ERROR and SERVER_ERROR.
[%$ActionName.ERROR_MESSAGE%]
Evaluates to the error message, in case an action ended in a hard or soft error. When more that one error was produced by an action, evalutes to the error message of the first soft error. The error message is usually a short English phrase or sentence that provides further details about the error.
[%$ActionName.ERROR%]
Evaluates to the additional data provided by the error, in case an action ended in a hard or soft error. When more that one error was produced by an action, evalutes to the error data of the first soft error. Which data is available depends on the action and the error code. Refer to the info window of an action for a list of data provided for each error code. For example, the HTTP request action lets you access the response code via the variable [%$ActionName.ERROR.responseCode%], in case the action ended with the error code SERVER_ERROR or CLIENT_ERROR.
[%$LAST_ERROR_CODE%], [%$LAST_ERROR_MESSAGE%] and [%$LAST_ERROR%]
Evaluates to the error code, message, or additional error data of the most recent hard error. This is especially useful when used inside an error block, as it lets you access the error without having to refer to the name of a particular action. You can also use this variable within an error event.
[%$LAST_ERROR_NODE_NAME%] and [%$LAST_ERROR_NODE_TYPE%]
Evaluates to the name and technical type of the most recent action that resulted in a hard error.