Status: Validated

Declaration of Page Items

Once a page has been declared, items can be added to the configuration. The declaration of an item involves:

  • Associating it with a component in the page capture (selecting),
  • Setting the item parameters,
  • Defining the criteria that allow the software to recognize this item on the page.

Declaration of items is performed offline, from the page captures.
Even the validity of criteria can be tested offline.
Final validation must be performed online on the running application.

Selecting a page in the Project Tree allows you to work on a page capture.

The capture of the page is displayed:

Associate a Component With a New Item

Right-clicking a component in the Screen Display and selecting the 'Associate to a new Item' context menu lets you associate a component with a new item.
The same can be achieved by double-clicking the component.

The same method is available in the Tree Display, the SubTree tool window, and in the Text Tool Window.

The item is added to the page items in the Project Tree and an internal link is memorized between this item and the component selected in the screen capture.

The new item is created with default parameters and default criteria.
The default criteria depend on the technology:

  • For Windows items, there is no default criterion,
  • For Web Items, the default criterion is the tag of the component.

If the action is performed from the Text tool window, a criterion is added on the 'Text' property.
These parameters and criteria can be edited in the 'Item properties' panel (described later).

Associate an Existing Item With a Component

Associating an existing item with a component is necessary when:

  • Changing the component already associated with the item,
  • There is no component associated with it (the item was created before the capture).

Association is performed by selecting the existing item in the Project Tree, right-clicking the component in the Screen Display and selecting the 'Associate to the selected Item' context menu.

The same method is available in the Tree Display, the SubTree Tool Window, and the Text Tool Window.

The parameters and criteria of the existing item remain unchanged.

Quick-Add Criteria to an Item

Criteria can be added directly from the Captured data tool window by double-clicking the Property that requires a new criterion.

If the selected component is not yet associated with an item, a new item is automatically created.
Otherwise, the pointing item is automatically selected.

The criterion is set on this property, with its complete value and the default scan value for this property.

Once an item has been created, various elements can be set in order to define it:

  • The item parameters,
  • The criteria used for item recognition,
  • The technical events notified by the item.

Selecting the item in the Project Tree gives you access to the 'Item definition' panel.

Set Item Parameters

Page Parameters Tool Window

The Parameters Tool Window lets you set the item parameters:

General category
Name Name of the entity used in scripts to monitor the item
Comment Description of the entity
Folder Used to organize items (see Project Tree).
Useful when you have a large number of items.
Technical Indicates that the page/item is technical (true) or functional (false).
Technical pages/items are filtered in Perspectives other than the Explorer.
Driver category
Parameters specific to each technology
Technical category
Driver Name of the driver used to monitor the application (read-only)
Offlinepath Path where page captures are stored (read-only)
Technology Technology of the page (read-only)

A description of each parameter is available in the 'Help' panel (2).

Track Events Tool Window

Set Item Tracked Events

The Track Events Tool Window lets you set the technical events monitored on the item.

The list of available technical events depends on the page technology.
A description of each event is available in the 'Help' panel.

Set Item Criteria

There are two methods used to specify item criteria, depending on the page technology:

  • The 'Single Component' method, which consists in setting criteria on the properties of the component to recognize,
  • The 'Components pattern' method, which consists in setting criteria on a pattern of one or more components to recognize, one of these components being the component to target.

The 'Single Component' method is used in any technology available with Desktop Studio.
The 'Components pattern' method is only used with Web and UIAutomation technologies.

'Single Component' Method

Page Captured Data Tool Window

Page Criteria Tool Window

The Captured Data Tool Window shows the properties of the component that can be used as criteria.

These properties are collected when the page is captured.
This tool window is empty if the page was captured with the Desktop Studio.

The properties captured depend on the page's technology and on the connectors: only the properties used by the connector are captured.

The Criteria Tool Window lets you edit the criteria of the item that will be used by the connector to recognize an item at runtime.

For a complete description of this tool window, refer to Criteria Management

'Components Pattern' Method


The 'Components pattern' method consists in recognizing a set of related components (a pattern), rather than a single component.

