Error Handling

Flux does the following when an error is encountered:

  • Check for an error flow. If there is no error flow, use the default error handler.
  • "Insert" the default error into the flow chart at the point of failure. Execute the default error handler flow chart as usual. 
  • If the default error handler ends in an Error Action, the main flow chart enters the failed state. If it ends in any other type of action, the main flow chart is retried from the point of failure. 

If you haven't installed your own default error handler, a built-in error handler will retry the failed flow chart every minute up to 5 times. If these retries fails, then the flow chart is moved to a FAILED state.

Error Flows

In addition to error flows, note that errors can be handled in a more general way using default flow chart error handlers as described below. Sometimes, errors occur in triggers and actions. For example, an Email Action may not be able to contact its email server. In this case, you can define explicit error flows that let your flow chart explicitly deal with the error condition.

JavaAction javaAction = flowChart.makeJavaAction("My Java Action");
...
JavaAction errorAction = flowChart.makeJavaAction("My Error Action");
...
javaAction.setErrorFlow(errorAction);

If the above Java Action throws an exception, thus indicating an error, control flows into "My Error Action", where the error can be handled appropriately. As of Flux 7.7, transactions are no longer rolled back by default; instead, error flows can be defined to rollback the current transaction. The transaction can be explicitly rolled back by using theAction.setErrorFlowWithRollback() method. Once this rollback is complete, a new transaction begins and the flow of execution continues through the specified error flow. All work in that error flow, such as runtime data mapping and signal raising, is then performed. At the end of the error flow, a transaction break is encountered and the current transaction executing in that specific error flow is committed to the database. Once the transaction in the error flow is committed, flow will continue through the specified actions in the normal way.

From here you may set up actions to fix the problem and continue with the flow chart, or you may wish to just end the flow chart and exit.

In the case that an error occurs in a trigger or action and there is no error action defined, the Flux engine presumes that the flow chart is finished, because there is no appropriate flow to follow. By default, the Flux engine automatically deletes flow charts when they finish. This way, the database does not grow unbounded.

When an error flow is followed, there is a flow context variable generated named ERROR_RESULT. The type of this object is flux.ErrorResult. You can query this error result object to retrieve the exception that caused the error. This variable can be accessed by calling flowContext.getErrorResult(). After an error flow, if the action is successfully executed, the error result variable will be cleared. Furthermore, in the context of an error handler, if the error handler completes and control returns to the main flow chart, the error result variable is cleared as well. See the Javadoc documentation for flux.ErrorResult for further details.

Custom Error Handlers

The above section describes how to create an error flow to handle errors that occur when a trigger or an action executes. An error flow handles an error in a specific trigger or action in a specific way. To handle specific situations with a specific error flow, an error flow must be defined at each trigger or action for each specific situation.

On the other hand, default flow chart error handlers have a broad brush. A single error handler can be defined in one location. That error handler can be responsible for recovering from errors, retrying actions, sending notifications, and performing other error recovery actions.

By default, a default error handler is installed that retries actions up to five times, with one minute delays in between. If the action still fails after five retries, the execution flow context is placed into the ERROR super-state and the PAUSED sub-state.

Default error handlers are simply flow charts that are installed in the runtime configuration tree. When an execution flow context executes an action and that action throws an exception, if no error flow is defined, the Flux engine searches for a default error handler.

The Flux engine checks the hierarchical flow chart namespace in the runtime configuration tree, beginning at the location in the tree that corresponds to the name of the flow chart and working its way to the root of the tree. The first default error handler that is found is used. If no error handler is found, the flow chart is considered to be finished, in which case the flow chart terminates and is deleted in the normal way whenever a flow chart finishes.

However, if a default error handler is found, the following actions take place.

  • The execution flow context’s transaction is rolled back.
  • The execution flow context’s super-state is changed from NORMAL to ERROR.
  • The execution flow context creates the default error handler flow chart and begins executing it.
  • If the error handler flow chart terminates normally, without throwing an exception, the execution flow context commits the current transaction and resumes execution in the main flow chart from the point of the last committed transaction.
  • On the other hand, if the error handler flow chart terminates by throwing an exception, the execution flow context commits the current transaction, and the main flow chart is placed into the PAUSED state. Because paused flow charts do not execute when paused and because this flow chart is in the ERROR super-state, extraordinary actions can be performed in an attempt to remedy the flow chart and ultimately resume it.
  • Whenever a flow chart action is retried after an error, runs successfully to a transaction break, and successfully commits the transaction, the execution flow context’s super-state is changed back from ERROR to NORMAL, and the error handler flow chart instance is destroyed.

As with error flows, when a default flow chart error handler is entered, there is a flow context variable named error_result. The type of this object is flux.ErrorResult. You can query this ErrorResult object to retrieve the exception that caused the error. See the Javadoc documentation for flux.ErrorResult for further details.

Basically Flux does the following when an error is encountered:

  • Check for an error flow. If there is no error flow, use the default error handler.
  • "Insert" the default error into the flow chart at the point of failure. Execute the default error handler flow chart as usual. 
  • If the default error handler ends in an error action, the main flow chart enters the failed state. Any message entered in the "Message" property of the Error Action in the default error handler is displayed in the "Message" column on the Operations Console's flow charts page.

If it ends in any other type of action, the main flow chart is retried from the point of failure. 

Error handling can be done either inside the flow chart using error flows or it could be abstracted outside the flow chart using custom error handlers.

In order to define a custom error handler, you need to define the following configuration in Flux runtime configuration file:

/DEFAULT_FLOW_CHART_ERROR_HANDLER=/opt/flux-7-9-9/fluxproject/Custom Error Handler.ffc

Error handlers are defined per namespace in the runtime configuration file. An error handler on a namespace branch will take precedence over any error handlers set on higher branches.

/client1/data flow/DEFAULT_FLOW_CHART_ERROR_HANDLER=/opt/flux-7-9-9/fluxproject/Custom Error Handler1.ffc
/client2/data flow/DEFAULT_FLOW_CHART_ERROR_HANDLER=/opt/flux-7-9-9/fluxproject/Custom Error Handler2.ffc

For a complete working example demonstrating a custom error handler, refer to the /examples/end_users/error_handling directory under your Flux installation directory.

Displaying the Name of the Action that Caused an Error

As mentioned above, the grid on the flow charts page of the Operations Console has a "Message" column that displays the value of the "Message" field in the final Error Action of the default error handler for any flow charts in the FAILED state. You can use this to report information about the error back to the Operations Console; for example, you could report the name of the action in the main flow chart that originally caused the error (which, by default, is not displayed).

This requires two steps: first, on the Error Action in your default error handler, add the following prescript:

flowContext.put("errorActionName", flowContext.getErrorResult().throwingAction);

This prescript gets the name of the action that originally caused the error (obtained by calling flowContext.getErrorResult().throwingAction), then adding that value as a new flow context variable, "errorActionName" (you can change this to another name if you would prefer).

Next, set the Error Action's "Message" property and using variable substitution, include the value of the flow context variable you just set. When you're finished, the message property should look like:

The action ${errorActionName} caused an error.

Now, when a flow chart invokes the default error handler and eventually enters the FAILED state, you will see a message on the console like "The action MyActionName caused an error."

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.