Wizard error handling
The wizard consists of different logic blocks: wizard start, wizard steps, and wizard end. Each step is divided into two logic blocks: step start and step end, and are executed sequentially.
Errors may occur during execution such as a required window or object not found, or a blocked window. You can use error fallbacks to respond to these errors. For example, if an object is not found, you can configure the wizard to end unsuccessfully. Fallbacks can be customized for each wizard step.
Use fallbacks to create basic and complex business logic to ensure smooth execution of your automation tasks.
Before you begin:
-
Learn how to navigate the Wizard Editor
-
Understand how to create wizards and use Advanced commands
- This feature is available to users with extensive developer knowledge who create wizards for both Attended Robot and Unattended Robot. Use this feature only if you fully understand error handling, as it may impact expected behavior.
A fallback is a way to respond to errors. Use fallbacks to create your own business logic by constructing a logical path for errors.
It's recommended to define a fallback for each action, and it consists of two parts:
-
Fallback event: Defines when something happens during the execution of a wizard step, such as an object is not found.
-
Fallback command: Defines what happens when a fallback event occurs, such as end the wizard unsuccessfully.
There are two ways to configure error fallbacks in the Advanced Command editor:
-
Wizard steps (section A): Configure the error fallbacks in each wizard step individually.
-
Wizard start/end actions & error handling (section B): Configure the error fallbacks to apply to all wizard steps. Find this section at the end of the list of wizard steps in the editor.
When configuring the fallback commands in wizard steps (section A) and Wizard start/end actions & error handling (section B), the following logic applies:
• If section A and section B contains default values, default values are applied to all steps of the wizard.
• If section A contains default values and you customize section B by selecting a different value, the customized values are applied to all steps of the wizard.
• If section B contains default values and you customize a specific wizard step in section A by selecting a different value for that step, the value of the step in section A overwrites the default value of section B.
• If both sections A and B contains customized values, the value selected in section A overwrites the value of section B.
Example: You change the fallback command of Step start: Window not found in section A to End wizard successfully:
However, you also change the fallback command of the same step in the Wizard start/end actions & error handling (section B) to Go to step... 2: Click "File":
In this scenario, End wizard successfully is used as the fallback command when the window is not found.
There are different fallback events that may occur during the execution of a wizard step, and for each event, you can configure a fallback command:
Fallback event | Description | Default fallback command |
---|---|---|
Window not found |
The wizard fails to detect the window where the action is performed.
|
Raise error |
Window blocked |
This happens when dialog boxes or modal forms (pop-up windows that temporarily take control) opened by the application block access to the originally recorded window. * See Considerations |
Raise error |
Object not found |
The wizard tries to detect an object before executing an action and fails to identify it. |
Raise error |
Window closed | This happens when the recorded window, initially detected successfully, is closed during a step. | Ignore |
Object changed |
The wizard tries to locate the object linked to the anchored bubble, but the object has changed. This functionality is only available for anchored bubbles. |
Hide anchor |
Object hidden |
The wizard tries to locate the object linked to the anchored bubble, but the object is hidden. This functionality is only available for anchored bubbles. |
Hide temporarily |
Click blocked |
The wizard tries to execute a mouse click step action on an object or window, but the action is blocked, preventing the completion of the step. This can happen if the window is not ready for the click event or if the captured and current click areas differ. | Raise error |
Window does not close |
The wizard waits for a window to close, but it does not happen as expected. | Raise error |
Object does not disappear |
The wizard waits for an object to disappear, but it does not happen as expected. | Raise error |
Embedded wizard not found |
The wizard tries to execute an embedded wizard, but fails to find it. | Raise error |
Embedded wizard ended unsuccessfully |
The wizard executes an embedded wizard, but can't continue the automation flow because the embedded wizard fails. | Raise error |
For each error fallback event, you can choose one of the following fallback instructions for the execution engine:
Fallback command | Fallback action instruction | Example | Limitations |
---|---|---|---|
Raise error (default value) | This breaks the wizard execution and fail the automation task. |
You record a wizard to automate the creation of a new email message, including typing its content. As the wizard plays through the steps, if the user decides to change the email subject before the wizard reaches that specific point, the window caption of the message changes. In this case, the wizard searches for a window named RPA - Message (HTML). However, it can't find it because the user changed the caption. If you set up a fallback using the Raise error message for this step, the wizard pauses, and a message appears on the user's screen, showing that the process is paused due to the changed subject. This error can be avoided by editing window properties and setting the window Caption to Contains instead of Equals.
|
Not applicable to sensors or embedded wizard steps |
End Step | Ignore the step where the error occurred and continue with the next wizard step. | You record a wizard for setting a file name and location. In this case, users may click OK to confirm the action instead of waiting for the wizard to do it. This can result in the window closing before the wizard has a chance to click OK for the user. If the End Step fallback is applied to this scenario, the wizard ends the step instead of trying to detect the OK button. | |
Go to step | Ignore the step where the error occurred and continue with the specified wizard step. | You record a wizard to move email messages to a specific folder. If there's an open message, the wizard moves it. If there's no open message, and you set up the Go to Step fallback, the wizard then goes to a different step, where it executes the click to close Microsoft Outlook | |
Remove all blocks |
Ignore the step where the error occurred, try to remove blocks and cancel their functionality for that run of the wizard or sensor. |
You create a form-filling wizard, strategically adding blocks, including one on the Submit button, to prevent premature submissions. As the wizard completes the final section of the form and attempts to submit it, it gets an object blocked error because blocks are not specific to a certain step. If the Remove all blocks fallback is applied to this scenario, it removes all blocks allowing for the wizard to click Submit successfully. |
|
Keyboard shortcut | Ignore the step where the error occurred, try to send configured shortcut keys, and continue with the next wizard step. |
You create a wizard to insert an equation into an email message, but there's a problem. If the screen isn't maximized, the wizard can't see the Equation button properly. If you add the Keyboard shortcut fallback, the wizard doesn't get stuck. Instead of clicking the button, it types the specified shortcut keys (like ALT+N+E) to activate the Equation button. |
This option doesn't work for:
|
End wizard successfully | Ignore the step where the error occurred and end the wizard successfully. No further wizard steps are executed. | You create a wizard to save messages, and the final step involves handling a Microsoft Outlook message when the user attempts to save over an existing one. Now, if the user decides not to replace the existing message, and you added the End Wizard Successfully fallback to this step, the wizard ends at that point in the flow because there are no more actions needed. | |
End wizard unsuccessfully | Ignore the step where the error occurred and end the wizard unsuccessfully. No further wizard steps are executed. |
You create a wizard to fill out an online form. As it goes through the steps, it reaches a point where it needs to handle a pop-up to confirm the form submission. However, if the expected pop-up doesn't show up, and the wizard can't finish that step, you can use the End Wizard Unsuccessfully fallback. This stops the wizard early, signaling that something didn't go as planned. In the logs, it's marked as an unsuccessful end, and this information is shown in the Console Plus dashboard. |
If the wizard is an embedded wizard, like those inserted into the flow of a main wizard, their default fallbacks are ignored. Instead, the process continues based on the failure scenario set by the RPA developer for the main wizard. ** See workaround in Considerations |
Advanced commands | Ignore the step where the error occurred, execute a predefined set of advanced commands, and continue with the next wizard step. | You create a wizard to automate data processing in an application. In case the wizard encounters a Window Not Found error during its execution, you set up an error fallback using advanced commands. This ensures that when the window is not found, the wizard triggers predefined advanced commands, such as sending an email notification and logging the incident in an Excel file. Once the advanced commands are executed, the wizard continues with the subsequent wizard steps. |
* The Window blocked option is not present in the step action; therefore, the Step start: Window blocked error fallback is applied.
** Error fallbacks for embedded wizards
When errors occur in an embedded wizard step, they are handled following the same principles as in a regular wizard. As the parent wizard encounters an embedded wizard step, it treats each embedded step as its own, allowing configured fallback actions to seamlessly integrate. However, default fallbacks set for the embedded wizard are replaced with those of the parent wizard during execution.
If an embedded wizard encounters an error and uses the Raise error fallback, it normally doesn't affect the main wizard—it just continues. However, if you want these errors to be noticed by the main wizard, you can add the following Robot/Studio configuration. This allow errors from the embedded wizard to be recognized by the main wizard, making sure issues get the attention they need.
<add key="PropagateEmbeddedWizardRaisedErrors" value="true"/>