Mapping controls manually

Use the recorder to manually map controls from desktop applications by placing the cursor over a control and holding the Ctrl key. After that, you can use the recorder to generate commands that references the mapped control.

The Ctrl key function

Users interact with applications by using a graphical user interface (GUI). These applications have controls like buttons, labels, text box, and tables, which are arranged in one or more windows. These controls have attributes and properties that you can use to manipulate them while you automate these applications.

The recorder brings an auxiliary window, the Control Tree, that you can use to view the application controls and their attributes and properties. Open the Control Tree by clicking the button that brings the identifier of the mapped control on the recorder's bar.

The Control Tree loads a tree view that displays a hierarchical list of controls that contain nested relationships in an application. Controls, also known as nodes in the tree view, have their own position in the tree view.

For example, an application has a main window and a text box, a combo box, and a table over it. In this application's tree view, the window is the root parent control and contains independent children controls like the Text box, Combo box, and Table controls.

These controls can have children controls and be a parent. The Table control, for example, contains cells that cannot exist individually. It means that these cells are children controls of the Table control, and the Table control is the parent of these children controls.

The following image shows a sample tree view for an application that has the Window, Text box, Combo box, and Table controls. The Window control is the root node of this tree view, the Text box control is a node without children, and the Combo box and Table controls are nodes with children.

To map controls in the application interface, you need to place your cursor over them and hold one of the Ctrl keys. By default for all drivers, the left Ctrl key maps parent controls and the right Ctrl key maps children controls.

For example, the Tree control is a node that has children that cannot exist individually, so the left Ctrl key maps the whole Tree control even if you place your cursor on a specific child node.

While in the same Tree control, the right Ctrl key maps the child control only. It happens even if you place your cursor within the control's parent area, which in this example is the Tree control area.

The following animated graphic illustrates the process to map a Tree control in a Windows™ application with both the left and right Ctrl keys:

Notice that this behavior happens when an application has controls that have children controls that cannot exist individually.

Important:The behavior described to use the Ctrl keys with controls that have children controls that cannot exist individually is valid only for IBM RPA 23.0.x. For IBM RPA 21.0.x, the same behavior changes slightly for the Java™ driver. For more information, see The Ctrl key function in the 21.0.x documentation.

However, when nodes don't have children, both the left and right Ctrl keys map controls the same way.
For example, an application has a Field control that is a child of the Pane control in the control's hierarchy. However, it is not part of the pane, since it exists individually, then both the left and the right Ctrl keys map the Field control even though the field is over the pane.

The following animated graphic illustrates the process to map a Field control in a pane for a Windows™ application with both the left and right Ctrl keys:

In addition, you can also use the Ctrl+Shift keys to map controls by using an improved algorithm. Both the left and right Ctrl keys get the full control tree for an application.

Important:Drivers might behave differently regarding some controls. Some controls for one driver might not support to map their children, or some of that just maps the children for both Ctrl keys and doesn't map the parent, for example.

Performance

The recorder's performance might degrade if the application that you are mapping has many nested controls. In such scenarios, the recorder can take longer times to highlight a control.

Drivers and highlighted colors

When you map a control with the Ctrl key, it highlights in one color. The color indicates the driver that you are using:

  • The green highlight means that the active driver is the Windows™ driver.
  • The red highlight means that the active driver is the Java™ driver.
  • The purple highlight means that the active driver is the SAP driver.

Map controls on layered panes for Java applications

The Java driver requires that you use the Ctrl key to map controls based on the layer that they are placed. If a control is in front of the other, you use one of the Ctrl keys to get the control in the first layer, and the other key to get the controls behind the first layer. Use the following rules to map controls in this case:

  • The right Ctrl key maps the control on the first layer.
  • The left Ctrl key maps the controls behind the first layer.

Before you begin

This procedure assumes that you installed the drivers that are needed to record Windows™ or SAP™ applications, and started a driver.

Procedure

The following steps show how to map desktop application's controls developed under Windows™ or SAP™ technologies:

  1. In the recorder's menu bar, click Recording to enable it. The button turns from gray to blue.
  2. Place the cursor over a control.
  3. Hold one of the following keys on your keyboard until the control gets highlighted:
    • Hold the left Ctrl key to map parent controls.
    • Hold the right Ctrl key to map children controls.
    • Hold left Ctrl+Shift or right Ctrl+Shift to map the control by using an improved algorithm.
Tip:Read the Ctrl key function section for more information about how the Ctrl keys work, and how each driver behaves when you map a control.

What to do next

Use the recorder to generate commands that references the mapped control. In the recorder's bar, click the Window, Verify, Actions, and Image Grid menu options to add specific commands to your script. In IBM RPA Studio, you can go to the toolbox, and look for these commands are under the Windows category.