Error Handling in Microflows

Introduction

In a microflow, microflow elements (activities, decisions, or loops) can sometimes fail and produce an error. If you do nothing, Mendix reports the error with a system error message and roll back all the changes. However, you can also change this behavior and handle errors yourself.

This document introduces different error handling options in microflows and explains how they work using simple examples. An example of how combined custom error handling works is also given in An Example of Combined Error Handling.

This document also presents information on how you can inspect errors using predefined error objects and the best practices for working with error handling in microflows.

Error Handling Options

There are four error handling options:

• Rollback (default)
• Custom with rollback
• Custom without rollback
• Continue

In summary, the four error handling options do the following:

Except for the Rollback option, which is the default, the other three are all custom error handling options.

For Custom with rollback and Custom without rollback, you can create an additional flow from the microflow elements (activities or decisions) from which the error is returned and mark this flow as an error handling flow. You can end this flow with an error event or an end event. Hence, we introduce these two custom error handling options based on what event terminates the error handling flow.

It is important to know that when a microflow is started by an end-user (for example, by clicking a button), a savepoint is always created at the very beginning of the microflow. This is the case for Microflow 1 in all the following examples. Knowing how savepoints are created and function is key to understanding how error handling works.

In the following subsections, we introduce the functionality of each error handling option using simple examples. In the examples we have a microflow call which generates the error. In a real app, however, an error can be generated by any activity. No results from the activity which fails will be available (for example, if a Call REST Service returns an error, any data the REST call retrieved will not be kept). The error handling only applies to activities which happened before the activity which errors.

Error Handling - Default

In this example, the error handling in Microflow 2 is the default: Rollback.

When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. When an error occurs in Microflow 2, the default error handling is to roll back all changes to the state of this savepoint (so changes made in Create Order and in Create Customer are both reverted.), Microflow 2 terminates, then Microflow 1 terminates, the error is logged, and a system error message is shown to the end-user.

Error Handling - Custom with Rollback

Error Handling Which Ends with an End Event

In this example, the error handling in Microflow 2 is set to Custom with rollback and the error handling flow ends with an end event.

When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. When an error occurs in Microflow 2, everything rolls back to the state of this savepoint because the error handling is set to Custom with rollback. Hence, changes made in Create Order and in Create Customer are both reverted. A custom error is logged using a Log message activity.

Error Handling Which Ends with an Error Event

In this example, the error handling in Microflow 2 is set to Custom with rollback and the error handling flow ends with an error event.

When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. When an error occurs in Microflow 2, everything rolls back to the state of this savepoint because the error handling is set to Custom with rollback. Hence, changes made in Create Order and in Create Customer are both reverted. A custom error is logged using a Log message activity. After that, the error event throws a new error (with the same information as the original error) to terminate Microflow 2, and Microflow 1 will terminate because there is no custom error handing there.

Error Handling - Custom without Rollback

Setting Custom without rollback will not stop data changes within the actual activity which failed being lost. For example, if a Call REST Service returns an error, any data the REST call retrieved will not be kept.

Error Handling Which Ends with an End Event

In this example, the error handling in Microflow 2 is set to Custom without rollback and the error handling flow ends with an end event.

When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. Another savepoint is created right before GenerateError because the error handling is set to Custom without rollback. When an error occurs in Microflow 2, changes made in Create Order are kept because of the savepoint right before GenerateError. A custom error is logged using a Log message activity. Because the error flow ends with an end event, Microflow 1 does not receive the error and continues to its end. Changes made in Create Customer are kept.

Error Handling Which Ends with an Error Event

In this example, the error handling in Microflow 2 is set to Custom without rollback and the error handling flow ends with an error event.

When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. Another savepoint is created right before GenerateError because the error handling is set to Custom without rollback. When an error occurs in Microflow 2, changes made in Create Order are at this moment still kept because of the savepoint right before GenerateError. A custom error is logged using a Log message activity. After that, the error event throws a new error (with the same information as the original error) to terminate Microflow 2 and, because this error is not handled in Microflow 1, rolls back everything to the state of savepoint 1 which is at the very beginning of Microflow 1. Hence, changes made in Create Customer and in Create Order are both reverted.

Error Handling - Continue

The Continue option can only be set on a Call microflow activity or on a loop.

In this example, the error handling in Microflow 2 is set to Continue.

