Error handling

Error handling in xFlow is a critical feature that allows developers to manage and respond to exceptions that may occur during workflow execution. Here's how error handling is implemented in xFlow:

Error Handling Mechanism

xFlow utilizes the Serverless Workflow specification to provide a robust error handling mechanism. This system allows workflows to respond to exceptions gracefully and ensures the continuation of the workflow process whenever possible.

Error Events and Transitions

When an error occurs within a workflow, it triggers a transition to an alternative state designed to handle that error. This transition deviates from the typical flow and acts similarly to a try-catch block in traditional programming or a goto statement, redirecting the process to a specified error-handling routine.

Error Definition Structure

Error handling definitions in xFlow consist of the following elements:

• Name: A descriptive label for the error, used for easy identification by developers.

• Code: A unique identifier used by the xFlow engine to map the error to a runtime exception.

Error Handling Strategies

xFlow supports multiple strategies for mapping errors to runtime exceptions:

• Fully Qualified Class Name (FQCN): Maps the Java exception class name to an error definition.

• Error Message: Uses regex patterns to match part of the error message thrown by an exception.

• Status Code: Associates an error with the status code returned by an invoked service.

Error Handling Examples

Below are examples illustrating how to define error handling in xFlow:

• Runtime Exception: Matches a Java exception to an error code.

• Error Message: Matches a partial error message using regex, supporting both case-sensitive and case-insensitive patterns.

• Status Code: Matches the error code against a status code returned from an external service.

Workflow Example

The checkEven state in a hypothetical xFlow workflow might look like this:

{
  "name": "checkEven",
  "type": "operation",
  "actions": [
    {
      "name": "checkEvenAction",
      "functionRef": {
        "refName": "isEven",
        "arguments": {
          "number": "${.number}"
        }
      }
    }
  ],
  "transition": "even",
  "onErrors": [
    {
      "errorRef": "odd number",
      "transition": "odd"
    }
  ]
}

Here, a function isEven is defined to invoke a Java method. In case of an error, the workflow transitions to an odd state to handle the exception.

Error Definition

The error definition could be as follows, allowing any RuntimeException to be caught and handled:

"errors": [
  {
    "name": "odd number",
    "code": "java.lang.RuntimeException"
  }
]

State Injection

The even and odd states use the Inject state to set the response message accordingly.

Final State

The finish state concludes the workflow execution and outputs the result, which verifies the message has been set as expected.

Conclusion

xFlow's error handling is designed to be flexible and comprehensive, ensuring that workflows can be robust against unexpected conditions. By leveraging the Serverless Workflow specification, xFlow allows for complex error handling scenarios that are essential for resilient workflow execution.

Additional Resources

For detailed examples and further reading on error handling within the xFlow system, please refer to the official Serverless Workflow specification on error handling strategies and configurations.