Error Detection and Handling

Introduction
Automate provides three levels in which it can automatically detect and handle errors. They include the System (or Global) Level, Task Level and Step Level. Furthermore, Automate includes different options for each level to handle errors when they occur. How Automate reacts to an error and what can be done when one occurs depends on how its 'Error Handling' parameters are set in the managed task's properties.

Flow of Error Handling
Each step has its own set of errors that can occur based on the purposes of the action itself. Additionally, every available action in Automate contains two special tabs called 'Error Causes' and 'On Error.' If an error occurs, the step checks the 'Error Causes' tab to verify whether or not the error should be handled (by default all errors of a step are handled). If the error is to be handled, the step examines the settings of the 'On Error' tab and executes each option chosen. Finally, the step checks whether the 'Flow Control' tab is set to "Stop Task" or "Continue Task" upon error. More details regarding the 'Error Causes' and 'On Error' tabs are listed below.

Tri-Level Error Detection and Handling

System Level 
Automate can handle errors globally for all tasks that run on a system. If this option is enabled, Automate will act upon ALL managed tasks that fail with an error. The settings for Global Error Handling can be configured in the Task Administrator by going to 'System' -> 'Options' -> 'Task Errors' tab. The available options are:

1. E-mail error notification for all tasks
   When selected, Automate will send an email notification containing details about the error. If this option is checked, the option "Attach task file" becomes available. When selected, Automate will attach a copy of the task file (i.e. the task steps) associated with the failing task. This file can be opened in any Automate Task Builder to investigate the cause of the error. Be sure to provide a valid SMTP server on the "E-mail" tab of System Options. Automate will use this server to send the error e-mail. 
   
2. Run task on error
   When selected, another Automate Managed Task or Automate Task File will be executed upon error. Note: The drop-down arrow displays only managed tasks created from the Task Administrator. In order to specify a separate task file, simply enter the full path and filename manually.

Task Level Error Detection and Handling
As part of Automate's "tri-level" error handling, errors may be handled on a per task basis. This is ideal if the user wants Automate to perform specific error handling procedures for a managed task. A task level error occurs when a step within a task fails and Automate generates an error. This causes the task to notify the Task Service of the failure which allows the task's error level handing events to occur. Task Level Error handling can be configured in each task's Managed Task Properties window under the 'Errors' tab. The available options are:

1. E-Mail
   The task will send an email message containing the task and the generated error information. The default mail server settings configured in 'System' -> 'Options' -> 'E-Mail' tab is used to send the message.
2. Log File
   The error that occurs will be written to a task-specific text log file specified by the user. This log file is separate from the Automate system Log file. 
3. Run a Task
   Another Managed Task or Task File will be executed upon error (identical to the Global Error Handling option 'Run Task on Error'). For example, a default error handling task can be configured to run if an error occurs in the task.
4. Windows Event Log
   An entry will be created in the Windows Event Log upon task error.

Step Level Error Detection and Handling
Errors may be handled on a per step basis as well. Normally, any failure of a step within a task causes a step error. What causes a step to fail is, however, dependent on the step and it's parameters. These parameters can be adjusted under the 'Error Causes' tab of any Automate step. If a step fails, the user can select from a number of actions to be carried out. These actions are located in the 'On Error' tab of any specific step.

Error Causes Tab
Every available action in Automate includes an 'Error Causes' tab. The 'Error Causes' properties allows the task developer to determine what conditions Automate should consider an error for each step. During task execution, if one of these conditions is met, the specified actions in the 'On Error' tab (also available in every available action) are carried out. The following options are included under the 'Error Causes' tab:

The following should cause this step to fail...

- Any Error: Any problem encountered during step execution will cause the instructions specified in the On Error tab to be carried out.

- Only Certain Errors: Only the errors selected from the list of possible errors will cause the instructions specified in the On Error tab to be carried out. Any other errors are ignored.

If this step takes more than this many milliseconds to complete:
When checked, this option acts as a timeout value for the step. For example, if a SQL Query step is being executed and this value is set to 5000 milliseconds and the query took longer than 5 seconds, the step would error and the instructions in the 'On Error' tab would be carried out.

On Error Tab
The 'On Error' tab allows the task developer to determine what Automate should do if a particular step encounters a problem as defined in the 'Error Causes' tab. The following options are:

If the step fails, the following actions should be carried out...

Retry the step X times then: This allows the task developer to specify that the step should be retried a specified number of times before actually considering it a true step failure. When enabled, the step will attempt to retry execution by number of times specified. If after these retries the step still fails, the remainder of the actions below will be carried out.

1. Start Task: If enabled, specifies that another task should be executed if this step generates an error. This is generally used to execute steps to rectify the error. 'Task' 
   specifies the a managed task name or the path and file name of the task file (.AML) that should be executed.
2. Break Loop: If enabled, specifies that, if the step is inside a loop, the task should stop looping on error. Task execution jumps to the first step after the End Loop step associated with the Loop.
3. Set Variable: If enabled, specifies that an already existing Automate variable should be populated with a user defined value if the step generates an error. 'Variable Name' specifies the name of a variable. The variable must have been previously created within the task using the 'Create Variable' action. 'Variable Value' specifies the value to place into the variable.
4. Send Email: If enabled, specifies that an SMTP message should be sent if this step generates an error. The message will be populated with information about the specific error that occurred and other task information. 'Recipient' specifies the recipient of the email message. 'From' specifies the email address that should be used in the "From" header of the message.
   Note: Many SMTP mail servers require a valid "From" address.
5. Goto: If enabled, specifies that Automate should skip to another step number or label step in the task if an error occurs. If using a Label, the label must already exist in the task.
   Note: Try to limit the use of 'Goto' within each task and use 'Start Task' instead. Too many "Goto" instructions can produce extremely unmanageable tasks.

Flow Control

Stop Task: The task should stop if an error occurs (as defined in Error Causes) during execution of this step.

Continue Task: The task should continue if an error occurs (as defined in Error Causes) during execution of this step. This option if useful if one if the following conditions are true:

1. The error is non-critical.
2. Additional error handling steps is located below the step.

Applies To: Automate 5, Automate 6