Exception Handling in Automation Studio

This topic explains how exceptions are handled in Automation Studio.

Automation Studio differentiates between two exception types. Each type is handled differently:

Caught Exceptions

A caught exception is a non-runtime exception for which an exception handling mechanism is provided (using a try-catch block).

The built-in functions in Automation Studio handle all foreseen exceptions. Functions created externally by developers in services (SDKs) should also include try-catch blocks, but that is not mandatory.

Examples of Caught Exceptions

  • When using the Divide Numbers function in the Math built-in service, division by zero is a caught exception.

  • When using the Write Text to File function in the File built-in service, specifying a file directory that does not exist is a caught exception.

Handling

When a caught exception occurs:

  • A message is written to the Real-Time Client log file (RTClient.log).

    2021-07-13 16:31:58,908 [Direct Logic Thread] ERROR LibraryObjects - Math_Functions.DivideIntegers - dividing by zero.

  • The automation solution continues to run. The next function after the function that caused the exception will be executed.

  • No event is triggered as a result of the exception.

Example Project

This example project displays a callout as shown below.

When the user clicks the Set Variables button, a workflow is executed. The workflow sets the value of the three variables. The workflow performs the following actions in a single step:

  • Sets a to 42.2.

  • Sets b to the result of 30 divided by 0 using the Divide Numbers built-in function.

  • Sets c to 3.14.

When the workflow is executed, the variables' values are displayed in the callout:

Note that:

  • Variable a is set to 42.2, as expected.
  • Variable b is set to 0. The built-in try-catch block in the Divide Numbers function caught the divide-by-zero exception and returned a null value.
  • Variable c is set to 3.14. Note that the function that sets the value of c was performed even though the previous function caused an exception. That is because the exception caused was a caught exception.

An error is written to the Real-Time Client log file:

2021-07-13 16:31:58,908 [Direct Logic Thread] ERROR LibraryObjects - Math_Functions.DivideIntegers - dividing by zero.

Uncaught Exceptions

An uncaught exception is a non-runtime exception for which no exception handling mechanism (try-catch block) has been provided.

Example of an Uncaught Exception

  • The developer creates a service (SDK) that includes a function that copies files to a specified directory. If that directory is unavailable during run-time, an uncaught exception will occur (unless the developer included a try-catch block to handle it).

Handling

When an uncaught exception occurs:

  • No error message is written to the Real-Time Client log.

  • Any functions following the function that caused the exception are not executed.

    In user-defined functions, event handlers, and callout control events, all functions following the function that caused the exception are not executed.

    In a workflow, all functions that follow the function that caused the exception in the same workflow step are not executed. The solution will progress instead to the transition exiting that workflow step.

  • The Exception Occurred event in the Error Handling built-in service is triggered. Details about the exception are written to the event's Exception parameter.

Example Project

This example project displays a callout as shown below.

When the user clicks the Set Variables button, a workflow is executed. The workflow sets the value of the four variables.

The workflow performs the following actions in its first step:

  • Sets a to 42.2.

  • Sets b to the result of 30 divided by 0 using a function that a developer added to a service (SDK) that was imported into the project. The function is called Divide by Zero and divides any specified number by zero. The developer did not provide a try-catch block for that function.

  • Sets c to 3.14.

The workflow performs the following action in its second step:

  • Sets d to 53.

When the workflow is executed, the variables' values are displayed in the callout:

Note that:

  • Variable a is set to 42.2, as expected.
  • Variable b was not set. Because the Divide by Zero function caused an error, the value of b was not set.
  • Variable c was not set. The function that sets c was not performed because it is located after the Divide by Zero function in the same workflow step.
  • Variable d was set to 53. Because the function that sets d is not in the same step as the Divide by Zero function, it was performed normally.

The project also includes an event handler that is triggered by the Exception Occurred built-in event.

The event handler populates a second callout with the data collected by the Exception Occurred event in its four event properties.

As soon as the Divide by Zero function is executed, the event handler populates and displays this callout.

Note that:

  • The Catching Item Display Name property is set to the name of the workflow step in which the error occurred.

  • The Description property gives the name of the service (SDK) that caused the error.

  • The Name property returns GeneralException as no further information is available.