Workflow Editor: On Exception and Failure Handling

Overview

Etlworks allows workflows to define custom logic that executes when an error occurs.

Exception handling can be configured in two places:

• For the entire workflow 
• For an individual step or transformation

Both mechanisms use the same JavaScript-based handler and follow the same execution rules. The difference is where the handler is configured and which failures it handles.

Exception handlers allow you to:

• Log errors 
• Perform cleanup actions
•  Decide whether execution should stop or continue 
• Control behavior during loops or nested workflows

Workflow-Level Exception Handling

A workflow can define a handler that executes when the workflow fails.

This handler is configured in the On Exception tab of the workflow itself.

The handler is triggered when an unhandled exception occurs during workflow execution.

This is commonly used to:

• log workflow failures 
• notify external systems 
• perform cleanup actions 
• decide whether to ignore the error or propagate it

If the workflow itself is used as a step inside another workflow, the exception handler controls how the failure is propagated to the parent workflow.

Step or Transformation-Level Exception Handling

Exception handlers can also be configured inside a flow step or individual transformation.

These handlers are configured directly in the flow or transformation settings.

They allow handling errors that occur inside a specific step without affecting the entire workflow.

Typical uses include:

• ignoring specific transformation
• errors logging errors for individual records 
• implementing custom recovery logic

Detailed configuration for these handlers is described in:

Handle exceptions in the flows and in the transformations

How Exception Handlers Work

When an exception occurs, the configured handler is executed.

The handler is implemented using JavaScript.

The script must set the variable value to control how execution proceeds.

Possible values:

Example:

value = 2; // ignore exception

What Happens When an Exception Is Ignored

When an exception handler sets value = 2, the error is ignored and execution continues.

The behavior depends on where the error occurred.

If the error occurs in the main workflow

The workflow finishes with status success.

The ignored error is recorded in the workflow log.

If the workflow runs inside another workflow

Execution continues in the parent workflow.

The ignored error is recorded in the workflow log.

If the step runs inside a loop

The current iteration stops and the next iteration begins.

The error is recorded in the workflow log.

Available Variables in Exception Handlers

The exception handler script can access the following objects.

Example Exception Handler

The following example logs the exception to a database table and ignores the error.

importPackage(com.toolsverse.etl.sql.util);
importPackage(com.toolsverse.config);
importPackage(com.toolsverse.util);
var con = etlConfig.getConnection("log");
var props = SystemConfig.instance().getProperties();
var fileId = Utils.str2Int(props.get('fileid'), 0);
var error = exception != null ? Utils.getStackTraceAsString(exception) : null;
var fileSql = "update etl_feed_file_log set ended = CURRENT_TIMESTAMP, error = ? where fileid = ?";
try {
   SqlUtils.executeSql(con, fileSql, error, fileId);
} catch (err) {
   // already logged
}
value = 2;

This handler:

• Retrieves a database connection. 
• Extracts workflow properties. 
• Converts the exception stack trace into text. 
• Writes the error to a log table. 
• Ignores the exception and allows execution to continue.

Error Pipelines

In addition to exception handlers, a workflow can execute a separate flow when an error occurs.

This is commonly called an error pipeline.

An error pipeline is a normal workflow that runs only when another step fails. It does not handle the exception directly and cannot ignore the error. Instead, it allows you to run a multi-step recovery or notification process after a failure occurs.

Typical uses include:

• sending notifications when a workflow fails 
• writing failure information to audit tables 
• performing cleanup actions 
• triggering recovery workflows

Unlike script-based exception handlers, an error pipeline can contain multiple steps and its own internal logic.

Configure an Error Pipeline

To configure a workflow to run when an error occurs:

1. Create a workflow that will be executed when an error occurs. 

2. Add the steps required to handle the error (logging, notifications, cleanup, etc.). 

3. Open the Flow Control tab. 

4. Enable Execute if Error. 

5. Add this workflow as a step in the main workflow.

When an exception occurs anywhere in the main workflow, the configured error pipeline will execute.

Using Error Pipelines Across Workflows

A single error-handling workflow can be reused in multiple workflows.

The same error pipeline can be added as a step in multiple workflows and will execute whenever a failure occurs in those workflows.

This allows centralized error handling logic across multiple pipelines.

Summary

Etlworks provides multiple mechanisms for handling failures in workflows.

Failure handling can be implemented using:

• Exception handlers that run JavaScript code when an error occurs 
• Step or transformation exception handlers inside individual flows 
• Error pipelines that execute a separate workflow when a failure occurs

Exception handlers allow fine control over whether execution continues or stops.

Error pipelines allow running additional steps such as logging, cleanup, or notifications after a failure.

Together, these mechanisms provide flexible and controlled failure handling for complex workflows.

Read Next

• Retry Patterns and Resilient Workflow Design