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. Execution errors are visible to the caller that sent the request to the process engine.

Users with process administrator (process-admin) or administrator (admin) roles can access execution 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

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). You can view a filtered list of errors that were or were not acknowledged. Acknowledging an error saves the user information and time stamp for traceability.

Procedure

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

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

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

  4. Optional: 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 the Manage Execution Errors screen, you can use the Filters panel to display only the errors that fit chosen criteria.

Prerequisites

  • The Manage Execution Errors screen is open.

Procedure

Make changes in the Filters panel on the left side of the screen as necessary:

Figure 31.1. Filtering Errors - Default View

The *Filters* panel
Type

Filter execution errors by type. You can select multiple type filters. If you deselect all types, all errors are displayed, regardless of type.

The following execution error types 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

    Select the Custom option to open a calendar tool for selecting a date and time range.

    Figure 31.2. Search by Date

    Search by Date Range

31.4. Auto-acknowledging execution errors

By default, execution errors are unacknowledged when they occur. To avoid the need to acknowledge every execution error manually, you can configure jobs to auto-acknowledge some or all execution errors.

Note

If you configure an auto-acknowledge job, the job runs every day by default. To auto-acknowledge execution errors only once, set the SingleRun parameter to true.

Procedure

  1. In Business Central, select Menu → Manage → Jobs.
  2. In the top right of the screen, click New Job.
  3. Enter any identifier for the job in the Business Key field.

  4. In the Type field, enter the type of the auto-acknowledge job:

    • org.jbpm.executor.commands.error.JobAutoAckErrorCommand: Acknowledge all execution errors of type Job where the job to which the error relates is now cancelled, completed, or rescheduled for another execution.
    • org.jbpm.executor.commands.error.TaskAutoAckErrorCommand: Acknowledge all execution errors of type Task where the task to which the error relates is in an exit state (completed, failed, exited, obsolete).
    • org.jbpm.executor.commands.error.ProcessAutoAckErrorCommand: Acknowledge all execution errors of any type where the process instance from which the error originates is already finished (completed or aborted), or the task from which the error originates is already finished.

  5. Select a Due On time for the job to be completed:

    • To run the job immediately, select the Run now option.

    • To run the job at a specific time, select Run later. A date and time field appears next to the Run later option. Click the field to open the calendar and schedule a specific time and date for the job.

      Figure 31.3. Example of scheduling an auto-acknowledge job

      Scheduling an auto-acknowledge job

  6. By default, after the initial run the job runs once every day . To change this setting, complete the following steps:

    1. Click the Advanced tab.
    2. Click the Add Parameter button.

    3. Enter the configuration parameter you want to apply to the job:

      • If you want the job to run only once, add the SingleRun parameter with the value of true.
      • If you want he job to run periodically, add the NextRun parameter with the value of a valid time expression, such as 2h, 5d, 1m, and so on.

    4. Optional: To set a custom entity manager factory name, enter the EmfName parameter.

      Figure 31.4. Example of setting parameters for an auto-acknowledge job

      Setting parameters for an auto-acknowledge job
  7. Click Create to create the job and return to the Manage Jobs page.

31.5. Cleaning up the error list

The process engine stores execution errors in the ExecutionErrorInfo database table. If you want to clean up the table and remove errors permanently, you can schedule a job with the org.jbpm.executor.commands.ExecutionErrorCleanupCommand command.

The command deletes execution errors that are associated with completed or aborted process instances.

Procedure

  1. In Business Central, select Menu → Manage → Jobs.
  2. In the top right of the screen, click New Job.
  3. Type any identifier for the job into the Business Key field.
  4. In the Type field, enter org.jbpm.executor.commands.ExecutionErrorCleanupCommand.

  5. Select a Due On time for the job to be completed:

    • To run the job immediately, select the Run now option.
    • To run the job at a specific time, select Run later. A date and time field appears next to the Run later option. Click the field to open the calendar and schedule a specific time and date for the job.
  6. Click the Advanced tab.

  7. Add any of the following parameters as necessary:

    • DateFormat: The format for dates in parameters. If not set, yyyy-MM-dd is used, as in the pattern of the SimpleDateFormat class.
    • EmfName: Name of the custom entity manager factory to be used for queries.
    • SingleRun: Schedules the job for a single execution. If set to true, the job runs once and is not scheduled for repeated execution.
    • NextRun: Schedules the job for repeated execution in a time period. The value must be a valid time expression, for example, 1d, 5h, 10m.
    • OlderThan: Deletes only errors that are older than a set date. The value must be a date.
    • OlderThanPeriod: Deletes only errors that are older than a given time period, compared to the current time. The value must be a valid time expression, for example, 1d, 5h, 10m.
    • ForProcess: Deletes only errors that are related to a process definition. The value must be the identifier of the process definiton.
    • ForProcessInstance: Deletes only errors that are related to a process instance. The value must be the identifier of the process instance.
    • ForDeployment: Deletes only errors that are related to a deployment identifier. The value must be the deployment identifier.