Workflow Exception Handling

Overview

In computing, “exceptions” are recognized as unforeseen error events that disrupt the normal flow of a running process. Exceptions, however, can be unique to a particular user environment. Some potential reasons can be due to network issues, restricted user permissions, task execution priority, and sudden changes in resources or faulty workflow design. Workflow level exceptions are especially critical as workflows may encompass a sequence of long-running tasks or high level processes. Unhandled workflow errors, in most cases, result in a restart of the entire workflow. This can lead to costly delays that negatively impact production.

A common expectation in automated workflow systems is their ability to detect and respond efficiently to exceptions that may occur. Automate meets such expectations with its dynamic approach to handling exceptions at the step, task and workflow level. This tri-level scheme provides flexibility to deal with both predictable and unpredictable exceptions.

Related Topics

Preparing for exceptions

For workflow level errors to be handled properly, the first step is for a workflow developer to determine, for a given “ideal” workflow, the ways that the process may fail and then “instrument” the workflow so that such failures can be detected or even anticipated. For each exception type of interest, the developer can then decide how to augment the workflow to prepare for (anticipate or detect) such exceptions. The next step is to figure out how to react when an exception is anticipated or detected during workflow execution. Once an exception has been detected and diagnosed, the third step is to define a "prescription" that responds appropriately to the anticipated or actual exception.

Exception handling techniques

Because of the inherent complexity of workflows, this article will largely emphasize workflow level exception handling with regards to workflow item error detection and repair. It will present some basic workflow layouts that implement an assortment of error handling techniques, point out specific methods to deal with exceptional cases and provide links to for easy navigation to additional information about specific topics.

Error causes

Many common situations take place during workflow execution that can generates an error. For example, an error can occur when workflow execution arrives at a sub-workflow that is currently disabled or arrives at a task whose assigned agent is currently off-line. You may want the workflow to ignore such errors or bypass other errors that are irrelevant or insignificant to the workflow's overall execution/completion. The Error Causes properties can be used to determine which workflow item error events should be taken into account as actual exceptions and which ones should be ignored. With this capability, you can globally set all workflows to ignore non-critical or insignificant error events, allowing execution to proceed without interruption.

Error Causes contains properties handles common errors as they relate to specific workflow items, therefore, available types of exceptions may vary depending on the type of workflow item. With regards to workflow items assigned to an agent group, Error Causes can dictate whether specific event types should lead to an error as they relate to individual agents contained in a group. It can also dictate whether or not an exception should be thrown based on the percentage or numerical ratio of agents in the group encountered the error.

To access Error Causes properties, from Server Management Console, navigate to Options > Default Properties > Default Workflow Item properties and double-click Error Causes. For more details, see Default Workflow Item Properties - Error Causes.

On Error

The On Error properties work hand-in-hand with Error Causes and allows you to define how a workflow behaves in the event that one of its items causes an error as specified in the Error Causes properties. This functionality enables you to determine whether workflows should continue or immediately halt execution upon error. It is specifically useful for handling multi-branch workflow items. You can configure the workflow to stop execution on only the branch that caused the error, allowing all other branches to proceed or stop execution of all other branches except the one that caused the error.

Also, in the event that one of the workflow items causes an error, On Error enables you to dictate whether the current execution should be written to the Windows Event Log as Failed or Successful, which can be useful for auditing and reporting purposes. This does not, however, affect the workflow's progress as specified in the On Workflow Item Error properties. For example, if the On Workflow Item Error property is set to Continue, and the On Error properties is set to write log execution as Failed, execution of this workflow will be logged as “failed”, although the workflow will still continue its normal course.

To access On Error properties, from Server Management Console, navigate to Options > Default Properties > Default Workflow Item Properties and double-click On Error. For more details, see Default Workflow Item Properties - On Error.

On Workflow Error

During execution of a workflow, one of its items might cause an error that requires immediate attention from a specific user, team member/leader or administrator. For example, task execution may fail because it cannot locate a file, open an Excel document, or perhaps cannot upload files to an FTP server. Information about such errors may need to be sent to the proper individual so he/she can solve the problem in a timely manner. The On Workflow Error feature is ideal for this situation. When a workflow exception occurs, or a workflow finishes in a Failed state, this feature allows an error notification email to be sent to the specified address. Details about the error (that is, error description, date/time of the event, error code) will be included in the body of the email.

To access On Workflow Error properties, from Server Management Console, navigate to Options > Default Properties > Default Workflow Properties, and then double-click On Workflow Error. For more details, see Default Workflow Properties - On Workflow Error.

Conditional branching

Automate workflows are both powerful and multifaceted. You can insert highly visible and comprehensible conditional logic to your workflows without writing a single line of code. As powerful as they are, workflows are also prone to a variety of problems that may occur, typically because they house all of the items that actually perform the work. By default, if an exception happens that is not handled, execution immediately terminates at the item that caused the exception and information about the error is logged. This usually indicates an incomplete operation resulting in unfinished work. In an automated environment, this may not be a suitable solution. Instead, you may want execution to continue and conceivably, the workflow can attempt to recover from the problem causing the exception. A common method is creating a workflow designed to use “conditional branching” to logically handle errors and alter the course of a workflow in case one is encountered.

