Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

X-ray Vision

Updated on September 30, 2022

X-ray Vision is a powerful method of identifying controls in applications, so you can use those controls in your automations.

When interrogating or recording an application, if new controls become available in the application (due to navigation of the application, or from a screen change that makes new controls appear), the new controls are added to the X-ray database file for the application. The system assigns each control a numeric PegaId that is stored in the X-ray database file for the application, along with a collection of attributes that define the control.

When you interrogate a control to use it in an automation, the PegaId is set as the match rule that maps the adapter's object to the control within the X-ray database file. This PegaId match rule never needs modification. When the X-ray Vision engine sees the control a second time, it compares all of its attributes to those stored in the database, to determine the best attribute to use. The database file is constantly updated while the application is in interrogation mode.

When you create the automation package during the deployment process, the system includes the database files. Robot Runtime uses these files to provide the attribute values that are used for control identification. If an attribute changes for a control in Runtime, the engine continues to track the control by finding the next best attribute to use. The system keeps this attribute change in memory until you close Robot Runtime.

X-ray Vision supports .NET, WPF, and Windows Form applications.

PegaId match rule

When you enable X-ray Vision for an application, the controls that are interrogated in the application are assigned a PegaId match rule. This match rule ties the control to the application’s .xraydb file. Only the PegaId match rule is needed when you enable X-ray Vision for the adapter. Do not include additional match rules when using X-ray Vision and the PegaId match rule.

PegaID match rules

When to use legacy match rules versus X-ray Vision

In most situations, X-ray Vision is the best solution for identifying controls in an application. However, there are times when you should use legacy Match Rules.

Here are a few limitations of using X-ray Vision:

  • X-ray Vision is not supported for applications that contain embedded frameworks. For example, if you start a Windows Presentation Foundation (WPF) application that has embedded controls, X-ray Vision assigns PegaIds for the WPF controls. Legacy match rules are used for embedded controls of a different framework than the application.
  • X-ray Vision is not supported for the Infragistics ultratab control.
  • The PegaId match rule is not available for top-level forms, context menus, or menu items. Use legacy match rules for these controls instead.

Enabling X-ray Vision

Check the Enable X-ray Vision box with the application open to turn on X-ray. Enabling X-ray Vision enables Automatic Step Creation in Intelligent Recording.

  1. In Pega Robot Studio, open the application you want to use X-ray Vision for.
  2. Enable X-ray Vision

  3. In the Properties Grid, check the EnableX-rayVision checkbox to enable the feature for this application. By default, X-ray Vision is disabled for a newly added application, so it must be enabled.
    When you interrogate an application with X-ray Vision, Robot Studio creates four files in the X-ray folder, located in the project folder. If an application starts other applications, Robot Studio creates a set of four files for each application.
    Each file is named with a shared GUID. The files represent the application whose data they store, and have the following extensions:
    • .xrayConfig – Contains configuration information for the application.
    • .xrayDb – Contains the X-ray control information that has been collected for the application. This includes the assigned PegaId, the technique used to identify the control, and the attribute values.
    • .xrayTad – Contains attributes and their weights that have been modified for the application from the default framework TAD file (Tagged Array Data).
    • .xray – The .xray file is the master file that contains the name of the application executable in its file name, along with the GUID. This file makes it clear which files belong to what application, tying the .xrayConfig, .xrayDb, and xrayTad files together for the application. For example:
      GUID.APPNAME.xray [master]
    When you deploy an automation, all of these files are included, along with the default framework TAD files. Robot Runtime uses these files as it executes the automation.

Universal Web Adapter considerations

While you can use X-ray Vision with Universal Web Adapter (UWA) applications, there are some important considerations.

Note: The following UseKeys considerations only apply when you are using X-Ray Vision and the Universal Web Adapter. These considerations do not apply when you are using X-ray Vision to interrogate .NET or Windows Presentation Foundation applications.

When you use X-ray Vision and the Universal Web Adapter, consider the following limitations:

  • Do not enable UseKeys, unless you are in interrogation mode. Controls have to be matching in interrogation mode.
  • When you enable a property for the control, Robot Studio displays the following message:
    Match Rule confirmation message
    Message box saying that legacy match rules will be used for this control.

    To have Robot Studio convert the match rules for the control, and any children of those legacy match rules, click OK. If you change UseKeys to false after you click OK, Robot Studio will continue to use the legacy match rules. To go back to using the PegaId match rule, delete the control and interrogate it again.

  • If you try to enable UseKeys when the control is not matching or before you start interrogation, Robot Studio displays the following error message:
    Match Rule error message
    Error message stating that you must be in interrogation mode to enable UseKeys.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us