The X-Ray desktop tool is essential when you need to capture specific values from an application's UI that cannot be obtained from the URL or window title. These values often represent additional dimensions of a structured process.
For example, while tracking a BPMN process in a web application, you can capture the task ID for a task from the URL. However, if you also need to capture the task status and assignee, then these details are only accessible from the background data in the web application. In this case, you would use the desktop tool to capture an X-Ray of the window.
Once the X-Ray is captured, the desktop tool enables you to precisely identify the data points from the UI and automatically generate data collection rules for them.
The X-Ray desktop tool has the following main components:
X-Ray File Selector: All captured X-Ray files are listed here. You can easily switch between files by clicking on the file name in the list. Each file includes a timestamp showing when the X-Ray was captured, along with the active process name.
Application Screenshot: When an X-Ray is captured, a screenshot of the active window is taken. This section displays how the window appeared at the time of capture.
UI Tree: This section shows all UI elements from the selected X-Ray, with the underlying page structured based on the screenshot.
Filtering: You can search for specific elements within the UI tree by applying filters. Details on how to use filters are provided in the next section.
Show Parent Elements: By default, the UI tree displays individual elements without their parent context. To view elements in a tree structure, simply check the Show Parents option.
Selected Element Data: By clicking an element in the UI tree, you can view all the data available for that element, which can be captured during data collection.
Pattern Window: This section shows the navigation path to the selected element. If the element contains data you'd like to capture, you can copy the text from this box and paste it into X-Ray Tooling → Step 4 to configure the data collection.
The search box can be opened by clicking the Filter button. In this search box, you can write simple Python queries to find elements. Typically, your query will consist of three main components:
The search string is often determined by reviewing the application screenshot and recognizing the relevant text within the target element.
For instance, to identify the element displaying the value for "Cases Started" in the image shown below, you can search for a specific value such as 14.
Since the values are strings, they should always be enclosed in double quotes. For example, to search for the element displaying the value for "Cases Started," the search string would be "14".
The most commonly used operators are == (equals), != (not equal), in, and not in. For example, to search for an element where the value is equal to 14, the query would be: "14" ==.
Sometimes, it may be more effective to match only part of the text within the element. In such cases, you can adjust the query accordingly.
Field to Use in Search There are several fields available for matching the search string. By selecting an element, you can view the available fields in the element’s data and choose the most appropriate one.
There are several fields available to match the given search string. By selecting an element, you can view its data to see which fields are available for use in the search.
When searching text from a screenshot, it is most commonly stored in the Label, Value, or Name fields, depending on the application. In our example, the value can be found in either the Name or Label fields. Therefore, our final query could be:
"14" == LabelOR"14" == Name
Additionally, you can also define multiple query conditions with or/and operators. Here are some examples:
"14" == Name and ControlTypeName == "TextControl"
"process-counter-total" == ClassName
"Completed" == Name or "In Progress" == Name
"Invoice" in Label and "navigation" not in ClassName
After identifying the element containing the value you'd like to capture for data collection, you'll need to determine the navigation path within the UI tree. For this, the X-Ray tool provides the Pattern Window. By selecting the element, you will be presented with instructions guiding you to navigate to the element.
Follow these steps to configure data collection for the element:
Copy the text from the Pattern Window.
Navigate to Admin Panel → Configure Data Collection → Advanced Setup → X-Ray Tooling.
Go to step 4 and select the application and window where the element’s data should be captured.
Paste the text from the Pattern Window into the Paste Reaction field.
Assign a name to the captured element (e.g., Cases Started based on the earlier example).
The last part of the copied instructions contains an Extract command:
{"Extract": {"Property": "Name", "As": "Name"}}
This command specifies that the value of the Name field/property will be captured. If you want to capture a different field from the UI element, manually modify the "Property": "Name" part before saving.
For instance, if you want to capture the Label field, the Extract section should look like this:{"Extract": {"Property": "Label", "As": "Name"}}
It’s important not to modify the "As": "Name" section to ensure proper functionality.
To activate the reaction:, Go to Admin Panel → Structured Processes.
Add a new Dimension to an existing process. The dimension name can match the name of the captured element, such as Cases Started.
From the Key dropdown, select the captured element you just added.