Flow control arrows allow conditional branching to take place by determining a workflow’s progress depending on specific events or conditions that transpire. A workflow executes along the path of any flow control arrow containing the value equaling that of the previous object. The sample workflow below illustrates exception handling by way of conditional branching at its simplest form. If Task1 completes successfully on Agent 1, execution follows the path of the Success (green) arrow, which will run Task 2 on Agent 2. If Task1 fails, execution follows the path containing the Failure (red) arrow instead, which points to Task 3 on Agent 3.

Conditional branching is similar to an If statement in that it gives a workflow the ability to implement intuitive decision making in order to respond accordingly to any exceptions and ideally allow the workflow to branch off to another task, process or sub-workflow designed to remedy the problem and continue processing. If continuation is not possible, conditional branching allows a workflow to branch to an alternate task, process or sub-workflow that can perform a thorough clean-up, such as returning documents or other content to their original state, logging the appropriate information and gracefully shutting down unnecessary processes or the system itself. The sample workflow below illustrates a more intuitive way to handle workflow level exceptions. If Task1 completes successfully on Agent 1, execution follows the path of the Success (green) arrow, which will run Task 2 on Agent 2 and eventually, complete the workflow by running Task 3 on Agent 3. If Task1 fails, however, execution follows the path containing the Failure (red) arrow which points to a task designed specifically to resolve the error and continue to Task 3 on Agent 3.

For additional details and more examples, see Workflow Logic.

Using conditions to handle errors

Automate conditions are sophisticated multi-role objects that can trigger or suspend a workflow or alter its course. When a condition is placed as the first object in the beginning of a workflow, it takes on the role of a trigger, at which point, it can monitor for the occurrence of a condition and "fire off" a task or workflow when the condition is met. When placed anywhere else in a workflow’s path other than its start, the condition takes on the role of a conditional (or decision making) object which can change the path of a workflow depending on whether or not the specified condition is met, or a wait  object which can suspend workflow execution until a specific condition is met.

Conditions can't exactly "handle" errors that transpire, however, they can intuitively detect system states or anticipated conditions that may commonly lead to an error and instruct the workflow to perform alternate steps to avoid such errors altogether.

For example, if a File condition is selected, it can be used in the following scenarios:

  • Trigger - Used as a trigger object to initiate workflow or task when a particular file appears in the monitored folder (for example, If File X exists in Folder Y, execute Task1).
  • Wait - Used as a Wait object to pause workflow execution at the condition object until a certain file exists (for example, Wait for File X to exist before running Task A). For instance, an error handler sub-workflow can contain steps to notify the user of the exact error that occurred so he/she can manually perform the appropriate steps to fix the problem. A wait object can be used in this situation to allow the workflow to wait for the appropriate fixes to be performed.

  • Conditional  - Used as a conditional object to determine which path a workflow should take depending on whether or not a file currently exists. If TRUE, execution proceeds to the Success (green) flow control arrow. If FALSE, it proceeds to the Failure (red) flow control arrow. A condition’s behavior is influenced primarily by its Behavior properties (illustrated below).

Condition behavior properties are comprised of two main options that dictate whether the workflow should wait for the condition to take place or perform the evaluation immediately. By default, a newly created condition is always set to the parameter Wait for condition and sub-parameter Indefinitely, which means that it will behave as a trigger object. To set a condition to act as a wait object, select the Timeout After parameter. This suspends workflow branch execution at the condition object until the monitored condition occurs or the specified timeout period expires.

To set the behavior of a condition as a conditional or decision making object, select the Don't wait, execute immediately parameter. In this situation, the condition does not wait. Instead, it evaluates immediately whether the specified condition has occurred. If the evaluation results to TRUE, the execution is marked as success and therefore execution follows the path marked by a Success (Green) Arrow. If the evaluation results to FALSE, the execution is marked as failure and execution follows the path marked by a Failure (Red) Arrow.

For more on condition behavior parameters, see Condition Behavior.

AMError

To fix errors, you need as much information about them as possible. It is often the case that the logged error description alone isn't enough information for the workflow to handle the error or even determine what went wrong. When an Automate task generates an error, it automatically creates a fixed name dataset called AMError which can be used to examine important properties about the error that occurred (for example, error number, error description, task name and step number that caused the error, etc.) in subsequent task steps. When declared in a shared variable, specific AMError values can be passed to subsequent workflow items as well.

To reference AMError return data, use the following syntax:

%AmError.[Parameter Name]%

For example, using a Message Dialog activity as a task step with the Message to display parameter set to %AmError.ErrorDesc% would display a message box returning a textual description of the error.

Parameters

The following table provides a list of available fields that AMError populates and their return values:

Name Type Return Value
AMError.ErrorDesc String Returns a textual description of the error that occurred.
AMError.ErrorNumber String Returns the error number associated with the error text.
AMError.FunctionName String Returns the name of the function that generated the error (if applicable).
AMError.IPAddress String Returns the IP address of the computer which generated the error.
AMError.ParentTaskName String Returns the name of the parent task (if the task that failed was a child task or sub-task).
AMError.StepNumber String Returns the step number that generated an error.
AMError.StepText String Returns a textual description of the step that generated an error in AML format (similar to how it would appear in the Task Builder's Steps panel if the View parameter is set to AML).
AMError.TagLine String Returns the AML tag line of the step that failed with an error.
AMError.TaskName String Returns the name of the task that generated an error.