In this case, components are linked together by a parent-child relationship.
One of these components is the target one and is addressed in the project.

This method is useful when the target component has no (or insufficient) discriminant properties.
It also lets you define a 'Components pattern' with only one component, which is equivalent to the single-component method.


For example, suppose a Web page has several TABLE components.
We want to target the TABLE component that has a column header 'Date'.

Object Pattern criterions We can define the following components pattern:

  • One component (the target one) that recognizes the TABLE component (1),
  • One child component that recognizes the TH component that has the 'Text' property equal to 'Date' (2).

Build the 'Components Pattern'

  • First, create the item from the page capture,
  • The SubTree tool window(1) shows a part of the complete captured page tree. It is centered on the component associated with the item, letting you add components to the pattern to recognize:
    Object Pattern Criteria
  • To add a component to the pattern, right-click the component in the SubTree Tool Window(1) and select 'Add as new Component in the pattern' in the context menu.
    The Component is added in the Criteria Tool Window (2).
    Object Pattern Criteria
  • To remove a component from the pattern, right-click the component in the Criteria Tool Window (2) and select 'Remove Component' in the context menu.

The 'Components Pattern' Properties

'Component pattern' properties can be set in the Criteria Tool Window (2).

The parent-children relationship

When added, components are automatically set at the right position in the pattern.
This position is determined by the relative positions of the associated components.

Associated components must have a parent-children relationship. It is not possible to add a sibling component.

The depth of the relationship between recognized components can be set via the 'Children' checkbox.
If checked, the component recognized must be a direct child of the component recognized as the parent in the pattern.

In the preceding example, if the 'TH' component has the 'Children' checkbox checked, the 'TABLE' component target will not be recognized because the 'TH' recognized component is not a direct child of the 'TABLE recognized component.

The 'Occurs' Property

The 'Occurs' property of a Component can be used if we want to address a collection of components.
This is mainly used to set this property on the target component, but it can be set on any upper component in the pattern.

The 'Target' property

The 'Target' property is used to change the target component of the pattern.
The target component is highlighted in bold in the pattern tree.

The Component Criteria

The Item Criteria

  • To edit the criteria of a component in the pattern, select the component in the pattern tree (2).
    The associated component is automatically selected in the Captured data tool window (2).
  • Component criteria can be managed the same way as with the 'Single-Component' method.

In HLLAPI, an item is defined by:

  • Its 'X' and 'Y' coordinates,
  • Its 'CX' width,
  • Optionally, if it's a 'MustExist' label, its TEXT.

Declaration of items with HLLAPI is a little different than with other technologies.
An HLLAPI page capture doesn't contain components, but only the text of the screen.

That means that in order to declare a new item, you have to select the relevant part of the text instead of the component. After selecting the text, right-clicking the selection gives you several options:

  • Associate with new item: create a new item with the X, Y, CX value of the selection,
  • Associate with new MustExist Label: create a new 'MustExist' item with the X, Y, CX, TEXT value of the selection,
  • Associate with the selected item: update the selected itemwith the X, Y, CX value of the selection.

Item Declaration on an HLLAPI Page

A soon as an item has at least one criterion, Desktop Studio attempts to recognize it. When selecting an item in the Project Tree, its associated element (if any) is bordered by a blue rectangle.
As a result, its recognized Component(s), if any, is bordered by :

  • A green rectangle if it matches with the associated one.
    As the two rectangles match, only one green rectangle is visible:
  • A red rectangle if not.
    As the two components don't match, two rectangles, one blue AND one red, are visible:

Using the Recognition Tool Window

The Recognition Tool Window helps you to investigate the cases where there's no recognized component or where the recognized component is not visible.

For a fuller description of item recognition, see Using Recognition.

Choose the Current Capture for Recognition

When several captures have been created for a page, you can manually select the capture to use for recognition by selecting its Tab (1, 2, 3, …) in the Capture Selector.

When selecting an item in the Project tree, the current capture is automatically set to the one where the item was pointed.

This behavior can be disabled by locking the current capture using the button in the Capture Toolbar.