Try/Catch step

Overview

The Try/Catch step captures process-level or document-level errors for one or more documents that fail during execution. You must place the Try/Catch step before the main processing steps in your process.

The Try/Catch step sends documents down the Try path to be processed. Documents that fail are caught and sent down the Catch path.

The Try/Catch step allows you to design advanced logging and error handling for failed documents because the original documents and their properties are sent down the Catch path. You can also capture the exception message and include it in logs or notifications using the parameter reference: Document Property → Meta Information → Base → Try/Catch Message.

The goal of the Try/Catch step is to prevent process-level failures when a document fails, so that you can handle or act upon those failures later in your process flow.

note

The Try and Catch paths are executed in separate execution threads. For any failed documents, the Try path is always executed first, followed by the Catch path.

Adding a Try/Catch step to a process

1. Add the step

• Drag the Try/Catch step to your process canvas.
• The Try/Catch step dialog opens.

2. Configure General Settings

   Field	Description
   Display Name	Enter a descriptive name. If left blank, the step displays as “Try/Catch.”
   Retry Count	Specify how many times a failed document retries (0–5).
   Failure Trigger	Choose what type of errors the step catches: Document Errors (default) or All Errors.

3. Retry Count Behavior

In the Retry Count field, enter a numeric value (from 0 to 5) to specify the maximum number of times a failed document can retry through the main series of steps after the Try/Catch step.

Retry Count	Retry Behavior
0	The document is not retried. You can handle the failure in other ways (e.g., archive, email alert).
1	Retry occurs immediately after the first failure.
2	Waits 10 seconds before retrying.
3	Waits 30 seconds before retrying.
4	Waits 60 seconds before retrying.
5	Waits 120 seconds before retrying the final time.

note

The Try/Catch step does not perform auto-retries in Test Mode.

4. Failure Trigger Options

   In the Failure Trigger field, select one of the types of errors that the Try/Catch step catches:

   Option	Description
   Document Errors (default)	Captures document-level errors such as connector or mapping issues.
   All Errors	Captures both document-level and process-level errors.

   Captured and Uncaptured Errors

   Always captured (regardless of Failure Trigger):

   • Connector errors for specific documents (e.g., invalid ID during update)
   • Exception step with Stop Single Document enabled
   • Map step with no output, validation errors, or connector errors

   Not captured when set to Document Errors: (To capture these, set Failure Trigger to All Errors.)

   • NullPointerExceptions or similar process-level errors
   • Exception step with Stop Single Document disabled
   • Connectors that throw process-level exceptions instead of logging per-document errors

5. Add notes in the Notes tab. a. Enter a Title.
   b. Enter the note content in the Note field.

6. Click OK.

Behavior in multi Try/Catch scenarios

Configuration	Behavior
Single Try/Catch (Document Errors)	Catches only document-level errors.
Single Try/Catch (All Errors)	Catches both document and process-level errors.
Two consecutive Try/Catch steps	The outer step catches all errors (document + process), regardless of its Failure Trigger. The inner step follows its own Failure Trigger setting.
Two Try/Catch steps separated by other steps (post–Aug 2015 behavior)	Each Try/Catch step behaves according to its own Failure Trigger setting.

note

To revert to pre–August 2015 behavior, change the outer Try/Catch step’s Failure Trigger to All Errors.

Examples

Example 1: Tracking document errors

The Try/Catch step tracks document-level errors by setting Failure Trigger = Document Errors.
If an HTTP Client operation fails (e.g., invalid request), the failed source document is sent down the Catch Error path.

Because the Try/Catch step is positioned before a Flat File to XML Map, the failed document is passed as flat file data.

You can reference the error message using:

• Document Property → Meta Information → Base → Try/Catch Message

To notify users, add this parameter to a Message or Notify step.
You can also include a Flat File Profile Element lookup (such as a record ID) to identify the specific document that failed.

Example 2: Using Try/Catch with sub-processes

In this example, a Try/Catch step at the beginning of the parent process captures errors from a subprocess.

The Process Call step is configured with:

• Wait for process to complete: ON
• Abort if process fails: OFF

If the Try/Catch step were inside the subprocess, it would capture errors only from within that subprocess.

Behavior based on Process Call settings

Setting	Behavior
Abort if process fails = Off	Subprocess failures are tracked at the document level and sent down the parent Catch path.
Abort if process fails = On	Failures are tracked at the process level, and the parent process fails at the subprocess.
Wait for process to complete = On	Parent waits for subprocess to finish before continuing; behavior depends on Abort setting.
Wait for process to complete = Off	Parent does not wait for subprocess; errors in the subprocess are not returned to the parent. The parent only catches its own errors.