Skip to main content
Version: Current

Custom Error Handlers

Overview​

Custom Error Handlers allow you to build activity-specific error handling flows directly within the workflow designer.

When an activity encounters a runtime error, execution can be redirected to a dedicated error path where corrective actions, notifications, logging, auditing, or recovery logic can be performed.

Unlike standard On Error policies, which define generic behavior such as Fault, Continue, Retry, or Suspend, Custom Error Handlers provide complete control over how individual activity failures are processed.

Availability​

Custom Error Handlers are available for most workflow activities.

Some lightweight activities, such as primitive activities, may not currently support Custom Error Handlers.

Enabling a Custom Error Handler​

Custom Error Handlers are configured directly from the workflow designer canvas.

  1. Right-click the activity.
  2. Select Custom Error Handler.
  3. An additional Error output port is added to the activity.
  4. Connect the error port to the activities that should execute when an error occurs.

The error connector is displayed in red to visually distinguish error-handling paths from normal execution paths.

Designer Example​

In this example:

  • Successful execution follows the normal workflow path.
  • Failed execution follows the error path.
  • The error-handling activities can perform notifications, remediation, logging, or recovery actions.

Error Execution Flow​

When an activity encounters an error:

  1. Normal execution of the activity stops.
  2. The workflow captures error information.
  3. The configured error path is invoked.
  4. The error-handling activities receive access to the error context through the ErrorHandler object.
  5. Execution continues through the configured error flow.

Activities that do not have a Custom Error Handler continue to use their configured On Error strategy.

Error Handler Category​

Activities executing within a custom error-handling path automatically receive access to the Error Handler category in the Data panel.

The Error Handler category contains a single object named Activity Error that provides detailed information about the activity failure.

Error Handler
└── Activity Error
    ├── Source
    ├── Exception
    ├── Context
    └── Inputs

The Activity Error object is automatically populated when the error path is triggered.

Source​

The Source object identifies the activity that generated the error.

FieldDescription
Activity IDUnique identifier of the activity definition.
Activity Instance IDUnique identifier of the activity execution instance.
Activity TypeType of activity that generated the error.
Activity NameInternal activity name.
Activity Display NameDisplay name configured in the workflow designer.
Node IDDesigner node identifier for the activity.

Exception​

The Exception object contains details about the actual error.

FieldDescription
MessageError message generated by the activity.
TypeException type.
Stack TraceStack trace when available.
SourceSource component that generated the exception.

Context​

The Context object contains workflow execution information.

FieldDescription
Occurred AtUTC timestamp when the error occurred.
Workflow IDWorkflow definition identifier.
Workflow Instance IDWorkflow execution instance identifier.
Automation IDProcess instance identifier associated with the execution.

Inputs​

The Inputs object contains the input values that were provided to the activity when the error occurred.

Unlike the other sections of the Activity Error object, the structure of Inputs is dynamic and depends on the activity that generated the error.

This information can be used to:

  • Diagnose failures
  • Audit processing
  • Reconstruct execution context
  • Generate detailed notifications
  • Implement recovery logic

Example:

Error Handler.Activity Error.Inputs.FilePath

The available properties depend on the activity type and the inputs configured for that activity.

Typical Usage Scenarios​

Custom Error Handlers are commonly used for:

Sending Notifications​

Notify support teams when critical activities fail.

Send Email
    Subject: Activity Failed
    Body: ErrorHandler.Exception.Message

Creating Incidents​

Create incidents in external systems with detailed failure information.

Audit Logging​

Record error information for compliance and troubleshooting.

Recovery Actions​

Execute compensating activities to restore a consistent system state.

Escalation Workflows​

Route critical failures to different teams based on the activity type or exception details.

Best Practices​

  • Use Custom Error Handlers only for activities that require specialized handling.
  • Keep error flows focused and easy to understand.
  • Include logging for all critical failures.
  • Use the ErrorHandler object rather than hardcoded messages.
  • Avoid exposing stack traces directly to end users.
  • Use the Inputs object when detailed diagnostics are required.
  • Combine workflow-level error handling and Custom Error Handlers to create layered recovery strategies.