Wait stage

The wait stage allows you to pause a business object's execution until a certain condition has been met in the target application. Examples include waiting until a window is present, or waiting for a particular status bar message. Your business object may be waiting for one of several different outcomes to occur. For example after committing new data a pop-up window could appear, an error message window could appear, or something different altogether may happen. If no change is detected, your business object may be designed to move after a particular 'timeout' period. The wait stage accommodates for this uncertainty by allowing you to branch the flow of your business object depending on the outcome observed. In this sense it is much the same as a choice stage (where the 'otherwise' option of a choice stage corresponds to the 'timeout' option of the wait stage).

Uses

A wait stage has two main uses: detecting readiness for interaction, and detecting the outcome of a particular action

A wait stage can be used to ensure the readiness of the target application. For example, after launching the application it may be necessary to wait for it to finish loading. This could be achieved by waiting for the main application window to become visible. Another example might be waiting for a 'system idle' message in the status bar before submitting new data. This could be achieved by waiting for the status bar text to read 'system idle'.

As discussed above, when multiple condition checks are made, the opportunity of branching the flow of the business object arises, depending on which outcome occurs first.

Properties Form

The wait properties form presents a list of conditions to be checked. The conditions will be checked in the order that they appear in the list, from top to bottom. As soon as one of the conditions is met, the business object follows the corresponding branch on the process diagram. There is one branch per condition, and the branches appear on the diagram in the same order as the conditions in the list. If none of the conditions is met after the last condition has been checked then the checks rebegin from the first row. This looping continues until either a condition is met or the timeout period elapses.

For example the first condition may be "check whether a 'save as' dialog exists"; the second condition might be "Check whether an error message window exists".

Each wait condition consists of an application element, a condition, a comparison type and the expected value. The application element is the target of the condition (eg the window to check that exists). The condition describes which state is to be checked against that element (eg CheckExists, GetWindowText etc). The comparison type describes how the value supplied should be compared to the data found in the target application. This may be to detect whether the data is equal, unequal, whether it matches a wildcard pattern, or to see if one value is larger than another (eg in the case of numbers) .

Adding a new wait condition

First click the "Add" button to add a new row. Then drag and drop an application element from the Application Explorer on the left into the appropriate field.

Depending on the nature of the application element (specifically whether you chose to make the application element dynamic when you created it), you may need to supply parameters to the application element by clicking the appropriate button. This allows the element to be identified using live data at runtime.

Next you should choose a condition from the drop-down list. This list varies dynamically according to the type of application element selected. If a condition does not appear in the list then it cannot be checked against the chosen application element.

You may wish to choose a custom comparison type, for example to perform a wildcard pattern match. However, in most cases it is likely that you will wish to use the default comparison type, which is a test for equality.

The last field allows you to enter the expected value. For example with CheckExists the value will be either "True" or "False", in the case of GetText the value will be the expected text. The value entered here must match exactly in order for the condition to match as positive.

Specifying a timeout period

At the very bottom of the wait stage properties form is the timeout field. This can be populated with a simple numeric value which represents the maximum amount of time in seconds that the wait stage will keep checking for one of the conditions to be met. Alternatively the timeout value can be populated with an expression. This is useful for example if you want to store a global timeout value in a data item and reference this data in all your wait stages.

If none of the conditions is met after the timeout period has elapsed, then the business object flow will follow the link from the timeout stage on the process diagram. If no such link exists then the business object will halt with an error.