Workflow Error Handling

Most workflow tasks let you decide how any errors they encounter will be handled.

There are three options: ignore the error, follow an outgoing sequence flow from the task that generated the error, or throw a BPMN error which can be caught by an error handling sub-process or event. It's also possible to throw errors using the End Error Event.

Note that this error handling relates to error responses returned from activities, not configuration errors in the task itself.

In the following examples there's an API Server task making a call to an iCM End Point. The End Point has been misconfigured and always returns the following error:

{
    "jsonrpc": "2.0",
    "id": 25,
    "result": {
        "id": "_82",
        "error": {
            "message": "Method not found",
            "code": -32601
        },
        "jsonrpc": "2.0"
    }
}

Throwing Errors

By default, tasks ignore any errors they encounter; outgoing sequence flows are followed as if the error hadn't occurred.

Following Error Transitions

In this example the API Server task has a default sequence to follow (to the right) and an additional error sequence flow to handle the error. The Error Handling property has been set to "Follow Error Transition".

On the Advanced tab of the API Server task, the ID of the upward flow has been added to the Error Transition property (another good reason why it's good practice to enter IDs for your elements rather than use the randomly generated ones inserted by the workflow engine on deployment).

Now, when the error returns, the upward sequence flow will be followed.

Throwing BPMN Errors

The third option in the Error Handling property is to "Throw BPMN Error". The error thrown can be caught by an event sub-process or a boundary error event (see Catching Errors below).

The name of the error that is thrown is defined on the Advanced tab of the task that generates the error.

Error End Events

There may be times when throwing errors directly from a task isn't appropriate. This could happen if you need to handle a range of responses, many of which should be considered as errors, or if the error occurs as part of a sub-process.

In this example a call to another service has been defined in a sub-process.

The default flow from the API Server task ends the sub-process. Should an error occur the Error End Event will throw an error, the sub-process will end, and the the error will be caught by the boundary error event.

The name of the error that is thrown by the end event is set in its Error Reference property.

Catching Errors

There are two ways to catch errors. Boundary error events are attached to tasks and sub-process, catching the errors that they throw. Error start events listen out for errors with a particular reference, and are used to start error handling event sub-processes.

Boundary Error Event

Boundary error events can be attached to tasks or sub-processes. If an error occurs, the attached event will catch it. Even though the event is attached to the element, you still need to set up the error names in the advanced tab of the element and error reference in the event.

In this example, an error returned from the API Server task will cause the upward path to be followed.

When an error event is caught, the activity on which the boundary event is defined is destroyed, also destroying all current executions within it (concurrent activities, nested sub-processes, etc). The process execution follows the outgoing sequence flow of the boundary error event.

Error Start Events

BPMN errors thrown by tasks and error events can start an event sub-process.

In this is example, the API Server task throws an error called MyError. When this error is thrown the workflow engine halts the main process flow.

The error start event in the event sub-process is listening for MyError (it's message reference looks just like the reference thrown by the error end event), and will start the event sub-process when it is received.

In this example, once the event sub-process completes, the whole instance will end.

The advantage of this type of error handling is that a single event sub-process could be used to handle all of the errors thrown from all of the activities in your model (assuming they all throw the same error).

Error Information

When an activity generates an error, the content of the error message is saved as a process variable. You can set the name of this process variable on the "Main" tab of the activity:

The default name for this variable is APICALLERROR, but you can call it whatever you want (and will probably want to create different error variables for different tasks).

Error process variables can be used just like any other. The structure of the message object will vary, depending on the type of error. Exceptions encountered by the workflow include an exceptionMessage:

{
  "errorType": "ClientException",
  "exceptionMessage": "An error occurred while attempting to send the email(s). Error Message: [An error was returned from the Email worker: [Failed to send [1] message(s). Reasons: [Unknown SMTP host: fake\n]]] ExecutionId: [142693]",
  "exceptionClass": "class org.apache.commons.mail.EmailException"
}

A successful call to an End Point, but the End Point itself returning an error, includes a message which is the error returned by the End Point.

{
  "errorType": "Application Error",
  "code": "-32601",
  "message": "Method not found"
}