When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. Another savepoint is created right before GenerateError because the error handling is set to Continue. When the error in Microflow 2 occurs, Microflow 2 continues as if nothing happened. Changes made in Create Customer and Create Order are both kept. No error message is logged and no message is displayed to the end-user.

Data changes within the activity which returns an error (for example, within an iteration of a loop) will always be rolled back. It is only data changes outside the activity returning the error which will be kept.

An Example of Combined Error Handling

In this example, the error handling on the GenerateError activity in Microflow 2 and on the call of Microflow 2 are both set to Custom without rollback. The error handling flow in Microflow 2 ends with an error event.

There are three savepoints. When Microflow 1 starts with a button click, a savepoint is created at the very beginning of Microflow 1. Another savepoint is created right before the call of Microflow 2, and the third savepoint is created right before GenerateError - this is because the error handling on the GenerateError activity in Microflow 2 and on the call of Microflow 2 are both set to Custom without rollback.

When an error occurs in Microflow 2, changes made in Create Order are at this moment saved because of the savepoint right before GenerateError. A custom error is logged using a Log message activity. After that, the error event throws an error to terminate Microflow 2 and rolls back everything inside Microflow 2 to the state of savepoint 2, (at this moment, what was saved in Create Order is now rolled back). The custom error handling in Microflow 1 that applies to the call of Microflow 2 causes the error handling flow in Microflow 1 to be followed and terminates Microflow 1 with an end event. Changes made in Create Customer are hence kept.

Inspecting Errors

When an error occurs inside a microflow, a Java exception is raised that contains information about the error that occurred. Inside a custom error handler (as in, after an error handling flow), you can inspect the type of this Java exception as well as several other properties. Every microflow contains two predefined error objects, $latestError and $latestSoapFault. $latestError is an object of entity System.Error, while $latestSoapFault is an object of entity System.SoapFault, which is a specialization of System.Error.

In a custom error handler that is executed after an error occurs, $latestError is set to an object of entity System.Error containing information about the error that occurred. It contains the following attributes:

Inspecting REST Errors

If the error is a REST fault (an error that occurs as a result of a REST call), the result of the call will be stored in the $latestHttpResponse variable which is an object of type HttpResponse. This object is available in your custom error flows and you can use it to write more focused messages to the log or to make other decisions within the error flow. For more information, see the Response Tab section in Call REST Service.

Inspecting SOAP Errors

If the error is a SOAP fault (an error that occurs as a result of a web service call), $latestSoapFault is set to an object of type System.SoapFault that contains more specific information about the SOAP fault. Otherwise, $latestSoapFault is empty.

The attributes of the System.SoapFault entity are shown below:

For more information, see SOAP Fault.

Best Practices

Consider the following best practices for error handling:

• Always use a log activity to print the error message and stack trace.
• Add custom error handling for activities that depend on third-party systems, as these activities might fail and usually provide detailed information on the cause of failure. With custom error handling, you should log the object that might have caused the error, the error type and message, or any responses from REST, SOAP, or Java action calls.
• Where possible, avoid using the Continue option and use Custom without rollback instead.
• Do not try to commit objects which were rolled back, Mendix will no longer see them as being changed. See How Commits Work in Commit Object(s) for more information about this.
• Do not overdo it – you can specify a lot of complicated error handling combinations, but this makes it more difficult (and slower) for the Mendix Runtime to evaluate the microflow, and it also makes it more difficult to predict the exact behavior in case of an exception.

What Error Handling Gives You

Consistent Data

Everything that happens within your app happens in a transaction. By default either all activities are completed or nothing is completed. If you don't specify any error handling and the microflow you are trying to run encounters an error, it will appear that nothing has changed. That means that all the objects you created or changed will be reverted, and the end-user will get an error. This ensures that processes and data remain consistent.

Isolated Changes

While updating or creating your objects, you do not want other end-users to see updated information until your microflow has finished executing.

To ensure that every end-user or process can only see persisted data, data changed and committed in a microflow is not made available to all end-users of the application until the top-level microflow has successfully completed all the activities. Before then, only the end-user running the microflow has access to the data.

Protection from Parallel Updates

When an object is updated, your app will place a write lock on that object until the transaction/microflow ends. While the microflow is running, nothing else can write to that same object and anything that attempts to do so will have to wait. This lock is released automatically as soon as the microflow ends, allowing any waiting processes to continue normally.

Read More

• Error Handling in Nanoflows