Catch Step
Since version 26.2.0 the Catch step no longer supports the legacy catch behavior (the ENABLE_LEGACY_CATCH_BEHAVIOR flag has been removed). The behavior described on this page is the current one; the two points below explain how it differed from the legacy behavior.
Where the Catch step ran. The current Catch step runs in its own position, following the normal step execution order — it catches errors thrown by the steps executed before it. The legacy behavior instead checked for errors after every step and, when an error occurred, scanned the flow for a Catch step and executed the first one it found regardless of its position, so the Catch step did not have to come after the failing step. It only skipped Catch steps placed before the step that failed.
What happened to the caught errors. The current step copies the errors onto the doc object (errors property by default) and clears them from the flow execution context, so they remain available on doc. The legacy behavior exposed the errors under errorPath only inside the sub-flow's doc and then removed them once the Catch step finished.
If you relied on the legacy behavior, review your flows: remove the existing Catch steps and add them back in the correct positions so errors are caught as expected. A Catch step handles errors from the steps that precede it, so place it after the step whose errors it should handle — or after a Mixed step to handle errors from the whole invoked flow.
Overview
Catch step is used to catch errors in previous step block execution.
Errors are copied to the doc object (errors property by default) and are cleared from flow execution context.
If errors are not caught, then ACE continues with error processing as described here.
If error is caught it can stop further execution of the flow and will execute a selected sub-flow in order to deal with the error.
Configuration
Stop execution (stopExecution)
If checked the further flow execution will be stopped, otherwise the flow will continue with the next step after catch step.
Flow name (mixedFlowConfig.flowId)
Select a flow you wish to execute when an error is caught (e.g. flow that returns some generic error information, logs the error in custom way)
Flow payload path (mixedFlowConfig.payload)
Path in doc to send as payload to catch flow.
If not specified the whole doc will be sent to the catch flow
Target path (mixedFlowConfig.targetPath)
Path in doc to store the flow result (original flow target if not defined).
Errors object path (errorPath)
Default errors
doc key in which execution errors are passed to catch flow.
Examples
Example 1
Let's build a sample flow on top of the Schema Validator step where we want to stop flow execution in case the validation fails.
It will consist of 3 steps:
Schema Validator- that will validate thedocinputJSON Clean- that will remove the input valuesCatch- that will stop execution of further steps if previous step throws an error (so JSONATA Step will not be executed)JSONATA Mapthat will add a node on thedocresultnode showing the successful execution of flow
As well as a sub-flow - that will be executed if Catch Step throws an error (it will add property result that equals error)
Catch Step configuration
checkbox- checked to stop the flow executionflow name- exampleReturnResultErrorflow payload- emptytarget path- result
Sample flow
tags: []
steps:
- stepType: ajv
config:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: http://example.com/example.json
type: object
title: The root schema
description: The root schema comprises the entire JSON document.
default: {}
examples:
- name: John Smith
required:
- name
properties:
name:
$id: "#/properties/name"
type: string
title: The name schema
description: An explanation about the purpose of this instance.
default: ""
examples:
- John Smith
additionalProperties: true
dataPath: body
targetPath: result
error: true
name: Schema Validator
description: ""
condition: ""
- stepType: clean-object
config:
paths:
- removePath: '"{{body}}"'
name: JSON Clean
description: ""
condition: ""
- stepType: catch
config:
stopExecution: true
mixedFlowConfig:
flowId: exampleReturnResultError
targetPath: result
name: Catch
description: ""
condition: ""
- stepType: jsonata
config:
maps:
- mergeArrayItems: {}
jsonata: '{ "result": "success" }'
targetPath: result
name: JSONATA Map
description: ""
condition: ""
sampleData:
body:
name: 123
The sub-flow contains just a simple JS Code step that assigns value "error" to variable result
tags: []
steps:
- stepType: code
config:
codeBlock: result = "error"
targetPath: result
name: JS Code Functions
description: ""
condition: ""
sampleData: {}
Example 2
Let's build a sample flow that resembles real life use situation
In this flow we use Rest Http step that retrieves data from server
In case where no data is retrieved error is thrown
Catch step catches this error and executes subflow provided to the catch step
in this subflow we use error handling to provide end result of the flow
otherwise api will return error thrown by Rest Http step
Subflow could also be used to generate data needed for main flow but then error handling need to be used in the main flow
tags: []
steps:
- stepType: rest-new
config:
endpoint:
url: https://62851a5c3060bbd34744c103.mockapi.io/test/{{id}}
restRequest: JSON
expectedResponseLocation: body
oAuthConfig: {}
json: {}
targetPath: result
disableHeadersInKey: false
name: REST Http
description: ""
condition: ""
- stepType: catch
config:
stopExecution: true
mixedFlowConfig:
flowId: catchStepSubFlowExample
errorPath: testy
name: Catch
description: ""
condition: ""
- stepType: jsonata
config:
maps:
- mergeArrayItems: {}
jsonata: '{ "result": "success" }'
targetPath: result
name: JSONATA Map
description: ""
condition: ""
sampleData:
id: 51
tags: []
steps:
- stepType: jsonata
config:
maps:
- mergeArrayItems: {}
targetPath: result
jsonata: |-
{
"errorHandler": true,
"errorResponse": {
"statusCode": 404,
"response": "Some other response message"
}
}
name: JSONATA Map
description: ""
condition: ""
sampleData: {}