About Selectors

To automate specific actions in the user interface, you are required to interact with various windows, buttons, drop-down lists and many others. One of the ways in which UI elements can be identified is by using their position on the screen, but this can be unreliable.

To overcome this problem, Studio uses what we call selectors. These store the attributes of a graphical user interface element and its parents, in the shape of an XML fragment.

Most of the times, selectors are automatically generated by Studio and do not require further input from you, especially if the apps you are trying to automate have a static user interface.

However, some software programs have changing layouts and attribute nodes with volatile values, such as some web-apps. Studio cannot predict these changes and, therefore, you might have to manually generate some selectors.

A selector has the following structure:

<node_1/><node_2/>...<node_N/>

The last node represents the GUI element that interests you, and all the previous ones represent the parents of that element. <node_1> is usually referred to as a root node, and represents the top window of the app.

Each node has one or more attributes that help you correctly identify a specific level of the selected application.

Each node has the following format: 

<ui_system attr_name_1='attr_value_1' ... attr_name_N='attr_value_N'/>

Every attribute has an assigned value. It is important to pick attributes with a constant value. If the value of an attribute changes each time the app is started, then the selector will not be able to correctly identify the element.

Selectors are displayed in the Properties panel of activities, under Input > Target > Selector. All activities related to graphical elements have this property.

The Selection Options window enables you to select and edit a target. To access this window, in the Workflow Designer panel, click the Options button in the body of an activity and select Indicate target on screen or Edit target.

The Selector Editor window enables you to see the automatically-generated selector and edit it and its attributes. To access this window, use the Ellipsis button next to the Selector field, in the Properties panel.

Option	Description
Validate	The button shows the status of the selector by checking the validity of the selector definition and the visibility of the target element on the screen. The Validate button has three states: Selector is being validated Valid selector Invalid selector Modified selector, revalidate The button is correlated with UI Explorer validation states.
Indicate Element	Indicate a new UI element to replace the previous one.
Repair	Enables you to re-indicate the same target UI element and repair the selector. This operation does not completely replace the previous selector. The button is available only when the selector is invalid.
Highlight	Brings the target element in the foreground. The highlight stays on until the option is disabled with a click. The button is enabled only if the selector is valid.
Edit Attributes	Contains all the application components needed to identify the target application (a window, a button etc.). This section is editable.
Edit Selector	Holds the actual selector. This section is editable.
Open in UI Explorer	Launches the UI Explorer. The option is enabled only for valid selectors.

Note: In some situations, when Studio and the targeted application are opened with different elevated privileges, the selector might not work. We recommend to always open both applications with the same privileges.

Supported tags and attributes

The following tables present the compatibility between tags and attributes used to build selectors and the selector capability:

Note: Selectors generated for Java applications which contain multiple WND tags cannot be used with events monitoring.

WND

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
app	The file name of the application containing the UI element.
cls	Class name of the window containing the UI element.
title	The window title of the UI element.
aaname	'Active Accessibility' name of the UI element.
ctrlname (WinForms)	WinForms name of the UI element.
ctrlid (WinForms)	Win32 control ID of the window containing the UI element.
idx	The instance number of the UI element.
tid	ID of the thread that created the UI element.
pid	Process ID of the application containing the UI element.
isremoteapp
aastate	'Active Accessibility' state of the UI element.
sapClient (SAP)	SAP Client selected on the login screen.
sapLanguage (SAP)	SAP Language specified on the login screen.
sapProgram (SAP)	SAP source program that is currently being executed.
sapScreen (SAP)	SAP Screen number currently displayed.
sapSession (SAP)	SAP Session Number, also displayed in SAP GUI statusbar.
sapSysName (SAP)	SAP System Name.
sapSysNumber (SAP)	SAP Application server.
sapSysSessionId (SAP)	All SAP GUI sessions of the same connection are represented on the server with the same SysSessionId.
sapTransaction (SAP)	SAP Transaction that is currently being executed.
sapUser (SAP)	SAP User logged into the system.

HTML

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
url	The URL of the web page containing the current element.
htmlwindowname
title	The window title of the element.
class	Class name of the accessible context of the element.
app	The file name of the application containing the UI element
idx	The instance number of the UI element.
pid	Process ID of the application containing the UI element.
tid	ID of the thread that created the UI element.
excludehwnd
bsid (Browser Session ID)
isremoteapp

WEBCTRL

The tag and idx attributes use string values. All other WEBCTRL attributes have dynamic values.

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
tag	HTML tag of the element.
idx	The instance number of the UI element.
aaname	'Active Accessibility' name of the UI element.
name	Name property of the UI element.
id	The unique identifier of the UI element.
parentid	HTML ID attribute of the fist ancestor element that have ID.
class
css-selector
innertext	The innerText property of a HTML element.
visibleinnertext
isleaf
parentclass	HTML class attribute of the fist ancestor element that has class.
parentname	HTML name attribute of the fist ancestor UI element that has a name.
src	Specifies the location, or source of the element.
href	The URL of the page the link goes to.
tableCol	Table column number that contains the UI element.
tableRow	Table row number that contains the UI element.
colName	The name of the table column that contains the UI element.
rowName	The name of the table row that contains the UI element.
aria-label	Aria label attribute of the element.
aria-labelledby

CTRL

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
role	The 'Active Accessibility' role property of the UI element.
name	Name property of the UI element.
automationid	The 'UI Automation' ID of the UI element.
labeledby	The 'UI Automation' labeled by attribute of the UI element.
aastate	'Active Accessibility' state of the UI element.
virtualname	The name of the element given by the underlying accessibility technology.
text	The text of the UI element as it appears on the screen.
rowName	The name of the table row that contains the UI element.
idx	The instance number of the UI element.

UIA

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
accelkey (Accelerator Key)
acskey (Access Key)
automationid	The 'UI Automation' ID of the UI element.
cls	Class name of the window containing the UI element.
helpText	The help string of the UI element.
legacyAccHelp (Legacy Accessible Help)
enabled
kbfocus (Is Keyboard Focusable)
ispwd (Is Password)
itemstatus
itemtype
rtid (Runtime ID)
role	The 'Active Accessibility' role property of the UI element.
name	Name property of the UI element.
pid	Process ID of the application containing the UI element.
tableRow	Table row number that contains the UI element.
tableCol	Table column number that contains the UI element.
rowName	The name of the table row that contains the UI element.
colName	The name of the table column that contains the UI element.
idx	The instance number of the UI element.

JAVA

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
role	The 'Active Accessibility' role property of the UI element.
name	Name property of the UI element.
virtualname	The name of the element given by the underlying accessibility technology.
javastate	The state of the UI element as provided by 'Java Accessibility Bridge.
tableRow	Table row number that contains the UI element.
tableCol	Table column number that contains the UI element.
rowName	The name of the table row that contains the UI element.
colName	The name of the table column that contains the UI element.
idx	The instance number of the UI element.

SAP

Attribute	Description	Fuzzy	RegEx	Case-Sensitive
id	The unique identifier of the UI element.
leafid	This attribute is not exposed in the Attribute panel because it is mutual-exclusive with the id attribute. It can be added manually.
tableRow	Table row number that contains the UI element.
tableCol	Table column number that contains the UI element.
colName	The name of the table column that contains the UI element.
relpath
itemId

SILVERLIGHT

Please note that the Silverlight tag does not support Fuzzy, RegEx, and Case-Sensitive capabilities.