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:
| Value | Behavior |
| 1 | Raise the exception and stop execution |
| 2 | Ignore the exception and continue |
Example:
value = 2; // ignore exceptionWhat 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.
| Name | Class name / JavaDoc |
|---|---|
| etlConfig | com.toolsverse.etl.core.config.EtlConfig |
| scenario | com.toolsverse.etl.core.engine.Scenario |
| exception | java.lang.Exception |
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.