Try / Catch

Try / Catch

Type: try-catch  ·  Package: Core Activities v1.0.8

Runs a block of activities and, if any of them fails, instead of stopping the whole execution, jumps to an alternative block where you can react: log the error, notify, or follow a plan B. It is the key tool to make your automation robust against the problems you know can happen (a page that doesn’t load, a file that doesn’t exist, a system that sometimes fails).

It has three blocks: try (what you attempt), catch (what to do if it fails) and finally (what always runs, no matter what).

How it works

1. Runs the try activities.
2. If they all succeed, it skips the catch.
3. If any fails, it stops the try at that point, stores the error in errorVariable (if you set one) —a ZoanError object with the details of the exception— and runs the catch block.
4. At the end, it always runs finally —whether there was an error or not— ideal for releasing resources (closing a browser, a connection).

After the catch, execution continues normally with whatever comes after the Try/Catch: the error was “caught”. Details worth knowing:

• An empty catch also catches the error: the flow goes on as if nothing happened. Use it only if you really want to ignore the failure, and leave at least a Log.
• An error inside the catch or the finally is not caught by this same Try/Catch: it goes up to the next one that contains it, or makes the execution fail.
• To throw the error again after logging it, use Throw with message = error.Message and errorType = error.Type.

Required parameters

None. (The only mandatory block is the try sub-flow.)

Optional parameters

Parameter	Type	Default	Description
errorVariable	string	—	Name of the variable that receives the caught error, of type ZoanError. In the catch, access .Message, .Type, .Source and .StackTrace. You don’t need to declare it; if you declared it as text (string), it receives only the message.

Sub-flows

try required

Activities to attempt. If one fails, the rest of the try does not run.

catch optional

Activities that run only if something in the try failed.

finally optional

Activities that always run, whether the try failed or not. Also if someone terminates the execution (Terminate in Zoan Cloud, the Designer or the Agent): the finally has 10 seconds to close what is open, so it is the place to close the application or the browser. If it doesn’t finish in that time, a warning is left in the log and the execution ends anyway.

Output

This activity does not return a value. The caught error is stored in the errorVariable variable:

Property	Content
.Message	The error message.
.Type	The type: the errorType of a Throw (PlaybookException by default, BusinessRuleException for business errors) or the name of the system exception (TimeoutException, HttpRequestException…).
.Source	The component where it originated.
.StackTrace	The trace, for diagnosis.

If the error comes from an invoked playbook or process, ZoanError shows the original error, not the invocation’s wrapper.

Example

Try to read an Excel file; if it fails, log the error and continue; and close the workbook no matter what:

Try / Catch   errorVariable = error
 ├─ try:
 │    Excel Open        path = asset("data.xlsx")   → output: workbook
 │    Excel Read Range  excel = workbook   range = "A1:D100"   → output: table
 ├─ catch:
 │    Log   level = error   message = "Could not read the Excel file (" + error.Type + "): " + error.Message
 │    Set Variable   name = table   value = newDataTable()    // default value
 └─ finally:
      Excel Close   excel = workbook

errorVariable is a ZoanError object

Treating it as text still works: error or "Error: " + error use the message, so playbooks that already read it as a string don’t break. Use error.Type to tell errors apart and branch the catch.

Try/Catch vs Retry

• Use Try / Catch when you want to handle an error and continue with an alternative plan.
• Use Retry when the error is transient (a slow website, the network) and trying again is enough.

You can combine them: a Retry inside a Try/Catch retries first and, if it still fails, the catch handles the situation.

Cancellations and break/continue are not errors

If you terminate the execution from the portal, or use Break/Continue inside the try, they are not treated as errors: the catch does not fire. The finally, however, does run.

Timeouts are errors

When an activity runs out of time on its own (a web service that does not answer, an application that does not respond, the activity’s own timeout), it fails with a normal TimeoutException error that the catch catches and Retry retries. The message names the activity. Only terminating the execution, or the playbook’s time limit, are still cancellations. Since version 1.2.29.

Common errors

Message	Cause and fix
Finally did not complete after the execution was terminated: …	Warning: the execution was terminated and the finally did not finish within 10 seconds (or failed). Keep only quick cleanup in the finally.
The error gets “lost”	The catch is empty and there is no errorVariable: the failure is caught without a trace. Log the error with a Log or throw it again with Throw.

Related activities

• Retry — automatically retry a block that fails.
• Throw — throw an error on purpose (which an outer Try/Catch can catch).
• Log — log the error caught in the catch.