Chapter 31. Execution error management

When an execution error occurs for a business process, the process stops and reverts to the most recent stable state (the closest safe point) and continues its execution. If an error of any kind is not handled by the process the entire transaction rolls back, leaving the process instance in the previous wait state. Any trace of this is only visible in the logs, and usually displayed to the caller who sent the request to the process engine.

Users with process administrator (process-admin) or administrator (admin) roles are able to access error messages in Business Central. Execution error messaging provides the following primary benefits:

  • Better traceability
  • Visibility in case of critical processes
  • Reporting and analytics based on error situations
  • External system error handling and compensation

Configurable error handling is responsible for receiving any technical errors thrown throughout the process engine execution (including task service). The following technical exceptions apply:

  • Anything that extends java.lang.Throwable
  • Process level error handling and any other exceptions not previously handled

There are several components that make up the error handling mechanism and allow a pluggable approach to extend its capabilities.

The process engine entry point for error handling is the ExecutionErrorManager. This is integrated with RuntimeManager, which is then responsible for providing it to the underlying KieSession and TaskService.

From an API point of view, ExecutionErrorManager provides access to the following components:

  • ExecutionErrorHandler: The primary mechanism for error handling
  • ExecutionErrorStorage: Pluggable storage for execution error information

31.1. Viewing process execution errors in Business Central

You can view process errors in two locations in Business Central:

  • Menu → Manage → Process Instances
  • Menu → Manage → Execution Errors

In the Manage Process Instances page, the Errors column displays the number of errors, if any, for the current process instance.

Prerequisites

  • An error has occurred while running a process in Business Central.

Procedure

  1. In Business Central, go to Menu → Manage → Process Instances and hover over the number shown in the Errors column.

  2. Click the number of errors shown in the Errors column to navigate to the Manage Execution Errors page.

    The Manage Execution Errors page shows a list of errors for all process instances.

31.2. Managing execution errors

By definition, every process error that is detected and stored is unacknowledged and must be handled by someone or something (in case of automatic error recovery). Errors are filtered on the basis of whether or not they have been acknowledged. Acknowledging an error saves the user information and time stamp for traceability. You can access the Error Management view at any time.

Procedure

  1. In Business Central, go to Menu → Manage → Execution Errors.
  2. Select an error from the list to open the Details tab. This displays information about the error or errors.

  3. Click the Acknowledge button to acknowledge and clear the error. You can view the error later by selecting Yes on the Acknowledged filter in the Manage Execution Errors page.

    If the error was related to a task, a Go to Task button is displayed.

  4. Click the Go to Task button, if applicable, to view the associated job information in the Manage Tasks page.

    In the Manage Tasks page, you can restart, reschedule, or retry the corresponding task.

31.3. Error filtering

For execution errors in Menu → Manage → Execution Errors, you can use the Filters and Advanced Filters panels to sort errors as needed.

Figure 31.1. Filtering Errors - Default View

Filtering Errors

You can filter execution errors by the following attributes in the Filters panel:

Type

Filter by errors by type. You can select multiple type filters. Removing the status filter displays all processes, regardless of status.

The following filter states are available:

  • DB
  • Task
  • Process
  • Job
Process Instance Id

Filter by process instance ID.

Input: Numeric

Job Id

Filter by job ID. The job id is created automatically when the job is created.

Input: Numeric

Id

Filter by process instance ID.

Input: Numeric

Acknowledged
Filter errors that have been or have not been acknowledged.
Error Date

Filtering by the date or time that the error occurred.

This filter has the following quick filter options:

  • Last Hour
  • Today
  • Last 24 Hours
  • Last 7 Days
  • Last 30 Days

  • Custom

    Selecting Custom date and time filtering opens a calendar tool for selecting a date and time range.

    Figure 31.2. Search by Date

    Search by Date Range