Use Wait Criteria

Wait criteria in the Continue when option are powerful instruments to help you build robots in a fast and reliable manner.

Every robot step, which requires the browser to start running, can be configured with a set of criteria to pinpoint when the processing of an action (such as a click or a page load) has completed enough for the robot to continue.

The Continue when feature, combined with the built-in algorithm, allows for browser steps to run only as-long-as-needed for the robot to be able to continue. Also the user can point and click an element on the page and create a new stop criterion for the browser step.

Wait criteria can be specified in the following steps:

• Click

• Close Window

• Create Page

• Enter Password

• Enter Text

• Execute JavaScript

• For Each Option

• For Each Radio Button

• Insert Tag

• Load Page

• Loop Field Values

• Move Mouse From

• Move Mouse To

• Press Key

• Replace Tag

• Scroll

• Scroll To

• Select File

• Select Multiple Options

• Select Option

• Select Radio Button

• Set Checkbox

All robots created in Kofax RPA version 9.6 and later have their default waiting set to Page Stops Changing for 500 ms. You can see this setting on the Advanced tab of the Robot Configuration window. All wait-criteria-enabled steps have a default No Page Changes for 500 ms wait criterion with the enabled Resume button, which can be seen in the Result View. This wait criterion is always grayed out in the Wait view and always met. All other browser steps have a default Initial Page Load Complete wait criterion with the disabled Resume button. This criterion is also always grayed out in the Wait view and always met.

If you migrate the Default browser engine robot to a Classic browser engine robot, the following rules are applied:

• If a step in the Default browser robot has a specified wait criteria, this step in the Classic browser robot is set to Wait Real-Time for Timer Events=true

• If a step in the Default browser robot has Legacy timing, in addition to Wait Real-Time for Timer Events=true, this step in the Classic browser robot has Max Wait for Timer Events set to the time specified in Legacy timing.

• If you migrate the same robot back to the Default browser robot, wait criteria are not restored.

Adding Wait Criteria

To specify a wait criterion for a step, click "+" in the Continue when field and select a criterion:

To add Wait criteria from the Browser and Source view after execution of a wait-criteria-enabled step, right-click the browser or source view, choose Wait for from the menu, and select a criterion. The step is re-executed after the criterion is added, which is shown by the Re-execute 'Load Page' button in the wait criterion configuration window.

Once the criteria are added, you can add, remove, move up, move down, and edit wait criteria using the panel under the list. Right-clicking a wait criterion in the Continue when list, opens an option menu to copy, cut, and paste a criterion.

You can add more than one wait criterion to a step. If you have several wait criteria, execution stops when any wait criterion is met. You can have several met wait criteria such as if you are waiting for two HTML elements that appear on the same load, or if you are waiting for an element on the main frame, and Initial Page Load Completes is set.

If adding a wait criteria to a wait-criteria-disabled step from a shortcut menu, the criteria is added to the previous wait-criteria-enabled step. For example, if you try to add a wait criterion after the Extract step as in the following example:

the criterion will be added to the Load Page step.

Wait View

The Wait view shows the results of wait criteria execution as well as disabled wait criteria.

Right-clicking a criterion in the list opens a shortcut menu. You can enable, disable, and delete a criterion as well as open properties for the selected criterion. For HTML Element Appears, you can select an element found in the DOM in the Browser view.

This view also shows whether the page was completely loaded. If the page is loaded completely, the Resume button is disabled. If the page is not completely loaded, because of the short timeout, the Resume button is disabled and you need to extend the timeout.

The Resume button in the Wait view is used to resume the browser operation after a wait criterion is met. If you have several wait criteria and one of them is met, clicking the Resume button marks the met wait criteria with a grey sign and the browser continues working until the next wait criterion is met. Once all criteria are met, clicking the Resume button starts loading the page during the time specified in the Timeout for Each Attempt option in the Options dialog box.

The Resume button is enabled for wait-criteria-enabled steps.

For default wait criteria you can click the Resume button as many times as you want. For non-default wait criteria, you can click the Resume button only once.

If a wait criterion is displayed without an icon, the criterion is not met.

Wait Criteria Properties

Each wait criterion except Initial Page Load Completes has its settings. To configure a wait criterion, either double-click a criterion in the Continue when or Wait view, click in the Continue when view or right-click a criterion in the Wait view and select Properties.

Disabling Wait Criteria

Wait criteria can be disabled and enabled in its configuration window. By default, all criteria are enabled. To disable a wait criterion, clear the Wait Criterion Enabled check box. When a wait criterion is disabled, it is not taken into account during the step execution.

You can right-click a wait criterion and use the shortcut menu to disable and enable a criterion.

After you disable or enable a wait criterion, the previous step is re-executed.

Ignore All Pending Loads When Met

Each wait criterion except Initial Page Load Completes has the Ignore All Pending Loads When Met option that stops loading a page when a wait criterion is met. This option can help in cases when a wait criterion is already met, but timers continue execution and loading does not stop. This option is not selected by default. If the browser was stopped by this option, a warning sign is added to the green icon in the Wait view.

HTML Element Appears

This criterion is met when a specified HTML element is present in the DOM tree. This criterion configuration is similar to the Tag Finders tab in "Step Configuration", except for additional property Found Element must be that contains two options:

• Enabled: If this option is selected, execution must stop when result = !element.disabled;

• Visible: if this option is selected, execution must stop when result = style.display !== "none" && style.visibility !== "hidden";

If HTML Element Appears criterion is met, it is marked in the Browser and Source views when you use the Select in Browser View command on the Wait view option menu.

HTML Element Disappears

This criterion is met when a specified HTML element disappears from the DOM tree. This criterion configuration is similar to the Tag Finders tab in "Step Configuration", except for an additional property: Initial Element Detection that contains two options:

• Element is Found on Page: the robot waits until the element appears on the page and only after that the robot waits for the element to disappear from the DOM tree.

• Wait for Fixed Amount of Time the robot waits the specified time and then verifies if element exists in DOM:

  • If the element is present in the DOM tree, the robot waits until the element disappears.

  • If the element is not present in the DOM tree, the wait criteria is met and the robot proceeds to the next step, even if the element has not appeared in DOM as the beginning of page load.

Page Stops Changing

This criterion is met if the DOM tree is not changing for the specified time. To set the time, open the criterion properties and specify a timeout in milliseconds in the Timeout (ms) text box.

Initial Page Load Completes

This wait criterion is met when the initial page load completes similar to the Javascript onload event.

Though this criterion does not have the Ignore All Pending Loads When Met option, by default the loading stops when all loads are met.

Waited Fixed Amount of Time

This wait criterion is met when the execution is waited for a specified time. To set the time, open the criterion properties and specify a time in milliseconds in the Wait (ms) text box.

Old Robots in Kofax RPA 9.6 and Later

When you open your Default Browser robots created in Kofax RPA version prior to 9.6, you can see the Default Waiting settings on the Advanced tab of the Robot Configuration dialog box.

Default Waiting settings for Robots from previous releases is Use Pre 9.6 Default Waiting. For such robots you can change this setting to Page Stops Changing for 500 ms.

• If Default Waiting is set to Use Pre 9.6 Default Waiting, adding a new wait criterion to a step produces the following warning.

  Default Waiting should be set to Page Stops Changing for 500 ms in the robot settings when using wait criteria.

• If Default Waiting is set to Use Pre 9.6 Default Waiting and the step is set to use the Legacy Timing wait criterion, changing the Default Waiting to Page Stops Changing for 500 ms produces the following error.

  'Default Waiting' must be set to 'Use Pre 9.6 Default Waiting' in Robot Settings when using legacy wait criteria.

Upgrading Existing Robots to 9.6

If you open your robots created in Kofax RPA version prior to 9.6 (9.3, 9.4, 9.5), depending on the Max. Wait for Timer Events and Wait Real-Time for Timer Events settings, you must perform different steps to use new wait criteria in your robots:

Max. Wait for Timer Events and Wait Real-Time for Timer Events settings are not default

If Max. Wait for Timer Events and Wait Real-Time for Timer Events settings are not set as default in your robots, Design Studio adds a non-editable Legacy Timing criteria to your robot.

This wait criterion is always green after step execution. If you add any new wait criterion, Legacy Timing is automatically removed and you can take advantage of the new Wait criteria.

Max. Wait for Timer Events and Wait Real-Time for Timer Events settings are default

If Max. Wait for Timer Events and Wait Real-Time for Timer Events settings are set as default in your robots, you need to perform the following to switch to the new default settings when updating an existing robot to 9.6: go to the File > Configure Robot dialog box, click the Advanced tab and clear the Use Pre 9.6 Default Waiting check box. Now you can take advantage of the new Wait criteria in your robots.

Fixing Page Load

In some cases when a robot uses the Use Pre 9.6 Default Waiting or Legacy Timing options, after loading the page you get the Page loading completed message, but the page is not completely loaded. This might happen when previous page loads were aborted. To fix page load, remove the Use Pre 9.6 Default Waiting option by changing it to the Page Stops Changing option and use a new wait criterion on the step.