SAP Help - Desktop Stu Dev Guide

Developer Guide | PUBLIC
Document Version: 1.0.0 – 2023-04-30
Desktop Studio Developer Guide

© 2023 SAP SE or an SAP affiliate company. All rights reserved.
THE BEST RUN

Content
1 Developer Guide Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.1 Architecture Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
1.2 About Desktop Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How Desktop Agent Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Software Architecture of Desktop Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3 About Desktop Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
The Explorer Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The Workflow Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
The Editor Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
The UI Designer Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
The Debug Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Accessibility Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
1.4 Code Editing Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Navigation Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Search Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Code Editor Help Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
1.5 About Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Overview of Project Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Project Structure and Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Project Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2 Capturing, Declaring and Controlling Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

2.1 Technology Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
The Web Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
The UI Automation Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
The SAP GUI Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
The SAPUI5 and S/4HANA Connectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
The Win32 Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
The Java Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
The HLLAPI Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
The OCR Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Controlling Individual Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Multi-Instance Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Controlling Entities Using the Desktop SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
2.2 The Declaration Phase: General Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Entities for a Desktop Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Entities for a Web Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

2 PUBLIC Content
Entities for a Mainframe Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Declaring Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Declaring Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Page Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Declaration of Page Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Criteria Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Controlling Pages with Event-Driven UI Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
2.3 Advanced Declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
About the Recognition Mechanism. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Making Robust Capture and Declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Advanced Recognition Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
3 Designing Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

3.1 Bootstrap your Project with Workflow Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Main Steps in Creating a Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Setting Timeout Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Workflows and Functional Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Activities and Where to Use Them. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
3.2 Scenario Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
3.3 Control Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
3.4 Designing Control Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
3.5 Managing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
3.6 Designing Scenarios Through Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Managing Steps and Scenarios Using Desktop SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Declaring Steps with Desktop SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Declaring Scenarios with Desktop SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Managing Merge Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Managing Loops and Conditional Switches in Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Managing Data Within a Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Starting a Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Stopping a Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358
Managing Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Managing Timeouts in Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Declaring Environment Variables from SAP Intelligent RPA Factory. . . . . . . . . . . . . . . . . . . . . . 368
3.7 Designing Scenarios Involving Citrix or RDP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Example Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
3.8 Business Activity Monitoring (BAM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Use BAM in a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
BAM Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
3.9 Script Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Add a New Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Edit a Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Content PUBLIC 3
Move a Script to Another Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Rename a Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Exclude a Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Delete a Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Editing the XML List of Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
3.10 Systray and Menu Bar Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
3.11 Display Message Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
3.12 Display Tooltips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
3.13 Managing Popups With Desktop SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Create a Popup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Customize the Popup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Open the Popup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .402
Wait Until the Popup Closes and Get the Popup Result. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
4 Managing Custom Pages With UI Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404

4.1 The UIDesigner Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .409
4.2 Advanced Techniques for Custom Page Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417
5 Testing and Deploying Your Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

5.1 Building a Project for Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Compiling a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
5.2 Exporting a Project for Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Exporting a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Converting a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
Deploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
5.3 Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Debugging Your Code with Script Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Debugging and Testing with the Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Debugging Offline with Debug Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Offline Debugging – Trace Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Offline Debugging – Audit and Diagnoses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
5.4 Using TraceViewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
5.5 Recognition Error Cases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
6 References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
6.1 Commands Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Main Window Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Code Editor Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Project Tree and Script Tree Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
6.2 Code Snippets Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
6.3 File and Folder Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
6.4 Multilingual Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

4 PUBLIC Content
6.5 Registry Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
6.6 XML/JSON Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .496
6.7 Clipboard Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
6.8 Cryptography Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
6.9 Microsoft Office Excel Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
6.10 Microsoft Office Outlook Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .502
6.11 PDF Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
6.12 Single Sign On Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
6.13 Managing External Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
6.14 Web Service Calls and Remote File Download. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
6.15 Understanding Asynchronous and Synchronous Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
6.16 Managing Technical Events Using the Desktop SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
6.17 Customizing a Windows Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
6.18 Customizing a Web Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
7 Best Practices for the Desktop Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

Content PUBLIC 5
1 Developer Guide Overview
Congratulations on acquiring SAP Intelligent Robotic Process Automation. If you want to create your first
automation project and your first bots, this document will guide you through this journey.
Please take the time to read About Desktop Studio [page 8], where we will present the different perspectives
of the tool.
You should also read the Capturing, Declaring and Controlling Applications [page 67] section as it contains
important information on how to identify UI elements in the applications that you would like to automate.
The business logic and sequences of actions are explained in Designing Scenarios [page 287].
You can start with the Workflow Designer, which will help you to design your first project. As projects can be
complex, a good knowledge of JavaScript is recommended to leverage the full power of Desktop Studio, deploy
jobs to Desktop Agents, and orchestrate them with Cloud Factory.
Before you start to use Desktop Studio and Desktop Agent, set up Cloud Factory and register your workstation.
For more information, see the Installation Guide.
1.1 Architecture Overview
SAP Intelligent Robotic Process Automation is a cloud solution (Cloud Factory) that works with the on-premise
components Desktop Agent and Desktop Studio.
Solution Components
SAP Intelligent Robotic Process Automation is composed of different elements:
Desktop Agent

6 PUBLIC Developer Guide Overview
• Is a software component that is installed on a user's workstation and leverages the user session
• Requires an automation scenario, that is, a set of scripts describing what is expected. These scripts are
authored using Desktop Studio and deployed through Cloud Factory.
• Uses existing applications to perform the corresponding tasks
• Controls applications by replicating user actions or by handling regular events
• Requires a connection to Cloud Factory in order to work properly
Cloud Factory
• Is a software component that runs and is hosted on SAP BTP (Business Technology Platform)
• Centrally manages all common resources related to SAP Intelligent Robotic Process Automation:
• Management of environments
• Management of agents and agent groups
• Deployment of projects through packages and configurations
• Controlling of jobs, agents, and triggers
• Cloud Factory then deploys the projects, scenarios, or even jobs (both attended or unattended usage) to
Desktop Agent
Desktop Studio
• Is a software component that is installed on a developer's workstation

• Is the tool for authoring all process automation aspects including
• Application capture and recognition
• Scenarios and workflows
• Testing and debugging
• Desktop Studio requires Desktop Agent and a connection to Cloud Factory in order to work properly (for
more details about prerequisites, see Technical Prerequisites and System Requirements)
1.2 About Desktop Agent
1.2.1 How Desktop Agent Works
Desktop Agent is one of the on-premise components that works with SAP Intelligent Robotic Process
Automation.
Here's how it works:
• Desktop Agent is installed on a workstation and has a set of connectors for different technologies that help
it control applications.
• Desktop Agent has a work manager component that receives messages from the connectors. The work
manager component decides how to handle the messages (including determining whether they are
relevant to the project) as defined by the configuration scripts.

Developer Guide Overview PUBLIC 7
• Desktop Agent maintains a set of variables for each application (known as context or data type). It also
maintains a list of libraries containing methods that can be used to interact with applications.
• The project is developed on a specific development workstation running SAP Intelligent Robotic Process
Automation Desktop Studio. It's then exported to a central repository (Cloud Factory). When each
workstation in the project is started, it downloads the configuration files from this central repository.
1.2.2 Software Architecture of Desktop Agent
Desktop Agent has several components:
• An application launcher that starts processes and downloads project files

• A work manager that executes projects
• A set of connectors to interact with various application technologies, such as:
• Windows OS
• Native Windows applications
• Web applications
• Java applications
• Terminal applications (HLLAPI)
• SAP applications and technologies
• A JavaScript engine to execute libraries and implement specific behaviors
• An HTML engine to display popups, forms, and mash-up Web interfaces
1.3 About Desktop Studio
SAP Intelligent Robotic Process Automation is used to automate parts of external applications.
Perspectives
Desktop Studio is structured according to the concept of perspectives. A perspective is a workshop dedicated
to a specific development task. Desktop Studio includes the following perspectives:
• The Explorer Perspective [page 9] used to declare applications

• The Editor Perspective [page 23] used to develop automation scripts
• The Debug Perspective [page 41] used to control execution of automation
• The Workflow Perspective [page 22] used to design workflows
• The UI Designer Perspective [page 33] used to design user interfaces
The Desktop Studio Integrated Development Environment
When launched, Desktop Studio opens the Main window shown below.

This window comprises the following panels:
• The Menu bar (1)

• The Toolbars (2)
• The Perspective selector (3)
• The current perspective panel (4)
• The Status bar (5)
1.3.1 The Explorer Perspective
Purpose
The Explorer perspective provides a graphical interface for declaring applications. It lets you:
• Perform screen captures (including screenshots and internal page structures).

• Work offline without access to the live applications.
• Define recognition criteria based on the captures.
• Check page and item criteria to identify potential conflicts and ensure items are declared in an
unambiguous way.
• View a graphical overview of all pages declared in an application.

The Explorer Perspective Panel
The first time you start Desktop Studio or open a project, the Explorer perspective panel appears.
Hover over each panel for a description. Click the panel for more information.
• The Capture Panel [page 15]

• The Project Tree [page 14]
Tool Windows in the Explorer Perspective
The Explorer Perspective contains the following tool windows:
• Parameters
• Track Events
• Text
• Name
• Subtree
• Criteria
• Capture data
• Recognition
These tool windows are described below.

Layout Management
You can dock tool windows anywhere in the Explorer Perspective by dragging and dropping their title bar. You
can also close some of them using the cross button on the title bar. All available tool windows are listed in the
View\Tool Windows main menu. To display or hide a tool window, simply check or uncheck it.
You can save your current layout by clicking View Layout Save . This layout will then be restored the
next time you start Desktop Studio. To restore this layout without restarting Desktop Studio, click View
Layout Restore .
The Parameters Tool Window
This window lets you view or edit item, application, or page parameters. It consists of:
• A parameters panel (1)

• A help panel (2)
A description of each parameter is available in the help panel (2).
For more information on using this tool window, see Declaring Applications [page 249], Declaring Pages [page
252], and Declaration of Page Items [page 262].

The Track Events Tool Window
This window lets you check/uncheck event tracking for an item, application, or page.
A description of each event is available when you hover over the checkboxes.
For more information on using this tool window, see Declaring Pages [page 252] and Declaration of Page Items
[page 262].
The Subtree Tool Window
This tool window shows a part of the tree view associated with the item selected in the current view. It contains
up to three parent levels of this item, including all children.
 Note
You can change the depth of the subtree (between 3 and 10 levels) using the slider on the left.

This subtree can be useful with some technologies (such as Web), where the focused component in the screen
view is not always the best one to capture. It is used just in the same way as the tree display, except that it
displays only part of a tree.
This tool window is synchronized with other tool windows and views: selecting a component in this tool window
selects the same component in the other tool windows/views, and vice versa.
The Text Tool Window
This tool window shows all the components that have a non-empty Text property. The Text property depends
on the technology:
• For Windows, it is the text of the component

• For Web, it is the inner text of the component (only for the leaf elements without children)
This tool window can be useful for detecting invisible components, such as menu items.
As in the tree display, right-clicking a component displays a context menu that lets you:
• Associate the component with a new item

• Associate the component with an existing item
• Add the component to an item components pattern
• Create a new subpage from the component
• Associate the subpage with the selected page
This tool window is synchronized with the other tool windows and views: selecting a component in this tool
window selects the same component in the other tool windows/views, and vice versa.
The Criteria Tool Window
This tool window allows you to view and edit item (or application and page) criteria. It consists of:
• A criteria tree (1)

• An editing panel (2)
A complete description of this tool window can be found in Criteria Management [page 269].
The Captured Data Tool Window

This tool window lets you view the captured properties:
• Of the application or page selected in the project tree

• Of the component associated with the item selected in the project tree
• Of the component selected in the capture view.
When you right-click a property, a context menu appears that lets you:
• Copy the property value to the clipboard

• Add a criterion to the property.
If you add a criterion to a property of a component that is not associated with any item, a new item is created
automatically. For a complete description of this tool window, see Criteria Management [page 269].
The Recognition Tool Window
This tool window shows the component associated with the selected item and the corresponding recognized
components, if any. It lets you investigate recognition problems.
For a complete description of this tool window, see About the Recognition Mechanism [page 276] .
1.3.1.1 The Project Tree
The project tree displays all of the applications, pages, and items that are declared in the current project. It lets
you:
• Select a declared element to see its captured and declared properties

• Declare new elements
• Edit application, page, and item declarations
• Rename existing elements (with F2 )
• Move pages and items
• Delete elements
Each node (element) in the tree has a shortcut menu with the main functions associated with that element. For
more information, see Commands Reference [page 474].
Elements of the tree are colored as follows:
• Green if the element has been recognized

• Red if the element is not recognized
• Black if no recognition has been attempted on that element
For a full explanation, see About the Recognition Mechanism [page 276].
1.3.1.2 The Capture Panel
Depending on what you selected in the project tree, the Capture panel displays one of two views:
• The Application view if you selected an application

• The Page view if you selected a page or an item
The Application View
The Application view displays a mosaic consisting of one thumbnail (1) for each page declared in the selected
application.
If a page has several captures, only the first one is displayed. To display a different one, edit the capture
properties in the capture selector (part of the Page view described below).
In this view, you can:
• Change the selected page comments using the page comment editor (3)
• Change the zoom level with the zoom slider (4)

The Page View
The Page view displays one page capture.
Hover over each panel for a description. Click the panel for more information.
• The Display Selector [page 17]

• The Capture Selector and Capture Toolbar [page 16]
• The Capture Selector and Capture Toolbar [page 16]
• The Display Panel [page 17]
1.3.1.3 Page View Panels
The Capture Selector and Capture Toolbar
Here you can select the capture that is currently displayed. The capture toolbar lets you perform the following
actions:
•  Make a new capture: adds a new capture (or replaces the current one)
•  Lock/Unlock capture: useful for locking the selected capture during recognition
•  Delete capture: delete the current capture
•  Edit capture properties:

• Change the capture comment shown as a tooltip on the Capture tab in the Capture selector
• Select the capture(s) shown in the Application view
The Display Selector
Here you can you choose the way the selected capture is displayed in the Display panel:
• A screen display
• A tree display
• A split display showing both screen and tree displays
• A source display
The Display Panel
What is shown here depends on what you have chosen in the display selector.
Screen Display
This display shows the selected screen capture.
It consists of the following panels:
• A resize panel (1)

• An action toolbar (2)
• A correction toolbar (3)
• A display panel (4)
Display Panel (4)
The display panel displays the page capture. You can select any component simply by clicking on it. The
selected component is then surrounded by a blue rectangle.
Right-clicking a component displays a context menu that lets you:

• Associate the component with a new item
• Associate the component with an existing item
A component can be surrounded by:
• A blue rectangle when selected

• A green or a red rectangle. This colored rectangle is set by Studio Recognition
For a complete description of recognition with Desktop Studio, see About the Recognition Mechanism [page
276].
Resize Panel
The resize panel lets you change the zoom level of the
screen capture:
• Using the Slider (1) of the resize panel (or using the
mouse wheel with the CTRL key pressed)
• Using the Zoom to fit (2) button to fill the display panel
with the screen capture
• Using the Reset view (3) button to restore the native
size of the screen capture
You can scroll through the screen capture using:
• The Scroll button (4) at the top of the Resize panel

• The scrollbars
• The mouse wheel
The resize panel can be hidden/shown using the Hide but

ton (5).
Correction Toolbar
When the captured page is displayed, you can click each item on the page, which is then surrounded by a green
rectangle. If the rectangle position is incorrect due to a general offset or a ratio error in the screen capture, you
can adjust it via the Offset and Ratio values. To do this, uncheck then check the desired value, then enter the
corrected value or use the Spin button.
Action Toolbar
The action toolbar lets you:
•  Copy the entire screen capture to the clipboard

• Display an image selector
Image Selector
The image selector (1) lets you:
• Crop the screen capture

• Copy a part of the screen capture to the clipboard
• Create items from a rectangle or from an image
In order to do this:
• Show the image selector by checking the Hide/Show Image Selector button (2)
• Move and size the image selector rectangle (drag&drop over the rectangle or on the sides of the rectangle)
• Right-click the image selector to display the context menu. The following menu items are displayed:
• Copy image selection
• Create new item from image selection
• Crop image to selection
 Note
With the Crop image to selection command, the captured image is not cropped to the image selector
rectangle. It is cropped from the top-left corner of the image to the bottom-right corner of the image
selector rectangle.
Tree Display
The tree display shows the DOM tree (internal structure) of the capture.


• The display panel itself (2)
The action toolbar (1) lets you:
•  Show the full tree or only the rooted tree (for subpage captures)
•  Show/hide the recognized items and subpages
The rooted tree is the Document Object Model (DOM) subtree under the root component. You cannot
associate a component that is outside of the rooted tree with an item of the page.
The display panel shows the DOM tree. Each component can be displayed in one of the following ways:
A regular component
An “out of the rooted tree” component. Only visible if the

 button is selected.
A recognized item
An associated , unrecognized item
A badly recognized/unrecognized item
A recognized page
An associated, unrecognized page

A badly recognized/unrecognized page
As in the screen display, right-clicking a component displays a context menu that lets you:
• Associate a component with a new item

• Associate a component with an existing item
The tree display is useful if you want to:
• Access invisible components, such as menu items

• Display the recognized subpages
• See a technical view of the capture
This view is synchronized with the screen display: If you select a component in one display, it is also selected in
the other display.
Source Display
The source display shows the source of the capture, where available (that is, the HTML source).

• The display panel itself (2)
• Search for text in the source using the Find button

• Manage the word-wrap option.
The source display can help to view page elements not shown in the DOM, like JavaScript code for Web pages.

 Note
This display is not synchronized with the other displays.
1.3.2 The Workflow Perspective
Desktop Studio provides a Workflow Designer that lets you create automation workflows. It includes:
• A graphical method for describing functional automation sequences

• A context structure for data management
• A set of functional activities
• A generic “Comment” activity for describing functional requirements
The Workflow perspective is where you design your workflows.
This perspective has the following components:
• The Workflows window (1), which contains a list of all the declared workflows.
• The Workspace (2), where you design a workflow.
• The Activities window (3), from where you can drag activities and pages.
• The Properties window (4), where you modify activity properties.
• The Context window (5), which contains the context structure of the project.
• The Errors window, which displays any errors encountered when the workflow is built.

1.3.3 The Editor Perspective
Purpose
The Editor perspective provides a graphical interface for developing automation scripts. It includes a powerful
code editor with:
• Syntax highlighting
• IntelliPrompt features
• Code snippets
• And much more
For more information, see The Code Editor [page 26].
It also includes:
• Multi-document management
• Script compilation
• Layout personalization
You can debug your scripts with the integrated script debugger, which includes:
• Breakpoints, watches, locals, call stack management

• Step-by-step execution
• Instant code execution
• And much more

The Editor Perspective Panel
When you select the Editor tab, the Editor Perspective panel is displayed:
This panel consists of:
• The document editor (1). The following document editors are currently implemented:
• The code editor
• The inline help viewer,
• The document selector (3),
• Various tool windows (4,5,6,7) that can be docked around it
The script tree (2) tool window displays all of the script files included in the current project. You can use it to
open scripts for editing.
The Document Selector
Background
Any number of scripts can be open simultaneously. Each script is loaded into its own, independent document
editor.
The document selector helps you to manage open documents.

It consists of:
• Document tabs (1), (2), (3), and so on – one per open document. The document that is currently being
edited is highlighted (4)
• A selector menu (5)
Document Tab
The document tabs let you:
• Change the document currently being edited by clicking its tab

• Close the document currently being edited by clicking the cross on the right of the tab
• Change the tab order by dragging one tab and dropping it at a new location in the selector
• Split the perspective panel to display two (or more) documents at the same time (see Docking
Management [page 30]).
The Selector Menu
The selector menu is useful when you have opened more documents than the number of tabs that the selector
can display.
It lets you view all of the open documents and select one of them for editing.

The Code Editor
Background
The code editor is used to edit script files and XML blocks.
The code editor panel consists of:
• An indicator margin (1)

• A line number margin (2)
• A selection margin (2)
• An outlining margin (2)
• The editor itself (3)
The Editor
The editor is a powerful text editing control that is packed with features for efficient code editing, including
syntax highlighting, code outlining, block selection, IntelliPrompt, split views, zooming, and more.
Here is a detailed list of the editor’s features:
Editing Features
• Unlimited undo/redo with support for batch-replace operations

• Block indent/outdent
• Automated line modification tracking
• Block (rectangular) selection and ability to prevent certain selection methods (select with the Alt key
pressed)
• Edit multiple lines at the same time via block selection
• Line selection in the selection margin
• Clipboard operations and drag/drop natively supported (cut, copy, paste), with support for any data object
• Over 100 edit actions, including everything provided by Visual Studio, such as caret movement, selection,
indenting, tabification, transposition, and more

• Block, none, and customizable smart auto-indent modes when pressing Enter
• Current line and delimiter (bracket) highlighting
• Delimiter (bracket) auto-completion
• Auto-case correct
• Code block selection (expansion/contraction)
• Scrolling accelerates the longer scrollbar buttons are depressed
Appearance Features
• Syntax highlighting
• Word wrap
• Whitespace display
• Optional line number, selection, outlining, ruler, and word wrap glyph margins
• Indicators (bookmarks, breakpoints, current statement, etc.)
• Four-way or two-way split views
• Animated zoom in and out, with mouse wheel support
• Squiggle lines for marking errors and spelling mistakes
• Complete support for both automatic and manual code outlining (folding), with customizable outlining
node options
• Collapse (hide) regions of text independently of the outlining feature
• Indentation guides
IntelliPrompt Features
• Completion lists that improve editing productivity and support complete word functionality
• Completion lists support filters (tabs/buttons), multiple matching algorithm options, ability to create
custom matching algorithms, matched text highlights, description tips, and much more
• Quick info tips that can show detailed information about what is under the mouse, with automated mouse
hover tracking
• Parameter info tips that can show multiple signature overloads and track the current parameter
• Code snippets that allow predefined text fragments to be inserted into the editor, and declared fields
edited
See also Code Editor Help Features [page 53] and Code Editor Commands [page 476].
Code Editor Margins
Indicator Margin
The indicator margin displays various indicators:
•  : bookmark indicators
•  : breakpoint indicators
•  : todo indicators
• : running line indicator
You can change the margin visibility with the Is Indicator Margin Visible setting in the editor perspective
settings.

Line Number Margin
The line number margin displays the code line numbers.
You can change the margin visibility with the Is Line Number Margin Visible setting in the editor perspective
settings.
Selection Margin
The selection margin displays colored bars where code has been modified:
• Yellow bar: indicates modified code that has not yet been saved
• Green bar: indicates modified code that has been saved.
You can change the margin visibility with the Is Selection Margin Visible setting in the editor perspective
settings.
Outlining Margin
The outlining margin displays the code outlining (folding) node tree. It lets you expand and collapse nodes:
• ‘+’ expands the node

• ‘-’ collapses the node
You can change the margin visibility with the Is Outlining Margin Visible setting in the editor perspective
settings.
The Scripts Tree

The scripts tree contains all the script files included in the current project. It contains the following node types:
Folder Node
Framework or library script
Project script
Each (SDK or project) script node contains subnodes displaying a first-level code map (see Navigation Using
Code Map [page 44]).
Each tree node has a shortcut menu providing the main associated functions (see Commands Reference [page
474]).
It lets you:
• Add new scripts

• Edit scripts
• Organize scripts in folders
• Rename scripts (with F2 )
• Delete scripts
The Project Tree
The project tree contains all of the processes, applications, pages, and items declared in the current project.
In projects, it lets you:
• Add resources
• Select the application/page/item displayed in the page viewer
• Drag&drop application/page/item names in the current code editor (see Code Editor Help Features [page
53])
• Insert a snippet in the current code editor (see Code Editor Help Features [page 53])

The Editor Perspective Tool Windows
The editor perspective contains the following tool windows:
Navigation
• Page viewer (see Code Editor Help Features [page 53])

• Bookmarks (see Navigation Features [page 44])
• Todo list (see Navigation Features [page 44])
• Code map (see Navigation Features [page 44])
• Code tree (see Navigation Features [page 44])
Find/Replace
Find Results (see Search Features [page 48]).
Compilation
Output and Error List (see Compiling a Project [page 419])
Debugging
• Breakpoints (see Debugging Your Code with Script Debugger [page 425])
• Locals (see Debugging Your Code with Script Debugger [page 425])
• Call stack (see Debugging Your Code with Script Debugger [page 425])
• Watches (see Debugging Your Code with Script Debugger [page 425])
Docking Management
Background
The editor perspective layout is a docksite that consists of:
• Four tool window zones on the left, top, right and bottom sides.
• One document zone in the center. This document zone can be split into several document zones.
You can change the layout of the editor perspective by:
• Docking document editor instances in split document zones

• Docking tool windows in the various tool window zones, or in the split document zones
You can also open a linked docksite (by clicking View Open linked docksite in the Main Window menu
bar). This a second docksite where you can dock document editor instances and tool windows.
To do this:
• Drag the code editor tab or the tool window tab. The docking guide is displayed automatically.
• Drop the dragged tab onto the desired section of the docking guide.
Dock Document Editor Instances
To dock a document editor instance, drag the document Editor tab over a document zone.

The docking guide is displayed and consists of the following targets:
• One central guide (1)

• Four splitting guides: (2), (3), (4), (5)
If you drop a tab:
• Onto one of the splitting guides, this action splits the document zone and moves the dragged document
editor instance to the newly created document zone
• Onto the central guide, this action moves the dragged document editor instance to the corresponding
document zone
• Outside the docking guide, this action makes the dragged document editor instance a floating instance.
 Note
• If you double-click the title bar of a floating document editor instance, you move it back to its document
zone
• You can use the CTRL key to prevent the docking guide from being displayed
• Similarly, you can use the Shift key to lock the splitting guides in place, ensuring that they are not
changed or removed as you move the mouse around

Docking Tool Windows
To dock a tool window, drag the tool window tab or title bar over a document zone.
The following docking guide is displayed:
It consists of the following targets:
• One document guide (1)

• Four tool window zones guides: (2), (3), (4), (5)
• Four splitting guides: (6), (7), (8), (9)
If you drop a tool window:
• Onto the document guide, this action moves the dragged tool window as a document to the corresponding
document zone
• Onto one of the tool window zones guides, this action moves the dragged tool window to the corresponding
tool window zone
• Onto one of the splitting guides, this action splits the tool window zone and moves the dragged tool window
to the newly created tool window zone
• Outside the docking guide, this action makes the dragged tool window a floating window
Until the new layout has been saved, you can restore the previously saved layout.
 Tip
• You can lock and unlock a tool window in opened mode using the pin and unpin buttons in the title bar.
• Some tool windows can be closed using the X button in the title bar.
• You can display all the available tool windows by clicking View Tool Windows from the main
menu. Check or uncheck individual tool windows to show or hide them.
• Double-click the title bar of a floating tool window to move it back to its tool window zone.

• To reposition a single tool window, drag its tab. To reposition a group of tool window, drag the title bar.
Layout Management
You can save your layout by clicking View Layout Save from the main menu. This layout will be restored
the next time you launch Desktop Studio.
To restore this layout without restarting Desktop Studio, click View Layout Restore .
 Note
The editor perspective manages two independent layouts: one for debugging mode and one for editing
mode. If you save the layout while the project is running, the debugging layout is modified. Otherwise, you
modify the editing layout.
1.3.4 The UI Designer Perspective
The UI Designer perspective is where you design user interfaces, such as input forms or custom pages. It
features:
• A graphical view of the UI being created

• A tree view containing the UI structure
• Editable JavaScript code corresponding to the UI
• A Parameters window for every object in the UI
When you select the UI Designer perspective tab, Desktop Studio displays the UI Designer perspective panel:

• The Resources tree (1)

• The popup editor zone (2)
• Various tool windows (3, 4) that can be docked around it.
The Resources Tree
The Resources tree displays a list of the popups included in the project. It allows you to:
• Manage the popups included in the project

• Manage the list of files used by the popup
• Manage the list of items of a popup
Manage the Popups Included in the Project
Add a new popup: To create a new popup, right-click the POPUPS root node of the Resources tree and select
Add a new Popup … from the context menu. This displays a dialog where you have to:
• Enter the name of the popup – this name must be unique among the popups of the project
• Choose the template that best meets your needs
Edit a popup: To edit a popup, right-click the corresponding Popup node in the Resources tree and select Edit
from the context menu. A new editor then opens in the popup editor zone.

 Note
If the popup editor is not yet open, the properties of the popup are displayed in the Properties tool window.
Delete a popup: To delete a popup, right-click the popup node in the Resources tree and select Delete from the
context menu. A confirmation message is displayed before the popup is deleted.
Manage the List of Files Used by the Popup
Each popup subtree displays the list of files used by the popup:
• Popup.html: the HTML page

• Settings.js: the JavaScript file containing the page design
• Popup.js and Popup.css: let you to customize the page behavior and style sheet (see Advanced
Techniques for Custom Page Design [page 417])
This list automatically includes all of the project files in the page subdirectory found in the local folder of your
project.
Add a new file: To add a new JavaScript or CSS file:
• Right-click the popup node in the Resources tree and select Add a new file … from the context menu
• Enter the name and the type in the displayed popup and validate
• The new file is created in the page subdirectory
• It is added to the Resources tree, which means you can edit it in the UI Designer
•  Note
The new file is automatically included in the popup.html file.
You can also manually add any existing file (for example, an image) as follows:
• Copy the file to the page subdirectory

• Refresh the Resources tree by selecting Refresh file list from the context menu
The added file appears in the Resources tree, allowing you to edit it in the UI Designer.
 Note
In this case, the added file is not included in the popup.html file. If necessary, update the file manually.
Edit a file: To edit a file:
• Right-click the file node in the Resources tree

• Select Edit from the context menu
• If necessary, the associated popup is then opened in the popup editor zone
• The file is opened for editing in its editor zone
Delete a file: To delete a file, you need to remove it manually in Windows Explorer. If necessary, manually
update the popup.html file to remove any “include” clauses.
Manage the List of Items of a Popup
The Popup subtree also contains an Items node that contains a hierarchical view of the popup items.
Add a new item: You cannot add a new item using the Resources tree. You must do it in the Designer view.

Edit an item: To edit an item, right-click the Item node in the Resource tree and select Edit from the context
menu. The item properties are then displayed in the Properties window, where you can edit them.
Move an item in the hierarchy: Some items are container items that accept other items as children. This
enables you to build a hierarchy of items.
You can move an item within the hierarchy using drag&drop in the Resources tree.
Delete an item: To delete an item, right-click the Item node in the Resources tree and select Delete from the
 Caution
If you delete a container item that has children, the children will be deleted too.
Popup Editor Zone

The popup editor zone allows you to design popups. It can contain one or more popup editors, each of
which lets you design one popup. You can switch between them using the document selector (see The Editor
Perspective [page 23]). Each popup editor instance consists of the following:
• The designer view (1)

• The editor zone (2)
The Designer View
The designer view displays the popup in an embedded Internet Explorer window. This allows you to graphically
design your popups. The toolbar contains the following items:
• : Refresh the design view from the settings.js JavaScript file
• : Switch design mode on/off
• : Switch test mode on/off
• : Open the popup in an external Internet Explorer browser
• : Capture the popup to make it available in the workflow designer
• : Replace the popup
Design Mode
When design mode is active, each item is surrounded by a dotted rectangle with the Name property in the
top-right corner. In this mode, you can:
• Add new items

• Select an item to edit its properties
Add new items:
With design mode active ( ), right-click in the page:
• A context menu is displayed showing all available items (button, edit, table, and so on). Each item is
mapped to a bootstrap component.
• Select the desired item type and validate.
• The new item is added to the Resources tree, under the Items node.
Edit an item:
With design mode active ( ), click the item in the designer view. The item properties are then displayed in the
Properties window, where you can edit them.
Set the position of an item:
UI Designer uses the Bootstrap-3 framework to manage popups. That means that you cannot simply set (X,Y)
properties to choose the position of an item. Instead, you have to create a grid using row and columns items.
With design mode active ( ), right-click within the page in the design view:
• Expand the Insert grid menu item and choose a grid item to add (such as containers, rows, columns).
• The new grid item is added to the Resources tree [1] under the Items node.
The Items subtree reflects the structure of the grid. You can change this grid structure using drag&drop in the
Resources tree.

For a full description of how to design a grid, see Managing Custom Pages With UI Designer [page 404].
To set an item position, simply drag&drop it to the right grid cell.
 Note
This is not possible in design view. You must do it in the Resources tree.
Delete an item:
You cannot delete an item in design view. You have to do it in the Resources tree.
The Editor Zone
The editor zone allows you to edit the text files associated with the popup: settings.js, popup.html, and so on.
You can open multiple files at the same time and switch between them using the document selector (see The
Editor Perspective [page 23]).
Each file is opened in an editor that provides a wide range of features, including syntax highlighting, unlimited
undo/redo, IntelliPrompt, outlining, and zoom. For a complete description of these features, see The Code
Editor section in The Editor Perspective [page 23].
 Note
By editing the settings.js file, you can change the design of your popups in JavaScript.

The Tool Windows
The UI Designer perspective contains the following tool windows:
• Properties
• Code Map (see Navigation Features [page 44])
• Find Results (see Search Features [page 48])
Properties Tool Window
The Properties tool window allows you to change the properties of popups and their items. The toolbar contains
the following items:

• : Manually refresh the design view with the new properties value
• : Switch auto-refresh mode on/off
Edit Properties
You can edit the properties of a popup or an item in different ways:
• From the Resources tree, right-click the corresponding node and select Edit from the context menu.
• From the design view, either select the item in design mode, or right-click the item and select Edit Item or
Edit Popup from the context menu.
The properties are then displayed in the property grid.
Refresh Mode
If auto-refresh mode is on, the design view is automatically updated each time you validate a property change
in the property grid. If not, you need to update the design view manually using the button.
Manage Complex Items
Most properties are simple to edit. But some items, such as radio buttons and checkboxes, have complex
properties that are editable as arrays of objects.
For these properties, you can:
• Add a new object to the array using the + button (1).

• Remove an object from the array using the - button (2).
 Note
You can also edit these properties in the settings.js file
Docking Management
The layout of the UI Designer perspective is a DockSite comprising:
• Four tool window zones at the left, right, top and bottom
• One documents zone in the center. This zone can be split into multiple documents zones.
As in the editor perspective, the layout can be modified and saved (see Docking Management in the The Editor
Perspective [page 23]).
Related Information
Managing Custom Pages With UI Designer [page 404]

1.3.5 The Debug Perspective
You use the debug perspective for debugging offline.
Desktop Studio has an integrated debugger that lets you control the execution of automation scenarios. It
includes:
• An Events view to display events received and actions executed in response

• A Pages view to display recognized pages
• A Scenarios view to display the automation scenarios being executed
• A Tester view to execute actions on the fly
• A Screenshots view to display screenshots captured during execution
A debug session is basically a set of trace lines shown in JSON format. There is one line for each:
• Event received by the engine of the Desktop Agent

• Framework action performed by the project scripts
• Scenario/step/handler status change
Additionally, it can include .png files that correspond to the screenshots captured during execution.
The Debug Perspective
When a debug session is loaded into Desktop Studio, a new debugger instance is launched in embedded mode
in a new Debug perspective:

Manage Debug Sessions
Save a Debug Session

To save the current debug session, click File Save Debug Session in the main menu.
The first time the session is saved, the debugger asks you for the file path and the name of the file to save the
session.
The debugger will then automatically save the complete debug session in this file when execution ends.
Reopen the Last Debug Session

When execution ends, Desktop Studio automatically keeps the last debug session in memory. You can open it
by clicking File Open Last Debug Session .
Load a Debug Session

You can load a debug session that was saved previously by clicking File Open Debug Session .
You can also do this by:
• Double-clicking the corresponding file in Windows Explorer

• Dragging & dropping the file from Windows Explorer to the Desktop Studio PSC tree
1.3.6 Accessibility Features

The following features will help you navigate more easily through the SAP Intelligent Robotic Process
Automation Desktop Studio.
Keyboard Navigation
With this feature, you can navigate through the elements of the page without using the mouse. You can activate
and use the keyboard navigation by using the Tab key. An outline appears around the focused element.

Screen Reader
With this feature, you can navigate through the SAP Intelligent Robotic Process Automation Desktop Studio
with the help of an audio narrator. Every action is detailed by the voice (the letters you type, the elements you
select on the page...).
High Contrast Black Theme
With this feature, users with low vision or visual disabilities can change the theme of the page to black.
Procedure
1. Select Settings 
2. Change the theme to HighBlackContrast.
 Note
If you set the theme to black in your Windows settings, it will automatically change the theme to black in
the SAP Intelligent Robotic Process Automation Desktop Studio.
1.4 Code Editing Features

1.4.1 Navigation Features
The following features help you to navigate through Desktop Studio code.
Navigation Using Code Map
The Code Map tool window in the Editor perspective displays the code structure of the script or the XML block
being edited in the code editor that has the focus.
It lets you:
• Navigate to the code from the code map by selecting the desired map entry. The code editor automatically
scrolls to the first line of the corresponding code block.
• Navigate from the code to the code map by right-clicking within the code editor and selecting Show in code
map from the context menu. The code map tree automatically scrolls to the corresponding map entry and
selects it.
Script Code Map

The tree displays all the functions coded in the script, including the callback functions:
• Scenario
• Step
• Event handler
• Function
• Callback
XML Block Code Map

The tree displays XML nodes, depending on the XML block being edited:
Edited Block XML Nodes Displayed
SCENARIO Scenario, steps, step, handler
ACTIONS ACTION
EVENTS EVENT
CONTEXT STRUCTUREDON
Other blocks First-level child nodes
Navigation Using Bookmarks
Bookmarks are navigation marks that can be set anywhere in the code. Setting a bookmark on a line of code
makes it easy to return to this line later.

Manage Bookmarks
To set a bookmark on a line, put the cursor anywhere in the line and click the  button in the navigation toolbar.
A bookmark is set and  is displayed in the code editor margins. If a bookmark is already set on the line, it is
removed when you click the icon.
You can also remove all bookmarks by opening the dropdown for the bookmark icon and clicking Clear All
Bookmarks.
Navigate to a Bookmark
The Bookmarks tool window in the Editor perspective displays all the bookmarks in the current project. By
double-clicking an entry, you can navigate directly to the selected line in the script file or XML block.
You can also navigate between bookmarks using the navigation toolbar:
• To navigate to the next bookmark, select the option from the bookmark dropdown or press F2 .
• To navigate to the previous bookmark, select the option from the bookmark dropdown or press SHIFT +
F2 .
Navigation Using To Do Items
To do items help you set reminders in the code.
Manage To Do Items
To set a to do item in a script or an XML block, simply type a comment line containing the word TODO. When
saved, the corresponding line is shown like this:
To remove a to do item, simply remove the word “TODO” and save.

Navigate to a To Do Item
The To Do List tool window of the Editor perspective displays the to do items in the current project.
By double-clicking an entry, you can navigate directly to the corresponding line in the script file or XML block.
Navigation Using Navigation History
Desktop Studio stores all the navigation actions in a navigation history. This lets you navigate backwards and
forwards within this history.
Navigation History
Desktop Studio stores a navigation point every time:
• You navigate using the navigation methods described

• You navigate from one document to another (see The Editor Perspective [page 23])
Navigate Backwards and Forwards

You can navigate within the history using the navigation toolbar:
• To navigate backwards, click the  button

• To navigate forwards, click the  button.
 Note
• You cannot navigate forwards until you have navigated backwards

• If you navigate backwards and then navigate manually, you can no longer navigate forwards
Navigation Using Goto Definition
Desktop Studio lets you navigate from a code editor to a statement definition.

The meaning of the term statement definition depends on the statement. A statement is:
• The application/page/item definition, for an application/page/item name

• The function implementation, for a function name.
To navigate from a code editor to a statement definition:
• Right-click the statement and select Goto Definition from the context menu
• Or move the caret to the desired statement and press F12
Depending on the respective statement, you automatically navigate:
• To the application/page/item definition in the Explorer perspective if the statement is an application/

page/item name
• To the function implementation in the Editor perspective if the statement is a function name
Code Tree Tool Window
The Code Tree tool window in the Editor perspective displays the JavaScript parsing tree of the script currently
being edited in the code editor that has the focus.
It is available for internal development purposes only.

1.4.2 Search Features
Desktop Studio lets you:
• Find a string in the current code editor,

• Quick find a string in the current code editor,
• Find a string in any file in any project file,
• Find and replace a string in any project file.
Find
To find a string inside the scope of the current code editor:
• Select the desired string in the code editor, right-click the selection and select Find and Replace Find
from the context menu (or press Ctrl + F )
• The following Find dialog is displayed:
You can:
• Edit the search string with the Find what field (1) (or select one from the Find what history),
• Change the scope of the search via the Look in combo box (2):
• Current Document – search in the whole document
• Selection – limits the search to the current selection (if not empty)
• Change the find option using the Options checkboxes (3):
• Match whole word only lets you search for whole words rather than partial words
• Match case lets you perform a case-sensitive search
• Regular expression interprets the searched string as a regular expression rather than a literal string

• Search up lets you perform the search backwards rather than forwards
Find the Next Occurrence
To find the next occurrence of the search string, click the Find Next button:
• The code editor automatically scrolls and selects the next occurrence found
• When the end of the document is reached, the search continues from the beginning of the document
• If no other occurrence is found, the Find Next button is disabled
Find All Occurrences
To search for all occurrences:
• Click the Find All button

• The Find dialog closes and the search results are displayed in the Find Results tool window.
Quick Find
Quick find lets you search in the current code editor without opening the Find dialog:
• Select the desired string in the code editor, right-click on the selection and select Find and Replace
Quick Find Next from the context menu (or press Ctrl + F3 )
• The code editor automatically scrolls and selects the next occurrence found.
Find the Next Occurrence
• Press F3 to find the next occurrence

Find the Previous Occurrence
• Press Shift + F3 to find the previous occurrence

• When the start of the document is reached, the search continues from the end of the document
Find in Files
To find a string outside the scope of the current code editor:
• Select the desired string in the code editor, right-click the selection and select Find and Replace Find in
Files from the context menu (or press Ctrl + Shift + F )

You can:
• Edit the search string in the Find what field (1) (or select one from the Find what history),
• Change the scope of the search in the Look in combo box (2):
• Whole Solution extends the search to all project files
• All Open Documents extends the search to all documents (script files and XML blocks) opened in the
Editor perspective,
• Current Document limits the search to the current code editor.
• Change the find options with the checkboxes (3):
• Search in SDK files lets you include SDK files in your search.

You can choose to search for all occurrences of the search string:
• Click the Find All button

• The Find dialog is closed and the results of the search are displayed in the Find Results tool window
To find and replace a string outside the current code editor:
• Select the desired string in the code editor, right-click the selection and select Find and Replace
Replace in Files from the context menu (or press Ctrl + H )

You can:
• Edit the search string in the Find what field (1) (or select one from the Find what history)
• Edit the replacement string in the Replace with field (2) (or select one from the Replace with history)
• Change the scope of the search using the Look in combo box (3):
• Whole Solution extends the search to all project files
• All Open Documents extends the search to all documents (script files and XML blocks) opened in the
Editor perspective
• Current Document limits the search to the current code editor
• Selection limits the search to the current selection (if not empty)
• Change the find options using the checkboxes (4):
• Search in SDK files lets you include SDK files in your search

To find the next occurrence of the search string, click the Find Next button:
• The code editor automatically scrolls and selects the next occurrence found
Replace the Selected Occurrence

To replace the selected occurrence of the search string, click the Replace button:
• The code editor replaces the selected occurrence and automatically searches for the next occurrence

Replace All Occurrences
To replace all occurrences of the search string:
Click the Replace All button.
Find Results Tool Window
The Find Results tool window in the Editor perspective displays the results history of the various Find All
operations.
It consists of:
• A result selector (1)

• The current results set (2)
The result selector (1) displays a Results tab for each results set. Each Results tab shows the search text of its
results set.
Using the Result Selector
The current results set can be changed by selecting the corresponding Results tab.
The Results tab menu suggests the following operations:
Close Close the corresponding results set

Refresh Restart the corresponding Find All search without changing
the search options, and update the results set
Edit Edit the corresponding Find All search options
Close All But This Close the results history apart from the this results set
Close All Clear the results history
Using a Results Set

A results set displays all the occurrences found by the corresponding Find All operation. These occurrences are
grouped by document (script file or XML block).
You can navigate to the position of an occurrence by double-clicking that occurrence.
1.4.3 Code Editor Help Features
IntelliPrompt
IntelliPrompt displays a list of available words while you type code in the The Code Editor [page 26].
The IntelliPrompt list consists of the following parts:
• The list itself (1)

• The list filter (2)
• The QuickInfo tooltip (3)
IntelliPrompt List Filtering

The suggested list is filtered by:
• The context of the code (for example: Mantis)

• The word typed (for example: pa). The filtering is updated while the word is typed
• The list filter (2)
In this example, the list displays all the properties and methods of Mantis that start with "pa".
The list filter (2) lets you:
• Include/exclude properties from the list

• Include/exclude methods from the list
IntelliPrompt Validation
To validate a list entry:
• Select the desired entry

• Press Enter or Tab
The word entered is replaced by the selected list entry.
To cancel and close the list entry, press ESC .
QuickInfo Tooltip
The QuickInfo tooltip (3) is associated with the list selection. For a full description of its content, see QuickInfo
[page 54].
QuickInfo
QuickInfo displays a Help tooltip when the mouse cursor is positioned on a statement in the code editor.
This tooltip consists of:
• The statement syntax (1)

• A brief description of how the statement is used (2)
• A description of each parameter, including its type (3)
 Note
The QuickInfo display can be managed in the editor settings.
Snippets
Snippets are predefined code blocks that can be inserted into the code. For a complete list of snippets, see the
Code Snippets Reference [page 484].
Insert a Snippet
A snippet can be inserted in a code editor in various ways:
• Select the snippet from the IntelliPrompt list,

• Click Select Snippet in the code editor context menu (see Commands Reference [page 474])
• Type the snippet shortcut (see Code Snippets Reference [page 484]) in the code editor and press Tab
• Click Insert in the context menu of the Page Viewer tool window.

Complete a Snippet
Most of the snippets contain variable names that can be replaced with custom names after insertion.
The snippet code block is inserted in edit mode so that it can be completed:
 Sample Code
for (var <index> = 0; <index> < <count>; <index>++= { }
In this mode:
• Variable names are highlighted in yellow.

• You can navigate from one variable name to another using the Tab key.
• Once the cursor is positioned on a variable name, you can replace the default name with a custom name.
All other occurrences of the name are then replaced automatically.
• Press Enter or Esc to exit edit mode.
 Note
• You cannot return to edit mode once you have exited

• Some automatic completion (application/page/item names) can be performed by Desktop Studio
when inserting snippets from the Page Viewer tool window.
Drag & Drop
You can insert application/page/item names in the code editor by dragging & dropping them from various tool
windows in the Editor perspective:
• Project tree
• Page viewer

Display a Page Capture
The Page Viewer tool window in the Editor perspective displays a page capture.
• The breadcrumb (1)

• The capture selector (2)
• The captures toolbar (3)
• The action toolbar (4)
• The resize panel (5)
• The display panel (6)
Breadcrumb
The breadcrumb (1) lets you select the application/page/item displayed.

• To display an application mosaic:
• Click the current application (2),
• Or click the first selector (1) to display a list of all declared applications.
• To display a page capture:
• Click the current page (4)
• Or click the second selector (3) to display a list of all of the declared pages of the current application
(2)
• To select an item, click the third selector (5) to display a list of the declared items of the current page (4)
Capture Selector
The capture selector (2) lets you select the capture that is currently displayed.
Capture Toolbar
The capture toolbar (3) lets you perform actions on the captures:
•  Make a new capture: adds a new capture (or replaces the current one)
•  Lock/unlock capture: useful for locking the selected capture during recognition
•  Delete capture: deletes the current capture
•  Edit capture properties:
• Change the capture comment shown as a tooltip on the capture tab in the capture selector (1)
• Select the capture(s) shown in the Application view
Action Toolbar
•  Copy the whole screen capture to the clipboard
• Display an image selector
The image selector lets you:
• Crop the screen capture

• Copy part of the screen capture to the clipboard
You will find a full description of the image selector in The Explorer Perspective [page 9].
Resize Panel
The resize Panel (5) lets you change the zoom level of the screen capture:
• Using the slider
• Using the Size to fit button to fill the display panel with the screen capture.
 Tip
• Problems may occur when zoom factors are tuned with different values on a multiple screen
display. This is a known issue, in particular with Chrome and Firefox during capture. Capture with
Chrome and Firefox works if the window zoom factor is the same on every screen (whatever the
browser zoom factor).
There should be no issue with Win32, UI Automation, or SAP GUI applications.

If you have some issues capturing UI elements, you may be able to solve the problems by setting
the zoom factor to 100%. Go to the Scale and layout settings of your laptop and ensure that your
zoom factor is set to 100%, then restart your session to apply the change.
In the Capture window, a warning message lets you know if the zoom level of the target page is not
set to 100%.
• Rarely, other issues can occur when the zoom factor is not set to 100% in the runtime phase:
• Highlighting of items can be incorrectly positioned.
• In the rare cases where a mouse click driven by coordinates is used, the coordinates may be
incorrect and the mouse click can fail.
Display Panel
The display panel (6) displays the current screen capture.
In this view, only the non-technical recognized items (1,2,3,4,5) are clickable (see Set Item Parameters under
Item Definition [page 263]). They are highlighted with a green rectangle.
Once selected by clicking on it, this type of item is highlighted with an orange rectangle (1).
The breadcrumb selection is updated to reflect the item currently selected.
By right-clicking within the display panel, you can:
• Edit the page: automatically navigate to the Explorer perspective to edit the current page or item
• Copy the capture screen to the clipboard
• Insert a snippet into the current code editor (see Snippets [page 54]).
1.5 About Projects
Desktop Studio uses projects to enable authoring in SAP Intelligent Robotic Process Automation. All related
resources are stored in the project structure [page 60]. Once defined, the project can be deployed to SAP
Intelligent Robotic Process Automation Factory for testing purposes and later for production.

1.5.1 Overview of Project Development
This topic provides a brief description of what project development involves in terms of phases and the
standard development cycle.
Main Development Phases
Declaration Phase
To declare elements, you need to:
• Declare applications (executable name and a set of properties for this application)
• Declare pages for each application
• Declare relevant objects (Windows class, HTML tags, and so on) for each page
• Define criteria that ensure best recognition: the criteria are key for ensuring the robustness of the object
identification
• Declare tracked technical events to which Desktop Agent must react
For more information, see The Declaration Phase: General Information [page 240].
Implementation Phase
• Development of automation scripts to meet business requirements
• Handling technical events
• Scenario implementation
• Use of declared objects and pages
The Development Cycle
A standard development cycle is used for projects in SAP Intelligent Robotic Process Automation:
Delivery and validation of functional requirement specifica The main entry point for the project
tions
Identification of the nature of applications and processes Entails exploring the applications with Desktop Studio
Detailed functional specifications of processes to assist/au Entails describing the procedures, the process steps, the
tomate nominal case, and any error cases
Detailed design Entails splitting the processes into scenarios, scripts steps,
handlers, and events
Development Using Desktop Studio Explorer to recognize applications, pa

ges, and objects,

Project development/implementation • Creation of a detailed project framework (scenarios,
events, and so on)
• Coding the procedures, events, and actions
Validation and unit testing Testing the project on client applications using the inte
grated debugger
Validation phase and support Project delivery using Cloud Factory and its environments.
A group of pilot users can try out the project under real-life
conditions.
Production phase and support Productive use of the project by all users
Development stages of a project in SAP Intelligent Robotic Process Automation:
1.5.2 Project Structure and Organization
Overview
Desktop Studio allows you to develop your own projects. Once imported in SAP Intelligent Robotic Process
Automation Factory, they become available for both attended and unattended mode using Desktop Agent.
A project in SAP Intelligent Robotic Process Automation contains a set of files:
• A main project file (.PSCP)

• Application declaration files (.PSCP) (also captures bitmaps and structures)
• A set of JavaScript files to implement the scenarios and optimizations
• Language framework files, extensions, and libraries (copied from SDK)

• HTML resources (HTML, JS, bitmaps, and so forth) to display custom-generated user interfaces
Typical Structure of a Project
When you create a new project, Desktop Studio automatically generates the following set of folders, which
contain the different files for the solution:
 Sample Code
<root folder>
<project name>
<project name>.pscp
<project name>.pscr
app
app1.pscp
<app1>_Screens
*.html
*.png
*.xml
app2.pscp
...
archive
archive_<project name>_<version>_<date>_<time>.zip
...
bin
<project name>.psc
<project name>.debug.psc
<project name>.js
<project name>.min.js
html
*.html, *.js
...
export
<project name>_<version>
<project name>.zip
...
<project name>_<version>.zip
local
<project name>.js
html
*.htm
...
log
...
<project name>_Screens
server
html
*.htm
updatepkg
...
File or Folder Name Description
<project>.pscp Main project file

<project>.pscr Resource project file (optional file, only if you use the split
resources option)
archive Archive folder – contains ZIP files generated by Desktop

Studio to archive all the files required for development:
Source script files (.PSCP, .PSCR, and so on), HTML, JS files,

Studio Explorer capture files (bitmaps and structures), and
so forth.
Archive files have the name: archive_<project

name>_<version>_<date>_<time>.zip
For example: archive_testProject_1.0_29092012_183725.zip
bin Folder containing all JS, XML, and resource files used for
execution when testing the project with Desktop Studio. This
folder is used to generate the project-export archive
export Export folder – contains files generated by Desktop Studio to

archive all of the files necessary for deployment:
• Generated script file (.PSC, and so forth), HTML, JS

files, and so on
The export is saved in a folder named <project

name>_<version> that contains:
• Export file named <project name>.zip
• A markup file named key.xml: This file is mandatory

for the update mechanism
• and more
The content of the folder is also saved in an archived file

named <project name>_<version>.zip
local Contains all files that will be locally deployed on the worksta
tion. These files are saved to an archive when the project
is exported. In particular, the target project file (<project
name>.psc) is generated in this folder.
log Folder used as a working directory when the project is tested

with Desktop Studio. This folder contains log files that are
generated by Desktop Agent (named LogCtxt.000 and
so on).

<project>_Screens Contains the captured screens for the declared applica

tion(s). Each capture consists of three files:
• *.png: page snapshot

• *.xml: page internal structure
• *.htm: html source code (for Web pages)
server Contains all files that will be deployed on the server. It typi
cally contains mash-up Web pages that are located on the
server and launched using a Web browser. These files are
saved as-is (without compression) when the project is ex
ported.
updatepkg Contains a list of subfolders associated with the <Update

Packages> section.
 Note
The “archive”, “bin”, “export”, “local”, “log”, and “server” folders are mandatory. You can also add other
folders to organize your project files.
1.5.3 Project Management
1.5.3.1 Create a Project
Procedure
1. Click File New Project
The following dialog is displayed:

2. Enter a project name (1) and a project title (3).
3. Optional: Enter the client name, the initial version of the project, the date, and comments about the
project.
4. Specify the folder where the new project will be created (5).
If necessary, this folder is created automatically. A subfolder containing the project files is also created at
this location.
5. Click OK to validate project creation.
The project structure is automatically created in the specified location (see Typical Structure of a Project
[page 61]).
1.5.3.2 Open a Project
Procedure
There are two ways to open an existing project.

• From Windows Explorer, double-click the project file (which has extension .pscp).
A new instance of Desktop Studio is launched and the project is loaded automatically.
• From an open instance of Desktop Studio:
1. Drag & drop the project file from Windows Explorer onto the Project tree or the Scripts tree.
2. Select the project file from the list of recent projects in the File menu in the menu bar.
3. Click File Open Project... in the menu bar and choose the project file you want to load.
1.5.3.3 Edit a Project
Procedure
1. Click File Edit project in the menu bar.

2. Optional: Change the project data as required.
For example, you can change:

• The project name
• The project title
• The client name
• The current project version
• The date (displayed in the About box)
• The comments
3. Optional: Include new framework libraries in the project via the Libraries tab.
4. Optional: Update project properties via the Properties tab.
5. Optional: Update project evolutions via the Evolutions tab.
1.5.3.4 Archive a Project
Procedure
Click File Archive Project... in the menu bar to create a backup of the project.
A new archive file is created in the archive folder. The name of this file has the following format:
archive_<project name>_<project version>_<date>_<time>.zip
It contains all of the files and folders in the project structure apart from the archive and export folders.

1.5.3.5 Export a Project
Procedure
Click File Export Project to export a project.
A new export output folder is generated in the export subfolder. Depending on the project's structure, this
folder will contain:
• The local folder in an output ZIP file, if the compression option was selected prior to generation.
• If the compression option was not selected, all files from the local folder are copied as raw data files.
• The server folder
• The key.xml markup file
The markup file ensures the integrity of:

• All file names
• All data files
• The properties in the XML <Properties> section of the main project file.
If any of these conditions are invalid, the export will be rejected.
 Note
Exporting a project also creates a raw ZIP file in the root export folder. The name of the ZIP file is:
<project name>_<project version>.zip.
This archive can be hosted by SAP Intelligent Robotic Process Automation Factory, when needed.

2 Capturing, Declaring and Controlling
Applications
Capturing and declaring applications means identifying one or more applications that you want to control.
After you have identified the applications, you then need to identify the relevant UI elements. Even though
applications can use different “flavors” of technology, they share many common patterns.
You start by locating the screens or pages that you want to use. Within a page, you then look at the UI elements
that you will later use, such as input fields, output fields, and buttons.
Another key task when capturing and declaring applications is to set criteria for all of the UI elements that you
want to manage. You define an application and its UI elements only once. If an application evolves over time and
your criteria are unable to handle the change, you simply have to refresh the capture. Usually, this is enough to
resolve any issues that may occur.
2.1 Technology Connectors
The Desktop Studio and the Desktop Agent provide a set of technology connectors for controlling purposes.
The following topics cover the specific properties of each technology.
• The Web Connector [page 67]

• The UI Automation Connector [page 92]
• The SAP GUI Connector [page 117]
• The SAPUI5 and S/4HANA Connectors [page 162]
• The Win32 Connector [page 175]
• The Java Connector [page 188]
• The HLLAPI Connector [page 202]
• The OCR Connector [page 215]
2.1.1 The Web Connector
Definitions
For the Web connector,
• A screen is an HTML page displayed in a Web browser tab, in a frame or an iframe (inline frame
<iframe>/).

Capturing, Declaring and Controlling Applications PUBLIC 67
• A component is any HTML element belonging to the DOM of a screen.
• An application is a set of screens that match a given set of criteria.
The DOM of a Web screen does not include the DOM of its frames or iFrames. If you need to control a
component inside a frame or iFrame, you must declare a page for it.
 Note
You can use the following web browsers:
• Internet Explorer
• Google Chrome
• Firefox
• Microsoft Edge
To control popup windows belonging to the Web browser (for example, information or error popups, “Open
file” popups), you need to:
• Declare the Web browser application as a desktop application

• In this desktop application, declare a page entity for each popup window you need to manage (see
Entities for a Desktop Application [page 247] )
Page Recognition
When the Web connector detects the opening of a Web screen:
• It looks for the first declared Web application with matching criteria
• If it finds one, it looks for the first declared page of the application with matching criteria
• If it finds one, it associates the new Web screen with the page that was found and notifies a LOAD event
for this page
• Otherwise, if it is a main frame, it associates the Web application with the generic _Undefined_ Page
and notifies a LOAD event for this page
• In all cases, it keeps the Web screen under control
• Otherwise, it ignores the Web screen
For each controlled Web screen, the Web connector regularly checks whether the Web screen still matches the
application criteria:
• If not, it notifies an UNLOAD event for the associated page (if any) and releases control over the Web
screen
• If it still matches:
• If the Web screen is still associated with a Web page, it checks whether the Web screen still matches
the page criteria and if not, it notifies an UNLOAD event for the associated page
• Otherwise, it looks for the first declared page of the application whose criteria match. If it finds
such a page, it associates the Web screen being controlled with that page and issues a LOAD event
notification for the page
 Note
The control frequency can be changed with the Synchro delay parameter of the application.

68 PUBLIC Capturing, Declaring and Controlling Applications
Application Instance Management
An application instance is a running instance of an application.
The Web connector handles applications instances as follows:
• A Web application loaded in one Web browser tab is considered as one instance of the Web application
• If a Web application is loaded twice in two different Web browser tabs, the Web connector regards them as
two instances of the same Web application
 Note
If a Web application instance navigates to another Web application in the same tab, the Web application
instance is considered to be ended.
iFrame Capture
You must capture the iFrame as a new page to get the content of this page.
• To capture the iFrame, you can deploy the tree to find the iFrame page.

• Sometimes, you must load the iFrame in a new page to able to capture its content.
You can find the URL of the iFrame in the main page, under the iFrame tag.
If the iFrame is not recognized by the application:
You must make sure that the iFrame page has the same criteria as the application. If the page is not recognized,
you must modify the recognition criteria of the application to make sure that they are similar:
• You can either change the Part(DOMAIN) criterion.
• Or the Part(URL) criterion.
Related Information
Declaring Entities Using the Web Connector [page 71]

Controlling Entities Using the Web Connector [page 78]

2.1.1.1 Declaring Entities Using the Web Connector
This task comprises:
Declaring an Application [page 71]
Declaring a Page [page 72]
Declaring an Item [page 74]
2.1.1.1.1 Declaring an Application
For general information on this topic, see Declaring Applications [page 249].
Set Application Criteria
Application criteria are used by the Web connector as follows:
• It looks for the first declared Web application whose criteria match
• If it finds one, it looks for the first declared page of that application whose criteria match. If it finds a page, it
associates the new Web screen with that page.
• Otherwise, it ignores the Web screen
That means that application criteria must be:
• Broad enough to match all the Web screens of the Web application
• But not too broad, to ensure they do not match the Web screens of other Web applications
You set recognition criteria using Desktop Studio (see Declaring Applications [page 249]):
• You can use the following operators on properties of type string: Any, Empty, Full, Part, start-with, end-with,
like.
• You must declare at least one recognition criterion.
• You can set multiple criteria on the same property, which are then connected by a logical OR.
Usually, you set a recognition criterion for the domain property.

Set Application Parameters
Web applications have the following specific parameters:
One Instance per Thread Changes the way the application instances are managed
Synchro Delay Sets the Web connector recognition frequency (see Page
Recognition [page 68]). The default value is 250 millisec
onds (max 60000 ms). If it is set to 0, no regular control
is performed but dynamic Web forms will not be managed
correctly.
Use ID as Object Name If checked, Desktop Studio generates a new item name
based on the id property of the component that has the
focus.
For general information on declaring an application in Desktop Studio, see Declaring Applications [page 249].
2.1.1.1.2 Declaring a Page
Set Page Criteria
The Web connector applies page criteria as follows:
• It looks for the first declared Web application whose criteria match
• If it finds one, it then looks for the first declared page of the application whose criteria match. If such a page
is found, the connector associates the new Web screen with that page.
• And so on.
That means that page criteria must be:
• Broad enough to match the desired Web screen of the Web application
• But not too broad, to make sure not to match the other Web screens of the Web application
You set recognition criteria using Desktop Studio (see Criteria Management [page 269]). Using the Web
connector, you:
• can use the following operators : Full, Part, Starts, Ends, Like
• must declare at least one recognition criterion.
• can use OR to define a combination of criteria for each property
Usually, you will set a recognition criterion on the page part of the Url property.

Advanced Recognition Methods for Web Pages
If a Web page has no unique distinguishing property, you can use one of the following advanced declaration
methods:
• MustExist: for details, see MustExist Method [page 284].

This method is very often used in Web page declarations. It can also be used when Web screens are loaded
dynamically. When the Web connector recognizes such screens, it can notify a LOAD event before the
whole content of the screen is loaded. To ensure that a specific item is present before receiving the LOAD
event, define this item as MustExist.
 Note
If you set the MustExist parameter for a multiple item, the parameter will be ignored.
• MustNotExist: for details, see MustNotExist Method [page 284].

• Order of Pages: for details of this issue, see Order of Declared Pages [page 286]
Page-Based Events
A declared page automatically receives the following technical events:
LOAD The page is loaded
UNLOAD The page is closed
The Web connector can also notify the following technical event:
RESIZE: the onresize event is emitted by the HTML window of the Web screen.
This event must be explicitly tracked in order to be notified.
Page Parameters
Page parameters can be set using Desktop Studio.
The Web connector provides the following specific parameter:
Capture (Cache): If set, all Capture (Auto) parameters set on the page items will then be considered as
Capture (Cache) parameters.
For general information on declaring a page in Desktop Studio, see Declaring Pages [page 252].

2.1.1.1.3 Declaring an Item
Set Item Criteria
Item criteria are used by the Web connector in the following way:
Once the Web connector recognizes a Web screen as a declared page, it can search the screen DOM to find the
target of each item:
• An item will target the first DOM component that matches its criteria
• If an item is multiple, it will target all of the DOM components that match its criteria.
That means that item criteria must be:
• Precise enough to match the desired component of the Web screen

• Broad enough to be able to resist as far as possible to Web screen evolutions
Items are usually declared for controlling purposes. You can also use items to aid page recognition by setting
MustExist or MustNotExist parameters (see Set Page Criteria [page 72]).
You set recognition criteria using Desktop Studio (see Criteria Management [page 269]):
• You can use the following operators: Full, Part, Starts, Ends, Like
• You must declare at least one recognition criterion
• You can use OR to define a combination of criteria for each property
Usually, you will set recognition criteria for the following properties:
TAG The Web connector requires a criterion for the HTML name
(TAG) of the component : INPUT, DIV, SPAN, and so on.
When you create an item from a Web component, Desktop
Studio automatically sets this criterion. It cannot be edited
or removed.
id or name It is advisable to set a criterion for the properties ‘id’ or

‘name’ of the component, if present and unique. These prop
erties are usually set by Web developers and do not change.
When an item is created, Desktop Studio automatically sets
a criterion for one of these two properties if the criterion is
suitable.

Text With some components (such as SPAN or TH), if the id or
name properties are not usable, you can set a criterion for
the text property.
 Note
This property corresponds to the HTML property, Inner
Text. So, if a component has a text property equal to My
Text, all ancestor components also have a text property
containing My Text.
Advanced Recognition Methods for Items
In some cases, it is not possible to recognize a targeted component merely by setting criteria for its
properties. Another component is recognized by mistake. To ensure your declaration is correct, you can
use the components pattern method described in Items Pattern Method [page 286] or the ancestor method
described in Ancestor Method [page 285] .
The ancestor method requires you to declare an additional technical item. Use it when the components pattern
method cannot be used. Sometimes, using the ancestor method means you avoid duplicating complicated
declarations of components patterns.
Example:
On a Web page with several TABLE components, you need to target the ROWS of the TABLE component which
has a column header (TH) Date.
The TR, TABLE, and TH components are not in a parent-child relationship. That means you can't directly
declare your oRow item by using the components pattern method described earlier. Instead, you must:
• First declare a technical oTable item which targets the TABLE component, using the components pattern
method
• Then declare the oRow item with the oTable item as ancestor to target the ROWcomponents
Using the Range Property
Consider the following use case: On a Web page with a table comprising two columns and two rows, you declare
an oCell Item to target the cells (TD) of the second column in the table.

To address this use case, you can set a criterion for the range property:
The range property is calculated by the Web connector during recognition of an item. Its 0-based value
indicates the range of an HTML tag relative to an HTML node. This HTML node depends on the declaration of
the item you need to find.
You declare the oCell item using the components pattern method.
With the following oCell declaration, you cannot use the range property to target the second column because
the Web connector calculates the range values relative to the table node:
If you declare the oCell item in the following way, the Web connector calculates the range values relative to the
TR node. You can then use the range property to target the second column.

 Note
You can't use the range property as a criterion for a multiple item.
As you can see, it can be difficult to know which range value will be calculated by the Web connector. It is
advisable to use the range property only to distinguish direct children of an HTML tag. The range value given in
the Captured data is calculated in this way.
Item-Based Events
The Web connector implements the following technical events:
SETFOCUS Notified each time the onfocus event is issued by the tar
geted HTML component
KILLFOCUS Notified each time the onblur event is issued by the targeted
HTML component
CLICK Notified each time the onclick event is issued by the targeted
HTML component
COMMAND Equivalent to the CLICK event (for legacy compatibility)
CHANGE Notified each time the onpropertychange event is issued by

the targeted HTML component. The nature of the change
is transmitted in the _ItemChangeData_ node of the Event
_ObjectData_
These technical events must be explicitly tracked in order to be notified. They are notified to the page with the
name of the item in the _ItemName_ data (complemented by a possible index).
Note that tracking events is not supported (no event will be issued) for multiple items.

Item Parameters
Web items implement the following specific parameters :
Must exist If set, the page will be recognized only if the item exists (for
more details, see MustExist Method [page 284])
Must not exist If set, the page will not be recognized if the item exists (for
more details, see MustNotExist Method [page 284] )
Ancestor Name of the ancestor item (for more details, see Ancestor
Method [page 285] )
Capture If set to ‘Auto’, the item value is collected before a page-

based event is notified. If set to ‘Cache’, the item value is
captured each time the targeted component value changes.
These values are included in each page-based event.
Key type Can be used only for a <select> component. If set, this
tells the Web connector to consider the ‘Text’ property of
the <option> nodes of the ‘value’ attribute (see Controlling
Complex Items Using the Web Connector [page 85]Control
ling a <select> component)
GetValueMethod Allow the software to override the default ‘get’ method be
havior (see Controlling Entities Using the Web Connector
[page 78])
SetValueMethod Allow the software to override the default ‘set’ method be
havior (see Controlling Entities Using the Web Connector
[page 78])
2.1.1.2 Controlling Entities Using the Web Connector
Controlling an Application Using the Web Connector
The Web connector implements the standard control methods described in Controlling an Application [page
234]. It does not provide any additional features for controlling applications beyond these standard methods.

Controlling a Page Using the Web Connector
The Web connector implements the standard control methods described in Controlling a Page [page 232]. It
also provides additional features for controlling pages.
Execute a Script within a Web Page
In Web pages, some user actions are impossible to automate using the page UI. For example, an action that is
started when the mouse hovers over a menu cannot be automated in this way.
If you can’t mimic the user action, try to automate what is triggered by this action.
You can then try one of the following ways:
• Trigger the event fired by the user action by means of a script.

• Execute the JavaScript code executed by the event handler.
To discover which event is fired and what code is executed, you can:
• Search in the Web page source using the Source Display, described in The Explorer Perspective [page 9], or
using the Web browser.
• Search in the script files used in the Web page (downloaded to the Internet temporary files directory).
• Use external tools (such as Internet Explorer Developer Tools – activated with F12 – or Visual Events).
Once you have found what you need, you can execute the corresponding JavaScript code in the Web page using
one of the following methods:
evalScript Evaluates a JavaScript function in the page and returns the

result
execScript Executes JavaScript code in the page
You can also execute a script directly on an item (see Execute Script on an Item Within a Web Page in
Controlling an Item Using the Web Connector [page 82]).
Inject Script Into a Web Page
You can inject a JavaScript function into a Web page using one of the following methods:
injectFunction Injects the code of a JavaScript function or set of JavaScript

functions into the page
injectFile Injects a JavaScript or VBScript file (or set of files) into the
page
You can then execute the injected functions using the evalScript or execScript methods.
 Note
The script is injected on the client side. If the Web page reloads, its content is restored from the Web server
and the script is no longer present.

 Sample Code
// Declare in my script the JavaScript function to be injected

function MyInjectedFunction()
{
document.body.insertAdjacentHTML(....);
}
// Inject the function into the Web page
MyWebAppli.MyPage.injectFunction(MyInjectedFunction);
// Execute the function inside the Web page
MyAppli.MyPage.execScript(‘MyInjectedFunction();’);
Modifying Web Page Content

The Web connector allows you to enrich the content of a controlled Web page.
This is very useful when you need to display:
• Buttons or links to start controlling sequences

• Data collected elsewhere
You can easily integrate these UI elements directly into the controlled Web page.
You can insert any kind of Web component into the contents of a Web page using the following methods:
insertButton Inserts a button into a page
insertImageButton Inserts an image button into a page
insertLink Inserts a link into a page
insertHtml Inserts HTML code into a page
insertObject Inserts an HTML object into a page
Using these methods, you can specify a functional event that will be fired when the inserted component is
clicked.
 Sample Code
// insert a button with id 'myButton', label 'My Button', after item

MyAppli.MyPage.btSearch
res = MyAppli.MyPage.insertButton('myButton', MyAppli.MyPage.btSearch, 'My
Button', {
...
MyAppli.events.evOnClickMyButton
);
// callback called when the button is clicked
MyAppli.on({ evOnClickMyButton: function(ev)
{
ctx.log("'My Button' was clicked !");
}});

Once injected, the components are present in the DOM and can be controlled like any other component. You
can also control them using the following methods:
deleteObject Remove a Web object from the Web page
disableObject Disables/enables a Web object created using

ctx.page.insertObject
 Note
The components are injected on the client side. If the Web page reloads, its content is restored from
the Web server and the components are no longer present. You may have to insert them each time the
controlled Web page loads.
It is advisable to remove created components when Desktop Agent stops. This is particularly relevant for
injected buttons and links.
Other Features of the Web Connector for Controlling Web Pages

The Web connector provides the following additional features that are used less frequently:
Start a Web page
You can start a Web page using the start method:
 Sample Code
MyAppli.MyPage.start() ;
By default, this method uses the page’s URL that was registered when the page was captured.
 Note
In general, you cannot use the same URL for a page in the development and the production phase:
• In the development phase, you generally use the test platform.

• In the production phase, you use the production platform.
You can resolve this issue by providing the right path in the start method:
 Sample Code
if (ctx.options.env == e.env.dev)
MyAppli.MyPage.start('MyEnvPath') ;
else
MyAppli.MyPage.start('MyProdPath') ;
Another way to resolve this issue is to set the page’s URL for each environment using the setPath method:
 Sample Code
// define production and test URL for MyAppli.MyPage

MyAppli.MyPage.setPath(e.env.prod, 'MyProdPath');
MyAppli.MyPage.setPath(e.env.dev, 'MyEnvPath');

...
// select 'production' as current environment
ctx.options.env = e.env.prod;
...
// start MyAppli.MyPage (with 'production' URL)
MyAppli.MyPage.start();
You can also navigate from one Web page to another using the following method:
navigate Navigates to a new page from the given page
Use navigation history
You can use the browser navigation history with the following methods:
historyBack Loads the previous URL into the history list
historyForward Loads the next URL into the history list
historyGo Loads a specific URL from the history list.
historyCount Returns the length of the history list.
Miscellaneous features
Here are some other methods that can be useful:
html Gets the html content of the page
isBrowserVisible Checks if page browser is visible
reload Reloads the html page
scrollTo Scrolls the html page to the specified coordinates
scrollBy Scrolls the html page by the specified number of pixels
getItemAttributes Gets all the item attributes in the page
Controlling an Item Using the Web Connector
The Web connector implements the standard control methods described in Controlling Individual Entities
[page 226]. It also provides additional features for controlling items.
Execute a Script on an Item Within a Web Page
If you cannot complete a control action on an item using standard methods, the Web connector allows you to
execute JavaScript code on the targeted component within the Web page.

You can first use the scriptItem method:
scriptItem Executes JavaScript code on an item and returns the result
For example, the following action:
 Sample Code
MyWebAppli.MyPage.oLogo.scriptItem(“src”);
is executed by the Web connector as follows:
return element.src ;
where <element> is the Web element targeted by the oLogo item.
 Sample Code
// get an attribute
var src = MyWebAppli.MyPage.oLogo.scriptItem ("src");
// set an attribute
MyWebAppli.MyPage.oLogo.scriptItem ("src='http://....png'");
// Fire an event
MyWebAppli.MyPage.oLogo.scriptItem ("dispatchEvent('onblur')");
You can also use the execScript method:
execScript Calls a function on an item
This method is more powerful than the previous one. It also requires greater effort to implement, because
execScript executes a function that has the following signature:
 Sample Code
function myFunction(element, obj)
where:
• <element> is the HTML object associated with item

• <obj> is an extra parameter
This function must be injected into the Web page if it is not yet present.
 Sample Code
// Create a function to change attributes ('obj' contains attributes to

update)
function changeAttributes(element, obj)
{
if (element) {
for (var id in obj) { element[id] = obj[id]; }
}

}
// Inject function in the page

MyWebAppli.MyPage.injectFunction(changeObject);
// Call the function

res = MyWebAppli.MyPage.oLogo.execScript('changeAttributes', {src: ...,
alt : ...});
Getting the HTML Attributes of an Item

You can get additional information about an item using the following methods:
innerHtml Gets the innerHtml content of the item
html Gets the outerHtml content of the item
getAttributes Returns an object with item attributes
You can also get the HTML attributes of all of a page's declared items using the following page method:
getItemAttributes Gets the attributes of all declared items of the page
Overriding the Get/Set Methods

Get and set actions are executed on the controlled application by the Web connector. The standard connector
behavior depends on the type of component being controlled.
 Note
You can override the connector behavior by setting the GetValueMethod or SetValueMethod
parameters.
For each parameter, the value provided is the name of a JavaScript function (up to 63 characters).
The GetValueMethod function overrides the behavior of the get action. It receives the targeted component as
a parameter and must return the component value:
 Sample Code
function myGetValue( theElement )

{
// returns the component value
return theElement.value;
}
The SetValueMethod function overrides the behavior of the ‘set’ action. It receives the targeted component
and the new value as parameters and must set the component value:
 Sample Code
function mySetValue( theElement, theNewValue )

{
// sets the component value

theElement.value = theNewValue;
// sets the component's 'charged' attribute to true
theElement.changed = true ;
}
These functions must have been injected into the running Web screen using one of the following methods:
• the page's injectFunction method

• the PAGE-ONLOAD section
The PAGE/ONLOAD Node
This node lets you specify the source of a script to be injected into the page each time the connector issues a
LOAD of the page. The goal is to inject the specific method scripts (GetValueMethod and SetValueMethod)
as soon as possible to get these methods in the LOAD event for items in CaptData (which is not possible if the
scripts are injected with EXECSCRIPT).
This feature is not implemented in Desktop Studio. If required, you must create this node manually in the
corresponding PSC file.
 Sample Code
<PAGE Name="o_MAIN">
<...>
<ONLOAD>
<![CDATA[
function MyGetValue( TheElement ){ return TheElement.value; }
function MySetValue( TheElement, TheValue ){ TheElement.value =
TheValue; }
]]>
</ONLOAD>
<...>
</PAGE>
Controlling Complex Items Using the Web Connector
Controlling a <select> Component
Get and set actions on a <select> component are executed on the controlled application side by the Web
connector. By default, these actions are executed the following way:
• The get method returns the ‘value’ attribute of the first selected <option> node (or an empty string if no
<option> is selected)
• The set method selects the first <option> node whose value attribute matches the supplied string
You can change the connector behavior using the Key type parameter. If this parameter is set, the Text
property of the <option> node is used instead of the value attribute.
Controlling Other Complex Items
Except for <select> components, the Web connector doesn’t provide specific help for controlling complex
items such as tree, list or grid. To control complex items of these types, you need to control the elements in
their subtrees.

Controlling ActiveX Controls Using the Web Connector
Some Web pages include ActiveX components, such as Treeview.
The content of an ActiveX control cannot be explored by the Web connector, which sees it as a black box.
The best way to control controls of this type is to:
• Declare an item that targets the ActiveX control.

• Control the ActiveX via its API using the scriptItem or execScript methods.
 Sample Code
// Call theAPI method on the ActiveX control targeted by theActiveX item

MyWebAppli.MyPage.theActiveX.scriptItem ("theAPI(..theAPI parameters..)");
The main difficulty is to discover the set of APIs provided by the ActiveX control:
• One way is to search the Web page files (source, scripts) to discover how the ActiveX is controlled (script
files can be found in temporary Internet files).
• Another way is to use the OleView tool to instantiate the installed ActiveX and discover exposed APIs.
• The best way is to obtain the ActiveX API reference guide (where possible).
If you cannot control the ActiveX control by these methods, you can try to use keystrokes or mouse-click (see
Controlling Individual Entities [page 226]).
Special Use Cases With the Web Connector
Applications Running in a Plugin

Applications running in a plugin included in a Web browser (such as Flex applications, Silverlight applications,
or Java applets) must be declared as desktop applications.
WebBrowser embedded in a Desktop application

To control Web screens embedded in a desktop application, don't declare a Web application
• Declare the desktop application using its technology (such as Windows, Java)
• Declare the Web pages required for this application.
Using '_Undefined_' Page

If the Web connector detects an opening Web screen which:
• is a mainframe
• matches application criteria
• doesn't match any page criteria
then the Web connector recognizes it as the special _Undefined_ Page.
This _Undefined_ Page has no items, but it can be used to perform page controlling (such as navigation).
By using this page, you can avoid having to declare a page to perform this type of controlling.

Manage Masked Technical Frames: Use the CY Property
Some Web applications (such as Siebel) use a large number of frames for technical purposes. Some of these
frames are masked and are used to keep Web Screens in cache. These frames are not displayed on the screen,
and must be ignored by the Web connector. A technical frame is identical to a displayed frame, except that its
height is equal to 0.
So, to ignore such technical frames, set the following criterion on the CY property: CY > 0
UNLOAD Event Management

Some use cases need item values to be collected when the Web screen closes.
Ccollection must be executed when the UNLOAD event notification is received. At this time, targeted
components will have been destroyed, so you cannot read item values by controlling the components.
The only way to collect this data is to set the Capture (Auto) parameter on the associated items.
This parameter tells the Web connector to:
• Collect the value of the item's targeted component each time a technical event is notified (not only
UNLOAD).
• Store this value in the event data.
Usually, the Web connector still has access to the Web components when it notifies the UNLOAD event.
Sometimes, certain components are inaccessible, so their value will be missing from the event data.
If you still want to collect this data, you can set the Capture (Cache) parameter of the associated item.
This parameter tells the Web connector to:
• Collect the targeted component value each time its onpropertychange event fires.
• Store this value in an internal cache that will be used to populate the notified technical events.
The Capture (Cache) parameter can also be set at the page level (see Page Parameters [page 73]).
All Capture (Auto) parameters set on the page's items will then be treated as Capture (Cache)
parameters.
Note that if you set the Capture (Auto) or Capture (Cache) parameter on a multiple item, the parameter
will be ignored.
Manage Different Web sites

Depending on the phase of the project, you may have to control the same Web application running on different
Web sites.
For example:
• In the development phase, you control the Web application running on the test site
• In the production phase, you control the Web application running on the production site
You can manage this by setting different criteria on the Domain or Url property. These criteria will be combined
together using the OR logical operator (see Criteria Management [page 269])
Using Broad Criteria

If it is really necessary, you can use very broad criteria for an application (i.e. : Part(URL) = 'http:'). In that case,
declare this application after all other declared Web applications.

Otherwise, all opening Web screens of all running Web applications will match these application criteria. So it is
not possible for them to be recognized as pages of the other declared Web applications.
Script Recognition using the Occurs Method

Sometimes, it is not possible to target a component simply by using an item declaration.
In these cases, you can use the Occurs method.
For multiple items, the Desktop Agent connector targets all occurrences of the recognized components.
You can then use the appropriate index value in a script to target the desired occurrence.
Consider the following use case:
On a Web Screen with a TABLE, you declare an oCell Item to target the cells (TD) of the Date column, knowing
that the user can change the order of the columns.
The only way to manage this use case is to:
• Declare an oHeader multiple Item to target the TH components of the TABLE

• Declare an oCell multiple Item to target the TD components of the TABLE
• By means of a script:
• Loop on the oHeader item occurrences to get the Date column index
• Use this index with the oCell item to target the TD components of the Date column
One Instance per Thread

The identifier of the instance will be the Thread Identifier if checked. Otherwise, it will be the Process Identifier.
Under Windows 7 and Internet Explorer 8 in protected mode, each tab runs in a dedicated process, and popups
are managed by threads of this process.

So, for applications that display popups, using value T for the InstID attribute will cause multiple instances to
be created.
Control a Siebel Application using the Dedicated Extension
Desktop SDKprovides an extension to simplify control of certain Web software products.
A dedicated extension:
• Offers new, specialized methods for controlling pages or items

• Overrides some standard methods to adapt them to the special features of the controlled application
Desktop SDK provides an extension to simplify control of Siebel software. To activate this extension, simply set
the Custom Type parameter of your Web application to SIEBEL.
Mark of the Web
Internet Explorer sometimes refuses the injection and/or execution of JavaScript, or warns the user and asks
for permission:
It may append when the HTML page being controlled is from a local file, or a private network, or even a http
resource that Internet Explorer classifies as unsafe:
To work around this problem, simply include a so-called Mark of the Web in the page's HTML source:
• The URL provided in the mark will be used instead of the actual URL of the page to determine the page's
security.
• The number of characters in brackets gives the size of the specified URL
 Sample Code
<html>

<input Value="ONE"/>
<input Value="TWO"/>
<input Value="THREE"/>
</html>
Using DispatchEvent
At some point, you will have to fire a specific event on a Web page. There are different ways to do that:
• fireEvent
• dispatchEvent
The first way works on Internet Explorer < 9, but for Internet Explorer >= 9 you have to use dispatchEvent.
DispatchEvent does exactly the same things, but before you use it, you have to:

• Create an event.
• Initialize it.
You can then send the event on the current page element using dispatchEvent().
 Sample Code
appli.page.execScript("var eventOnChange =
document.createEvent('HTMLEvents');" //create
"eventOnChange.initEvent('change',true,false);"); //init
appli.page.myItem.scriptItem("dispatchEvent(eventOnChange);"); //send
As you can see, you need to:
• Create and initialize an event directly on the web page using execScript.
• Send the event on the item we want to fire using scriptItem.
Disable HTML Links

Desktop Agent can disable HTML elements thanks to its JavaScript injection features. Whereas disabling
buttons or inputs is quite straightforward with the attribute disabled, this is not the case for links, as this
attribute is not native for <a> elements. So here is how links can be disabled. First, you add a disabled attribute
(we can name it differently) to all of the elements you want to disable:
 Sample Code
// setting disabled attribut on my selector

MyApp.myPage.execScript("$('p >
a.button:contains(\"Stop\")').attr('disabled', 'disabled');");
// here the Jquery selector points to P>a elements with class 'button' and
text containing 'Stop'
The following code must to be executed into the page to disable the 'flagged' elements :
 Sample Code
// code injection that disables all P>a with class="button" and att disabled
MyApp.myPage.execScript("$('p > a.button:contains(\"Stop\")').on('click',
function(event){
if ($(this).attr('disabled') != undefined) {
event.preventDefault();
}
}
);");
To enable the elements:
 Sample Code
MyApp.myPage.execScript("$('p > a.button').removeAttr('disabled');");
Control Web Applications Developed Using Rich HTML and JavaScript Frameworks
Some Web frameworks used in Web applications use dozens of elements to mimic a native HTML element, with
styles and some controller functions.

In some of these frameworks, all or part of the HTML DOM is constructed dynamically by the JavaScript (JS)
framework, rather than by a flat HTML file.
In these cases, you can sometimes see a dropdown select menu that is in fact made with several <divs>,
an image for the down arrow, and a hidden <div> containing the options, which will be displayed when the
element is clicked.
Example:
A select menu in the Dojo + diji framework with two options found on a customer project, will be nine or more
overlapping tags without options, and all control between these tags is performed by the framework:
 Sample Code
<div class="dijit dijitReset dijitInline dijitLeft dijitTextBox dijitComboBox

dijitValidationTextBox entryTemplateSelectorControl dijitTextBoxIncomplete
dijitComboBoxIncomplete dijitValidationTextBoxIncomplete dijitIncomplete"
id="widget_ecm_widget_AddContentItemGeneralPane_0_entryTemplateSelector"
role="combobox" aria-disabled="false" aria-haspopup="true"
widgetId="ecm_widget_AddContentItemGeneralPane_0_entryTemplateSelector"
data-dojo-attach-point="_popupStateNode">
<div class="dijitReset dijitRight dijitButtonNode dijitArrowButton
dijitDownArrowButton dijitArrowButtonContainer"
role="presentation" data-dojo-attach-point="_buttonNode">
<input tabindex="-1" class="dijitReset dijitInputField
dijitArrowButtonInner"
role="button presentation" aria-hidden="true" type="text"
readonly="readonly" value="▼ ">
</div>
<div class="dijitReset dijitValidationContainer">
<input tabindex="-1" class="dijitReset dijitInputField
dijitValidationIcon dijitValidationInner"
role="presentation" type="text" readonly="readonly" value="Χ ">
</div>
<div class="dijitReset dijitInputField dijitInputContainer">
<input tabindex="0" class="dijitReset dijitInputInner"
id="ecm_widget_AddContentItemGeneralPane_0_entryTemplateSelector"
role="textbox" aria-disabled="false" aria-invalid="false" aria-
required="true" type="text" value=""
data-dojo-attach-point="textbox,focusNode" autocomplete="off">
<span class="dijitPlaceHolder dijitInputField">Entrez ou sélectionnez
un modèle d'entrée</span>
<input
name="ecm_widget_AddContentItemGeneralPane_0_entryTemplateSelector"
type="hidden" value="">
</div>
</div>
The same class in the framework documentation: DropDownMenu.html
Reading
In these rich frameworks, Desktop Agent is usually fairly consistent and easy to use when it comes to reading
the value of the element - provided that you find the right HTML element to point to, including possibly in a
hidden field. That is usually done by searching in the elements, the tree or the source of the page captured in
Desktop Studio.
For example, if you want to “read” a birth date, you can just search for the element containing this value,
without really caring about the tag or mechanism used by the framework to display it to the user.
The Name or Text tool windows in the Desktop Studio explorer can be helpful in finding the value you're looking
for.

Or you can use a search in the Tree view.
Writing
In these rich frameworks, writing a value can be much more complex than reading one. In fact, it's sometimes
not possible with the regular .set() instruction alone:
• Partly because the HTML element to be set is very specific and can differ from the one where reading is
possible.
• Partly because setting the element manually (by the end user), triggers JavaScript methods that will
sanitize or look up a value to be passed via code instead of by standard HTML methods.
Usually the challenge will lie in finding and understanding this method, which may be dynamically attached. To
find these methods should you need them, you can use:
• Visual Event 2 (a bookmarklet that is helpful, especially in older browsers, such as before Internet Explorer
11)
• Developer tools in more recent browsers - these will show you which JavaScript functions are attached
when you look at the element
• A site downloader app to search the code across all included files directly in your preferred text editor
Sometimes, depending on the application and its framework, you can use:
• A regular set method, followed by a trigger (execscript or scriptitem with fireEvent for instance or a
JQUERY equivalent) for the method called after manual evaluation, if that's easy to find out.
• A keystroke method, which should trigger the surface controls and the scripts attached to the element
• A change in focus after each input evaluation
• A custom set method (custom function)
When the framework seems overly complicated, and none of the above suggestions seem to help, you can
always search how to set the element by coding according to the framework in question, directly in Google or
Stack Overflow.
This line of JavaScript can then be tested directly in the browser, in the developer tools, and in the JavaScript
console.
Once satisfied with your instruction to set the element, you can use this JavaScript instruction in an
app.page.execscript() command in Desktop Studio, realized with your variables and needs.
2.1.2 The UI Automation Connector
The UI Automation Protocol
UI Automation is a standard protocol developed by Microsoft. It enables applications developed with the
following technologies to be controlled:
• Microsoft technologies (such as Win32, WinForm, WPF, or Silverlight)

• Any technologies that support MSAA (such as QT)

The control capabilities with UI Automation are constrained by:
• The capabilities provided by the UI Automation protocol (you cannot create a component in the controlled
application)
• How the UI Automation protocol is implemented in the controlled applications
Depending on the application to be controlled, the UI Automation protocol can give access to data elements
displayed in complex IHM components, such as:
• Tree items or list items in TreeView or ListBox components in QT applications (requires an accessibility
plugin)
• PDF document content in Acrobat Reader
Performance Management
Unlike other Desktop Agent connectors (such as Windows or Web), the UI Automation connector runs “out of
process”. In other words, it runs in the Desktop Agent process, not in the process of the controlled application.
All control operations are therefore carried out by means of inter-process communication, which is slower than
in-process communication. Most exchanges involve searching through the application tree during recognition.
You can significantly improve recognition performance by limiting the size of the DOM tree that is searched:
• Exclude parts of the DOM tree from being searched

• Set the maximum search depth
• Limit the search space
Defining Entities for a Desktop Application
For details of the entities to define, see Entities for a Desktop Application [page 247].
 Note
If you need to control Web pages embedded in a desktop application, you must define page entities for
each of these Web pages as though they were regular pages of the application.
Application-Based Events
For details, see Application-Based Events [page 247].
Page-Based Events
For details, see Page-Based Events [page 247].

Related Information
Declaring Entities Using the UI Automation Connector [page 94]

Recognition With the UI Automation Connector [page 108]
Controlling Entities Using the UI Automation Connector [page 110]
2.1.2.1 Declaring Entities Using the UI Automation

Connector
This comprises the following tasks:
Using the UI Automation connector:
like.
Usually, you set recognition criteria on the EXE property (process name of the application). This criterion is
automatically set by Desktop Studio when you declare an UI Automation Application.
When you use the UI Automation connector, the following specific parameters are available:
Polling delay Sets the polling timer frequency in milliseconds. The 0 value
sets the default value, so 1000ms (polling mechanism can
not be stopped).

App page name If set, specifies the name of an application page created
when the controlled application starts. You can then use
this page to perform special controlling at application level
(see Controlling Entities Using the UI Automation Connector
[page 110])
Pending delay If > 0, allows you to delay recognition of a loading page when
MustExist items have not yet been created
Refresh on polling Unchecked, allows to avoid starting recognition polling when

the project starts. Note that polling is then stopped for all
the technologies used in the application (UI Automation,
SAPGUI, OCR). It is up to the script to start the recognition
polling by calling the startRefreshOnPolling method
on any running p of the application.
Set Page Criteria
Page criteria are set on the properties of the root component of the targeted screen. They are used by the UI
Automation connector as follows:
The UI Automation connector searches the DOM tree to find all DOM components matching the page's criteria.
If a component matches, the connector doesn't search its subtree to find other instances of the page. The
connector creates one instance of the page for each matching component.
• Precise enough to match the desired root component, and no other

• Robust enough to still work should the screens change
• You can use the following operators: Full, Part, Starts, Ends, like
Usually, you will set recognition criteria on the following properties:
ControlType Controls such as Window or Pane

AutomationId If present and unique, this property is usually set by develop
ers and does not change
Deepness See Use Deepness property under Declaring an Item below
Advanced Recognition Methods for Pages
If the targeted root component has no unique distinguishing properties, you can use one of the following
advanced declaration methods:
• The Root Item Method

For details of this method, see Root Item Method [page 284]:
• The MustExist Method
For details, see MustExist Method [page 284].
• The MustNotExist Method
For details, seeMustNotExist Method [page 284].
• Order of Pages
For details of this topic, see Order of Declared Pages [page 286].
Page-Based Events
The UI Automation protocol describes a wide range of notification events that can be fired by the controlled
applications. The UI Automation connector provides the special SPY(SUBTREE) track event to listen to all
notification messages fired by the components of the page:
• Check the SPY(SUBTREE) track event (see Select Page tracked Events)
• Run your project
• All notification events fired by the application are displayed in the Events view in the following format:
SPYTREE(event)
After receipt of these messages during the execution of the PSC, it is possible to track the events you need.
To do this, right-click the desired event and select Track this event. The corresponding event is added in the
TrackEvents tool window of Desktop Studio.

Page Parameters
Page parameters can be set using Desktop Studio (See Declaring Pages [page 252]).
The UI Automation connector provides the following specific parameters:
Auto Capture on polling Indicates (true) to regularly capture values of items declared
in auto capture.
Multi-instance Indicates (true) if the page can possess multiple instances.
Subpages Type Indicates whether the page can possess multiple (Multiple)
or single (Single) instances of subpages.
Root Item Indicates the item on the parent page used as the root item,
if any (see Root Item Method [page 284])
Refresh mode Determines how page recognition is refreshed (see Recog

nition refreshment) – No: no refresh needed – Window:
refresh on WINDOWOPENED event notification – Polling: re
fresh by polling
Performance Optimization for Page Recognition
Detect optimization needs

To detect optimization needs in page declaration, you can use the recognition cost displayed in the page part of
the Recognition tool window (see About the Recognition Mechanism [page 276]).
For each page, the recognition cost expresses the number of components that must be tested in order to
recognize the page. It is the sum of the number of components tested to recognize:
• The page's root item

• All of its MustExist items
• All of its MustNotExist items
The recognition cost does not give a precise value of the time spent, but a high score (for example, more than
100) indicates pages that are good candidates for optimization.
Before recognizing a page, the UI Automation connector tries to recognize its preceding sibling pages. So, the
actual recognition cost for a page is its own cost or the cost of its preceding sibling pages, whichever is greater
(not the sum of both, thanks to cache management).
So, to optimize the recognition time of a specific page, you need to reduce the recognition cost of the page and
of its preceding sibling pages.
Optimize Page Recognition

The first way to optimize page recognition consist in optimizing:
• Recognition of its root item

• Recognition of all of its MustExist items
• Recognition of all its MustNotExist items
To do this, see Performance Optimization for Item Recognition.
 Note
If you need to use Items Pattern Method [page 286] to optimize root item recognition, you can use Root
Item Method [page 284].
Optimize Cache Management
Refreshing a page by means of polling can be time-consuming, because it requires the cache to be cleared
and the searched subtree to be reloaded from the controlled application (see Performance Management [page
93]).
To optimize cache management, it is possible to avoid refreshing subpages that are always present.
Example:
You have to control an application with a main window (1) that permanently displays a TabControl with
TabItems. You have to control two TabItems (2) and (3):
You declare the following pages:
• pMainWindow to target the main window (required)

• pTabItem1 and pTabItem2 as subpages of pMainWindow.
The pTabItem1 and pTabItem2 targets are not window components and must be detected by polling.

With this declaration, the whole application DOM tree is regularly reloaded. You can optimize performance by
modifying your declaration as follows:
• Declare a pTabControl page to target the TabControl component.

• Since it is always present, you avoid refreshing the pTabControl page.
This way, only the TabControl DOM subtree is regularly reloaded.
In addition, as only one TabItem can be loaded at a time, you can set the pTabControl’s ‘Subpages type’
parameter to ‘Single’). This way, when one pTabItem SubPage is recognized, the software no longer tries to
recognize other subpages of pTabControl.
Pages with a single subpage instance
By default, a parent page that has multiple subpages tries to recognized all of its subpages.
When you declare a parent page to target a TabControl and subpages to target the TabItems, you know that
only one subpage is present at one time.
You can then set the Subpages type parameter of the parent page to ‘Single’. This way, if one subpage is
recognized, the parent page doesn’t try to recognize the others.
Pages with multiple instances
Most pages target only one screen. To optimize page recognition performance, the UI Automation connector
only searches for a page's first target by default.
If you have to manage a page that has multiple targets, check its Multi-instance parameter.
Related Information
Optimizing Page Recognition Performance [page 99]
2.1.2.1.2.1 Optimizing Page Recognition Performance
Detect Optimization Needs
the Recognition tool window’ (see About the Recognition Mechanism [page 276]).

For each page, the recognition cost expresses the number of components that must be tested in order to
recognize the page. It is the sum of the number of components tested to recognize:

The recognition cost does not give a precise value of the time spent, but a high score (for example, more than
Before recognizing a page, the UI Automation connector tries to recognize its preceding sibling pages. So, the
actual recognition cost for a page is its own cost or the cost of its preceding sibling pages, whichever is greater
(not the sum of both, thanks to cache management).
So, to optimize the recognition time of a specific page, you need to reduce the recognition cost of the page and
of its preceding sibling pages.

To do this, see Performance Optimization for Item Recognition.
 Note
Optimize Cache Management
Refreshing a page by means of polling can be time-consuming, because it requires the cache to be cleared
and the searched subtree to be reloaded from the controlled application (see Performance Management [page
93]).
To optimize cache management, it is possible to avoid refreshing subpages that are always present.

Example
You have to control an application with a main window (1) that permanently displays a TabControl with
TabItems. You have to control two TabItems (2) and (3):
You declare the following pages:
• pMainWindow to target the main window (required)

• pTabItem1 and pTabItem2 as subpages of pMainWindow.
The pTabItem1 and pTabItem2 targets are not window components and must be detected by polling.
With this declaration, the whole application DOM tree is regularly reloaded. You can optimize performance
by modifying your declaration as follows:
• Declare a pTabControl page to target the TabControl component.

• Since it is always present, you avoid refreshing the pTabControl page (see Page Parameters [page 97]).
This way, only the TabControl DOM subtree is regularly reloaded.
In addition, as only one TabItem can be loaded at a time, you can set the pTabControl’s ‘Subpages type’
parameter to ‘Single’). This way, when one pTabItem SubPage is recognized, the software no longer tries to
recognize other subpages of pTabControl.

Pages with a Single Subpage Instance
By default, a parent page that has multiple subpages tries to recognized all of its subpages.
Pages with Multiple Instances
only searches for a page's first target by default.
Set Item Criteria
Item criteria are used by the UI Automation connector as follows:
Once the parent page connector recognizes a UI component as a declared page, it can search the component's
subtree to find each item’s target:
• An item will target the first DOM component that matches its criteria.
• If an item is multiple, it will target all of the DOM components that match its criteria.
• Precise enough to match the desired component

• Broad enough to still work if the DOM changes
MustExist or MustNotExist parameters.
You set recognition criteria using Desktop Studio (see): Criteria Management [page 269]).
• You can use the following operators: Full, Part, Starts, Ends, like.
• You can use OR to define a combination of criteria on each property.

ControlType (such as Edit, Button, Text) This criterion is required and automatically set by Desktop
Studio.
AutomationId If present and unique, this property is usually set by develop

ers and do not change.
Deepness Indicates the depth of the component inside the DOM tree
In some cases, it is not possible to recognize a targeted component merely by setting criteria on its properties.
Another component is recognized by mistake. To ensure your declaration is correct, you can use advanced
recognition methods.
The Items Pattern Method [page 286] is frequently used when declaring items with the UI Automation
connector.
 Example
A window contains several DataGrid components, with no discriminant property. You must target the DataGrid
component having a column header (HeaderItem) Date.
You declare your oTable item using the Items Pattern method as follows:
 Sample Code
DataGrid [target]
HeaderItem (Value = 'Date')
The Ancestor Method [page 285] involves declaring an additional technical item. Use it when the Items Pattern
method can't be used. Sometimes, the Ancestor method can also avoid duplication of complex Items Pattern
declarations.
 Example
In a window with several DataGrid components, you have to target the rows (DataItem) of the DataGrid
component which has a column header (HeaderItem) Date.
The DataItem, DataGrid and HeaderItem components are not in a parent-child relationship. That means
you can't declare your oRow item directly using the Items Pattern method. You first have to declare a

technical oTable item which target sthe DataGrid component using the Items Pattern method. You can then
declare the oRow item with the oTable item as its ancestor.
The Labelled By Method [page 285] can also be used.
Use the Range property

In a window with a DataGrid comprising two columns and two rows, you declare an oCell Item to target the cells
(Edit) of the second column of the DataGrid
To address this use case, you can set a criterion on the Range property:
The Range property is calculated by the UI Automation connector and indicates the absolute position of the
component within the DOM tree. When the recognition process tests a criterion on the Range property, it
considers the criterion value as relative to the preceding recognized component:
• The component recognized by the parent item if the Items Pattern method is used.
• The component recognized by the ancestor item if the Ancestor method is used.
• The component targeted by the page if none of these methods are used.
When you set a criterion on the Range property, Desktop Studio automatically sets the relative criterion value.
 Caution
Be aware that this calculation is performed with the criterion is set. If you change the method used (such as
setting the Ancestor) after setting the criterion, the criterion value is not recalculated.
You declare the oCell Item using the Items pattern method. You can then use the Range property to target the
second column.
 Sample Code
oCell declaration
DataGrid
DataItem [occurs]
Edit (range=R1= [target]

Item-Based Events
Item-based events must be explicitly tracked in order to be notified. The UI Automation connector implements
the following standard technical events:
ENABLE Fired when the component becomes enabled
DISABLE Fired when the component becomes disabled
SHOW Fired when the component becomes visible
HIDE Fired when the component becomes invisible
SETFOCUS Fired when the component has gained the input focus
KILLFOCUS Fired when the component has lost the input focus
COMMAND Fired when the component is clicked
CHANGE Fired when the component’s value changes
In addition, the UI Automation connector provides two special track events:
SPY Tracks UI Automation events fired by the targeted compo

nent
SPY (SUBTREE) Tracks UI Automation events fired by the targeted compo

nent and its descendants
The UI Automation protocol specifies a certain number of notification messages, depending on the type of
item. With SPY track events, you can discover the UI Automation notification messages fired by the targeted
component:
• Check the SPY or SPY(SUBTREE) track event

• Run your project
• All notification events fired by the application are displayed in the Events view in the following format:
SPY(event) or SPYTREE(event)

After receiving these messages during the execution of the PSC, it is possible to track the events you need:
• Right-click on the desired event and select menu item Track this event.
• The corresponding event is added in the TrackEvents tool window of Desktop Studio.
 Note
Tracking SPY events is time-consuming. Take care to remove tracking before delivering your project.
Item Parameters
The UI Automation connector provides the following specific parameters:
more details, see MustExist Method [page 284] )
more details, see MustNotExist Method [page 284])
Method [page 285] )
Capture auto If set, the item value is included in each page-based event
Labelled by Indicates (if not empty) the name of the item that must be
recognized as the label (see Labelled By Method [page 285]
Occurs Indicates (true) that the item is indexed
Performance Optimization for Item Recognition

To detect optimization needs in declaring items, you can use the Recognition cost displayed in the Recognition
ToolWindow (see About the Recognition Mechanism [page 276]).
This value is the number of components tested to recognize an item (or the root item of a page). It does not
give a precise value of the time spent, but a high score (for example, more than 100) indicates items that are
good candidates for optimization.
Limit the Search Depth

The first way to optimize item recognition is to limit the search depth.
You do this by setting a criterion on the Deepness property of the targeted component, with the LTOE
operator. This way, the UI Automation connector will limit its search to the indicated depth.
Limiting the search depth can greatly improve recognition performance when controlling an application with a
huge DOM. It is advisable to set a criterion on the Deepness property in page or item declarations.

Note that the Deepness property of a component indicates its depth inside the whole DOM tree. The UI
Automation connector considers the Deepness criterion value as relative to the direct recognized ancestor:
• The preceding component in the Items Pattern method.

• The ancestor in the Ancestor method.
• In all other cases, the parent page.
When you set a criterion on theDeepness property, Desktop Studio automatically calculates the right
criterion’s value, relative to the direct recognized ancestor. If you change the direct ancestor after setting
the Deepness criterion so it can be recalculated.
Limit the Search Space

Another way to optimize item recognition is to limit the search space. This consist in limiting the branches of
the DOM tree where the item is searched.
This can be done by using Ancestor Method [page 285] or Items Pattern Method [page 286].
 Example
You have to declare the oMenuOpen item in the pMain page to target the MenuItem ‘Open’ component
If you declare it as follows, the recognition will search in the three preceding components (StatusBar, Tab,
ToolBar) before searching in the MenuBar pane, and you get a recognition cost of 135.

With the following declaration, you avoid recognition in this three preceding components
For general information on declaring items in Desktop Studio, see Declaration of Page Items [page 262].
2.1.2.2 Recognition With the UI Automation Connector
Advanced Recognition Methods
The following advanced recognition methods can be used with the UI Automation connector:
• Ancestor Method [page 285]

• Labelled By Method [page 285]
• Items Pattern Method [page 286]
• MustExist Method [page 284]
• MustNotExist Method [page 284]
Order of Declared Pages
Please note that the order in which pages are declared is significant. For more information, see Order of
Declared Pages [page 286]

Recognition of Application and Root Pages
The UI Automation connector listens to the desktop to detect the opening of root UI components (children of
the desktop):
• By listening for a WINDOWOPENED event to detect root Windows opening

• By polling to detect opening of anz other type of root components
When the connector detects the opening of a root UI component,
• It looks for the first declared UI Automation application whose criteria match.
• If it finds one, it looks for the first declared root page whose criteria match. If a corresponding root page
is found, the connector associates the new root UI component with that root page, and a LOAD event
notification is issued for the page.
• Otherwise, it ignores the root UI component.
 Note
You must declare a root page entity to control an application's main window.
Subpage Recognition
The UI Automation connector implements the concept of subpages (see Declaring a Page [page 243]).
As soon as a page is recognized, the UI Automation connector tries to recognize each of its subpages. This
recognition is performed in the subtree of the component targeted by the page. That means you must pay
attention to the page-subpage relationship when declaring pages.
Example:
You need to target an application with a main window that sometimes opens a child window. To control the
child window, you will have to declare the following pages:
• a pMainWindow Page to target the main Window (required)

• a pChildWindow as a subpage of pMainWindow, to target the child window
Recognition Refreshment
Page recognition is performed when Desktop Agent starts, and is reexecuted later to refresh the detection of
subpage instances. The way this refresh is performed depends on the individual subpage:
• By listening for the WINDOWOPENED event for subpages targeting window components (RefreshMode
Window)

• By polling for subpages targeting other types of UI component (RefreshMode Polling)
This refresh mode is automatically set when a page is created, but can be modified individually by setting the
subpage parameters (see Page Parameters).
 Caution
Setting this parameter incorrectly can lead to the following error case:
• A page is recognized if the target component is opened when Desktop Agent starts: recognition works
correctly
• A page is not recognized if the target component opens after Desktop Agent has started: refresh fails
2.1.2.3 Controlling Entities Using the UI Automation

Connector
Controlling an Application [page 110]
Controlling a Page [page 111]
Controlling an Item [page 113]
Advanced Use Cases [page 114]
2.1.2.3.1 Controlling an Application
The UI Automation connector implements standard control methods described in Controlling Individual
Entities [page 226]. It also provides the following additional features:
Set Asynchronous Mode
Control actions required by scripts are performed synchronously by the UI Automation connector (see
Understanding Asynchronous and Synchronous Processes [page 517]). If necessary, you can change that
using the following methods:
startAsyncMode Starts asynchronous mode
stopAsyncMode Stops asynchronous mode
In asynchronous mode, all control actions are executed asynchronously.
Example – manually refresh a page using asynchronous mode:
Suppose that you need to refresh a page manually, which takes a long time.

If you execute the ctx.page.refresh method synchronously, you will probably get a server busy message.
To avoid that, you can use asynchronous mode as follows:
 Sample Code
// Starts asynchron mode

MyUIAAppli.startAsyncMode() ;
// Refresh MyPage using asynchron mode
MyUIAAppli.MyPage.refresh() ;
// Returns to default synchron mode
MyUIAAppli.stopAsyncMode() ;
Manage Recognition Polling
Some technologies make Pages recognition by using polling (UI Automation, SAPGUI, OCR). By default,
recognition is started as soon as the project starts, even if no scenario is running. This allows to:
• Test recognition without having any scenario running (Dev time)

• Start a scenario when one specific Page is recognized
It is possible to stop this polling on an UI Automation application:
• At runtime, by using the stopRefreshOnPolling methods on any of its running Page

• At start time, by unchecking the Refresh on polling flag in the Application parameters
Polling is then stopped for all the technologies used in the application (UI Automation, SAPGUI, OCR).
In both cases, it is up to the script to restart the polling by calling the startRefreshOnPolling method on
any running Page of the Application.
2.1.2.3.2 Controlling a Page
Entities [page 226]. It also provides additional features for controlling pages.
Suspend Automatic Refresh
If you have declared a page with a RefreshMode to ‘Polling’, the page subtree is periodically refreshed (see Page
Parameters [page 97] ). This refresh is made by polling, so you don’t know exactly when it is done.
If you have to control a set of items on a page of this kind, automatic refresh can slow controlling if it is
performed between control actions.

To avoid this, you can suspend automatic refresh using the following methods:
lockRefresh Suspend automatic refresh
unlockRefresh Resume automatic refresh
Example:
 Sample Code
// Suspend automatic refresh

MyAppli.MyPage.lockRefresh() ;
// Control Items
MyAppli.MyPage.MyItem1.set('my value1');
...
MyAppli.MyPage.MyItemN.set('my valueN');
// Resume automatic refresh

MyAppli.MyPage.unlockRefresh() ;
Force Manual Refresh
If you have declared a page with a RefreshMode to ‘Polling’, the page subtree is periodically refreshed (see Page
Parameters [page 97]). This refresh is performed by polling, which means you don’t know exactly when it is
done.
To be sure that a refresh has been done before control actions are performed, you can force a refresh.
To do this, use the following method:
refresh Force a page to refresh its subtree and to perform recogni

tion of its subpages
Example – Wait until an item is present:
 Sample Code
ctx.polling({delay: 100,nbMax: 10,

test: function(index)
{
// Force MyPage to refresh its subtree
MyAppli.MyPage.refresh() ;
// Test MyItem existence
return MyAppli.MyPage.MyItem.exist();
},
...
});

2.1.2.3.3 Controlling an Item
Entities [page 226]. It also provides additional features for controlling items.
Read the Value of Any Property
The standard get method returns the value of an item:
• The content of the Value property for EntryFields

• The content of the Value property of the selected element for ListBox
• The check state for radio buttons or checkboxes
You can also get the value of any other property of the targeted element. To do this, use the following method:
getProperty Gets the value of a property of the targeted component
Example – Get the name of an item
 Sample Code
// Get the value of the 'Name' property

var strName = MyAppli.MyPage.MyItem.getProperty('Name')
Controlling a Complex Item Using the UI Automation Connector
Using the UI Automation connector, complex items such as trees or lists often have a subtree containing their
elements (like in Web).
 Note
Very often, a subtree only contains visible elements. The following elements are generally not present in a
subtree:
• Elements of a collapsed branch of a tree

• Non-visible elements
If you control a complex item by using its subtree, you must manually refresh this subtree after executing
actions which changes the item display (scrolling, expand, and so on).
You do this by using the following method:
refresh Force the item to refresh its subtree
Example:

In a tree, double-click on a TreeItem, children of another TreeItem which is collapsed. You have declared:
• MyTree to target the Tree

• MyParentItem to target the parent TreeItem
• MyChildItem to target the child TreeItem
 Sample Code
// Double-click on MyParentItem to expand it

MyAppli.MyPage.MyParentItem.clickDouble();
// Refresh MyTree subtree so MyChildItem is recognized
MyAppli.MyPage.MyTree.refresh() ;
// Double-click on MyChildItem
MyAppli.MyPage.MyChildItem.clickDouble() ;
2.1.2.3.4 Advanced Use Cases
Declaration of a Multilingual Application
If the AutomationId property can't be used, you can set a criterion on the Name property. For multilingual
applications, you can set different values for this criterion, combined with the OR operator (see Criteria
Page is dynamically created and some MustExist Items are not present at load time
When you declare a page that has a RefreshMode parameter equal to 'Window' and a MustExist item, that item
must be recognized when the page opens.
 Note
If this MustExist Item is not present at load time, but is dynamically created later, the page will not be
recognized until you have set the 'Pending delay' parameter. For details of setting application parameters,
see Set Application Parameters [page 94] .
COMMAND event is tracked but doesn't fire
In some cases, a COMMAND event tracked on a button doesn't fire when the user clicks it. This is a known
problem due to a default in the implementation of the UI Automation protocol by the controlled application. To
get around this problem, you can tell to the connector to listen to another type of event termed WinEvents.
You must do this explicitly in a script using the listenWinEvents method:
 Sample Code
MyAppli.MyPage.listenWinEvents() ;
This method must be executed at least once to activate the workaround.

Declare Pages That Have Multiple Instances
only searches for the first target of a page. If you need to manage a page that has multiple targets, check its
Multi-instance parameter. For details of page parameters, see Page Parameters [page 97].
Collect Item Values When the Screen Closes
Some use cases implies collecting Items value once the Screen closes.
This collection must be executed when receiving the UNLOAD event notification. At this time, targeted
components will have been destroyed, so you can't use controlling to read item values.
The only way to collect this data is to set the Capture Auto parameter on the associated items. This
parameter tells the connector to:
• Collect the value of the component associated with the item every time a technical event is notified (not
only UNLOAD).
If there is no technical event to collect an item's value, you can tell the connector to collect data each time a
polling occurs, by setting the page parameter Auto Capture on polling. Please note, however, that this
option is time-consuming, because item recognition is performed on each polling.
Right-Click an Item
Using this connector, you can right-click an item using the actionApp method as follows:
 Sample Code
myAppli.myPage.actionApp('RFCTBTNM', 'myItem') ;
The right-click is performed in the center of the item. You can force a right-click at another position relative to
the top-left corner of the item by setting offsetX and offsetY values:
 Sample Code
myAppli.myPage.actionApp('RFCTBTNM', 'myItem', 'offsetX', 'offsetY') ;
If you need to right-click an indexed item, you can set the desired index as follows:
 Sample Code
myAppli.myPage.actionApp('RFCTBTNM', 'myItem[iIndex]') ;
 Note
The right-click is a mouse-click, so the controlled Item must be at the foreground to receive the right-
click.
Example:

 Sample Code
// Right-click on the third occurrence of myItem, at (10,10) pixels from the

top-left corner
myAppli.myPage.actionApp('RFCTBTNM', 'myItem[2]', '10', '10') ;
Script Recognition with the Occurs method

It is sometimes impossible to target a component simply by using item declaration. In these cases, you can use
the Occurs method.
For indexed items, the Desktop Agent connector targets all the occurrences of the recognized components.
 Example
In a window with a DataGrid, you declare an oCell item to target the cells (Edit) of the Date column, knowing
• Declare an oHeader item to target the HeaderItem components of the DataGrid

• Declare an oCell indexed item to target the Edit components of the DataGrid
• With a script:
• Loop on occurrences of the oHeader item to get the Date column index
• Use this index with the oCell item to target the Edit components of the Date column
 Sample Code
oHeader declaration
• DataGrid
◦ Header [occurs]
◾ HeaderItem [occurs] [target]
oCell declaration
• DataGrid
◦ DataItem [occurs]
◾ Edit [occurs] [target]

Capture Pages With Huge Trees
Sometimes, capturing pages with UI Automation can take a long time, depending on the application. There are
two ways to reduce this delay:
• If it takes a long time before the page you wish to capture is given the focus, uncheck the ShowAll button to
avoid exploring the whole tree
• If the capture itself takes a long time, click the Int button to stop counting and start capturing. You will then
have a partial capture, which may be big enough for the purpose of declaring items
Control Qt Applications
Controlling Qt applications requires:
• A Qt accessibility plugin to drive complex controls (such as trees)

• Version 7 of Microsoft Active Accessibility (MSAA) to enable this plugin (automatically installed by security
update http:/support.microsoft.com/kb/2564958)
Click a Button that Opens a Modal Popup
If you have to click a button that opens a modal popup, the MyAppli.MyPage.MyButton.click() method can:
• Block the execution of subsequent actions

• Block the receipt of technical events.
To avoid this, you can perform a mouse-click instead, using the MyAppli.MyPage.MyButton.click(true) method.
 Note
From version 3.3 of the SAP GUI connector, this problem is solved by performing asynchronous clicks that
do not lock the connector.
You can disable this mechanism by setting the AsyncElementInvoke setting to false in the
CxUIAProvider.xml file in theconfig subdirectory of Interactive.
2.1.3 The SAP GUI Connector
You can capture SAP applications with Desktop Agent using the SAP GUI connector.
SAP GUI for Windows is a front-end application that you can use to access SAP applications such as SAP ERP,
SAP Business Suite, and so on. It is designed for the Windows operating system and provides a Windows-like
user experience and integration with other applications based on OLE interfaces or ActiveX controls.
For automation purposes, you need to enable and use the SAP GUI Scripting API. You need to enable
both client [page 120] and server [page 124] scripting. A JavaScript library (SAPScripting.js) is available to
implement specific behaviors.
For more information, see the Desktop SDK Reference Guide.

Capturing an SAP GUI Application
1. Launch SAP Logon.

2. Start the Desktop Studio.
3. From the Explorer perspective, add a new application.
4. In the Capture Application window, choose UIAutomation if necessary, and select SAP Logon.
5. Add a page and leave Choose Technology unselected.
 Note
the correct technology is usually preset.
6. Choose the UI elements that you want to control.
Using an SAP GUI Application in Your Project
To use an SAP GUI application in your project, proceed as you would for a native Windows application. Use the
Workflow Designer or apply scripting directly.
Examples

2.1.3.1 Enabling Scripting on the Client Side
Context
To use SAP GUI for Windows for automation purposes, both client and server scripting must be enabled

Procedure
1. Launch the Control Panel, choose Appearance and Personalization , and launch SAP GUI configuration.
2. Navigate to Accessibility & Scripting.

3. Choose Scripting and check that only Enable Scripting is selected (the other options are not required).
You have now enabled scripting.

Next Steps
How to see if SAP GUI Scripting is running when a script is running
For some Visual Design options, you can know if SAP GUI Scripting is running by hovering over this icon:
For other options, you can know if SAP GUI Scripting is running by hovering over the following icon:

2.1.3.2 Enabling Scripting on the Server Side
Context
To use SAP GUI for Windows for automation purposes, server scripting must be enabled.
Procedure
1. Launch SAP Logon and connect to the server.

2. From the SAP Easy Access screen, enter transaction RZ11.

3. Enter parameter sapgui/user_scripting.
4. If not enabled, click Change Value.

5. Enter TRUE as the new value and click Save.
Scripting is now enabled.

 Tip
If you get an error message "Exception has been thrown by the target of an invocation", you must set
sapgui/user_scripting_set_readonly to FALSE in transaction RZ11.
Next Steps
Sometimes, following this procedure does not give you enough rights.
In this case, you must open a ticket for another component: BC-FES-GUI.
For more information, see Mode Combination for Server Side Protection in the SAP GUI Scripting Security
Guide.
2.1.3.3 Declaring Entities Using the SAP GUI Connector
Declaring the SAPLogon Application
SAPLogon.exe is a multi-technology application.

It includes:
• Windows technology
• SAP GUI technology
• Web technology
All SAP transactions based on SAP GUI are accessed through the SAPLogon application. This application must
be declared using UI Automation technology, by targeting the SAPLogon window (see Declaring an Application
[page 94]). UI Automation technology lets you declare UI Automation pages, SAP GUI pages, and Web pages.
Once you have declared the SAPLogon application, you need to do the same with the SAPLogon page.
This declaration activity also requires the following tasks to be performed:
Set Page Criteria
Page criteria are set on the properties of the root component of the targeted screen. They are used by the SAP
GUI connector as follows:
The SAP GUI connector searches the DOM tree to find all DOM components matching the page's criteria.
• Precise enough to match the desired root component, and no other

• Robust enough to still work should the screens change
like.
• You must declare at least one recognition criterion (unless you use Root Item Method [page 284]).
Type For example, GuiMainWindow, GuiModalWindow
Text The title of the window

Deepness See Performance Optimization for Item Recognition [page
134]
If the targeted root component has no unique distinguishing properties, you can use one of the following
advanced declaration methods:
• Root Item Method [page 284]

Page-Based Events
Page Parameters
Page parameters can be set using Desktop Studio (See Declaring Pages [page 252]).
The SAP GUI connector provides the following specific parameters:
Auto Capture on polling Indicates (true) to regularly capture values of items declared
in auto capture (see Advanced Use Cases [page 144]).
Multi-instance Indicates (true) if the page can possess multiple instances

(see Advanced Use Cases [page 144])
Subpages Type Indicates whether the page can possess multiple (Multiple)
or single (Single) instances of subpages (see Performance
Optimization for Page Recognition [page 130])
Root Item Indicates the item on the parent page used as the root item,
if any (see Root Item Method [page 284])

Performance Optimization for Page Recognition

the Recognition tool window (see About the Recognition Mechanism [page 276]).
For each page, the recognition cost provides the number of components that must be tested in order to
recognize the page. It is the sum of the UI components tested to recognize:

The recognition cost does not give a proper value of the time spent, but a high score (for example, more than
Before recognizing a page, the SAP GUI connector tries to recognize its preceding sibling pages. So, the actual
recognition cost for a page is its own cost or the cost of its preceding sibling pages, whichever is greater (not
the sum of both, thanks to cache management).
To optimize the recognition time of a specific page, you need to reduce the recognition cost of the page and of
its preceding sibling pages.


To do this, see Performance Optimization for Item Recognition [page 134].
 Note
Pages with a Single Subpage Instance

By default, a parent page that has multiple subpages tries to recognize all of its subpages.
Pages with Multiple Instances

Most pages target only one screen. To optimize page recognition performance, the SAP GUI connector only
searches for a page's first target by default.

Declaring an Item
For general information on declaring items in Desktop Studio, see Declaration of Page Items [page 262].
Set Item Criteria
Item criteria are used by the SAP GUI connector as follows:
Once the SAP GUI connector recognizes a UI component as a declared page, it can search the component's
• If an item is indexed, it will target all of the DOM components that match its criteria.
• Accurate enough to match the desired component

MustExist or MustNotExist parameters.
You set recognition criteria using Desktop Studio (see Criteria Management [page 269] ):
• You can use the following operators: Full, Part, Starts, Ends, like
• You can use OR to define a combination of criteria on each property.
Type (such as GuiButton or GuiTextField) This criterion is required and automatically set by Desktop
Studio.
Name If present and unique, this property is usually set by develop

ers and do not change.
LeftLabel Indicates the text of the label associated with the compo
nent.
Deepness Indicates the depth of the component inside the DOM tree.

The Items Pattern Method [page 286] is frequently used when declaring items with the SAP GUI connector.
 Example
A window contains several DataGrid components, with no unique distinguishing property. You must target
the DataGrid component that has a column header (HeaderItem) Date.
You declare your oTable item using theItems Pattern method as follows:
 Sample Code
DataGrid [target]
HeaderItem (Value = 'Date')
The Ancestor Method [page 285] consists in finding an ancestor component of the targeted component
that has unique distinguishing properties. This ancestor component must not be among the ancestors of
components that you do not want to recognize by mistake.
The Ancestor method requires the declaration of an additional technical item. Use it when the Items Pattern
method can't be used. Sometimes, the Ancestor method can be used to avoid the duplication of complex items
pattern declarations.
 Example
In a window with several DataGrid components, you have to target the rows (DataItem) of the DataGrid
component which has a column header (HeaderItem) Date.
The DataItem, DataGrid and HeaderItem components are not in a parent-child relationship. That means
you can't declare your oRow item directly using the Items Pattern method. You first have to declare a
technical oTable item which target sthe DataGrid component using the Items Pattern method. You can then
declare the oRow item with the oTable item as its ancestor.
The Labelled By Method [page 285] consists in finding another component that is at a fixed distance (CX, CY)
from the target component and has unique distinguishing properties.

Use the Range Property
 Example
In a window with a DataGrid comprising two columns and two rows, you declare an oCell Item to target the
cells (Edit) of the second column of the DataGrid
To address this use case, you can set a criterion on the Range property, as explained below.
You declare the oCell Item using theItems pattern method. You can then use the Range property to target the
second column.
 Sample Code
oCell declaration
DataGrid
DataItem [occurs]
Edit (range=R1= [target]
The Range property is calculated by the SAP GUI connector and indicates the absolute position of the
component within the DOM tree. When the recognition process tests a criterion on the Range property, it
considers the criterion value as relative to the preceding recognized component:
• The component recognized by the parent item if the Items Pattern method is used.
• The component recognized by the ancestor item if the Ancestor method is used.
• The component targeted by the page if none of these methods are used.
When you set a criterion on the Range property, Desktop Studio automatically sets the relative criterion value.

 Caution
Be aware that this calculation is performed when the criterion is set. If you change the method used (such
as setting the Ancestor) after setting the criterion, the criterion value is not recalculated.
Item Parameters
The SAP GUI connector provides the following specific parameters:
more details, see MustNotExist Method [page 284])
Method [page 285] )
Labeled by Indicates (if not empty) the name of the item that must be
Occurs Indicates (true) that the item is indexed
To detect optimization needs in declaring items, you can use the Recognition cost displayed in the Recognition
ToolWindow (see About the Recognition Mechanism [page 276]).
This value is the number of components tested to recognize an item (or the root item of a page). It does not
give an accurate value of the time spent, but a high score (for example, more than 100) indicates items that are
good candidates for optimization.
Limit the Search Depth
The first way to optimize item recognition is to limit the search depth.
You do this by setting a criterion on the Deepness property of the targeted component, with the ‘LTOE’
operator. This way, the SAP GUI connector will limit its search to the indicated depth.
Limiting the search depth can greatly improve recognition performance when controlling an application with a
huge DOM. It is good practice to set a criterion on the Deepness property in page or item declarations.

Note that the Deepness property of a component indicates its depth inside the whole DOM tree. The SAP GUI
connector considers the Deepness criterion value as relative to the direct recognized ancestor:
• The previous component in the Items Pattern method

• The ancestor in the Ancestor method
• In all other cases, the parent page
When you set a criterion on the Deepness property, Desktop Studio automatically calculates the right
criterion’s value, relative to the direct recognized ancestor. If you change the direct ancestor after setting
the Deepness criterion, you have to reset (delete+add) the Deepness criterion so it can be recalculated.
Limit the Search Space

Another way to optimize item recognition is to limit the search space. This consist in limiting the branches of
the DOM tree where the item is searched.
This can be done by using Ancestor Method [page 285] or Items Pattern Method [page 286].
 Example
You have to declare the oMenuOpen item in the pMain page to target the MenuItem ‘Open’ component:
If you declare it as follows, the recognition will search in the three preceding components (StatusBar, Tab,
ToolBar) before searching in the MenuBar pane, and you get a recognition cost of 135.

With the following declaration, you avoid recognition in these three preceding components:
2.1.3.4 Recognition with the SAP GUI Connector
Performance Management
Unlike other Desktop Agent connectors, such as Windows and WEB, the SAP GUI connector runs out of
process. That means that it runs within the Desktop Agent process and not within the process of the
application being controlled.
All control is therefore carried out by means of inter-process communication, which is slower than in-process
communication. Most exchanges related to exploring the application's tree during recognition. You can
significantly improve recognition performance by limiting the size of the DOM tree explored:
• Exclude certain parts of the DOM tree from exploration

• Set the maximum depth of exploration using the Deepness property
• Limit the exploration space
The SAPLogon main page must be declared. At runtime, as soon as this main page is recognized, a START
event is delivered for the SAPLogon application. The SAP GUI connector then starts collecting the DOM of the
SAPLogon application by polling the SAP GUI component.
For each GuiMainWindow or GuiModalWIndow detected,

• the SAP GUI connector looks for the first declared SAPGui root page whose criteria match.
• If it finds one, it associates the GuiWindow with the root page found, and a LOAD event notification is
issued for the page. As soon as a page is recognized, the SAP GUI connector tries to recognize each of
its subpages. This recognition is performed in the subtree of the component targeted by the page. That
means you must pay attention to the page-subpage relationship when declaring pages.
• Otherwise, it ignores the GuiWindow.
Subpage Recognition
The SAP GUI connector implements the concept of subpages (see Declaring a Page [page 243]).
As soon as a page is recognized, the SAP GUI connector tries to recognize each of its subpages. This
recognition is performed in the subtree of the component targeted by the page. That means you need to
take page-subpage relationships into account when declaring pages.
Example:
child window, you must declare the following pages:
• a pMainWindow Page to target the main Window (required)

Recognition Refreshment
Page recognition is performed when Desktop Agent starts, and is reexecuted later to refresh the detection of
subpage instances. The SAP GUI connector refreshes detection at each polling time. It is possible to stop this
polling:
• At runtime, by using the stopRefreshOnPolling methods on any of its running Page

• At start time, by unchecking the 'Refresh on polling' flag in the application parameters
Polling is then stopped for all the technologies used in the application (UI Automation, SAPGUI, OCR).
In both cases, it is up to the script to restart the polling by calling the startRefreshOnPolling method on
any running Page of the Application.
2.1.3.5 Controlling Entities Using the SAP GUI Connector
Controlling a Page [page 138]

Controlling an Item [page 142]
2.1.3.5.1 Controlling a Page
SAP GUI uses SAP scripting to execute automation scenarios.
The SAP GUI connector implements standard control methods described in Controlling Individual Entities
[page 226]. It also provides additional features for controlling pages.
Stop and Start SAP Scripting [page 138]
Check Whether the SAP GUI Server is Busy [page 140]
Extend the Wait Period When the SAP Session is Busy [page 141]
Suspend Automatic Refresh [page 141]
Force Manual Refresh [page 142]
Avoid the SAP GUI Busy Server Message [page 142]

When you are working with the SAP GUI application, you can receive a busy server message.
2.1.3.5.1.1 Stop and Start SAP Scripting
Methods to Explicitly Start and Stop Polling
SAP GUI bots enable SAP scripting in order to execute. A polling mechanism is used to recognize SAP
GUI pages that are loaded and unloaded dynamically, and to identify changes in a SAP GUI page. In turn,
continuous polling keeps SAP scripting enabled.
But when bot execution ends, it's necessary to stop polling. Otherwise, the UI will behave strangely to a
user who is controlling it manually. For example, script-friendly file dialog boxes are displayed rather than the
regular, user-friendly ones.
Two methods are provided to explicitly start and stop the polling process, which in turn starts and stops SAP
scripting:
• stopRefreshOnPolling
• startRefreshOnPolling

stopRefreshOnPolling
To stop SAP scripting, call this method on the SAP Logon page, as shown below. You need to
callstopRefreshOnPolling at the end of every workflow.
 Sample Code
SAPLogon750.pWindowSAPLogon76.stopRefreshOnPolling()
// Wait until the page loads
SAPLogon750.pageSortOrder.wait(function(ev) {
SAPLogon750.pageSortOrder.setFocus();
SAPLogon750.pageSortOrder.oItem3.click();
sc.endStep(); // end scenario
SAPLogon750.pWindowSAPLogon76.stopRefreshOnPolling();
return;
});
}});
startRefreshOnPolling
If SAP scripting has been stopped using the method stopRefreshOnPolling, you can enable it using
startRefreshOnPolling at the beginning of a workflow. You call the method on the SAP Logon page.
 Sample Code
SAPLogon750.pWindowSAPLogon76.startRefreshOnPolling();
// -------------------------------------
// Test menu for scenario oItem2Workflow
// -------------------------------------
GLOBAL.events.START.on(function (ev) {
if (ctx.options.isDebug) [
// Add item in systray menu.
systray.addMenu('', 'oItem2WOrkflow', 'Test.oItem2Workflow', '', function
(ev) {
var rootData = ctx.dataManagers.rootData.create();
SAPLogon750.pWindowSAPLogon76.startRefreshOnPolling();
SAPLogon750.scenarios.oItem2Workflow.start(rootData);
});
}
});
Call stopRefreshOnPolling Wherever a Workflow Could Fail
SAP Scripting does not automatically stop if a workflow fails. So you need to explicitly call
stopRefreshOnPolling at any step at which you think a workflow could fail, if SAP scripting should stop
at that point in case of failure.

Start Polling When Disabled by Default at Application Level
When the parameter Refresh on polling is unchecked in the Desktop Studio at application level, polling is
disabled by default. This prevents an agent from accessing SAP scripting when the agent starts.
However, refresh on polling needs to be enabled during bot execution in order to detect SAP GUI pages and
items. In the workflow JavaScript file, enable refresh on polling on the SAP Logon page. In the example below,
the page name is pLogon.
Add the following statement immediately after calling the start() method for the SAP GUI application:
SAPLogon760.pSAPLogon.startRefreshOnPolling();
 Sample Code
// ---------------------------------------
// Step: stStartSAPLogon
// ---------------------------------------
GLOBAL.step( {
stStartSAPLogon: function (ev, sc, st) {
var rootData_Data = sc.data;
ctx.workflow('DepreciationPostRun', '4c8d6beb-680d-486b-8f7a-
e65d53b4169d');
// Start 'SAP'
SAP.start();
SAP.pLogon.startRefreshOnPolling();
rootData_Data.output.message.push("Scenario started");
sc.endStep(); // stLogon
return ;
}
});
2.1.3.5.1.2 Check Whether the SAP GUI Server is Busy
While SAP GUI is waiting for some action to be completed, such as loading a large table or uploading a file, the
status of the SAP GUI server is busy. If you know that the previous automation action might cause the SAP GUI
server to be busy, it is best practice to check its status before sending the next automation action. If it is not
busy, you perform the action. Otherwise, return a 'server is busy' message. To check the current status, you
can use the isSAPGuiBusy method, which is available at page and item level.
 Sample Code
loop(SAPLogon750.pTCURRDisplayOfEnt.isSAPGuiBusy()){
ctx.log('SAPGUI is busy");
}
//then the next action
SAPLogon750.pTCURRDisplayOfEnt.oTxt.get();
If your current automation action could make the SAP GUI server busy, wrap the automation action inside an
asynchronous block.

2.1.3.5.1.3 Extend the Wait Period When the SAP Session is
Busy
When an action is sent to the SAP GUI, and the SAP session is busy - even for a few milliseconds - it can throw
an error. To overcome this issue, a timer is set for 1000 milliseconds by default whenever an action is sent to
SAP GUI. During this period, the system frequently checks whether the session is busy. If the session becomes
free before the time elapses, execution starts immediately. It is also possible to increase the time period using
the setBusyWaitTime method.
The setBusyWaitTime method should be called in the first step of a workflow so that the same wait time is
used for all of the following steps. You can call the method using any page that is currently loaded. For more
details and a code example, see setBusyWaitTime.
Make sure you call resetBusyWaitTime at the end of the workflow, using the page currently loaded in the
last step. This method resets the wait time to the default value of 1000 milliseconds. For details and a code
example, see resetBusyWaitTime.
 Note
It is mandatory to call resetBusyWaitTime at the end of a workflow in which setBusyWaitTime was

called. Otherwise the wait time is changed for all subsequent workflows as well.
2.1.3.5.1.4 Suspend Automatic Refresh
In the SAP GUI Connector, the DOM tree is automatically refreshed to recognize the page.
If you have to control a set of items on a page of this kind, automatic refresh can slow controlling if it is
performed between individual control actions.
To avoid this, you can suspend automatic refresh using the following methods:
lockRefresh Suspend automatic refresh
unlockRefresh Resume automatic refresh
Example:
 Sample Code
// Suspend automatic refresh

MyAppli.MyPage.lockRefresh() ;
// Control Items
...
MyAppli.MyPage.MyItemN.set('my valueN');
// Resume automatic refresh

MyAppli.MyPage.unlockRefresh() ;

2.1.3.5.1.5 Force Manual Refresh
To be sure that a refresh has been carried out before control actions are performed, you can force a refresh.
To do this, use the following method:
refresh Force a page to refresh its subtree and to perform recogni

tion of its subpages
Example – Wait until an item is present:
 Sample Code
ctx.polling({delay: 100,nbMax: 10,

test: function(index)
{
// Force MyPage to refresh its subtree
MyAppli.MyPage.refresh() ;
// Test MyItem existence
return MyAppli.MyPage.MyItem.exist();
},
...
});
2.1.3.5.1.6 Avoid the SAP GUI Busy Server Message
When you are working with the SAP GUI application, you can receive a busy server message.
This issue is caused by subpages. Subpages freeze SAP Scripting and a busy server message appears on your
screen.
The best practices to avoid this issue are the following:
• Avoid subpages when you are working with the SAP GUI application.
• Minimize the number of Must Exist / Must not Exist elements in a page.
2.1.3.5.2 Controlling an Item
The SAP GUI connector implements standard control methods described in Controlling Individual Entities
[page 226]. It also provides additional features for controlling items.

Read the Value of Any Property
The standard get method returns the value of an item:
• The content of the ‘Value’ property for EntryFields

• The content of the ‘Value’ property of the selected element for ListBox
• The check state for radiobuttons or checkboxes
You can also get the value of any other property of the targeted element. To do this, use the following method:
getProperty Gets the value of a property of the targeted component
 Example
Get the name of an item
 Sample Code
// Get the value of the 'Name' property

var strName = MyAppli.MyPage.MyItem.getProperty('Name')
Controlling Complex Items Via a Subtree
Using the SAP GUI connector, complex items such as tables often have a subtree containing their elements
(like in Web).
Be aware that, very often, the subtree only contains visible elements. The following elements are generally not
present in the subtree:
• Elements of a collapsed branch of a tree

• Non-visible elements
If you control a complex item using its subtree, you must manually refresh this subtree after executing
actions that change the item display (such as scrolling or expanding).
You do this by using the following method :
refresh Force the item to refresh its subtree
Example:
In a tree, double-click on a TreeItem, children of another TreeItem which is collapsed. You have declared:
• MyTree to target the Tree

• MyParentItem to target the parent TreeItem
• MyChildItem to target the child TreeItem

 Sample Code
// Double-click on MyParentItem to expand it

MyAppli.MyPage.MyParentItem.clickDouble();
// Refresh MyTree subtree so MyChildItem is recognized
MyAppli.MyPage.MyTree.refresh() ;
// Double-click on MyChildItem
MyAppli.MyPage.MyChildItem.clickDouble() ;
Declaration of a Multilingual Application
If the AutomationId property can't be used, you can set a criterion on the Name property. For multilingual
applications, you can set different values for this criterion, combined with the OR operator (see Criteria
Declare Pages That Have Multiple Instances
only searches for the first target of a page. If you need to manage a page that has multiple targets, check its
Multi-instance parameter. For details of page parameters, see Page Parameters [page 97].
Collect Item Values When the Screen Closes
Some use cases implies collecting Items value once the Screen closes.
This collection must be executed when receiving the UNLOAD event notification. At this time, targeted
components will have been destroyed, so you can't use controlling to read item values.
The only way to collect this data is to set the Capture Auto parameter on the associated items. This
parameter tells the connector to:
• Collect the value of the component associated with the item every time a technical event is notified (not
only UNLOAD).
If there is no technical event to collect an item's value, you can tell the connector to collect data each time a
polling occurs, by setting the page parameter Auto Capture on polling. Please note, however, that this
option is time-consuming, because item recognition is performed on each polling.
Right-Click an Item
Using this connector, you can right-click an item using the actionApp method as follows:
 Sample Code
myAppli.myPage.actionApp('RFCTBTNM', 'myItem') ;

The right-click is performed in the center of the item. You can force a right-click at another position relative to
the top-left corner of the item by setting offsetX and offsetY values:
 Sample Code
myAppli.myPage.actionApp('RFCTBTNM', 'myItem', 'offsetX', 'offsetY') ;
If you need to right-click an indexed item, you can set the desired index as follows:
 Sample Code
myAppli.myPage.actionApp('RFCTBTNM', 'myItem[iIndex]') ;
 Note
The right-click is a mouse-click, so the controlled Item must be at the foreground to receive the right-
click.
Example:
 Sample Code
// Right-click on the third occurrence of myItem, at (10,10) pixels from the

top-left corner
myAppli.myPage.actionApp('RFCTBTNM', 'myItem[2]', '10', '10') ;
Script Recognition with the Occurs method
It is sometimes impossible to target a component simply by using item declaration. In these cases, you can use
the Occurs method.
For indexed items, the Desktop Agent connector targets all the occurrences of the recognized components.
 Example
In a window with a DataGrid, you declare an oCell item to target the cells (Edit) of the Date column, knowing

• Declare an oHeader item to target the HeaderItem components of the DataGrid

• Declare an oCell indexed item to target the Edit components of the DataGrid
• With a script:
• Loop on occurrences of the oHeader item to get the Date column index
• Use this index with the oCell item to target the Edit components of the Date column
 Sample Code
oHeader declaration
• DataGrid
◦ Header [occurs]
◾ HeaderItem [occurs] [target]
oCell declaration
• DataGrid
◦ DataItem [occurs]
◾ Edit [occurs] [target]
Click a Button that Opens a Modal Popup

If you have to click a button that opens a modal popup, the MyAppli.MyPage.MyButton.click() method can:
• Block the execution of subsequent actions

• Block the receipt of technical events.
To avoid this, you can perform a mouse-click instead, using the MyAppli.MyPage.MyButton.click(true) method.
 Note
From version 3.3 of the SAP GUI connector, this problem is solved by performing asynchronous clicks that
do not lock the connector.
You can disable this mechanism by setting the AsyncElementInvoke setting to false in the
CxUIAProvider.xml file in theconfig subdirectory of Interactive.
2.1.3.6 Handling Multiple Themes with SAPGUI
Solutions for supporting multiple themes where UI components may be present or absent.
In SAPGUI for Windows, some components are added or removed whenever the theme is changed. The GUI
button that is used to start a transaction is one of those components absent from the latest themes.

In this screenshot, you can see that the current theme (Enjoy Theme) of the application provides the GUI
button used to start the transaction entered in the adjacent field:
In the following screenshot (Blue Crystal Theme), the GUI button isn’t available:
If the GUI button responsible for starting the transaction isn’t present, the “Enter” key is used instead.
Approach for Automation
Case 1: The Page Definition/Criteria Are the Same for Different Themes, but the Available
Components Differ
When a component such as the Enter button may or may not be present on the page, the bot developer can
create If (true), If (else) item-level activities. These check whether the button exists.

If the button exists, click on it.
If it doesn’t exist, add an "Enter" activity keystroke.
The code generated:
 Sample Code
SAPLogon750.step({ pSAPEasyAccess_manage: function(ev, sc, st) {

var rootData = sc.data;
ctx.workflow('DecisionWorkflow', 'efbafdfb-83d4-43c2-9f78-0ac08e489eef') ;
// Wait until the page loads
SAPLogon750.pSAPEasyAccess.wait(function(ev) {
// if (true)
if (SAPLogon750.pSAPEasyAccess.oEnter.exist())
{
SAPLogon750.pSAPEasyAccess.oGuiOkCodeField.set('va03');
SAPLogon750.pSAPEasyAccess.oEnter.click();
}
else
{
SAPLogon750.pSAPEasyAccess.oGuiOkCodeField.set('va03')
// Send '...' in '...'
SAPLogon750.pSAPEasyAccess.keyStroke(e.SAPScripting.key._Enter_);
}
});
}});
Case 2: The Page Definitions/Criteria Are Different

If the components and their definitions differ between two themes, the Wait Multiple activity can be used at
page level.
Consider the following two images, for example. They show the same window, but in different themes.

Window 1:
Window 2:
Sometimes a change of theme causes a page's definition and components to change completely. In this case,
the bot will probably fail to recognize the page and be unable to continue.
To prevent this kind of failure, create multiple flows of activities based on the condition of a page being timed
out.
You can do this with the Wait Multiple activity. The bot then waits for a page until time out, and if it fails to
recognize the page, it goes on to wait for another specified page.

In this example, if the page of Theme-1 isn’t loaded or recognized before the page times out, the Wait
Multiple activity causes the bot to wait for the default page until time out.
2.1.3.7 Using the GridView Component
The GuiCtrlGridView (also known as the GridView or ALV Grid Control) is a dynamic SAP GUI component
comprising a table and optionally, a toolbar. A child of the GUI Shell component, it's included in an SAP GUI
page in its entirety.
 Caution
When you create items out of components in a GuiCtrlGridView, make sure that you don't use a
component's type in defining the recognition criteria. If the Type attribute of a component is used as
the recognition criterion by itself or in combination with another attribute, recognition of the item fails at
runtime.
Where there are multiple items with the same captured data that only differ in their Type attributes, you
must use a pattern such as a parent-child relationship for recognition instead of using Type.

The Toolbar
The toolbar provides buttons used to perform actions on the table. The button types are as follows:
• GuiGridViewButton - can be clicked

• GuiGridViewCheckBox- can be clicked
• GuiGridViewGroup - can be clicked
• GuiGridViewButtonAndMenu - can be clicked and contains a drop-down menu containing menu items
• GuiGridViewMenu - contains a drop-down menu with menu items
The Table (Pane)
The table contains rows of data with dynamic columns that can be rearranged, removed, or hidden.
Activities
Activities are provided in the Workflow Designer under the SAP GUI category to automate GridView controls.
The available activities are as follows:
Activity Usage Supported by Parameters to be Filled in the Properties Tab
Click • GuiGridViewButton
• GuiGridViewButto
nAndMenu
• GuiGridViewCheck
Box
• GuiGridViewGroup
Select Click a • GuiGridViewButto Item - ID of the control that provides a list of menu items
toolbar menu nAndMenu
menu item item from Menu item's text
• GuiGridViewMenu
by text a drop-
down list.
menu item item from Menu item's position in the list (0 indicates the first item)
• GuiGridViewMenu
by position a drop-
down list

menu item item from Menu item's ID (string). The ID of a menu item.
• GuiGridViewMenu
by ID a drop-
down list
The following activities relate to the data rows, columns, and cells of the table (pane):
Activity Usage Parameters to be Filled in the Properties Tab
Click cell Click on a ta Row number of the cell

ble cell
Column ID of the cell - available in the capture data of GuiGridViewPane
Click button cell Click on a Row number of the cell

button that is
within a table Column ID of the cell - available in the capture data of GuiGridViewPane
cell
Get cell Get a value Row number of the cell

from a table
cell Column ID of the cell - available in the capture data of GuiGridViewPane
Get columns Get the list of

active col
umn headers
in the table
Get row Get the data Row number

in an entire
row
Get row count Get the num

ber of rows in
the table
Select cell Select a cell Row number

in the table
Selected Get the col

column umn ID of the
currently se
lected cell or
cells in the
table

Selected row Get the row

number of
the currently
selected cell
or cells in the
table
Set cell Set the value Value to be set in the cell

of a table cell
Row number of the cell
SelectContextM Select a con Item

enuItemByText text menu
item of a se itemText (string and case sensitive).
lected cell or
row by it's
text.
 Note
You must
use a
Select
Cell or
Select
Row ac
tivity to
select a
cell or
row be
fore us
ing this
activity,
SelectCo
ntextMen
uItemBy
Text


enuItemByPositi text menu
on item of a se itemPositiont (number). The position of a menu item (0 if it is a first item).
lected cell or
 Note
row by it's
position in If there are SEPERATOR lines in the middle of the context menu list, they must be
the list. counted to get the accurate position of the required menu item.
If the SEPARATOR is ignored while counting, the menu item selection will be incorrect
 Note
or fail to work.
You must
use a
Select
Cell or
Select
Row ac
tivity to
select a
cell or
row be
fore us
ing this
activity,
SelectCo
ntextMen
uItemBy
Position


enuItemByID text menu
item of a se itemID (string). The ID of a menu item.
lected cell or
 Note
row by it's ID.
The ID of a menu item can be fetched using the Recording and Playback option in the
 Note SAPGUI application.
You must Record only the step of selecting the required menu item from the context menu.
use a
The generated VB script will have a selectContextMenuIte call with the ID next to it.
Select
Cell or
Select
Row ac
tivity to
select a
cell or
row be
fore us
ing this
activity,
SelectCo
ntextMen
uItemByI
D
2.1.3.8 Using the GuiToolbar Component
The GuiToolbar is an SAP GUI component that's included in an SAP GUI page in its entirety. The children of a
GuiToolbar are buttons.
 Caution
When you create items out of components present within a GuiToolbar, make sure that you don't use
a component's type in defining the recognition criteria. If the Type attribute of a component is used as
the recognition criterion by itself or in combination with another attribute, recognition of the item fails at
runtime.
Where there are multiple items with the same captured data that only differ in their Type attributes, you
must use a pattern such as a parent-child relationship for recognition instead of using Type.

Activities
Activities to automate GuiToolbar controls are provided in the Workflow Designer under the SAP GUI category
GuiGridView. The available activities are as follows:
Click • GuiToolbarButton
• GuiToolbarButtonAn
dMenu
• GuiToolbarCheckBo
x
• GuiToolbarGroup
Select Click a • GuiToolbarButtonAn Item - ID of the control that provides a list of menu items
toolbar menu dMenu
menu item item from Menu item's text
• GuiiToolbarMenu
by text a drop-
down list
Select Click a • GuiToolbarButtonAn Item - ID of the control that provides a list of menu items
toolbar menu dMenu
menu item item from Menu item's position in the list (where 0 indicates the first
• GuiiToolbarMenu
item)
by position a drop-
down list
Select Click on a • GuiToolbarButtonAn Item - ID of the control that provides a list of menu items
toolbar menu dMenu
menu item item from Menu item's ID - can be fetched using record and playback
• GuiToolbarMenu
by technical a drop-
ID down list
Related Information
SAP GUI Activities [page 317]
2.1.3.9 Using Scrolling with the GuiTableControl
Scrolling is used with a GuiTableControl to overcome the problem that data is only retrieved from the visible
area of the table.
The GuiTableControl is an SAP GUI component. With Intelligent RPA, data is retrieved from this component
column-wise with the help of the Occurs attribute. When this attribute is checked in the Criteria pane, data is
retrieved in one operation from all table cells that match the criteria.

Problems arise with this component when the number of rows exceeds the number that fit into the visible area
of the table. That's because the component only provides access to the rows in the visible area. So, the only
way to fetch the data from the remaining, invisible rows is by scrolling through the table.
The vertical scroll bar provided for a GuiTableControl works as follows: The number of possible scroll-bar
positions is equivalent to the number of nonempty rows in the table. So, assuming the table contains five rows
of data, one row disappears on each scroll down.
Even when all nonempty rows are visible, SAP GUI still provides a scrolling function that scrolls one row at a
time.
In the following example, there are only two rows of data and the number of possible positions is also two
(positions 0 and 1). The maximum scroll offset is 1.
Before Scrolling:

After Scrolling:
Desktop SDK Methods Used to Scroll in a GuiTableControl
The following Desktop SDK methods are provided for scrolling:
Method Action Example Code Returns
scrollDownByOneRow Scrolls down one row at a Application.oPage.o True if scrolled, else false
time and a new row appears GuiTableCtrlCell.Sc
in the lower part of the table.
rollDownByOneRow();
scrollUpByOneRow Scrolls back up one row at a Application.oPage.o True if scrolled, else false
time. GuiTableCtrlCell.Sc
rollUpByOneRow();
scrollToPosition Scrolls to the exact scrollbar Application.oPage.o True if successful, else false
position provided by the bot GuiTableCtrlCell.Sc
developer.
rollToPosition(1);
Parameter: integer (0 to
ScrollMaximum)

Method Action Example Code Returns
GetVerticalScrollMa Gets the maximum value up Application.oPage.o Number
x to which scrolling is possible GuiTableCtrlCell.Ge

for the table.
tVerticalScrollMax(
);
getVerticalScrollPo Gets the current position of Application.oPage.o Number
sition the scrollbar. GuiTableCtrlCell.

getVerticalScrollPo
sition();
2.1.3.10 Best Practices
This section provides the best practices for a faster execution of captured SAP applications using the SAP GUI
connector.
Faster Recognition
• Add only Id (full) as criteria for an item if Id is stable (not applicable for a page).
• Add only Name (full) as criteria for an item if Name is stable and if Id is not available for the item (not
applicable for a page).
• Use only Name (full) as criteria for an occurs item if the Name property is available. Commonly used for
GuiTableControl cells.

Faster Loading of a Page
• Use only one unique Must Exist Item of each page for recognition if two or more pages have the same
criteria. Try avoiding the usage of Must not Exist item for this use case as it may slow the loading of the
page.
Example:
Here two pages pReportResult and pEmptyResult have the same criteria.
To uniquely identify the two pages, an item which is unique to each page is added as a Must Exist Item.
Here oTree is unique to the page pReportResult and oNoData is unique to the page pEmptyResult.
• Do not declare a Must Exist/Must not Exist item on a page unnecessarily if you do not have the above use
case.
• Avoid declaring subpages when using the SAP GUI connector.
• Make sure to enclose your statements within lock and unlock refresh calls as seen in Suspend Automatic
Refresh [page 141] for the following scenarios:
• While performing set/get operations on an occurs item.
• When executing a set of statements on a page where items remain constant.
• Use only item level wait block if required. Do not do an exitance check of an item and perform an operation.
• Do

• Don’t
Selecting an Item node
1. Manually select the node.

2. In the debugger, use the function
selected()
on the TreeView item to retrieve the node key.
 Sample Code
SAPLogon760.pEDocumentCockpit.oSAPTableTreeControl.selected();
3. To click on the link: the first parameter contains the value find above, the second parameter contains the
index of the column.
 Sample Code
SAPLogon760.pEDocumentCockpit.oSAPTableTreeControl.clickNodeItemLink("
2",0);

Different ways to the keys of a combobox (GUI)
• Enable the Show keys within dropdown lists option from the Interaction Design dropdown list for the
design time. For more information, see https://blogs.sap.com/2017/08/14/sap-gui-options-show-keys-
within-dropdown-lists/ .
• Create the item of the GuiCombox. Select the option you need the key for. Run the debugger and do get()
call on the GuiComboBox item to get the key of the selected option.
• Use the Script Recording and Playback of SAP GUI.
• Use the GetListmethod:
var liste = Saplogon.pCreateMaterialInit.cbMaterialType.getList();

var obj = ctx.json.parse(liste);
var index = 0;
while (obj[index] != undefined) { ctx.log(" key " + obj[index].Key + " label
" + obj[index].Value) ; index++; }
2.1.4 The SAPUI5 and S/4HANA Connectors
SAPUI5 is an extension of the Web connector. It's a framework that includes a collection of libraries you can use
to build applications which run in a desktop or mobile browser – while only maintaining one code base. SAP
S/4HANA offers multiple business applications built on the SAP HANA in-memory platform.
Declaring Entities
Entities are declared as described in the same way as for standard Web applications. For details, see Declaring
Entities Using the Web Connector [page 71].

Controlling Entities
The SAPUI5 framework provides standard methods for controlling standard components (see Controlling
Entities Using the Web Connector [page 78]). But it also provides a wide range of specific methods for
controlling custom SAPUI5 controls. The following custom controls and activities are currently supported:
Control Activity
ActionSelect Open
Carousel Next
Previous
ComboBox Get Items
Add Item
FeedContent Press
FeedInput No dedicated activity, but Item - Set can be used
Icon No dedicated activity, but Click can be used
Menu Open
NavigationList Add Item
Get Items
SegmentButton Get Items
Add Item
SuggestionSearchField Suggestion Search
Table Clear Selection
Table Data
Row Count
Row Data
Select All
Select Row
TAccount Add Credit
Add Debit

Control Activity
Get Credit
Get Debit
TreeGrid Expand
ToggleButton [page 173] IsChecked
Check
UnCheck
The UI5 controls listed below are supported by Desktop SDK methods (see also SAPUI5 Application
Management ):
• ActionSelect
• Button (methods also used for Link, Breadcrumbs, and URL Helper)
• CheckBox
• ComboBox
• DatePicker
• FeedContent
• FeedInput - a control that combines an input field with a button that's not enabled until there's an entry in
the input field
Example:
• Icon - a clickable icon that typically opens a popup when clicked.

Example:

• Input (methods also used for TextArea, DatePicker, FeedInput, and TextInEditModeSource)
• InputSwitch
• MultiCombobox
• MultiInput
• NavigationList (methods also used for SideNavigation)
• RadioButton
• RangeSlider
• SearchField
• SegmentButton
• SuggestionSearchField
• Table (see also Automation with SAPUI5 Tables [page 174])
• TableRow(see also Applying Type TableRowClick [page 173])
• Tile
• ToggleButton (see also Applying Type ToggleButton [page 173])
Related Information
Capturing SAPUI5 and S/4HANA Applications [page 166]

Applying Type ToggleButton [page 173]
Applying Type TableRowClick [page 173]
Automation with SAPUI5 Tables [page 174]

2.1.4.1 Capturing SAPUI5 and S/4HANA Applications
1. Start Desktop Studio and in the menu bar select File New Project... .
2. Enter the properties for the project and click Save.
3. In the menu bar select File Edit Project... .

Go to the Libraries tab and tick the SAP UI5 box in the CRM applications section.
4. Open an SAPUI5 or S/4 HANA page in your Web browser.

5. Go back to the Desktop Studio and in the Explorer perspective select + Add Application from the context
menu.
6. In the Capture Application window, select the SAPUI5 or S/4HANA page you previously opened in your web
browser. Click Save.
A new object is added to your project.
 Tip
Open the Editor perspective and check that the SAPUI5 library is included in the Framework of the
script tree tool window.

7. Go to Parameters and in the General section, select SAPUI5 in the Custom Types.

8. Double-click the new page in the capture panel.
9. Go to the SAPUI5 or S/4HANA page opened in your browser, and press Ctrl . A red rectangle appears
meaning that the page is now selected.

10. Go back to the Capture Page window in the Desktop Studio and click Scan and Capture.
After a few moments, the SAPUI5 or S/4HANA page is now added to your project. However, the page name
is shown in red because a recognition criterion is missing.
11. In the Captured data window, select the URL and then click the plus icon (+) in the criteria window.
12. The page is now ready for you to add UI objects. In the capture panel, click the object you want to add. In
this example, we'll add a radio button.

 Tip
Every UI element (object) you add must be associated with a SAP UI custom type.
13. Go to the Subtree tool window and select the input corresponding to the UI object you want to add.
Right click the input and select Associate to New Item.
Related Information
Loading Pages [page 173]

2.1.4.2 Loading Pages
Wait Until All Controls on a Page are Ready
A feature of SAPUI5 is that a control can have a busy state that's different from that of the page. A page can be
loaded although some controls are still loading.
To handle this behavior, you can use the waitReady method in your scripts. This method checks the state of
all controls on a page. The page is not ready until all controls are ready.
When to Use waitReady and When to Use wait
Whether you should use waitReady or the wait method depends on your use case:
• If your bot enters a text in a search field and then clicks Search, it is possible that only the area where the
search results are displayed will load. That depends on how the SAPUI5 page in question is implemented.
So for this kind of use case you should use waitReady to be on the safe side.
• If your bot fills out a form on the SAPUI5 page and then clicks Submit to navigate to the next page, for
example, you can use the wait method.
Related Information
waitReady
2.1.4.3 Applying Type ToggleButton
You can apply the type SAPUI5.ToggleButton to buttons on an SAPUI5 interface. This type takes into
account the state of the button (pressed or unpressed), so that different methods can be called accordingly.
 Sample Code
SAPUI5SDKDemoKit.pSAPUI5SDKDemoKit.oToggleButton.click()
2.1.4.4 Applying Type TableRowClick
You can apply the type SAPUI5.tablerowclick to handle clickable rows on an SAPUI5 interface.

 Sample Code
ProjectControl.pageofTableRow.objectofTableRow.index(5).click()
2.1.4.5 Automation with SAPUI5 Tables
With the SAPUI5 connector, the contents of tables or table rows can be captured using convenient methods
provided by the SAP Intelligent Robotic Process Automation Desktop SDK.
Example Table
Methods
The following SAP Intelligent Robotic Process Automation Desktop SDK methods are provided for use with
SAPUI5 tables (see SAPUI5.table):
• getTableData
• getRowCount
• getRowDatabyIndex

 Note
If lazy loading is enabled for the table, getTableData will return only the rows of data initially fetched from
the client side.
2.1.5 The Win32 Connector
For details of the entities to define, see Entities for a Desktop Application [page 247]
 Note
If you need to control Web pages embedded in a Desktop application, you must define page entities for
each Web page you need to control, as if they were regular pages of the application.
For details, see Application-Based Events [page 247]
Page-Based Events
For details, see Page-Based Events [page 247]
Related Information
Declaring Entities Using the Win32 Connector [page 176]

Recognition With the Win32 Connector [page 184]
Controlling Entities Using the Win32 Connector [page 185]

2.1.5.1 Declaring Entities Using the Win32 Connector
This declaration activity includes the following tasks:
Using the Win32 connector:
• You can use the following operators on the EXE property: Full, Part, Empty, No.
• You must set a criterion on the EXE property (process name of the application), using the Full operator.
 Note
This criterion on the EXE property is set automatically when you declare a Win32 application.
• You cannot set a criterion on any other property.

• You can set multiple criteria on theEXE property, which are then connected by a logical OR.
The Win32 connector provides the following specific parameters:
One instance per thread If true, tells the connector to manage an instance of applica
tion by thread. Do not use unless this is a specific require
ment.
Use V2 Set false to use the old version of Win32 connector. Do not
use unless this is a specific requirement.

Set Page Criteria
Page criteria are set on the properties of the root component of the targeted screen. They are used by the
Win32 connector as follows:
The Win32 connector searches the DOM tree to find all DOM components that match the page's criteria.
• Precise enough to match only the desired root component

• Reliable enough to still work if screens change
• You can use the following operators:

• Full, Part, No for text properties (No means "not equal")
• Equal for numeric properties
• You cannot use OR to define a combination of criteria
• NAME: if present and unique, this property is usually set by developers and does not change (WinForms
application only)t
• IDENT: If unique and not auto-generated, this property is usually set by developers and does not change
(Win32 application only)
• TITRE: Title or text
• CLASS: Classname (Win32 only)
• STYLE: Setting a criteria on this property with the WS_VISIBLE value can be useful to declare TabItems of a
TabControl as a page. If you do this, a page of this type will only be recognized if the TabItem is visible.
Here is a complete list of available properties:
Available Properties for Page Criteria
Most Used Properties
IDENT Window ID
NAME Name (WinForms only)
TITRE Title or text
CLASS Classname

Properties Relating to Position in the Subtree
ROW Row position, relative to the main window. When a criterion

is set on this property, Desktop Studio recalculates the crite
rion value to be relative to the ROW property of the Page
NBPARENT Number of ancestors (Deepness), relative to the main

window. When a criterion is set on this property, Desktop
Studio recalculate the criterion value to be relative to the
NBPARENT property of the Page
NBCHILD Number of children of the parent component (number of

siblings)
Properties Relating to Style
STYLE Window style
EXSTYLE Window extended style
Properties Relating to Position and Size
X Left position, relative to the main window left position. When

a criterion is set on this property, Desktop Studio recalculate
the criterion value to be relative to the X property of the page
XMax Maximum value for X property (equivalent to criterion: X < =

criterion value)
XMin Minimum value for X property (equivalent to criterion: X > =

criterion value)
Y Top position, relative to the main window top position. When

a criterion is set on this property, Desktop Studio recalcu
lates the criterion value to be relative to the Y property of the
page
YMax Maximum value for Y property (equivalent to criterion: Y < =

criterion value)
YMin Minimum value for Y property (equivalent to criterion: Y > =

criterion value)
CX Width
CXMax Maximum value for CX property (equivalent to criterion: CX

< = criterion value)

CXMin Minimum value for CX property (equivalent to criterion: CX >
= criterion value)
CY Height
CYMax Maximum value for CY property (equivalent to criterion: CY

< = criterion value)
CYMin Minimum value for CY property (equivalent to criterion: CY >

= criterion value)
RX Distance between right of parent and left of item
BY Distance between top of item and bottom of parent
If the targeted root component has no unique, distinguishing properties, you can use MustExist Method [page
284], which is an advanced declaration method.
Page-Based Events
The Win32 connector can also notify the following technical events:
ENABLE Fired when the targeted root component becomes enabled
DISABLE Fired when the targeted root component becomes disabled
SHOW Fired when the targeted root component becomes visible
HIDE Fired when the targeted root component becomes hidden
MENUPOPUP Fired when a Windows menu opens
SCROLL Fired when the targeted root component scrolls

SIZE Fired when the targeted root component is resized
These events must be explicitly tracked in order to be notified.
Page Parameters
Page parameters can be set using Desktop Studio (see Declaring Pages [page 252]).
The Win32 connector provides the following specific parameter:
Windowless container Indicates (true) that the page will contain windowless pages
Set Item Criteria
Item criteria are used by the Win32 connector as follows:
Once the Win32 connector recognizes a Win32 component as a declared page, it can search the component's
• The Win32 connector does not manage multiple items.
• Precise enough to match only the desired component

Items are usually declared for controlling purposes. You can also use items to aid page recognition, by setting
MustExist parameters.
• You can use the following operators: Full, Part, No for textual properties (No means "not equal")
• Equal for numeric properties

Usually, you set recognition criteria on the following properties:
NAME If present and unique, this property is usually set by develop

ers and does not change (WinForms applications only)
IDENT If unique and not auto-generated, this property is usually

set by developers and does not change (Win32 applications
only)
TITRE Title or text
CLASS Classname (Win32 only)
The complete list of available properties is the same as for setting page criteria (see Available Properties for
Page Criteria [page 177]).
The Ancestor Method [page 285] involves finding, among the targeted component's ancestors, an ancestor
component that has unique, distinguishing properties. This ancestor component must not be among the
ancestors of the wrongly recognized component.
With this method, you need to:
• Declare an item that targets this ancestor component

• Set this item as the ancestor of your item
The target component will be searched for among the descendents of the ancestor component.
 Example
A window has two groupboxes with a label in each one. The labels have the same text, but the groupboxes
have different titles. You need to target the first label.
 Sample Code
• Groupbox1
◦ Label
• Groupbox2
◦ Label
You must first declare a technical item oGroupbox1 that targets the first groupbox component. You can then
declare the oLabel item with the oGroupbox1 item as its ancestor.
This method involves finding another component that:

• Is at a fixed distance (CX; CY) from the targeted component.
• Has unique, distinguishing properties.
This component is typically a label component lying near the target component. But it can be any other
component in any position on the screen.
• Declare an item that targets this label component.

• Set this item as Labelled by your item.
Desktop Studio stores as a criterion the distance between the targeted component and the label component.
This distance is calculated in a unit that does not depend on the screen resolution.
The software will search for the target component among the components located at this stored distance from
the label component.
Use the ROW property
 Example
In a window that has three EntryField with no unique, distinguishing properties, you declare an oEdit item to
target the second one.
 Sample Code
Window
◦ EntryField
◦ EntryField ←
◦ EntryField
To address this use case, you can set a criterion on the ROW property. This property indicates the position of
the component within the DOM tree.
You declare the oEdit Item using the ROW property to target the second EntryField.
 Sample Code
oEdit declaration
• EntryField (ROW=R2)
 Sample Code
Window
◦ EntryField (ROW=R1)
◦ EntryField (ROW=R2) → oEdit
◦ EntryField (ROW=R3)

 Note
The captured ROW property is the absolute position of the component within the DOM tree. When you
set a criterion on the ROW property, Desktop Studio automatically calculates the criterion value to be
relative to the component targeted by the page.
Item-Based Events
Item-based events must be explicitly tracked in order to be notified. The Win32 connector implements the
following standard technical events:
CLICK Fired when the component is clicked or released
COMMAND Fired when the button component is clicked, then released
ENABLE Fired when the component becomes enabled
DISABLE Fired when the component becomes disabled
SHOW Fired when the component becomes visible
HIDE Fired when the component becomes invisible
Item Parameters
The Win32 connector provides the following specific parameters:
Method [page 285] )

NoWin If true, the item is a non-window item (such as a menu)
TypObj Indicates the way the connector must control the item (see
Controlling an Item Using the Win32 Connector [page 186])
2.1.5.2 Recognition With the Win32 Connector
The following advanced recognition methods can be used with the Win32 Connector:

Subpages
For information on subpages and when to use them, see Subpages [page 248]
The Win32 connector listens to the desktop to detect the opening of root UI components (children of the
desktop).
When the connector detects the opening of a root UI component,
• It looks for the first declared Win32 application whose criteria match.
is found, the connector associates the new root UI component with that root page, and a LOAD event

• Otherwise, it ignores the root UI component.
 Note
Subpage Recognition
The Win32 connector implements the concept of subpages (see Declaring a Page [page 243]).
As soon as a page is recognized, the Win32 connector tries to recognize each of its subpages. This recognition
is performed in the subtree of the component targeted by the page. That means you must pay attention to the
page-subpage relationship when declaring pages.
Example:
• a pMainWindow Page to target the main window (required)

2.1.5.3 Controlling Entities Using the Win32 Connector
Controlling an Application Using the Win32 Connector
The Win32 connector implements the standard control methods described in Controlling an Application [page
234]. It does not provide any additional features for controlling applications beyond these standard methods.
Controlling a Page Using the Win32 Connector
The Web connector implements the standard control methods described in Controlling a Page [page 232]. It
Modify Page Content

The Win32 connector allows you to enrich the content of a controlled Windows page.

This can be useful when you need to display:
• A button to start control sequences

• A label and an Editbox to collect a value from the user
You can easily integrate these UI elements directly inside the controlled page.
To insert a component into a Windows page content, use the following methods:
createButton Inserts a button into a page
createEditbox Inserts an editbox into a page
createStatic Inserts a static text into a page
Once injected, the components are present in the DOM and can be controlled like other components.
 Note
The injected components cannot be stylized. They look like basic system components
You can also control them using the following methods:
deleteObject Delete a component created using on of the previous meth

ods
disableObject Disables/enables a component created using one of the pre

vious methods
Controlling an Item Using the Win32 Connector
The Win32 connector implements the standard control methods described in Controlling Individual Entities
[page 226]. To know how to control an item, the Win32 connector uses its TypObj parameter.
The TypObj parameter
The TypObj parameter indicates to the Win32 connector the kind of the targeted component and the way to
control it.
When you declare an item, Desktop Studio automatically calculates the TypObj parameter based on the
ControlType of the targeted component.
If necessary, you can change it by choosing from a list of available TypObj values for that ControlType. This
allows you to:
• Try another type of controlling if the preselected one fails

• Manually select the controlling type when the ControlType of the targeted component is unknown (new
components, custom components)

The most used TypObj values are the following :
Value Title Meaning
Txt Text Control the component as a text con

trol. Enables the use of the selected
method to access the current selection
of the item
Cbx ComboBox Control the component as a ComboBox

control
Btn Button / Radio Control the component as a Button

control
Chk Check / Radio Control the component as a CheckBox

or RadioButton control
Lst ListBox Control the component as a ListBox

control
Lsv ListView Control the component as a ListView
Mn Menu Control the component as a MenuItem
ToolBar ToolBar Control the component as a ToolBar
VScroll VScroll Control the component as a vertical

Scrollbar
HScroll HScroll Control the component as an horizontal

Scrollbar
SysTabControl TabControl Control the component as a TabControl
The following TypObj values allow special types of controlling:
• Img: The item is declared as an Image

• Key: The item’s value is set by keystrokes. When setting the value, the following special characters are also
permitted:
• _Enter_
• _Clear_ (empty the field)
• _Down_ _Up_ _Left_ _Right_ (arrows)
• _Tab_ (tabulation)
• _Back_ (backspace)
• _Esc_ (Escape )
• _Del_ (Suppr)
• _Fx_ (x from 1 to 19 : function key) |
• Clipboard: The Win32 connector copy the provided value in the clipboard and set the targeted component
value by pasting from the clipboard

Controlling Complex Items with the Win32 Connector
To control complex items such as trees or lists, you must set the TypObj parameter to the correct value. You
then control complex items in the standard way (see Controlling Individual Entities [page 226]).
2.1.6 The Java Connector
For details of the entities to define, see Entities for a Desktop Application [page 247]
 Note
If you need to control Web pages embedded in a Desktop application, you must define page entities for
each Web page you need to control, as if they were regular pages of the application.
For details, see Application-Based Events [page 247]
 Note
The Start event is not fired when the application starts, but when the first recognized page is loaded.
Page-Based Events
For details, see Page-Based Events [page 247]
Related Information
Declaring Entities Using the Java Connector [page 189]

Recognition with the Java Connector [page 199]
Controlling Entities Using the Java Connector [page 201]

2.1.6.1 Declaring Entities Using the Java Connector
This declaration activity comprises the following:
Capturing an Application [page 189]
2.1.6.1.1 Capturing an Application
Context
Using the Java Connector, make sure that the debugger has been launched and that the correct EXE of the
application has been recognized.
To capture a Java standalone Application, follow the following steps:
Procedure
1. Capture the application using the SWG connector.

2. Set EXE and CLASSWIN a criteria for the application.
The CLASSWIN criterion is useful when the Java application contains a loading screen. If this criterion is
not set, the application may be not recognized during the runtime.
 Note
If you only use EXE without using CLASSWIN as one of the criteria , it may not work during runtime. If
you only use EXE as a criterion and if the debugger is not launched before the application, it will not
be recognized. However, if you use CLASSWIN and EXE as criteria, the application can be recognized
whether or not the debugger is launched before the application.
3. Launch the debugger.
Make sure that you see the load of an _Undefined_ page in the Events tab of the debugger. If you don’t see
this, the following steps will not work.

If you don’t see this event, check that the EXE criterion set in the Desktop Studio corresponds to the EXE
name of the Java application in the Windows Task Manager.
If this is not the case, update it manually in the Desktop Studio.

4. Go to the Desktop Studio, right-click on the captured application and select Capture a New Page.
5. In the popup that appears, make sure that the SWG technology is selected (this should be the default
choice).
6. Click on the refresh button next to Pages.You will see one page that should correspond to your Java
application.
7. Select this page and then click on the Scan and Capture button. You have now captured the page.
8. If the capture is not working, you can try to capture the Applet version of your application if it exists.
Next Steps
If the previous steps do not work, capture the application as a Java Applet (a Java application that is displayed
in a browser).
To capture a Java Applet:
1. Follow steps 1 to 6 above.

2. You can see an arrow next to the name of the page. Open the page. You must find the first node under the
Java connector node (the name may vary depending on the applet).
3. Select this node and then click on the Scan and Capture button. You have now captured the page.
If this is still not working, create a BCP ticket.
Using the Java Connector:
• You can use the following operators on properties of type string: Full, Part, like.
• You must set a criterion on thejava.exe or javaw.exe property using the Full operator.
 Note
This criterion on the exe property is set automatically when you declare a Java application.
• You must set a criterion on the classwin property. It enables the detection of a Java application if this
application contains a loading screen.

• To distinguish between Java applications, you have to set other criteria on one of the Text or Class
properties.
Application parameters are set in Desktop Studio.
 Note
For Java applications, you must capture pages while running the project. Indeed, you need to capture the
application itself first, then run the project with this application before capturing the pages. This is related
to the way the Java connector works as it needs to connect to the application first. Only then, the pages will
be visible in the capturing tool.
Set Page Criteria
Page criteria are set on the properties of the root component of the targeted screen. They are used by the Java
connector as follows:
The Java connector searches the DOM tree to find all DOM components that match the page's criteria. If
a component matches, the connector doesn't search its subtree to find other instances of the page. The
• Precise enough to match only the desired root component.

• Reliable enough to still work if screens change.
• You can use the following operators:

Full, Part, Like - the Like property value must match the criterion value considered as a regular
expression .
• You can't use OR to define a combination of criteria.
• CLASS: classname (Java only)

• TEXT: title or text describing the window/frame
• TOSTRING: a string concatenating some properties of the window/frame (such as Class, name, or
positions)
• NAME: if present and unique, this property is usually set by developers and does not change
• RANG: the RANG of the Window/frame
• VISIBLE: Boolean flag, equal to Yes if the window/frame is visible
Here is a complete list of available properties:
Properties
CLASS Classname
TEXT Title or text
TOSTRING String of some main properties
NAME Usually a name given by developers
RANG RANG of the window/frame
If the targeted root component has no unique distinguishing properties, you can use the MustExist Method
[page 284], an advanced declaration method.
Page-Based Events
The Java connector can also notify the following technical events:
SHOW Fired when the targeted root component becomes visible
HIDE Fired when the targeted root component becomes hidden
ACTIVATE Fired when a targeted root component is activated
These events must be explicitly tracked in order to be notified.

For general information on declaring a page in Desktop Studio, see Declaring Pages [page 252]
Set Item Criteria
Item criteria are used by the Java connector as follows:
Once the Java connector recognizes a Java component as a declared page, it can search the component's
• The Java connector does not manage multiple items.
• Precise enough to match the desired component

• Broad enough to be still function correctly if the DOM changes
Items are usually declared for controlling purposes. You can also use items to aid page recognition, by setting
MustExist parameters.
• You can use the following operators: Full, Part, like - the Like property value must match the criterion value
considered as a regexp
• You must declare at least one recognition criterion
Usually, you set recognition criteria on the following properties:
• CLASS: Class name of the item

• TEXT: Title or text describing the item
• TOSTRING: A string concatenating some properties of the item (Classname, name, positions, …).
• NAME: If present and unique, this property is usually set by developers and do not change
• RANG: RANG of the item in the DOM tree |
• VISIBLE: Boolean flag, equal to Yes if the item is visible
Here is the complete list of available properties:
Properties
CLASS Classname of the item
TEXT Label or text of the item

TOSTRING String of some main properties
NAME Usually a name given by developers
RANG RANG of the item
Another component is recognized by mistake. To ensure your declaration is correct, you can use one of the
following recognition methods.
Use the RANG Property
 Example
In a page that has four PPanel items with no unique distinguishing properties, you declare an item to target
the second one.
 Sample Code
• pTransactionSearch (Page)
◦ JRootPane
▪ JPanel
▪ JLayeredPane
▪ JPanel
▪ ContextProviderFinderForm
▪ PPanel
▪ PPanel ←
▪ PPanel
▪ PPanel
To address this use case, you can set a criterion on the RANG property. This property indicates the position
of the component within the DOM tree.
 Example
You declare the oPPanel item using the RANG property to target the second PPanel.
 Sample Code
oPPanel declaration
• oPPanel (RANG=R1R2R1R1R2)
 Sample Code
• pTransactionSearch (Page)

◦ JRootPane (RANG=R1)
▪ JPanel (RANG=R1R1)
▪ JLayeredPane (RANG=R1R2)
▪ JPanel (RANG=R1R2R1)
▪ ContextProviderFinderForm (RANG=R1R2R1R1)
▪ PPanel (RANG=R1R2R1R1R1)
▪ PPanel (RANG=R1R2R1R1R2) → oPPanel
 Note
The captured RANG property is the absolute position of the component within the DOM tree. When you
set a criterion on the RANG property, Desktop Studio automatically calculates the criterion value to be
relative to the component targeted by the page.
Item -Based Events
Item-based events must be explicitly tracked in order to be notified. The Java connector implements the
following standard technical events:
COMMAND Fired when the button component is clicked, then released
ENTER Fired when the ENTER key is actioned on the component
DBLCLK Fired when the component is double-clicked
MOUSE Fired when the component is mouse-clicked
KEY Control an application using Java connector
 Note
• MOUSE and DBLCLK are exclusive, which means that if both TRACK_EVENT are performed for the same
item, then only the latter is considered
• ENTER and KEY are exclusive, which means that if both TRACK_EVENT are performed for the same
item, then only the latter is considered

The COMMAND event
This event applies to:
Object Meaning Data Format
JButton Action on the button
JCheckBox Action on checkbox The checkbox status
JComboBox Selecting an item in the The selected item Item name

combo
JRadioButton Action on radio button
JList Selecting a row in the list The selected line
JCheckBoxMenuItem Action on the checkbox The checkbox status
JRadioButtonMenuItem Action on radio button
JMenuItem Action on the menu item
JFormattedTextField Action (Enter) on the field
JPasswordField Action (Enter) on the field
JTabbedPane Selecting a tab the selected tab tab
JTable Selecting a row in the table the selected line
JTextField Action (Enter) on the field
JTree Selecting a node in the tree name of the selected node
The ENTER Event

Object Meaning Data
JList Action (Enter) on a line of the list The (first) selected line
JTable Action (Enter) on a table row The (first) selected line
JTree Action (Enter) on a tree node The (first) selected line

The DBLCLK Event
Object Meaning Data
JList Action (DblClick) on a line of the list The (first) selected line
JTable Action (DblClick) on a table row The (first) selected line
JTree Action (DblClick) on a tree node The (first) selected line
The MOUSE KEY Event

Meaning Data
Action (keyboard) on the subject Event information: key code
Action (mouse) on the object Event information
Item Parameters
The Java connector provides the following specific parameters:
Must exist If set, the page will be recognized only if the item exists (see
MustExist Method [page 284])
TypObj Indicates the way the connector must control the item Con
trolling an Item Using the Java Connector [page 202]
2.1.6.2 Recognition with the Java Connector
The following advanced recognition methods can be used with the Java connector:

• Labelled By Method [page 285]
Subpages
For information on subpages and when to use them, see Subpages [page 248]
The Java connector listens to the desktop to detect the opening of root Java components (children of the
desktop).
When the connector detects the opening of a root Java component,
• It looks for the first declared Java application whose criteria match.
is found, the connector associates the new root Java component with that root page, and a LOAD event
• Otherwise, it ignores the root Java component.
 Note
In addition, the Java connector can only control Java applications running on a 32 bit Java JRE.
Subpage Recognition
The Java connector implements the concept of subpages (see Declaring a Page [page 243]).
Java subpages can be created from the main page components (see Capture a Subpage [page 256]).
As soon as a page is recognized, the Java connector tries to recognize each of its subpages. This recognition
is performed in the subtree of the component targeted by the page. That means you must pay attention to the
page-subpage relationship when declaring pages.

Example:
• a pMainWindow Page to target the main window (required)

2.1.6.3 Controlling Entities Using the Java Connector
Controlling an Application Using the Java Connector
The Java connector implements the standard control methods described in Controlling an Application [page
234].
For Java Oracle Forms applications, a special custom class to be developed by the SAP Intelligent RPA R&D
team must be integrated into the specific project. For classical Java applications, the Java connector doesn't
provide additional features for controlling applications beyond the standard control methods.
Controlling a Page Using the Java Connector
The Java connector implements the standard control methods described in Controlling a Page [page 232]. It
Modify Page Content
The Java connector allows you to enrich the content of a controlled Windows page. This requires a custom
class.
This method can be useful when you need to display:
• A button to start controlling sequences

• A label and a text field to collect a value from the user
The Java Connector directly includes these Java elements in the controlled page. Once included, the
components are present in the DOM and can be controlled like any other component.

Controlling an Item Using the Java Connector
The Java connector implements the standard control methods described in Controlling Individual Entities
[page 226]. To know how to control an item, the Java connector uses its TypObj parameter.
Controlling Complex Items with the Java Connector
To control complex items such as trees or lists, you must set the right value for the TypObj parameter. You
then control complex items in the standard way (see Controlling Individual Entities [page 226]).
2.1.7 The HLLAPI Connector
The HLLAPI Protocol
HLLAPI is an IBM API that enables communication with mainframe computers using applications such as
AS400, 3270, 5250, and terminal emulators.
A mainframe application is any application running in a terminal emulator which implements the HLLAPI
monitoring protocol.
Mainframe applications are generally launched, by users, with parameters:
• A parameter file containing a set of application parameter (such as working environment, key mapping, or
coloring scheme)
It is sometime possible to generate a parameter file by modifying parameters in settings of the application.
Parameter file extensions vary depending on the emulator application.
• An optional workspace (generally the URL of the executable)
To be able to control mainframe application, Desktop Agent will need to actively connect to it by opening a
channel to it.
• A channel is set with a specific session ID and is linked via a parameter file
• A channel can be set in most emulator application settings
• Multiple session may coexist, but Desktop Agent is not able to connect to two channels at the same time.
• If users open multiple emulators, you may have to manage multiple instances of the software, but only of
the pilwin/UI Automation application wrapping the mainframe screens.
 Note
• A mainframe application running in a Web terminal emulator (for example Crysalid or z/Scope
Anywhere) must be regarded as a Web application (see Controlling an Application Using the Web
Connector [page 78]).

• A mainframe application running in a desktop terminal emulator without the HLLAPI protocol enabled
may be regarded as a desktop application using a windowless control method .
Recognition with the HLLAPI Connector
Definitions
For a mainframe application:
• You define the application entity as the HLLAPI session that provides access to the mainframe application.
• You define a page entity for each screen of the application which you need to control. If necessary, you can
define generic page entities to represent multiple screens of the application.
• You define an item entity for every screen zone that you need to control.
Application Recognition
For the HLLAPI to be recognized, a connection first has to be actively established to it via the session ID.
 Note
• Until a connection is established by means of the HLLAPI monitoring protocol, Desktop Agent will not
be able to control the application.
• Although the application may have been captured while under a specific session ID ('A', for instance),
the application will still be recognized using other session ids.
Page Recognition
This is the algorithm applied for page recognition:
When the HLLAPI connector detects the opening of an HLLAPI screen:
• it looks for the first declared HLLAPI application whose criteria match
• if it finds one, it looks for the first declared page of the application whose criteria match
• if it finds one, it associates the new HLLAPI screen with this page and notifies a load event for the
page.
• Otherwise, if it’s a mainframe, it associates it with the generic _Undefined_ Page and notifies a load
event for this page.
• in all cases, it continuously controls the HLLAPI screen.
• Otherwise, it ignores the HLLAPI screen.
For each HLLAPI screen being controlled, the HLLAPI connector regularly checks whether the HLLAPI screen
still matches the application criteria:
• If not, it notifies an UNLOAD event for the associated page (if any) and releases control of the HLLAPI
screen.
• If it still matches:
• If the HLLAPA screen is still associated with an HLLAPI page, the connector checks whether the
HLLAPI screen still matches the page criteria. If not, it notifies an unload event for the associated
page.

• Otherwise, the HLLAPI connector looks for the first declared page of the application the whose criteria
match. If it finds one, it associates the HLLAPI screen being controlled with the page found, and
notifies a load event for this page.
Related Information
Declaring Entities Using the HLLAPI Connector [page 204]

Controlling Entities Using the HLLAPI Connector [page 209]
2.1.7.1 Declaring Entities Using the HLLAPI Connector
Declaring an Application
During capture, only the opened channels (indicated by their session ID) will be displayed and selectable.
There are no criteria to be set on applications using Desktop Studio (see Criteria Management [page 269]).
With HLLAPI connector, provides the following application parameter is available:
App page name When declaring an HLLAPI Application, Desktop Studio cre
ates a technical page, whose name can be modified. This
technical page is used to connect to an application session.
Declaring a Page
Set Page Criteria
NBROWS Number of rows in the screen
NBCOLS Number of columns in the screen

 Note
• No criteria are set for a page, as they are usually all the same throughout the application, which makes
it impossible to differentiate between them based only on such criteria.
• Screens occasionally have more rows and columns, or fewer.
Therefore, to be able to differentiate between pages, you must use the Must Exist method.

If the targeted root component has no unique distinguishing properties, you can use the Labelled By Method
[page 285].
Page-Based Events
TA page can receive the following technical event:
UPDATE The page is being updated
Declaring an Item
Set Item Criteria

Item criteria are used by the HLLAPI connector as follows:
X Column position
Y Row position
CX Field size
TEXT Field content
Once the page has been recognized, items will:
• Always exist
• Always have the size declared (CX propertz)
Items are usually declared for controlling purposes. They will:
• Always have position criteria (X,Y, CX)

• Occasionally have a TEXT criterion

• Also be used for page recognition by setting MustExist parameters
• You can use the following operators on properties of type string: Full, Part, Empty, No.
 Example
Declaration of an item with the following item criteria:
• EQ(X) = 11
• EQ(Y) = 9
• EQ(CX9 = 4

Another component is recognized by mistake. To ensure your declaration is correct, you can use one of the
following recognition methods:
The Labelled By method (for details, see Labelled By Method [page 285]).
The Occurs method
If you need to recognize an array in a screen, it may be useful to use the Occurs method. For multiple items,
the Desktop Agent connector targets all the occurrences of the recognized components. You can then use the
appropriate index value via a script to target the desired occurrence.
Unlike other connectors, occurs is managed by specific parameters on the item:
Occurs indicates the number of multiple elements beside the initial element. If Occurs is set at 8, then there
will be 9 elements.
Inc X and Inc Y respectively indicate the offset between columns and rows. If Inc X is set at 1 and Inc Y is
set at 0 then the multiple items will be side by side in a horizontal direction
Examples of the use of the Occurs method
• Occurs = 8
• Inc X = 0
• Inc Y = 1

These parameters enable you to retrieve a horizontal array of nine elements; each element attaching to the
next element .
• Occurs = 11
• Inc X = 2
• Inc Y = 0
These parameters allow you to catch a vertical array of 12 elements; each element is one column away from the
next.
• Occurs = 3
• Inc X = 2
• Inc Y = 2
Using a non-zero value for both Inc X and Inc Y will lead to a different (and generally unintended) type of
array recognition.

Item Parameters
The HLLAPI connector provides the following specific parameters:
Occurs Indicates the number of elements beside the initial element
Inc X Indicates the column offset between multiple elements
Inc Y Indicates the row offset between multiple elements
Item-Based Events
Unlike most other connectors, the HLLAPI connector does not provide any technical events on items.
Related Information
Controlling Entities Using the HLLAPI Connector [page 209]

2.1.7.2 Controlling Entities Using the HLLAPI Connector
Controlling an Application Using the HLLAPI Connector
The HLLAPI connector implements the standard control methods described in Controlling an Application
[page 234].
It also provides the following additional features:
connect Connects the HLLAPI channel
disconnect Disconnects the HLLAPI channel
 Note
• Session IDs are usually single letters or occasionally, numbers.

• It is not possible to connect to two different sessions at the same time. If you need to manage 2
different sessions, you will have to disconnect from one before you can connect to the other.
• Attempting to connect to a mainframe application that has not yet been launched will result in an
attempt to launch a terminal emulator first.
• Connecting to a mainframe application that is already launched will naturally result in a connection to
the session.
• It is not possible to check whether or not the application session is already in use.
Before you begin, agree with the customer what session ID will be used for automation.
Controlling a Page Using the HLLAPI Connector
Available control actions on pages are as follows:
getLine Get a screen line
getScreen Get the entire screen content
keyStroke Send a key function
 Note
With the HLLAPI connector, the application does not need to be topmost to receive keystrokes. That means
it is possible for the screen to be locked while interacting with the application.

Controlling an Item Using the HLLAPI Connector
Available control actions on items are as follows:
get Get the item's value
getCaptData Gets the item's value on page LOAD/UNLOAD in CaptData

mode
set Set the item's value
setFocus Sets focus on an item
 Note
With the HLLAPI connector, items will always exist as they have been declared using screen coordinates.
Related Information
Connection
 Sample Code
//set the session id in application variables

MYAPPLICATION.data.session = 'A';
//Connect to the application using session id
MYAPPLICATION.connect(MYAPPLICATION.data.session);
In some cases, the terminal emulator will ask for credentials to access to the mainframe screen:
 Sample Code
//In this example, MYAPPWIN is a pilwin application wrapping the MYMAINFRAME

(the mainframe emulator application).
//path to hllapi application EXE

var exeURL = ... ;
//path to parameter file containing environment/mapping ...
var cfg = ... ;

//Start the win/utomation application
MYAPPWIN.start(exeURL, cfg);
//Wait for the first page (login page here)
MYAPPWIN.pLogin.wait(function(ev) {
//Manage the user connection
//Caution: you have to do it using pillwin or ui automation.
MYAPPWIN.pLogin.oLogin.set('test');
MYAPPWIN.pLogin.oPwd.set('test');
MYAPPWIN.pLogin.oValidate.click();
//You may have to check error popup and/or connection message on the
pilwin/ui automation application on the bottom bar
//Once you detect the user connection you can connect to HLLAPI using
session ID
MYMAINFRAME.connect('A');
//Once connected, you can control the mainframe application
MYMAINFRAME.pHome.wait(function(ev) {
//Code here...
});
});
Once connected, START/END events of a mainframe application and page LOAD events will be cached, as well
as any other HLLAPI technical event.
Internationalization
The application screen for different languages is often very similar and items stay the same size.
The Must Exist item can be used to recognize page in different languages, by applying the like operator on it
and listing possible text parts.
Item criteria:
• EQ(X) = 2
• EQ(Y) = 1
• EQ(CX) = 8
• like(TEXT) = Home|Accueil

Page Hierarchies
Many mainframe screens simulate the display of popups:
Desktop Agent always tries to recognize the first page that matches its criterion.

Therefore, page ranking is important.
With HLLAPI, pages are usually recognized via MustExist items, and more specifically, their TEXT criteria.
In the example below:
• The pMain page under the popup could be recognized up to an item screen test (in orange)
• The pPopup page could be recognized up to an item popup title (in gray)
To be seen in the page hierarchy, the pPopup page must be above pMain.
Otherwise, pMain will be always found, and pPopup won't be found – whether or not pPopup is displayed.
Keystrokes and Special Characters
Set a field using keystrokes
You need to set focus on the targeted item before invoking the keystroke on the page.
 Sample Code
//Focus targeted image

MYAPPLICATION.pMyPage.oMyItem.setFocus();
//Send string as a keystroke
MYAPPLICATION.pMyPage.keyStroke('This is a test');
Unlike the keystroke method, the set method directly focuses on the item before setting its value.
Empty a field using constants
It is possible to send command sequences using constants and keystrokes. But remember that mainframe
applications have their own send key mapping, and constants (here e.key.Erase) may not be usable on every
mainframe.
 Sample Code
//Focus the element first

MYAPPLICATION.pMyPage.oMyItem.setFocus();
//Send command sequence to erase the focused field
MYAPPLICATION.pMyPage.keyStroke(e.key.Erase);
Use of Mnemonics
In general, the @ key is a special character used for mnemonic sequences, which means that writing an email
could be problematic. For instance, in some mainframe applications, @C will clear the focused item. To be able
to set/keystroke an @ character, it may be necessary to escape it using another @ character.
 Sample Code
MYAPPLICATION.pMyPage.oMyItem.set('myEmail@@sap.com');
Navigating Between Two Pages
Navigating between two screens by validating the first one
Navigating between two screens is often accomplished by validating the first one. This is generally done using
the Enter key.
 Sample Code
//Waiting for the first page

MYAPPLICATION.pFirstPage.wait(function(ev) {
//In this sample, Enter will validate the FirstPage and should bring us
to the second one
MYAPPLICATION.pFirstPage.keyStroke(e.key.Enter);
});
//Waiting for the second page

MYAPPLICATION.pSecondPage.wait(function(ev) {
...
});
Managing change on a page
Once declared, all objects will exist. There are no technical events.
 Sample Code
//This is the declaration of a navigation step

//Going from pFirst page to pSecondPage
//It can be stuck on an error message
//Change on the page will be triggered by UPDATE technical event
MYAPPLICATION.step({ stNavigateFromFirstToSecond: function(ev, sc, st) {
ctx.log('=== STEP ' + st.name + ' ===', e.logIconType.Event);
//In this case, validating a page may bring to the second page OR display
an error message
//this message can be catched when the page is UPDATED
MYAPPLICATION.pFirstPage.wait(function(ev) {

//Validating the page
MYAPPLICATION.pFirstPage.keyStroke(e.key.Enter);
});
//Waiting for the second page

MYAPPLICATION.pSecondPage.wait(function(ev) {
//Go to next step
sc.endStep();
});
//The page got an UPDATE technical event. Something changed

MYAPPLICATION.pFirstPage.events.UPDATE.on(function(ev) {
//Getting the value of the error field
var error = MYAPPLICATION.pFirstPage.oError.get();
//If it is not empty
if (error != "") {
ctx.log('error:' + error);
//Go to the abort step
sc.endStep(MYAPPLICATION.steps.stAbort);
}
});
}});
2.1.8 The OCR Connector
Image recognition and OCR are used to automate user interfaces whose underlying technology (including
the document object model, or DOM) isn’t accessible at design time or runtime. This technique is known as
surface automation.
Surface automation automates interactions with a user interface by means of visual elements such as labels,
controls, images, and icons rather than DOM elements or applicationspecific APIs. Typical use cases for
surface automation with the OCR connector:
• The application you want to automate is running in a virtual desktop or a Citrix environment and you’re not
permitted to install the Desktop Agent there.
• The application you want to automate can't be automated using any of the other technology connectors
supported by SAP Intelligent RPA, such as the Web connector or the Java connector. Flash applications
are one example. Another example are legacy applications for which native automation technologies don’t
exist or are very niche.
• Your automation use case requires the recognition of an image such as an icon.

Example - Creating and Executing a Bot with the OCR Connector
Consider this application:
We want to create a bot to do the following:
1. Set the Reference ID input field.

2. Click the Search button.
3. Read the values from the Lastname and Firstname fields.
4. Display the last name and first name in a popup window.
The following steps are required to create the described bot:
1. Open the Desktop Studio and create a new project. For details, see Create a Project [page 63].
2. In the Explorer perspective, open the context menu and choose Add a New Application ...:
• Select UI Automation in the Choose Technology field.
• Select the application from the list (in this case, CRM - WinForm). It’s then shown in the preview so that
you can check whether it’s the right one.
• Click Select.
• Return to the Explorer perspective and enter the application name and location in the Parameters tool
window.
Click Save.
3. Capture a page:
• Double-click in the new Page box.
• Hover the cursor over the page to be captured while holding down the Ctrl key.
• Name the page 'pMain'.
• Click the Scan and Capture button.
4. In the Captured data pane, double-click Name and ControlType to set them as recognition criteria for this
page.
5. For this use case, we control Tab 1 of the CRM - WinForm application, so associate Tab - Tab1 in thePage
tree to a new item.
6. Rename it 'oOCRRootItem'.
7. Set AutomationId and Deepness as recognition criteria by double-clicking them in the Captured data
pane.
8. Now, create a subpage using OCR:
• Right-click the 'pMain' page to add a subpage with OCR technology.
• Highlight Tab 1 - hover the cursor over the page while holding down the Ctrl key.

• Choose OCR technology for the capture.
• Click the Scan and Capture button.
• Name the page 'pOCRContainer'.
• In the Parameters pane, set the Root Item of 'pOCRContainer' to 'oOCRRootItem'.
 Tip
Make sure that these two Capture Page windows don't overlap with the application during capture.
9. Run the project by clicking the button.

10. You can now control subpages under 'pOCRContainer':
• Right-click 'pOCRContainer' to add a subpage.
• Capture the page as described earlier, and name it 'pTab1Page'.
• To control the page, create a must-exist item: Double-click on the Reference ID element shown in the
tree. This creates an item named 'ibReferenceID' under 'pTab1Page'.
• In the Parameters pane, check Must Exist.
• In the Criteria pane, keep only the Text property.
11. Create a zone around the required text field:
• Use OCR to identify the Reference ID input field. Select the image selector as shown in the screenshot.

• Associate 'inputReferenceId' with 'lbReferenceID' in the Parameters pane via the Labelled by
parameter, as shown:
• Now, create an item for the Search button in the same way as for the ReferenceID input field. In the
Criteria pane, keep only the Text property.
12. Create a subpage with data:
• Open the CRM WinForm application, enter 2 in the Reference ID field, and click Search.
• To capture the CRM WinForm with data, create another subpage. In the Explorer view, right-click
'pOCRContainer' and select Add Subpage.
• Once the Add Capture dialog appears, capture the screen. Enter the name 'pTab1PageWithData' and
click Scan and Capture.
• Double-click the field label Lastname. Lastname is shown in the Explorer view under
'pTab1PageWithData'.
• Identify the Lastname input field using OCR. Select the image selector around the Lastname input
field.
• Do the same for the Firstname label and input field.
• In the Parameters pane, set the Labelled by parameter for both the Firstname and Lastname input
fields.
13. Create the workflow:
• Navigate to the Workflow tab, select 'CRMWinForm', and click Create New Workflow. Enter the name
'readCRMWinForm'.
• Open the workflow. In the Activities view, select the Activities tab.
• Go to Application, select Start, and drag it under the Start box.

• From the Pages tab, drag and drop the page 'pTab1Page' under Start 'CRMWinForm'.
• Double-click the page and select the label ReferenceId.
• From the context menu, select Advanced Item - Wait Wait until the Item exists .
• Select Set action for the input field associated with ReferenceId, and select Click action for the
Search button.
• Set the value 2 in the Source Data property.
• From the Pages tab, drag and drop the page 'pTab1PageWithData' under Start 'pTab1Page'.
• Double-click the page 'pTab1PageWithData' and add Get actions for the Firstname and Lastname input
fields.
• From Activities Activities Popup , select MsgBox and drop it under the page
'pTab1PageWithData'.
• Add the following in the Properties pane:

• In the Activities view, select the Activities tab, go to Application, select Close, and drag it under Start.
• Save the workflow.
14. Run the application.

Related Information
Template Matching [page 221]

Handling Multi-Template Matches [page 222]
Identifying the Right Text from Multiple Matches [page 224]
2.1.8.1 Template Matching
This surface automation feature is useful in screens with fluid layouts.
When is Template Matching Useful?
Template matching makes it possible to detect any pre-selected pattern on a user interface, including non-
textual areas, regardless of the target location. A typical example is buttons with icons but no text. Template
zones are helpful in detecting patterns on user interfaces with fluid layouts, where the positions of controls
keep changing and the Labelled by property can't be used.
A template is treated like any other item and you can perform actions on it, such as clicking.
How Does Matching Work?
When you have defined a template, a pixel-to-pixel comparison between the template and the application’s
screenshot is performed at run time. The highest matched region is returned as the recognized template.
This feature delivers added bot stability in all bot types.

 Note
Template zones only work if the control you are tracking stays the same size.
How are Template Zones Used?
Choose the desired zone and right-click on the zone rectangle. Choose 'Create new Template from image
selection'.
The rectangle will change to green. The Zone Type property in the Properties pane is set to 'Template'.
 Note
Do not declare a template zone item as ‘must exist’. To uniquely identify a page, create a text item and
declare it as a ‘must exist’ item..
Related Information
Handling Multi-Template Matches [page 222]
2.1.8.2 Handling Multi-Template Matches
This is an enhancement of the Template Matching feature.
The Problem: Multiple Template Candidates
If you’ve created a template for an image pattern that has multiple candidates on a page, you can't predict
which of them the OCR connector will return at run time. So you must uniquely identify the template match you
need.

You can try to do this by specifying the expected coordinates of the target pattern when designing your
scenario. But the layout of application pages is often variable, and the coordinates may not be accurate enough
to ensure a correct hit at run time.
The Solution: 'Labelled By'

There's a better way to identify the location of the target image pattern at run time that doesn't depend on
accurate coordinates: specifying a reference label through the property "Labelled By".
In the example screen below, there are two occurrences of the search field (shown with yellow borders) and two
occurrences of the gear icon (red borders):
The implementation of the new feature works by looking at the items around the target template (shown below
with green borders). At design time, the bot developer must label the target template with the nearest item.
Let's say the bot developer wants to uniquely recognize the second gear icon. The developer must do the
following:
1. Create a template for the gear icon:

• Select the zone around the icon
• Right-click on the zone rectangle
• Select Create new Template from image selection from the context menu
2. Select the nearest text and create an item for it
3. Set the item created in step 2 as 'Labelled by' in the parameters for the template
At runtime the distances d1 and d2 between the two template instances and the label item are calculated and
as d1 is smaller, the second template is recognized.

This method still works if the application screen is resized and the spacing between the controls changes. The
OCR connector still finds the template that is nearest to the label you have specified.
Using this method improves the stability and resilience of your bot.
Related Information
Template Matching [page 221]
2.1.8.3 Identifying the Right Text from Multiple Matches
The Problem: Identifying the Correct Text Item from Multiple Matches
With the OCR connector, you can select text labels on an application page and declare them as an item. Then
you can associate activities such as click or set with the item. However, if there are multiple occurrences of a
text on the page, the topmost match will always be recognized. And that may not be the one you want to target.

The Solution: Nearest Match
Option 1: With Design-Time Coordinates

To uniquely identify your target text item at runtime, you can use the design-time coordinates of the text item
and also specify the expected deviation from that position along the x- or y-axis, or a combination of both. You
can configure the deviation by using one or both of the following parameters:
• Nearest match along width (%)

The value represents a deviation margin percentage compared to the width of the application page
(screen). At runtime, the nearest text along the x-axis is matched.
• Nearest match along height (%)
The value represents a deviation margin percentage compared to the width of the application page
(screen). At runtime, the nearest text along the y-axis is matched.
The values set for these properties can range between 0 and 100. The default value is 0, meaning that this
feature is disabled. If the deviation at runtime is greater than the configured percentage value, the text is not
recognized.
At runtime, the text will be returned that is within the area defined by the Nearest Match parameters and also at
minimum distance from the design-time coordinates. In the diagram below, the text “search” is the target item,
h is the expected percentage deviation along the y-axis and w the expected percentage deviation along the
x-axis. At runtime, the area shown in blue is scanned and if the target text lies inside it, the text will be correctly
identified. The midpoint of the blue search area is the top left corner of the target item. This is the reference
point that is applied when you use this option.
Option 2: With Label

The second option is similar to Option 1 but instead of using the target item's design coordinates as a reference
point, this option uses the offset distance from the center of the Labelled by item as the reference point.
In the diagram below, the reference point, or midpoint of the blue search area, is the offset distance from the
center of the Labelled by, Status and the offset distance is the distance between the center of the target item

Create and the item chosen as its label, Status. Once again, w and h are the expected percentage width and
height deviations, respectively.
If there are multiple hits for the text within the blue area, the one nearest the reference point is returned as the
matched text.
Whether you use Option 1 or 2, the Nearest Match feature improves the stability and resilience of your bots.
2.1.9 Controlling Individual Entities
The first step in controlling applications is to control individual entities: items, pages and applications.
To control an entity, the following conditions must be satisfied:
• The entity has been declared in the project

• Desktop Agent is running
• The entity is recognized by Desktop Agent
Controlling an Item
Basic Use Cases
In your projects, most control actions are performed on items. You usually perform control actions on simple
items such as:
• Fill or read an entry field

• Click a button
The following methods allow these simple actions to be performed:
Simple Control Actions

click Click an item (such as a button or link)
myAppli.myPage.myButton.
click();
get Read the value of an item

var value =
myAppli.myPage.myField.g
et();
set Set the value of an item

myAppli.myPage.myField.s
et(myValue);
check Check an item (a radio button or check

myAppli.myPage.myField.c
box) heck(true);
clickDouble Double-click an item

myAppli.myPage.myField.c
lickDouble();
setFocus Set focus on an item
Test Status of an Item
exist Test existence of an item

var bExist =
myAppli.myPage.myField.e
xist();
isEnabled Check if item is enabled
isVisible Check if item is visible
For a complete list of ctx.item class members, see the Desktop SDK Reference Guide.
Managing Control Errors

Before implementing control actions in the project scripts, it is advisable to test the controlling of individual
items using the Tester view in the Debugger. The following actions are very helpful to script developers:
• Clicking a field
• Setting the value of a field
If the controlled item doesn’t respond as expected, check whether the controlling method returns an error.
Additional Features By Technology

The previous control actions are available in all application implementation technologies.
According to the application implementation technology (such as Windows or Web), item instances can
implement additional features:
• Controlling an Item Using the Web Connector [page 82]:

• Execute script on an item within a Web page
• Get HTML attributes of a Web item
• Controlling a <select> component

• Controlling an Item Using the UI Automation Connector [page 113]
• Controlling an Item Using the Java Connector [page 202]
• Controlling an Item Using the Win32 Connector [page 186]
• Controlling an Item Using the HLLAPI Connector [page 210]
For a complete list of ctx.item class members, see the Desktop SDK Reference Guide.
Controlling a Multiple Item
Multiple items are controlled in the same way as non-multiple ones are. You must simply specify the index of
the item’s instance using the i method:
 Sample Code
var value = myAppli.myPage.myOccursedField.i(myIndex).get();
If an item is multiple (see ‘Recognition’), you must specify one index via the Occurs level:
 Sample Code
var value = myAppli.myPage.myMultiOccursedField.i(myIndex1, ...,

myIndexN).get();
Get the instances count of a multiple item
You can get the count of different instances of a multiple item using the nbOccurs property:
 Sample Code
var count = myAppli.myPage.myOccursedField.nbOccurs;
For multiple items, you can only get the count of the last Occurs level:
 Sample Code
var count = myAppli.myPage.myMultiOccursedField.i(myIndex1, ...,

myIndexN).nbOccurs; '' fails
count = myAppli.myPage.myMultiOccursedField.i(myIndex1, ...,
myIndexN-1).nbOccurs; '' ok
Manage in one call the values of all instances of a multiple item
You can manage in one call the values of all instances of a multiple item using the following methods:
getAll Get in one call the values of all instances of a multiple Item
setAll Set item values in multidimensional objects, from an array

object

getCol Get the items of a given column in a two-dimensional array
getRow Get the items of a given row in a two-dimensional array
 Sample Code
var allInstancesData = myAppli.myPage.myOccursedField.getAll();

for (var i=0 ; i<myData.length ; i++)
{
var oneInstanceData = myData[i] ;
}
Controlling Complex Items
Controlling complex items (such as a list or tree) can be more complex than controlling simple items.
First of all, try to control such items by using simple methods:
get Read the selected value of a tree view

 Sample Code
or list view
var value =
myAppli.myPage.myFiel
d.get();
set Select a value in a tree view or list view

 Sample Code
myAppli.myPage.myFiel
d.set(myValue);
getList Get the list of values of a tree view or list

view
select Select or deselect a value in a tree view
selected Get the selected value for a tree view or

list view
If the simple method doesn’t work as expected, there may be another way to control the targeted item, specific
to the connector used to control the application. Please look at the documentation on the corresponding
connector:
• Controlling Complex Items Using the Web Connector [page 85]

• Controlling a complex Item using the UI Automation Connector
• Controlling a complex Item using Java connector
• Controlling a complex Item using Windows connector

• Controlling a complex Item using HLLAPI connector
If you can't find a way to control your item, it may be due to the implementation of the application being
controlled.
Advanced Use Cases for Controlling Items
Control an Item with Keystrokes

The recommended way to set the value of an item is to use the set method.
In some cases, this method doesn’t set the item value correctly. This may be because control actions are
performed at a low level instead of at the user level.
In these cases, you can try setting the item’s value at the user level by:
• Activating the page using the activate method

• Setting the input focus on the item using the setFocus method
• Setting the item’s value by sending keystrokes using the ctx.keyStroke method
This way, you exactly mimic the user action.
The drawbacks of this method are as follows:
• The application cannot be controlled in the background

• The user must not change the input focus during controlling
 Sample Code
// Sets the focus on the combobox

MyAppli.MyPage.activate() ;
MyAppli.MyPage.MyCombo.setFocus() ;
// Opens the combobox by using the F4 shortcut
ctx.keyStroke(e.key.F4);
// Wait 10ms until the combo is opened
ctx.sleep(10);
// Sets 'the new value' and hit Enter to validate the value
ctx.keyStroke('the new value' + e.key.Enter);
Control an Item with Mouse-Clicks

The recommended method to click an item is to use the click method.
In some cases, this method doesn’t do the action as required. This may be because control actions are
performed at low level instead of the user level.
In these cases, you can try to click the item at the user level by:
• Activating the page using the activate method

• Clicking the item using the mouse, using the click method
This way, you exactly mimic the user action.
The drawbacks of this method are as follows:
• The application cannot be controlled in the background

• The user must not move the mouse during controlling
 Sample Code
MyAppli.MyPage.MyButton.click(true) ;
Retrieve the Content of an Item Using the Clipboard

If you cannot read the content of an entryfield by using the standard get method , you can try reading it using
the clipboard:
• Set the focus in the field

• Select all the content by sending CTRL + A shortcut
• Copy the content by sending CTRL + C shortcut,
• Get the content of the clipboard using the ctx.clipboard.get method .
 Sample Code
// Set the focus in the field

MyAppli.MyPage.MyItem.setFocus() ;
// Call 'Ctrl+A', to select the whole content
ctx.keyStroke(e.key.Ctrl+'A');
// Call 'Ctrl+C' to copy the selected content in the clipboard
ctx.keyStroke(e.key.Ctrl+'C');
// Get the content of the clipboard
var theValue = ctx.clipboard.get();
Retrieve the Index of a Clicked Multiple Object

You may have to track an event (such as CLICK ) on a set of multiple objects. For details on how to declare
these objects correctly, see Declaration Principles [page 282].
If you need to know which element has been clicked, you can retrieve this information thanks to the event
parameter ev.itemIndex.
 Sample Code
// This handler displays a popup indicating the index of the clicked object
MyApp.myPage.myObject.events.CLICK.on(function(ev) {
var data = {};
ctx.popup('pClickHandled', e.popup.template.Ok).open({
title: GLOBAL.labels.aboutPopup.title,
CX: 500,
CY: 300,
message: "click occurred on element number "+ev.itemIndex,
icon: ctx.options.resourceURL + '/bmp64/hello128.png'
});
});

Controlling a Page
Background
Most of the time, you do not need to perform control actions on pages. For example, there is no controlling
method to open a page. Instead, you execute the control sequence described in the Functional Specification of
the project. For example, click the Open button.
Basic Use Cases
However, the ctx.page class implements the following basic methods:
Simple Control Actions
activate Activate a page

 Sample Code
myAppli.myPage.activa
te();
close Close a page

 Sample Code
myAppli.myPage.close(
);
Test status of the Page
exist Test existence of a page

 Sample Code
var bExist =
myAppli.myPage.exist(
);
isEnabled Gets enabled or disabled state of the

page
isModal Gets the ‘modal’ state of the page
isVisible Checks if page is visible
Change the Page window state
maximize Maximizes the page
minimize Minimizes the page
restore Restores the page

setVisible Shows or hides the page (or an element
of the Web browser )
getTitle Gets the page title
Send a sequence of keys
keyStroke Sends a sequence of keys to the page
keyStroke2 Sends a sequence of keys to the

page (alternative method compared to
ctx.item.keyStroke)
Manage all items of a page
getItems Gets all the item values in the page
setItems Sets all the item values in the page,

from a data object
Additional Features By Technology

Depending on the application implementation technology (such as Windows, Web, or, Java), thectx.page
class implements additional features:
• Controlling a Page Using the Web Connector [page 79]

• Modify page content
• Execute a script within a page
• Use navigation history
• Control a Page Using the UI Automation connector [page 111]
• Manage the cache
• Execute asynchronous actions
• Control a page using the Win32 connector
• Add button or edit component to the page content
• Control menus
• Control a page using the Java connector
Advanced Use Cases for Controlling Pages
Manage Page Instances
count Returns the number of page instances for a given application

real instance
Get an Item by its name
If necessary, you can get an item by its name using the getItem method, instead of using the item object.

getItem Gets an item by its name
 Sample Code
MyAppli.MyPage.MyItem.set(myValue) ;
is equivalent to
 Sample Code
MyAppli.MyPage.getItem('MyItem').set(myValue) ;
Controlling an Application
Basic Use Cases

Most of the time, we do not perform control actions on applications. However, the ctx.application class
implements the following basic methods:
exist Tests application existence
For a complete list of ctx.application class members, see the Desktop SDK Reference Guide.
Additional Application Controlling Features By Technology

Depending on the application implementation technology (such as Windows or Web), the ctx.application
class implements additional features:
• Control an application using the UI Automation connector [page 110]

• Manage the cache
• Execute asynchronous actions
• Control an application using HLLAPI connector
• Connect to the HLLAPI session
Advanced Use Cases for Controlling Applications
Start an Application
With some technologies (such as WEB and WIN.), you can start a declared application by script, using the
start method:
 Sample Code
MyAppli.start() ;

By default, this method uses the application's path registered when the application was captured:
• The EXE file path for desktop applications

• The URL for Web applications
 Caution
Please be aware that, particularly with Web applications, you generally cannot use the same application
path in the development phase as in the production phase:
• In the development phase, the test platform is generally used

• In the production phase, the production platform is used.
This issue can be managed by providing the right path in the start method:
 Sample Code
if (ctx.options.env == e.env.dev)
MyAppli.start('MyEnvPath') ;
else
MyAppli.start('MyProdPath') ;
An alternative to set the application's path for each environment using the setPath method:
 Sample Code
// define production and test URL for MyAppli application

MyAppli.setPath(e.env.prod, 'MyProdPath');
MyAppli.setPath(e.env.dev, 'MyEnvPath');
...
// select 'production' as current environment
ctx.options.env = e.env.prod;
...
// start application (with 'production' URL)
MyAppli.start();
Manage Application Instances
For details on this topic, see Multi-Instance Management [page 236].
count Returns the number of application instances
setDefaultInst Memorizes the default instance for the application
Manage the Current Page
currentPage Current Page
Gets a Page by its Name
If necessary, you can get a page by its name using the following method, instead of using the page object.

getPage Gets a page by its name
 Sample Code
is equivalent to
 Sample Code
MyAppli.getPage('MyPage').activate() ;
2.1.10 Multi-Instance Management
Multiple Instances of a Declared Application

In some cases, an application declared in a SAP Intelligent RPA project may be launched on the desktop
multiple times.
In this example, Desktop Agent detects two running instances of the same Web application (here: CRM) with
two distinct InstanceIDs (CRM[13064] and CRM[9912]).
Desktop Agent receives technical events from the two running instances and can control both of them.
Multiple Instances of a Declared Page

In some cases, a page declared in an application can be detected several times in the same instance of the
application. This can be due to an incorrect declaration of the page, causing two different pages to be detected
as the same page. In this case, you must improve the recognition criteria of the page in order to target the right
one.
This can also happen if the controlled application opens the same page twice. In this case, the problem is: how
to make sure the right page instance is controlled?

Multi-Instance Management Using the Desktop SDK
Default Instance Management

In most cases, you control an application and a page without specifying their InstanceID. In these cases, the
Desktop SDK automatically selects controlled instances as follows:
• Determine the application's InstanceID

• If the last event received has a valid application InstanceID, this will be used (see the ev.appliInst
property).
• Else, if there are running instances of the application, the first InstanceID is used.
• Else, you must start an instance of the application and wait until you receive a technical event from it
(START event).
• Determine the page's InstanceID
• A valid application InstanceID has been determined.
• If the last event received carries a valid page InstanceID, it is used (see ev.pageInst property).
• Else, if there are running instances of the page, the first InstanceID is used.
• Else, the control action will return an error.
The application and page InstanceIDs carried by an event are set by the sender of the event:
• For technical events, they are set by the Desktop Agent connector.
• For functional events, the application InstanceID can be set by the sender of the event via the notify
method.
Examples:
Code executed on reception of a technical event
 Sample Code
MyApply.MyPage.events.LOAD.on(function(ev)
{
// Same as MyApply[ev.appliInst].MyPage[ev.pageInst].MyButton.click()
MyApply.MyPage.MyButton.click() ;
};
Code executed on reception of a functional event
 Sample Code
MyApply.addOn({ MyFuncEvent: function(ev)

{
// If no running instance of MyAppli : starts one (first instance is the
virtual one)
if (MyAppli.count() == 1)
MyAppli.start() ;
// Waits until MyApply.MyPage is present

MyApply.MyPage.wait(function(ev)
{
// Use the first living instance of MyPage
MyApply.MyPage.MyButton.click() ;
}, 0);
}});

Default instance management saves you from having to provide InstanceIDs when controlling actions. But that
is not enough if you have to manage multiple instances of an application.
Controlling a Specific Instance of an Application

Suppose that you have:
• A Web application controlled by Desktop Agent in the background.

• The same Web application used by the user in the foreground.
How can you be sure that the dedicated running instance is controlled, and not the one launched
by the user? You can do this by setting the default instance on an application using the
ctx.application.setDefaultInst method:
 Sample Code
var bStartPending = false ;

...
MyAppli.MyPage.start();
bStartPending = true ;
MyAppli.events.START.on(function(ev)
{
if (bStartPending)
{
MyAppli.setDefaultInst(ev); // filter MyAppli instances other than
ev.appliInst
bStartPending = false ;
}
});
Once the default instance is set:
• You will not receive any technical events from the other instances.
• Other instances will not be taken into account by default instance management.
• You cannot control other instances using the syntax <MyAppli[otherInstance]>.
 Note
The default instance is automatically reset when the controlled application ends.
Controlling Multiple Instances of an Application Simultaneously

Suppose that you control several instances of the same Application simultaneously. How can you be sure that
the technical events triggered by different instances don't interfere?
You can do this by setting a default application instance for a running scenario using the
sc.setDefaultInst method:
 Sample Code
MyAppli.step({ stStart: function(ev, sc, st)

{
MyAppli.start();
MyAppli.events.START.on(function(ev)
{
// filter MyAppli instances other than ev.appliInst for the current
scenario
sc.setDefaultInst(ev) ;
});

}});
Once the default application instance is set for a running scenario:
• Handlers set in the steps of the scenario will not be triggered by technical events from the other instances.
• Other instances will not be considered in Default instance management inside the steps of the scenario.
• You can still control other instances using the syntaxMyAppli[otherInstance]
2.1.11 Controlling Entities Using the Desktop SDK
You control entities such as applications, pages, and items by using a script. To make this simpler, the Desktop
SDK implements the following classes:
ctx.application
This class is used to control applications and processes.
 Sample Code
<application>.<action>(parameters...);
 Example
' ' start an application

myAppli.start();
Depending on the application implementation technology (such as Windows, Web, or Java), the
ctx.application instance implements different methods. For a complete list of ctx.application class
members, see Class ctx.application.
ctx.page
This class is used to control pages.
 Sample Code
<application>.<page>.<action>(parameters...);
 Example
' ' close a page

myAppli.myPage.close();
Depending on the application implementation technology (for example, Windows, Web, or Java), the ctx.page
instance implements different additional methods. For a complete list of ctx.class class members, see
Class ctx.page.
ctx.item
This class is used to control items.
 Sample Code
<application>.<page>.<item>.<action>(parameters);
 Example
'' click a button

myAppli.myPage.myButton.click();
'' get an Item value
var name = myAppli.myPage.myField.get();
'' set an Item value
myAppli.myPage.myField.set(name);
Depending on the application implementation technology (such as Windows or Web), item instances
implement different actions. For a complete list of ctx.item class members, see Class ctx.item.
Controlling Declared Entities
To allow you to control declared entities, an instance of the appropriate class is automatically created for each
declared entity. This code is included in the declaration script file <project name>.resources.js.
 Note
The entire content of the declaration script file is automatically regenerated. Do not write any code here: It
will be deleted.
2.2 The Declaration Phase: General Information
The main purpose of SAP Intelligent Robotic Process Automation is to automate tasks that humans perform on
applications running on user workstations. Typical tasks include:
• Copying and pasting data from one application to another

• Entering the same data in multiple applications
• Executing a functional task that comprises several subtasks across multiple applications
Most projects involve controlling applications that are running on a user's workstations. To control these
applications, you begin by declaring entities such as applications, pages, and items. These entities can then be
used to communicate with the application you wish to automate.
Basic Definitions
The application entity is used to communicate with a running, real-world application. An application entity can
contain page entities that can communicate with parts of the application’s user interface. A page entity can
contain item entities that can communicate with elements of the page entity.
These entities make it possible to:
• Control real-world applications to determine, for example, whether a button has been clicked or to read or
write a value in a field.
• Receive technical events from real-world applications, such as starting an application, loading or unloading
a specific object, or clicking on a specific button.
Process entities execute internal tasks that are not directly related to a running, real-world application.
Examples include:
• Managing exchange with external services (such as Web services and databases).
• Managing applications via APIs (such as Microsoft Excel, Microsoft Word, Microsoft Outlook, or SAP
Business Suite).
• Managing coordination when no running applications are able to perform this task.
All of the above entity types can exchange data by means of functional events.
The Solution Design Phase
Desktop Agent can control the following types of applications:
• Desktop applications
• Web applications
• Mainframe applications running in a terminal emulator
Although these types of application differ in some ways, the respective entities must always satisfy the same
rules.

General Rules
Application, page, and item entities must comply with the following rules:
Application entity rules • An application entity contains page entities.

• An application entity must contain at least one page entity.
• An application entity cannot contain item entities.
Page entity rules • A page entity must belong to an application entity (or, in the case of Desktop applica
tions only, to another page entity).
• A page entity can contain item entities.
Item entity rules • An item entity must belong to a page entity.

• An item entity can be declared as multiple to represent the elements of multiple pages.
For more information, see:
• Entities for a Desktop Application [page 247]

• Entities for a Web Application [page 248]
• Entities for a Mainframe Application [page 249]
To learn the key principles you need to observe to ensure that your entity declarations are robust, see
Declaration Principles [page 282].
Choosing the Control Technology
When you begin to declare an application, you must choose the connector used to control the targeted
application. Your choice mainly depends on the technology of the application. The most frequent cases are:
WEB A Web application
WIN A Windows desktop application (Win32 or WinForms)
HLLAPI A mainframe application running in an HLLAPI-compatible

emulator
SWG A desktop Java application (such as AWT or Swing)
UI Automation Other desktop applications (WPF, Silverlight, QT, and so on).

UI Automation can also be used for Windows desktop appli
cations (Win32 or WinForms).
Sometimes it is difficult to identify the technology of the target application, especially in the case of desktop
applications. The recommended approach in this case is to:
1. Choose a technology and verify that the targeted application appears in the list of detected applications.
2. Once found, create the application entity.
3. Declare a page in this application (see Declaring Pages [page 252]).

4. Verify that you can detect the components that you need to target (see Declaration of Page Items [page
262]).
5. If not found, try with another technology.
Declaring an Application
Set Recognition Criteria for Applications

Application criteria are set for target application properties. Available application properties are specific to
each technology:
• EXE name for desktop applications

• Web domain for Web applications
• Session ID for mainframe applications
When you create an application entity, Desktop Studio automatically sets the application criteria. In most
cases, the default criteria will be correct. If not, they can be adapted as required.
For a full description of this task, see Declaring Applications [page 249].
Declaring a Page
Subpages
In some technologies (such as WIN, JAVA, UI Automation), a page can contain another page, that is, a subpage.
 Note
Relationships between pages must mimic the relationships between their targeted components:
• A page within another page must be declared as a subpage of that page.

• A page that is not contained in another page may not be declared as subpage of that page.
Incorrect declaration of pages and subpages can lead to errors during page recognition:
• A subpage can only be recognized inside its parent page

• A subpage cannot be recognized if its parent page has not been recognized
• A page cannot be recognized inside another page if that is not its parent page

 Example
Consider the following example of a simple desktop application:
In Order to Control... You Declare...
The main window pMainPage, which targets component (1)
Tab 2 pTabITem2, which targets component (2)
Tab 1 pTabITem1, which targets component (3)
Components (2) and (3) are descendants of component (1), so pTabITem2 and pTabITem1 are contained in
pMainPage.
That means pTabITem2 and pTabITem1 must be declared as subpages of pMainPage.
Page Instances
Each recognized page is a page instance.
Set Recognition Criteria for Pages

Page criteria are set on target screen properties. The available screen properties are specific to each
technology. For more details, see the connectorspecific information below:
• Web Connector: Set Page Criteria [page 72]

• Win32 Connector:Set Page Criteria [page 177]
• Java Connector: Set Page Criteria [page 193]
• UI Automation Connector: Set Page Criteria [page 95]

• HLLAPI Connector:Declaring Entities Using the HLLAPI Connector [page 204]
For details of these methods, see Advanced Recognition Capabilities [page 283].
Tracking Technical Events
A declared page automatically receives LOAD and UNLOAD events. In some technologies, declared pages can
receive other types of technical events. These events must be explicitly tracked in order to be notified.
In special cases, it can be useful to declare more pages to generate additional LOAD and UNLOAD events.
Using Subpages
 Note
The use of subpages is only possible with WIN, Java, and UI Automation technologies.
Consider the case of a desktop application that has a TabControl with various TabItems. Suppose that we have
to perform the following control sequence:
• Navigate to a specific TabItem

• Perform control actions once this TabItem is displayed.
The best way to implement this sequence is to:
• Declare a pMainPage to target the main window of the application (required).

• Declare a pTabItemPage as a subpage of the pMainPage to target the specific TabItem concerned.
With this method, receipt of a LOAD event on the pTabItemPage triggers the continuation of the control
scenario.
For more details on declaring pages, see Declaring Pages [page 252].
Declaring an Item
Set Recognition Criteria for Items
Item criteria are set for target component properties (see Criteria Management [page 269]). The available
component properties are specific to each technology.
Item criteria are used by the connector in the following way:
Once the connector recognizes a screen as a declared page, it can search the DOM of the screen to find the
target of each item:
• If an item is declared as multiple, it will target all of the DOM components that match its criteria.
Multiple items (available in WEB, UI Automation, HLLAPI, and Java Swing only)
A multiple item is used to target an undefined number of components (for example, all the rows in a table).

To declare a multiple item:
1. Set recognition criteria that are broad enough to match all of the targeted components.
2. Set the Occurs item parameter (see Item Definition [page 263]).
The Occurs parameter can be also set on the ancestor item or on any item of the items pattern.
Advanced Recognition Techniques

Sometimes, a targeted component has no (or insufficient) unique, distinguishing properties. Another
component is incorrectly recognized in this case. To ensure you declare the corresponding item correctly,
you can use one of the following methods:
• Items Pattern Method [page 286] (available in WEB and UI Automation only)
• Ancestor Method [page 285] (available in WEB, WIN, and UI Automation only)
• Labelled By Method [page 285] (available in WIN, UI Automation, and HLLAPI only)
Track Technical Events

A declared item can receive technical events. To be received, a technical event must be tracked explicitly (see
Set Item Tracked Events under Declaration of Page Items [page 262].
 Note
A tracked event will be notified if it is fired by the targeted component. It is necessary to verify at runtime
that the tracked event is fired correctly.
The available technical events depend on the technology and on the type of component targeted.
Set Parameters
Item parameters can be set by using Desktop Studio (see Set Item Parameters under Declaration of Page
Items [page 262]).
Some parameters can be used to organize or filter items in Desktop Studio:
Parameter Description
Folder Organizes the declared items of a page. This can be useful if

there are a large number of declared items.
Technical Indicates that the item is technical (true) or functional

(false). Technical items are excluded from IntelliSense lists
and perspectives other than the Explorer perspective. Tech
nical items cannot be controlled.
The Technical parameter can be useful for filtering items declared for use as an:
• Ancestor item (see Ancestor Method [page 285])

• Label item (see Labelled By Method [page 285])
• MustExist item (see MustExist Method [page 284])
• MustNotExist item (see MustNotExist Method [page 284]).
For more information on declaring items, see Declaration of Page Items [page 262].

2.2.1 Entities for a Desktop Application
The following entities apply for a Desktop Studio application:
Application Entity
The Application entity is defined as the Desktop process of the application.
Page Entity
• A Page entity is defined for each window of the application that must be controlled, such as the main
window, popup windows, or MDI windows.
• You can also define Page entities for subparts of an application window, such as for a tab item in a tab
control, or control containers.
• If required, generic page entities can be defined to represent a set of windows. For example, you can control
a set of error popups using the same generic page entity.
• An Item entity must be defined for each component that has to be controlled, such as input fields,
buttons, labels, combo boxes, or checkboxes.
Item Entities
An Item entity must be defined for each component to be controlled, such as entry fields, buttons, labels,
comboboxes, or checkboxes.
An application is only notified of two technical event types:
• Start
• End
Notifications of these events are issued automatically.
Page-Based Events
LOAD The page is loaded.
UNLOAD The page is closed.

Subpages
The concept of subpages is related to the structure of desktop applications. These applications usually have a
main window, which often has child windows.
When you have to control applications of this type:
• You must declare a main page to target the main window.

• To target one of its child windows, you must declare a subpage of the main page.
The relationship between pages and subpages must be the same as the relationship between the
corresponding targeted windows.
During recognition:
• A subpage cannot be recognized until its parent page has been recognized
• A subpage can only be recognized among the descendants of the component targeted by its parent page
2.2.2 Entities for a Web Application
A Web application is a set of Web pages displayed in a tab of a Web browser.
Applications running in a plugin included on a Web page (for example, Flex applications, Silverlight applications,
or Java applets) are considered by Desktop Studio Desktop Agent as desktop applications.
For a Web application, the following entities apply:
• Application entity: This is defined as the set of Web pages of the application.
• Page entities:
• A page entity is defined for each page of an application that needs to be controlled
• For Web pages including a frameset, you need to define a page entity for each frame you want to
control
• If necessary, you can define generic page entities to represent a set of Web pages
• Item entities:
• An item entity is defined for each component that must be controlled, such as input fields, buttons,
labels, combo boxes, or checkboxes.
• For complex UI components (such as tables, lists, or trees), you will generally need to define a multiple
item entity to represent the component items.
 Note
Some Web pages may open popup windows owned by the Web browser (such as information or error
popups or “open file” popups). If you need to control such popups, you must:
• Regard the Web browser application as a desktop application

• Define a page entity for each popup window that you need to manage (see Entities for a Desktop
Application [page 247]).

2.2.3 Entities for a Mainframe Application
A mainframe application is any application running in a desktop terminal emulator implementing the HLLAPI
monitoring protocol.
A mainframe application running in a Web terminal emulator (such as Crysalid) is regarded as a Web
application. A mainframe application running in a desktop terminal emulator without HLLAPI protocol is
regarded as a desktop application.
For a mainframe application, the following entities apply:
• Application entity: This is defined as the HLLAPI session giving access to the mainframe application
• Page entities
• A page entity is defined for each screen application that must be controlled
• If necessary, you can define generic page entities to represent a set of application screens
• Item entities: An item entity is defined for the zone that must be controlled on each screen
2.2.4 Declaring Applications
To declare an application, you first capture it, then define the criteria that allow the software to recognize it, and
finally set the relevant application parameters.
Capture the Application
1. Launch the application (Web, Windows, and so on) to be managed by the project.
2. In the Explorer perspective, open the context menu and choose Add a New Application…

The following panel appears:
3. Select the technology of the application to be declared. Depending on this technology, the list below shows
all the running entities that can be chosen as an application:
• For Windows or UI Automation technology, all of the Windows executables running on the desktop
• For WEB technology, the Web pages loaded in all of the browser instances running on the desktop
• For HLLAPI technology, all of the HLLAPI sessions running on the desktop
4. Select the application that you want to add from this list.
5. Choose what you want to capture by selecting either the Print Window or Screenshot radio buttons. The
selected application is shown in the preview so that you can check that it is the right application.
 Recommendation
If the preview area is black, make sure that the application you want to capture is in the foreground.
Then select the Screenshot radio button.
6. Click Save or Save and Capture Page if you want to immediately capture one or more pages of the
application.
7. After you have finished capturing the application, return to the Explorer perspective to specify its
parameters and criteria.

 Tip
• Problems may occur when zoom factors are tuned with different values on a multiple screen display.
This is a known issue, in particular with Chrome and Firefox during capture. Capture with Chrome
and Firefox works if the window zoom factor is the same on every screen (whatever the browser zoom
factor).
If you have some issues capturing UI elements, you may be able to solve the problems by setting the
zoom factor to 100%. Go to the Scale and layout settings of your laptop and ensure that your zoom
factor is set to 100%, then restart your session to apply the change.
In the Capture window, a warning message lets you know if the zoom level of the target page is not set
to 100%.
Related Information
Declaring Pages [page 252]

Capture a Page [page 253]
2.2.4.1 Setting Application Criteria
After capturing an application, you need to set the criteria required for the software to recognize it.
The Captured Data tool window of the Explorer perspective panel shows the properties of the application that
can be used as criteria.
These properties are collected when the application is first captured. What properties are captured depends on
the application technology and corresponding connector: only properties used by the connector are captured
correctly.
The Criteria tool window lets you edit the criteria of the application that will be used by the connector to
recognize an application at runtime.

For a complete description of this tool window, see Criteria Management [page 269].
2.2.4.2 Setting Application Parameters
The Parameters tool window lets you set the following application parameters:
General Category
Name Name of the entity; used in scripts to control the application
Comment Description of the entity
Server Indicates whether the target application runs on a remote

server
Techno SDK Indicates which SDK (V2 for legacy XML or V3 for Java
Script) is used to develop the application
Connector Category
Parameters specific to the connector used to manage the application
Technical Category
Connector Name of the connector used to control the application (read-

only)
Launch path Path used to launch the target application
Offlinepath Path where application captures are stored (read-only)
Technology Technology of the application (read-only)
A description of each parameter is available in the Help panel.
2.2.5 Declaring Pages
After you have declared an application, you must add at least one page of the application. To do so, you capture
the page, set the page parameters, and then define the criteria that allow the software to recognize the page.
For a complete description of the different types of capture, see
Capture a Page [page 253]
Capture a Subpage [page 256]
Capture an HLLAPI Page [page 258]
Multi-Capture Management [page 258]

2.2.5.1 Capture a Page
 Note
Before you start a capture with Desktop Studio, make sure you are on the tab you want to capture. If there
are several windows open, the Desktop Studio only detects the current tab on the window where you are
active. Among all the different opened windows, the capture request works on the active window. During
the capture, make sure to activate the specific window you want to capture.
If you have just captured an application using the Save And Capture Page button, the Capture Page dialog box
will open automatically. Otherwise, open the context menu for the application and click Capture a New Page…
or double-click the New Page box shown in the Explorer perspective panel.
The following dialog box appears
Choosing the Technology
The technology of the selected page is detected automatically depending on the technology of the declared
application.
You can also specify it by checking Choose Technology: and selecting the desired technology from the
dropdown list.
Selecting the Page
To select the page to capture, keep the Ctrl key pressed and hover the cursor over the page.

Desktop Studio detects the page and responds as follows:
• It places a red rectangle around the page you have selected.

• It shows a screen capture of the page in the preview area.
• It shows a tree of the other potential pages detected around the selected page (the selected page is the red
one).
Select the page to capture by clicking it in the tree. A standard name and description will appear in the fields at
the bottom of the page, and you can edit them as desired. Then click Scan And Capture.
When scanning and capturing are finished, the window closes and the page is displayed in the Capture pane of
the Explorer perspective panel.
 Note
Some captures can be time-consuming, especially when capturing very large documents (Web
technology). You can interrupt an ongoing capture by clicking the Stop Scanning button. In this case, the
capture is not canceled entirely, but will be only partially completed.
 Note
Remember that for Java applications, you must capture the pages while running the project.
 Tip
• Problems may occur when zoom factors are tuned with different values on a multiple screen display.
This is a known issue, in particular with Chrome and Firefox during capture. Capture with Chrome
and Firefox works if the window zoom factor is the same on every screen (whatever the browser zoom
factor).
If you have some issues capturing UI elements, you may be able to solve the problems by setting the
zoom factor to 100%. Go to the Scale and layout settings of your laptop and ensure that your zoom
factor is set to 100%, then restart your session to apply the change.
In the Capture window, a warning message lets you know if the zoom level of the target page is not set
to 100%.
The Page Tree
The content of the page tree depends on the technology (automatically detected or manually selected):
• For a Web page, it contains all the frames displayed in the selected browser instance.
• For a Windows page, it contains all the controls of the selected Windows application.
• For a Java page, no tree is displayed.
The selected page can be changed by selecting it in the tree. The red border and the screen capture (if
available) are changed to reflect this selection.
Note that for a Windows page, the selected item will be considered as the root item of the page.

• Each page is preceded by the icon if it is detected as belonging to the application.
• A recognized page is given the corresponding page name.
Clicking the Scan And Capture button triggers the capture. Desktop Studio executes and stores:
• A screen capture of the page

• A capture of the internal page structure (HTML DOM for a Web page, or the class structure for a Windows
application)
• A capture of page source (Web pages only)
A progress bar is updated during the operation to show the capture in progress. Captures are stored on disk
and are available for working offline, so there is no need for the application to be running after the capture has
taken place). The elements captured depend on the page technology:
• Screen capture is the same for all technologies.

• DOM capture:
• For a Web page, this is the DOM of the Web document.
• For a Windows page, this is the tree of all the controls, with their properties.
• Source capture (HTML page source): available for Web pages only.
Capture Options
To set further capture options, click the cog icon at the top right.
Pick Page Shortcut

You can choose between using Ctrl + Hover and Shift + Hover to select the page you want to capture.
Start Capture On Hover

Use this option to capture pages that only open on some mouse action (for example, opening a menu with the
mouse). If checked, capture starts automatically when you press down the Ctrl key.
Show Pages Already Declared

This option helps you keep track of the pages that have been captured and declared already.
Show Hidden Controls

This is useful if you need to capture controls that are not displayed on the page at first.
Show Page Tree

The page tree shows other potential pages detected around the selected page (the one shown in red). If
unchecked, the page tree contains only the element selected. This can be useful when tree exploration is
time-consuming.
Capture:
This option lets you select the method used to make a screen capture of the page.
The default capture mode is Print Window, which lets you capture a page that is not completely visible on
the screen. If this capture fails, the other capture mode is used automatically. Sometimes, the Print Window

capture succeeds, but the resulting capture is not the same as the original. In this case, you can force the use of
Screenshot mode by checking it.
 Note
If you use this mode, the page must be visible (not covered by other graphical elements) when the capture
is validated.
Parameters
Max Capture Height

This is used to limit the height of the screen captured. It is useful for capturing very large web pages. The entire
DOM is captured but the screen is only partially captured.
Limit Depth To
This option limits the depth of the DOM captured. It's useful for capturing very large Acrobat Reader
documents with UI Automation technology. Capturing a huge DOM can take a very long time, and you may
only need the first few levels. The result is a partial capture of the DOM.
Limit Siblings To
This is useful when capturing Acrobat Reader content with UIAutomation technology. In some cases, Acrobat
Reader returns an infinite number of children of an element. Setting a limit on the number of siblings resolves
this issue. The result is a partial capture.
Disable Autoscrolling (Web)

By default, a Web page is automatically scrolled at capture time, to take different screenshots in order to build a
full image. Sometimes, scrolling can be infinite (such as in Facebook). This problem can be avoided by disabling
autoscrolling. The entire DOM is captured but screen capture is only partial.
2.2.5.2 Capture a Subpage
Some technologies (including Windows) require the declaration of subpages.
This requirement is due to the tree structure of Windows applications and to the way the Windows connector
recognizes Windows pages:
If a Windows control to be recognized as a Page_1 by Desktop Studio has a parent control which is recognized
as a Page_2, Page_1 MUST be declared as a subpage of Page_2.
This subpage relationship ensures that only the controls required are recognized. However, if not declared
correctly, it can prevent required controls from being recognized correctly.
A subpage is declared in exactly the same way as a simple page declaration.
The only difference is that it MUST be declared with the corresponding parent page.
In the Explorer perspective, you can define this subpage relationship in the following ways:

• Define a Subpage Relationship Manually
To define a subpage relationship manually, select the parent page and click the Add a subpage context
menu. The newly captured page will be created as a subpage of this page.
• Detect a Subpage Relationship With Recognition
If you do not define the subpage relationship manually, Studio Explorer tries to detect it by recognizing
pages in the captured control parents. The nearest page recognized is used as the parent page.
 Note
The parent page can be only detected if it has been recognized in the Page view.
• Detecting a Subpage Relationship Without Recognition

Multiple pages can be captured without having to define their criteria immediately. During this operation,
Studio Explorer detects the subpage relationship by comparing the parent tree of each captured page and
inserting a new captured page as a subpage of the correct parent.
 Note
The parent tree of a page is the chain of window handles (HWND) of the newly captured control's
parent controls. As this chain is comprised of window handles, it is valid until one of the parent controls
is closed or until the application itself is closed. In order to use this detection method, it is advisable to
capture all the pages during the same application session.
• Creating a Subpage from a Page Component

A subpage can be created directly from the parent-page capture by right-clicking the item (1) and selecting
Create a new Page from the context menu (2). The new subpage is created using the same capture, with
the selected item as the root item.
Changing the Subpage Root Item
When a subpage is captured, the root item is set. Later on, another item can be set as the root item by
right-clicking the new root item and selecting Associate with the Selected Page from the context menu.

2.2.5.3 Capture an HLLAPI Page
It is not possible to capture an HLLAPI page by selecting the page on the screen. Instead, to select an HLLAPI
page, click the  Refresh icon.
The page tree shows all the HLLAPI sessions opened on the desktop (A, B, and so on).
After selecting the session to be captured, click the Scan and Capture button.
2.2.5.4 Multi-Capture Management
Make a New Capture
Captures can be added to an existing page. Having multiple captures can be useful when a page has different
states. Select the page from the Project tree, then select Make a new Capture of this Page…. The capture
process is the same as for a new page, except that a popup appears asking if you wish to replace the current
capture.
The various captures associated with a page are available in the capture selector. Here is an example of a page
with two captures:

This toolbar lets you:
• Select the current capture

• Make a new capture
• Lock the current capture
• Edit the current capture
• Delete the current capture
Select the Current Capture
The current capture can be selected manually by selecting the corresponding tab. To make this simpler, each
tab has a tooltip showing the capture comment and the date of capture.
Make a New Capture
You can make a new capture by clicking the  button. The capture workflow is the same as described earlier.
Lock the Current Capture
When you select an item in the Project tree, the current capture is automatically changed to the one in which
the item was selected (see Associate Items With Components in the Page Capture [page 262]). In order to
prevent this, the current capture can be locked by clicking the  button. This way, the current capture remains
the same no matter which item is selected. To unlock the current capture, click the  button again.
Edit the Current Capture
By clicking the  button, you can change the data associated with the capture.
The following dialog appears:
Here, you can:
• Change the capture comment

• Indicate whether the capture should be visible in the Application view (by default, only the first one is
visible)
Delete the Current Capture
Delete the current capture by clicking the  button.

2.2.6 Page Definition
After a page is captured, or at any time afterward, the various elements of a page definition can be modified.
These are:
• The page parameters

• The criteria used in page recognition
• The technical events notified by the page
Regardless of the page technology, this panel contains the same subparts:
Set Page Parameters
The Parameters tool window lets you set the page parameters:
General category
Name Name of the entity used in scripts to control the page
Technical If set, the page is declared for technical use only
Connector category Parameters specific to the connector used to manage the

page
Technical category

only)
Launch path Path used to launch the target screen
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.
Select Page Tracked Events
The TrackEvents tool window lets you set the technical events controlled on the page. The list of available
technical events depends on the page technology. A description of each event is available in the Help panel.
For more information on the TrackEvents tool window, see Tool Windows in the Explorer Perspective [page 10]
Select Page Criteria
The Captured Data tool window shows the properties of the page that can be used as criteria. These properties
are collected when the page is captured. If the page was been captured by Desktop Studio, this tool window is
empty.

The properties captured depend on the page technology and connectors: Only properties used by the
connector are captured.
• For a Web page, these properties are associated with the captured frame
• For a window page, these properties are associated with the root item set at the beginning of the capture
The Criteria tool window lets you edit the page criteria that the connector uses to recognize a page at runtime.
When a page is selected in the Project tree, Desktop Studio tries to recognize it automatically in the current
capture. In the same way, when changing the current capture, Explorer tries to recognize the current page on
this capture. The page is highlighted in green if it is recognized, in red if not, and in black if no recognition has
been attempted.
2.2.7 Declaration of Page Items
Once a page has been declared, you can add items to the configuration. When you declare an item, you:
• Associate it with a component in the page capture (selection).

• Set the item parameters.
• Define the criteria that enable the software to recognize this item on the page.
Items are declared offline from the page captures. Even the validity of criteria can be tested offline. A final
validation must be performed online on the running application.
Associate Items With Components in the Page Capture
To work on a page capture, select a page in the Project tree.
The page capture is then displayed.
Associate a Component With a New Item
To associate a component with a new item, right-click the component in the Screen display and select
Associate to a New Item from the context menu or double-click the component. You can also do this in the
Tree display, Subtree tool window, and Text tool window.
The item is then added to the page items in the Project tree and an internal link is established between this item
and the component selected in the screen capture. The new item is created with default parameters.
Smart declaration automatically generates the right criteria to uniquely identify the component in the UI (user
interface). Smart declaration works in most scenarios except when the recognition requires complex patterns.
In this case, it is up to you to set the right criteria.
If the action is performed from the Text tool window, a criterion is added to the Text property. These
parameters and criteria can be edited in the Item properties panel.

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).
To associate the existing item, select it in the Project tree, right-click the component in the Screen display, and
click Associate to the selected Item.
You can also do this in the Tree display, Subtree tool window, and 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 created automatically. Otherwise,
the associated item is automatically selected.
The criterion is set for this property, with its complete value and the default scan value for this property.
Item Definition
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
The Parameters tool window lets you set the item parameters:
General Category
Name Name of the entity used in scripts to control the item
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.
Connector Category
Parameters specific to each technology
Technical Category

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).
Set Item Tracked Events
The Track Events tool window lets you set the technical events for 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 involves setting criteria for the properties of the component to be
recognized
• The components pattern method, which involves setting criteria for a pattern of one or more components
to be recognized, where one of these components is the component to be targeted
The single component method can be used with any technology available with Desktop Studio. The
components pattern method is used with Web and UI Automation technologies only.
The Single Component Method

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
Desktop Studio.
The properties captured depend on the page technology and connectors: Only the properties used by the
connector are captured.
The Criteria tool window lets you edit the criteria for the item that will be used by the connector to recognize it
at runtime.
Components Pattern Method

The components pattern method involves 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 component and is addressed in the project. This method is useful when the target
component has no (or insufficient) unique, distinguishing properties. It also lets you define a components
pattern with just one component, which is equivalent to the single component method.
Example:
Suppose a Web page has several TABLE components. We want to target the TABLE component that has the
column header Company.
We can define the following components pattern:
• One component (the target component) that recognizes the TABLE component (1)
• A 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 (which means targeted by) the item, letting you add components to the
pattern to be recognized:

• 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 from the context menu. The component is then added to the Criteria
tool window (2).
• To remove a component from the pattern, right-click the component in the Criteria tool window (2) and
select Remove Component from the context menu.
Properties of the Components Pattern
Components 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-child
relationship. It is not possible to add a sibling component. The depth of the relationship between recognized
components can be set with the Children checkbox. If it is checked, the component recognized must be a direct
child of the component recognized as the parent in the pattern.
In the example above, if the TH component has the Children checkbox checked, the TABLE component target
will not be recognized because the recognized TH component is not a direct child of the recognized TABLE
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

• 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.
Declaration of Items on an HLLAPI Page
In HLLAPI, an item is defined by:
• Its X and Y coordinates

• Its CX width
• Optionally, if it is a MustExist label, its TEXT.
Declaration of items with HLLAPI is a little different from declaration with other technologies. An HLLAPI page
capture doesn’t contain components, but only the text of the screen. This 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, and TEXT values of the
selection.
• Associate with the selected item: Update the selected item with the X, Y, CX value of the selection.

Item Recognition
A soon as an item has at least one criterion, Desktop Studio attempts to recognize it. When an item is selected
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 the associated one. As the two rectangles match, only one green rectangle
is visible:
• A red rectangle if it does not match. As the two components do not match, two rectangles, one blue AND
one red, are visible:
Using the Recognition Tool Window
The Recognition tool window helps you to investigate cases where no components are recognized or where the
recognized component is not visible.
For a more detailed description of item recognition, see About the Recognition Mechanism [page 276].
Choose the Current Capture for Recognition
When several captures have been created for a page, you can manually choose which capture is used for
recognition by selecting the corresponding tab (1, 2, 3, and so on) from the capture selector.
When you select an item in the Project tree, the current capture is automatically set to the one where the item
was associated with a UI component..
This behavior can be disabled by locking the current capture using the  button in the Capture toolbar.
2.2.8 Criteria Management
Criteria are rules set by the user and used by the Desktop Studio connectors to recognize defined elements
(applications, pages or items) in the running entities (Web pages, Windows items, and so on).
A connector recognizes a running entity as an element if the entity properties match the element criteria.
A criterion applies to one property of the entity. It comprises:
• The name of the property

• The value that the entity property with this name must match
• The operator used by the Desktop connector to test this match

Connector-Specific Features
Available Properties
The available property names depend on:
• The technology of the entity (in other words, the URL property is available in a Web page but not a Windows
page),
• The connector (in other words, the Window connector only tests the EXE property of a Windows
application).
When Desktop Studio captures a running entity, it captures only the properties available for use in criteria.
Available Operators
Text Properties
Any The property can have any value
Empty The property value must be empty
Full The property value must be equal to the criterion value
Part The property value must contain the criterion value
Starts The property value must start with the criterion value
Ends The property value must end with the criterion value
Like The property value must match the criterion value consid
ered as a regex
Numeric Properties
= The property must be equal to the criterion value
< The property must be less than the criterion value
> The property must be greater than the criterion value
⇐ The property must be less than or equal to the criterion

value
>= The property must be greater than or equal to the criterion

value
Desktop Studio displays only the available operators, depending on:
• The type of the property (for example text, numeric, Boolean, or enumerated)
• The connector (in other words, the Web connector manages the ‘starts-with’ operator for text properties
but the Windows connector does not)

Available Combinations of Criteria: AND / OR
The general rule is that all of the element’s criteria must be satisfied before an entity is recognized (AND).
However, some connectors accept two (or more) criteria for the same property. In these cases, only one of
these criteria must match (OR).
When the OR combination is available for a property, the Criteria Editor shows the plus icon (+). This button
adds a criterion to the edited property, even if a criterion already exists for this property.
The Criteria Editor
The Criteria Editor is available in the Criteria tool window (see Tool Windows in the Explorer Perspective [page
10]).
The Criteria Editor can manage four types of properties:
• Text properties:
• Numeric properties:
• Boolean properties:
• Enumerated properties:
Adding a Criterion
The procedure for adding a criterion is the same for all element types (applications, pages, and items):
• Select the captured property in the Captured Data tool window (see Tool Windows in the Explorer
Perspective [page 10]). The Criteria tool window is updated as follows:

• Edit (optional) the criterion value and the operator in the Criteria Editor
• Click the Refresh button to validate the criterion.
A captured property can be quickly added as a criterion by double-clicking it in the Captured Data tool window.
Updating a Criterion
To update a criterion:
• Select it from the Criteria list

• Update the criterion value or the operator in the Criteria Editor
• Click the button to validate your change.
Deleting a Criterion
To delete a criterion:
• Right-click it in the Criteria list

• Select Remove criterion from the context menu, or click the minus (-) button.
Build Criterion Doc
The criteria technical document can be automatically generated using the Build criterion doc menu item in the
File menu. This generates an additional HTML document for each PSC file. It is named PSCName.html:

The document is generated with the docGeneration_V1.xsl file located in the following (default) location:
C:\Program files\SAP Intelligent RPA\Studio\configuration\xsd. The file used for this purpose
can be modified by changing the XSLDocTechFile entry in the StudioExplorer.xml file.
2.2.9 Controlling Pages with Event-Driven UI Updates
What Are Event-Driven UI Updates?
A page implements event-driven UI updates when it fills fields, starts a calculation, or controls changes to the
state of the page.
Here are some examples of event-driven UI updates:
• Page1 processes the zipcode field value to get the corresponding city name and then fills the cityname field
• Page1 checks the value of the contractId field before allowing the other fields to be filled
When you control such pages, you must take into account the implemented event-driven UI updates to avoid
conflicts with them.
What Event-Driven UI Updates Are Implemented in the Page?
Some of these processes are visible and easy to detect:
• Page1 processes the zipcode field value to get corresponding city name and fill the cityname field
• Remaining fields are disabled or hidden until contractId field has been controlled
• …
Some processes are more difficult to detect, such as when the other fields are reset after the contractId field is
verified:
To detect processes of this type, you need to carefully examine how the page changes when a user interacts
with it. For example:
• Do some field values change when I fill a particular field?

• Can I fill a particular field before the contractId field is filled?
How Is an Event-Driven UI Update Started?
When you fill a field and start an event-driven UI update, the page is put into an unstable state until the process
has been completed. It is important to understand how the process starts so that you can control the actions
that are required to trigger it.

Event-driven UI updates generally start in response to user actions. For example, when:
• An input field loses focus

• The value of an input field changes
• An input field receives keystrokes
• A combo box selection changes
• The state of a checkbox or radio button changes
To detect the starting event, you must carefully examine how the page changes when a user interacts with it.
For example,
• Does the process start when I hit a key in the input field?
• Does the process start when I navigate to the next field?
On Web pages, you can also examine the page source to see which events are triggered on an item.
 Note
Only the HTML source is captured in Desktop Studio; included files such as CSS or JavaScript files are not
captured.
A full investigation may require you to have the application running. External tools can be useful for analyzing
an event-driven UI update, such as:
• Internet Explorer developer tools (accessed with F12 )

• Visual Events
For fieldrelated event-driven UI updates, if the basic control action doesn’t automatically trigger the event-
driven UI update, it is necessary to trigger it manually by appending additional control actions.
Once you have determined the starting event, there are different ways to trigger it. Below are some use cases
encountered in real projects, along with the methods used to handle them.
This is not an exhaustive list. Please don’t hesitate to send us other use cases you have encountered or other
methods you have implemented in your projects. We will add them to the list.
Use Case: Process Starts When an Input Field Loses Focus

• You can set the focus on the field and then on another field by using the setFocus method.
• You can set the focus on the field and then tabulate to the next field by using the keyStroke method:
 Sample Code
myItem.keyStroke('_TAB_') ; // or '{TAB}' with UI Automation
• On a Web page, you can fire the blur event using the scriptItem method:
 Sample Code
myItem.scriptItem("fireevent('blur')") ;

Use Case: Process Starts When an Input Field Value Changes
• On a Web page, you can fire the onchange event using the scriptItem method :
 Sample Code
myItem.scriptItem("fireevent('onchange')") ;
• On a Web page, you can call the onchange method using the scriptItem method:
 Sample Code
myItem.scriptItem("onchange()") ;
• You can set the field value using the keystroke method:
 Sample Code
myItem.keyStroke('value to set') ;
Use Case: Process Starts When an Input Field Receives Keystrokes
You can set the field value using the keyStroke method:
 Sample Code
myItem.keyStroke('value to set') ;
What Do Event-Driven UI Updates Do?
Generally, event-driven UI updates:
• Collect data from the page

• Perform a calculation or check something
• Cause a modification to the page content (such as a field value, visibility, or authorization)
It is important to know what an event-driven UI update does so that you can detect when the process has
ended.
It can also help you solve some problems during process execution:
Use Case : Process Starts Correctly but Aborts
The following problem was encountered in controlling a Web application: Although the input values are set
correctly, and the event-driven UI update starts correctly, the process aborts.
Taking a look at the JavaScript code for the process (using the Source display in the Explorer perspective's
Page view) gives you the solution. The changed attribute of the input fields must be set to 'true' to enable the
process to consider it.

Adding the following code just after setting each input field value solves the problem:
 Sample Code
myItem.scriptItem("changed=true;") ;
When Does the Event-Driven UI Update End?
Even if the event-driven UI update seems to be very quick, it does take a certain amount of time. These
processing delays must be managed in developments within SAP Intelligent Robotic Process Automation:
Controlling in SAP Intelligent Robotic Process Automation is much faster than user actions
• Processing delays may differ according to the responsiveness of the application
You must therefore ensure that the event-driven UI update has ended before you continue controlling.
The way you wait for process termination depends on the result of the process (see above):
• Wait for the CHANGE technical event on the result field

• Wait for the SETFOCUS technical event on the next field
• Wait by polling the value of the result field
These methods are described in Control Sequences [page 343].
2.3 Advanced Declaration
Capturing and declaring applications goes hand in hand with the recognition mechanism. To help ensure that
your applications are properly captured and recognized, we provide some guidelines here.
These guidelines also explain how to use methods to handle advanced use cases. Methods include MustExist,
MustNotExist, and Ancestor.
2.3.1 About the Recognition Mechanism
Principles
Desktop Studio includes an internal recognition mechanism. The goal is to allow offline validation for the
recognition criteria that are defined when pages and items were declared. The recognition mechanism
implements the same recognition rules as those implemented by each connector. You can check the page
recognition and item recognition for each page capture.

Page Recognition
Background
When you select a page in the project tree, Desktop Studio tries to automatically recognize it on the current
capture. In the same way, when you change the current capture, Desktop Studio tries to recognize the selected
page on this new capture. The page is highlighted:
• In green if it has been recognized

• In red if it is unrecognized
• In black if recognition has not been attempted
Page recognition means:
• Testing whether the declared pages can be recognized

• Testing whether the page’s selected root item (if any) matches its recognized root item
Page recognition can fail for the following reasons:
• The page doesn’t have declared recognition criteria

• A preceding declared page matches the capture
• The capture doesn’t match the page’s criteria
• A MustExist item is not recognized in the capture (or a MustNotExist item is recognized)

The Recognition tool window (see Tool Windows in the Explorer Perspective [page 10]) can be used to help
investigate recognition results. The Page tab displays the application’s page structure.
Each element is displayed in one of the following ways:
Recognized Application
Unrecognized Application
Recognized Page
Unrecognized Page
Untested Page
The number of tests displayed beside each page name is the recognition cost (in number of tests).
Example 1

In this example, the recognition process, applied to a pTabPage1 page capture, yields the following results:
• The ApplicationCRMWin application (1) is recognized (highlighed in green)

• The pTabControl1 page (2) is recognized (highlighed in green)
• The pTabPage1 page (3) has not been recognized (highlighed in red)
• The pTabPage2 page (4) has been tested but is not recognized (grayed with more than 0 tests).
In this case, the pTabPage1 page is highlighted in red, because recognition is performed on one of its captures
and the page has not been recognized. The pTabPage2 page is only grayed, because, even if it has not been
recognized, recognition is not performed on one of its captures.
Example 2
In this example, the recognition process, applied to a pMonAffichage page capture, gives the following results:
• The Mantis application (1) is recognized (highlighed in green),

• The pLogin page (2) has been tested but is not recognized (grayed with more than 0 tests),
• The pMonAffichage page (3) is recognized (highlighed in green),
• The following pages (4) have not been tested (grayed with 0 tests) These pages have not been tested, since
the preceding pMonAffichage page is not recognized.

Note the recognition cost (in test number) displayed near each page name:
• The pLogin page (2) recognition cost is 1,

• The pMonAffichage page (3) recognition cost is 112 (due to MustExist Objects),
• The recognition cost of the following pages (4) is 0 (no recognition has been attempted).
The cost is especially important when using the UI Automation connector. In this case, the connector can be
very slow, especially when the recognition cost is very high.
Using the Tree Display
When investigating the declaration of subpages, it can be useful to use the Tree display (see Page View Panels
[page 16]).
This view displays all the recognized pages.
As a subpage can only be recognized in its parent-page subtree, using the Tree display can be helpful when
trying to determine why a subpage is not recognized.
Item Recognition
Introduction
When you select an item in the project tree, Desktop Studio tries to automatically recognize it on its selected
capture. For an item, the selected capture is the page capture in which it has been associated with a UI
component and declared (if any). For more details, see Associate Items With Components in the Page Capture
[page 262].

Note that if a page is selected in the Project tree, recognition is performed on all the page’s items.
Similarly, when you change the current capture, Desktop Studio tries to recognize the selected item on this
capture.
The item node is highlighted:
• In green if it has been recognized

• In red if it is unrecognized
• In black if no recognition has been attempted
Item test recognition means:
• Testing whether the declared item is recognized (at least one captured component matches the item
recognition criteria)
• Testing whether the component associated with the item (if any) matches the recognized component.
The reasons an item could not be recognized in a capture are:
• The item doesn’t have declared recognition criteria

• No component in the capture matches the item’s criteria
Choose the Current Capture for Recognition

When several captures have been created for a page, it is possible to manually select the capture used for
recognition by selecting its tab (1, 2, 3, and so on) in the Capture Selector (see The Explorer Perspective [page
9]).
But when an item is selected in the Project tree, the current capture is automatically set to the one associated
with the item .
It is possible to disable this behavior by locking the current capture using the  button.
Using the Screen Display

The main tool used for investigating recognition results is the Screen display.
When an item is selected in the project tree, its target component (if any) is bordered with a blue rectangle. Its
recognized component(s), if any, are bordered with:
• A green rectangle if it matches the target component, As the two rectangles match, a green rectangle is
displayed:
• A red rectangle otherwise. As the two components don’t match, two rectangles, one blue AND one red, are
displayed:

The Recognition Tool Window (see The Recognition Tool Window [page 14] )can be used to further investigate
recognition results.
The item tab displays the selected item recognition result.
Each element is displayed in one of the following way:
Recognition succeeded
Target component matches recognized component
Recognized component with no target component
Associated component with multiple recognized compo

nent. One recognized component matches the associated
component
Recognition failed
Associated component doesn’t match recognized compo

nent
Associated component with no recognized component
No associated component with no recognized component
Associated component with multiple recognized compo

nents. No recognized component matches the associated
component
Note the recognition cost (in test number) displayed near each item name (for example, btAccueil [49 tests]).
This cost is especially important when using the UI Automation connector. In this case, the connector can be
very slow, especially when the recognition cost is very high.
Note also the index value shown next to each recognized multiple component (for example: [2] or [1][1]).
This index value indicates the index value that must be used to control each item instance (for example:
oLigneAssigneToMe[2]).

Using the Tree Display
It can be useful to use the Tree display to view the recognition results. This display shows all of the recognized
items within the technical DOM tree of the capture.
2.3.2 Making Robust Capture and Declaration
Declaration Principles
During the solution design phase, you defined the various application, page and item entities required by your
project.
In the declaration phase, you declare the entities in the SAP Intelligent RPA project.
Once you have created your project (see Create a Project [page 63]) you need to create the functional entities:
• Declare application entities

• For each application, declare page (and subpage) entities
• For each page, declare item entities.
Set Entity Recognition Criteria

Once you have created an entity, your main task is to set its recognition criteria.
Desktop Studio and Desktop Agent use recognition criteria to link the entity with the targeted component of
the real-world application to be controlled.

Recognition criteria are constraints defined on the properties of the targeted element. You set recognition
criteria in Desktop Studio (see Criteria Management [page 269]).
The way criteria are defined can depend on the technology of the targeted application. Generally, you can:
• Select the constraint operator (such as equals, contains, starts, ends, or like)
• Set several criteria on different properties combined by a logical AND
• Set several criteria on the same property combined by a logical OR
The real challenge in this step is to set criteria that are:
• Precise enough to target only the desired component of the controlled application
• Robust enough to still work even if the controlled application changes.
 Note
During the process of setting recognition criteria, Desktop Studio performs recognition on the various
captures. This way, you can easily validate declarations offline (see About the Recognition Mechanism
[page 276])
Once you have declared entities, we recommend performing test recognition online using the debugger.
For a list of common recognition errors, and how to resolve them, see Recognition Error Cases [page 470].
Track Required Technical Events

Depending on the requirements identified in the solution design phase (see Control Sequences [page 343]), it
may be necessary to track technical events.
 Note
Application events (START, END) and pages event (LOAD, UNLOAD) trigger notifications automatically and
don’t need to be tracked. Item events (such as CLICK, SETFOCUS) must be explicitly tracked in order to
trigger notifications.
Set Entity Parameters

Usually, there is no need to set entity parameters, except in the following cases:
• To set an item as MustExist or MustNotExist

• To use advanced recognition methods (Ancestor, Labelled by)
• To declare multiple items
2.3.3 Advanced Recognition Capabilities
If the screen that is to be controlled does not have unique, distinguishing properties, you can use an advanced
declaration or recognition method. The available methods depend on the technology.
MustExist Method [page 284]
MustNotExist Method [page 284]
Root Item Method [page 284]

Ancestor Method [page 285]
Labelled By Method [page 285]
Items Pattern Method [page 286]
Order of Declared Pages [page 286]
2.3.3.1 MustExist Method
The MustExist method is available in all technologies. It consists in detecting one or more components that
are present in the screen to be controlled but not in any other. These components are declared as items on the
page and their MustExist parameter is set.
Using this method, a screen is recognized as a page if:
• The screen matches the page criteria

• All MustExist items are found on the screen
2.3.3.2 MustNotExist Method
The MustNotExist method is only available for the WEB and UI Automation technologies. It consist in
detecting one or more components that are not present in the screen to be controlled but are present in others:
These components are declared as items on the page and their MustNotExist parameter is set.
Using this method, a screen is not recognized as a page if one of its MustNotExist items is found on the
screen.
To declare a MustNotExist item on a page:
• Add to the page a capture containing the component to be declared

• Declare the item from this capture and set its MustNotExist parameter
2.3.3.3 Root Item Method
The Root Item method is available for UI Automation and the SAPGUI connector. It is used to declare
subpages as follows:
• In the parent page, declare an item that targets the desired root component
• Set this item as root item in the subpage parameters
This method allows you to use advanced item declaration methods to target the root component.

2.3.3.4 Ancestor Method
The Ancestor method searches upwards in the hierarchy to find an ancestor component with a set of properties
that make it unique. This ancestor component can't be part of an ascending hierarchy that is incorrectly
recognized.
• Declare an item that targets this ancestor component

• Set this item as an ancestor of your item when you set item parameters (see Item Definition [page 263])
The target component will be searched in the descendance of the ancestor component.
Consider this use case:
In the following DOM, you want to target second leafnode (in orange):
The two leafnodes are the same, so, if you don’t use the Ancestor method, the first leafnode will always be
recognized, not the second. You cannot use node (id=1) as ancestor, because it is ancestor of both of the
leafnodes and the first leafnode will be recognized. So I must use subnode (id=3) as ancestor so that the
second leafnode is recognized.
2.3.3.5 Labelled By Method
The Labelled by method consists in finding another component:
• That is at a fixed distance (CX,CY) from the targeted component

• That has unique, distinguishing properties
This component is typically a label component located near the target component. But it can be any other
component, anywhere on the screen.
• Declare an item that targets this label component

• Set this item as Labelled by when you set item parameters (see Item Definition [page 263]).
Desktop Studio stores as a criterion the distance between the targeted component and the label component.
This distance is calculated in a unit independent of the screen resolution.
The target component will be searched for between the components located at this stored distance from the
label component.

2.3.3.6 Items Pattern Method
The Items Pattern method consists in recognizing a set (pattern) of related components, rather than a
single component.
These components must be linked together by a parent-child relationship. One of these components is the
target and will be addressed in the SAP Intelligent RPA project.
This method is useful when the target component has no (or insufficient) unique, distinguishing properties. For
more information, see Declaration of Page Items [page 262].
2.3.3.7 Order of Declared Pages
The order in which pages are declared is significant.
When the connector detects the opening of a screen, it searches for the first declared page whose criteria
match.
If you need to declare a generic page with broad criteria, you must declare it after declaring the rest of the
pages. This ensures that screens are correctly recognized as generic pages.

3 Designing Scenarios
Scenarios are used for process automation. Often, you will need to split process automation into small pieces:
the steps. You can decide to bootstrap your project with Workflow Designer.
Workflow Designer lets you use previously declared application pages and activities. You use dedicated
activities – such as set or get – within an application page added to the Workflow Canvas. By linking the
pages together, you create a set of steps which will generate a scenario script.
Scenario scripts can be also created from scratch in the Editor perspective. In this case, you use the Desktop
SDK.
3.1 Bootstrap your Project with Workflow Designer
A workflow refers to an automation sequence. It can describe the control of a single application or the
coordination of several apps.
Functional Description
When you design a workflow, you describe the implementation of the automation sequence in functional terms:
• The sequence of the screens and the actions to perform on each screen
• The data to collect and return
• The other actions to implement (manage files, data...)
The goal of a workflow is to describe the functional requirements (Scope Of Work), not the technical
implementation.
For this purpose, the Desktop Workflow designer provides:
• The applications, pages and items declared in the Explorer perspective

• A context structure for storing data - see Managing Data [page 347]
• A set of functional activities (Get, Set, Click, and so on)
• A generic comment activity for describing functional requirements
 Note
The screens and items that can be used in a workflow must be declared beforehand in the Explorer
Perspective.

Designing Scenarios PUBLIC 287
JavaScript Code Generation
You can generate the JavaScript code from a workflow at any time.
This generated code contains:
• The scenario declaration

• The steps implementation
• Some code for each included activity
• A comment associated with each comment activity, which helps the script developer
Script Development
The generated scripts should be reviewed by a script developer:
• To implement the requirements not generated (described in the comment activities)

• To modify the generated code, if required
Script development (coding, debugging) is still performed in the script editor.
Iteration
Functional requirements often change over time.
You can change a workflow and regenerate the code, even it has been manually changed by the script
developer. This requires you to set an external code merger tool.
Related Information
Workflows [page 290]

The Workflow Perspective [page 22]
3.1.1 Main Steps in Creating a Workflow
The main steps needed to create a workflow are as follows:
1. Create a new workflow in the Workflow Perspective

2. Design the workflow in a FlowChart:
• Drag & drop pages
• Drag & drop activities and edit their parameters

288 PUBLIC Designing Scenarios
• Use comment activity to describe functionalities which will be manually implemented in JavaScript (for
example, string manipulation)
• Link these blocks together to describe the process
3. Set activities on a page:
• Double-click a page block to edit its activities
• Add activities on items
• Change activity parameters
• Manage the context - see Managing Data [page 347].
4. Build the workflow:
• Check the validity of the workflow
• Manage errors
• Generate code
3.1.2 Setting Timeout Values
Prerequisites
You have created a workflow in Desktop Studio.
Context
The values for the Timeout and the steps are set by default in the workflow.
You can change these values and later manage your Timeouts in your workflow.
Procedure
1. In the Workflow Perspective, go to the pane at the top-right of the screen. There are 3 options : Context,
Events, Properties.
2. Click Properties.
3. Go to section 2-Activity.
4. You can make two modifications:
• Change the default Timeout Value in Scenario Timeout.

• Change the default Timeout value for the step in Step Timeout.

Related Information
Managing Timeouts in Scenarios [page 361]
3.1.3 Workflows and Functional Events
Workflows
A workflow is functionally tied to an automation sequence. From an implementation perspective, it is tied to a

scenario.
A workflow can contain two types of design:
• The flowchart is used to describe the sequence of pages in an automation sequence.

• The Activities page is used to describe the sequence of automation actions to be performed on a page.

Each of these designs may contain activities that are tied to actions to be performed (Set or Get on an Item,
Wait for an Event, and so on).
• Each activity has parameters that can be edited in the Parameters tool window.
• The list of available activities is presented in the Activities tool window, from which activities can be
dragged & dropped into the current design.
The data collected during the automation sequence can be stored in a context.
• This structure is composed of folders and items.

• The context can be edited in the Context tool window
Functional Events
Unlike technical events, functional events are created by a developer. A functional event has a name and is able
to transport data such as a string or a JavaScript object.
The functional event mechanism requires a receiver and a sender. The receiver is the entity that receives the
event, and can be any entity (including process entities). The sender is the entity that sends the event to the
receiver.
 Note
Any entity can be the sender, even the receiver itself. In this case, the entity sends the event to itself.
The functional event belongs to the receiver. Each functional event can have only one receiver. The event is
always delivered asynchronously, and it can be delivered with a delay (in ms).

3.1.4 Activities and Where to Use Them
3.1.4.1 Application Activities
Activity Description Technology Required Properties
Start Starts an application. Application - The name of applica

tion to start.
Filename - The full path where the

executable file of the application to
be opened can be found. Optional.
Arguments - The parameters that

can be passed to the application at
startup. Optional.
Wait starting - If true (in other

words, if the option is ticked), wait
until the application is started.
Close Closes a running application Application - The name of the ap

plication to close.
Wait closing - If true (in other

words, if the option is ticked), wait
until this application is terminated.
Connect Connects a session to HLLAPI Application - The name of applica

HLLAPI application. tion to connect at HLLAPI session
Session - The session identifier to

use for connection. This must have
been declared previously in HLLAPI
emulator.
Disconnect Disconnects a HLLAPI appli HLLAPI Application - The name of the ap
cation. plication to disconnect.
Highlight Highlights all detected items Win, Web, JavaSwing, UI au Application - The name of applica
in active pages of an applica tomation, OCR. tion to use for this action.
tion.
Duration - The highlight duration of
detected items in milliseconds. If 0
(zero), items remain highlighted.

3.1.4.2 Credentials
 Note
You can manage credentials locally (Windows Registry or Credential Manager) or on the server (Cloud
Factory).
You can write, read and save your credentials locally. For security reasons, you can only read credentials on
the server as the values can be shared between multiple bots. This means that if you try to set a credential
variable on the server, you get a "not implemented" error message because this function is not supported.
Activity Description Properties
Declare Declares a credential Credential name
Comment
Storage: local (false) or server (true)
Get Retrieves credential login and pass Credential name

word
Set Sets credential login and password Credential name
3.1.4.3 Event Activities
Notify Sends a functional event to itself or Event - enter a new event name or select an
another application or page. existing one from the list.
Sender - name of application or process which

sends the functional event.
Data sent with the event - this is an 'expression'.

Use:
• $data$ to send data from the context

• '…' to send a constant value (example:
'OK'),
• … to send a user variable (example: my
Data).
Wait for Sets an event handler to wait for a Event - name of the functional event to wait
functional event. for.

3.1.4.4 Excel Lib Activities
End Excel Closes the program.
Initialize Excel Initializes the Excel library in differ New instance - if true, the software initial
ent modes. izes Excel with a new instance.
Visible - if true, the software initializes Excel

in visible mode.
Display alerts - is true, the software initi

alizes Excel in Display Alerts mode.
Release Excel
Data
Get one value Gets one value from a cell. Row - the row number.
Column - the column number.
Variable - name of the context variable to

store the value in.
Set one value Sets one value in a cell. Row - the row number.
Column - the column number.
Value - the value to set.

Get values Gets values from a range of cells in Start column - the starting column, such as
the active worksheet. A (the limit is “XFD” or 16384).
Start row - the starting row, such as 2.
Last column - the final column in the range,

example: G
Last row- the final row in the range, exam

ple:. 10.
Default value - the default value to put in

undefined cells (this is "undefined" by default).
Variable- name of the context variable to

store the formulas in.
Set values Sets values in a range. Start column - the starting column, such
as A.
Data - the data to set in the cells.
Use keys as headers - if true, add the

keys as table headers
headers.
File
Close Excel file
Create new Excel file
Open Existing Excel file Excel filename - the full path and name of
the Excel file.
Save Excel file
Save as Excel Excel filename - the full path and name of

the Excel file.

Formatting
Format background color Changes the background color of a Range definition - string that represents
range of cells. the range, such as “A;5;G;67” or “1;5;7;67” or
“A5:G67” for a range, or A; 8 or 1;8 or A8 for a
single cell.
Font color - color to apply as an array RGB.

The collection e.color.rgb can be used to select
predefined colors.
Format bold Formats the text of a range of cells Range definition - string that represents
as bold, or removes bold format. the range, such as “A;5;G;67” or “1;5;7;67” or
“A5:G67” for a range, or A;8 or 1;8 or A8 for a
single cell.
Activate bold - true to activate bold. false

to remove it.
Format font color Changes the font color of a range of Range definition - string that represents
cells. the range, such as “A;5;G;67” or “1;5;7;67” or
single cell.
Font color- color to apply as an array RGB.

The collection e.color.rgb can be used to select
predefined colors.
Format font size Changes the font size of a range of Range definition - string that represents
cells. the range, such as “A;5;G;67” or “1;5;7;67” or
single cell.
Font Size - the font size to apply. This must

be a positive integer.
Format italic Formats the text of a range of cells Range definition - string that represents
as italic, or removes italic format. the range, such as “A;5;G;67” or “1;5;7;67” or
single cell.
Activate italic - true to activate italic.

false to remove it.

Formulas
Get formulas Gets formulas from a range of cells. Start column - the starting column, such as
A (the limit is “XFD” or 16384).
Last column - the final column in the range,

example: G
Last row - the final row in the range, exam

ple: 10.
Default value or formula for

undefined cells - this is "undefined" by
default.
Variable- name of the context variable to

store the formulas in.
Workbook
Use a specific workbook (already Excel workbook

opened)
Worksheet
Activate worksheet Activates an Excel worksheet from Excel worksheet - the name of the work
the active workbook. sheet.
Add new worksheet Adds a new Excel worksheet to the Excel worksheet - the name of the work
active workbook. sheet.

3.1.4.5 Factory API Activities
Add job Adds a job to the Factory server. Application - the name of applica
tion that contains the scenario to add to
the job manager.
Scenario - the name of the scenario.
Job data - data to use for scenario

execution and that will be associated
with the job.
Priority - the priority of the job.
Notification - send a notification

when the job is executed.
Add job List Adds a job list to the Factory server. Application - the name of applica
tion that contains the scenario to add to
the job manager.
Scenario - the name of the scenario.
Job list - the job list to be added.
Priority - the priority of the jobs.
Get job Gets a job from the job manager. Criteria - the criteria used to search
for jobs.
Get job list Gets a job list from the Factory server. Job data source
Max job count
Get/run job Gets, runs, and updates a job in the job Criteria - the criteria used to search
manager. for jobs.
3.1.4.6 File and Folder Activities
 Note
To use theses activities, the FSO library must be included in the project.

Advanced FSO Indicates briefly and clearly in this acti Available functions - All availa
vity's title field the aim of this advanced ble functions for manipulating files and
manipulation required in file system. folders with FSO library.
Describes in detail in this activity's de

scription field the advanced manipula
tion of files and folders that required
custom code based on FSO library.
No running code is generated by this

activity. Only an empty code block is
inserted to be filled by the developer
later (to realize effectively the required
actions in the file system at this step).
Additional and more advanced func

tions for manipulating files and folders
are available in the FSO library.
Download file Downloads a file from a web or network Source URL- the URL of the source
URL. file to download.
local path - the local destination

file name.
Delete file Permanently erases a file File - full path name to the file to
be deleted. Use double backslashes
(\\), for example: C:\\myFolder\
\SubFolder\\myFile.ext
Read CSV Reads all entries from a specified CSV Source file - the name of the
(comma-separated values) file. source file to read with its absolute
path.
Encoding - the encoding of the

source file: UTF-8, UTF-16, ASCII, Bi
nary.
Separator - Specifies the character

used as field separator in the source
file: '\t', ',', ';', and so on
Target data- the name of the varia

ble in which to store the reading result.

Read JSON Reads the content of a JSON (Java Source file - the name of the
Script Object Notation) file. source file to read, along with its abso
lute path.

nary.

Read text Reads the content of a text file. Source file- the name of the
source file to read, along with its abso
lute path.

nary.

Read XML Reads the content of a XML (eXtensible Source file- the name of the
Markup Language) file. source file to read, along with its abso
lute path.

nary.

Write CSV Writes a CSV (comma-separated val Source file- the name of the
ues) file. source file to read, along with its abso
lute path.
Target file- the name of the target

file to store data, along with its absolute
path and its extension.
Separator - Specifies the character

to use as field separator in the target
file: '\t', ',', ';', …

nary.

Write JSON Writes a JSON (JavaScript Object Nota Source data- the name of the var
tion) file. iable which contains data to store in
JSON (JavaScript Object Notation) file.

file to store data with its absolute path
and its extension.
Encoding - the encoding of the target

file: UTF-8, UTF-16, ASCII, Binary.
Write text Writes a text file. Source data- the name of the varia
ble which contains data to store in the
text file.

and its extension.
Encoding - the encoding of the target

file: UTF-8, UTF-16, ASCII, Binary.
Write XML Writes an XML (eXtensible Markup Lan Source data- the name of the varia
guage) file. ble containing data to store in the XML
(eXtensible Markup Language)
Tab separator- Specifies the char

acter to use as tabulation separator: '',
'\t', ' ', …

and its extension.
Encoding - the character encoding of

the target file: UTF-8, UTF-16, ASCII, Bi
nary.
Create folder Creates a new empty folder. This Folder - the full path of folder struc
action can be used to create ture to be created. The '\' character
multiple levels of new subfolders, must be duplicated. For example: C:\
such as C:\\NewParentFolder\ \NewFolder\\SubFolder1
\SubFolder1\\SubFolder2, etc.
In other words, an entire new folder
structure (tree) can be created in a sin
gle action; it is not necessary to create
each folder separately.

3.1.4.7 Flow Activities
Flow
No end step Prevents the current step from end

ing.
 Caution
This action must be used
within a scenario.
Output The output value. Output value - the internal name of output
of this step.
 Caution
This action can only be used
within a page and must be used
within a scenario.
Sequence A sequence of actions.
Reuse step Reuse step or steps.
Flow-If
If (else) Executes a block of code following

an IF action that evaluated to false.
 Caution
within a page.

If (start) Conditionally executes a block of Condition - This is an 'expression'. Use:

actions if the specified check of an
• $item$ to perform test on an item (exam
expression evaluates to TRUE.
ple: !$item$.exist())
• $data$ to perform test on data in the con
text (example: $data$ == 'null')
Flow- Loop
Start Starting instruction for a loop.
 Caution
within a scenario.
Exit Test block to exit from a loop. Exit condition - This is an 'expression' to
evaluate whether or not to leave the loop. Use:
 Caution
• $item$ to perform a test on an item (exam
This action must be used ple: !$item$.exist()),
within a scenario. • $data$ to perform a test on data in the
context (example: $data$ == '').
Loop Loops to the Start block.

Flow - Wait
Delay Delays execution for some millisec Delay - the number of milliseconds to wait be
onds. fore executing the code.
This is the standard pause that

should be used in normal situa
tions. It simply pauses the execu
tion of the script for the indicated
duration. It permits user interac
tion with Desktop Agent and other
programs for the duration of the
pause.
This can be useful for waiting for a

process to complete, to avoid going
too fast for the operating system,
or to give the user time to react.
Timer Sets a timer that executes speci Delay - the number of milliseconds to wait be
fied actions once after the timer ex fore executing the code.
pires.
 Caution
within a page.
Wait semaphore Waits for a semaphore Semaphore - name of the previously declared
semaphore.
Wait until Waits until a test condition evalu Condition - expression evaluated every 250
ates to true. milliseconds, within the limit of 20 attempts. If
condition evaluates to false, polling is repeated.
If the condition evaluates to true, control passes
to the following statement. Use:
• $item$ to perform the test on an item

(such as !
$item$.exist();)
• $data$ to perform the test on data in the
context (such as: $data$==').

3.1.4.8 Item - Click Activities
 Caution
These actions can only be used within a page.
Click Clicks an item. Item - name of item to use

for this action.
Mouse-click Simulates a mouse click on Win, Web, JavaSwing, UI au Item - name of item to use
an item. tomation, OCR, Flex. for this action.
X-coordinate - horizon
tal position (relative to item
top left position).
Y-coordinate - vertical
position (relative to item top
left position).
3.1.4.9 Item - Get Activities
Get Gets the content on an item. Item - name of the item to use for this action.
 Caution Where to store result - this is an 'ex

pression'. Use:
within a page. • $data$ to store in the context (example:
$data$ + '+++')
• Variable name to store in a variable (for ex
ample, var myVar)
Test item's existence
Get table Gets the content of a table item. Item - name of the item to use for this action.
Data - data used for storage.

3.1.4.10 Item - Set Activities
Keystroke Sets the content on an item (key Item - name of the item to use for this action.
stroke).
Source data - this is an 'expression'. Use:
 Caution • $data$ to get data from the context (exam
This action can only be used ple: $data$ + e.key.F4)
within a page. • '…' to set a constant value (example: 'my

value')
Select Selects a value in the content of the Item - the name of the item to use for this
item. action.
Select (check) or unselect (uncheck)
Set focus Sets the focus on an item. Item - name of the item to focus.
 Caution Source data - this is an 'expression'. Use:
This action can only be used • $data$ to get data from the context (exam
within a page. ple: $data$ + '+++')
• '…' to set a constant value (example: 'my
value')
Set Set the content of an item. Item - name of the item to fill with data.
 Caution
within a page.
Set table Sets data in a table. Item - name of the item to fill with data.
Data
3.1.4.11 Item - Wait Activities
 Caution
These actions can only be used within a page.

Wait change Waits until the content of an Item - name of item to use
item changes for this action
Wait click Waits until the end user Item - name of item to use
clicks an item for this action
Wait exist Waits by polling until an item Item - name of item to use
exists. for this action
Interval - the intervals

(in milliseconds) in which to
check item existence
Wait focus Waits until an item gets the Item - name of item to use
focus for this action
Wait command
3.1.4.12 Key Activities
Declare Declares a ciphering key. Key name
Key type (container or certificate)
Key usage (encryption or signature)
Comment
Storage -local (false) or server (true)
3.1.4.13 Outlook Lib Activities
Account
Enumerate accounts Enumerate the accounts of the cur Variable- name of the context variable to
rent Outlook instance store the retrieved information in.

Appointment
Accept appointment
Create appointment The generated appointment item Subject - subject of the appointment
will be set as current appointment
in the 'appointment context' after Body - body of the appointment. To start a new
wards if the property updateCon line use \r\n.
text is set to true

Location - location of the appointment
Start date time - date and time to start

the appointment. The format may be language-
or regionspecific.
Duration - duration of the appointment in mi

nutes. ENtereither Start date time and duration,
or Start date time and End date time.
End date time - date and time to end the

appointment. Enter either Start date time and
duration, or Start date time and End date time.
The format may be language- or regionspecific.
Importance - importance of the appoint

ment.
Busy status - busy status of the appoint

ment.
Category - category to use for the appoint

ment.
Sensitivity - sensitivity to use for the ap

pointment.
Display only - display the appointment but

don't send it. Use it only for attended scenarios.
Update context - if true, the 'appointment

context' is automatically updated with the new
appointment that is going to be created. No
search is necessary to work with it.
Decline appointment
Delete appointment Delete the current appointment de

fined in the appointment context.

Forward appointment Forward the current context ap "To” recipients - recipients must be
pointment. separated by semicolons, such as “email1@fac
tory.com; email2@factory.com; email3@fac
tory.com”. If you are using Active Direc
tory, “FirstName1 LastName1; FirstName2 Last
Name2; FirstName3 LastName3” can be used
instead of the email addresses.
“Cc” Recipients - recipients must be sep

arated by semicolons. If you are using Active Di
rectory, “FirstName4 LastName4; FirstName5
LastName5” can be used instead of the email
addresses.
“Bcc” Recipients - recipients must be

separated by semicolons. If you are using Ac
tive Directory, “FirstName6 LastName6” can be
used instead of the email addresses.
Display only - display the forwarded email

but don't send it. Use it only for attended sce
nario.
Get status Gets the status of the current con Variable- name of the context variable to
text appointment. store the retrieved information in.

Update appointment Updates the current context ap Subject - subject line of the appointment.
pointment.
Body - body of the appointment message. To
start a new line use \r\n.
Start date time - start date and time. The

format may be language- or regionspecific.

nutes. Fill either Start date time and duration or
Start date time and End date time.

appointment. Fill either Start date time and du
ration or Start date time and End date time. The

ment.

ment.
Ccategory - category to use for the appoint

ment.

pointment.

Create meeting Creates a meeting. Subject - subject line of the appointment.
Body - body of the appointment message. To

start a new line use \r\n.
Start date time - start date and time. The


nutes. Fill either Start date time and duration or
Start date time and End date time.

appointment. Fill either Start date time and du
ration or Start date time and End date time. The
Required attendees
Optional attendees
Resources

ment.
Organizer

ment.
Reminder set- true to activate a reminder,

false to not activate it.
Reminder minutes before start - de

fine minutes to configure the reminder.
Category - category to use for the appoint

ment.

pointment.
Display only - display the appointment but

don't send it. Use it only for attended scenarios.

Context
Appointment context filter Perform a selection of appoint Start after specific date - write a
ments which can be used later to date/time information to indicate that the ap
work on the items pointment must start after a specific date. Note
that this parameter depends on the language
and region. English: “12/25/20 4:30:00 PM”,
French=“25/12/20 16:30:00”.
End before specific date - write a

date/time information to indicate that the ap
pointment must end before a specific date. Note
that the value depends on the language and re
gionf.
Subject contains - write one or a se

quence of words and if they are find in the ap
pointments subject, the appointments will be
selected
Subject equal to - write a sequence of

words and if this exact sequence is find in the
appointments subject, the appointments will be
selected.
Duration higher than - duration from

which the appointments will be selected.
Duration lower than - duration below

which the appointments will be selected.
Include recurrent - include the recurrent

emails in the filtering.
Does current appointment exist? Returns true of the current context Variable- name of the context variable to use
appointment is existing, false oth for this action.
erwise.
Select first appointment Defines the current appointment as

the first appointment of the filtered
appointments.
Select last appointment Defines the current appointment as

the last appointment of the filtered
appointments.
Select next appointment Defines the current appointment as

the next appointment according to
the current appointment and the
filtered appointments.

Select previous appointment Defines the current appointment as

the previous appointment accord
ing to the current appointment and
the filtered appointments
Helper
Get information from time slot Get appointments information from Start date time - date and time to start
time slot. the appointment. Note that the value depends
on the language and region. English=“12/25/20
4:30:00 PM”, French=“25/12/20 16:30:00”, and
so on.
End date time - date and time to end

the appointment. Note that the value depends
on the language and region. English=“12/25/20
4:30:00 PM”, French=“25/12/20 16:30:00”, and
so on.
Variable - name of the context variable to

store the retrieved information in.
Store
Enumerate stores Enumerates the stores of the cur Variable- name of the context variable to
rent Outlook instance. store the result in.
3.1.4.14 Page Activities
Close Closes a page of an applica Page - name of the page of

tion. the application to close.

Get items Gets values of all items on a Page - name of the page to
page. use for this action.
 Caution Where to store

result - Values should be
This action can only be
stored in an object. Use:
used within a page.
• $data$ to store values in
the current context
• variable name to store
values in a dedicated
variable (for example,
myVar)
Highlight Highlights all detected items Win, Web, JavaSwing, UI au Page - name of the page of
in a page of an application. tomation, OCR, Flex. the application to use for this
action.
Duration - highlight dura

tion of detected items in mil
liseconds. If 0 (zero), items
remain highlighted.
Keystroke Sends a keys sequence on a Page

page.
Keys sequence - this is
an 'expression'. Use:
• $data$ to get data from

the context (example:
$data$ + e.key.F4)
• '…' to set a constant
value (example: 'my val
ue')
Screenshot Takes a screenshot of a page Page - name of the target

of an application. page to take a screenshot of.
The captured image file is
named
YYYYMMDD_HHMMSS_MS.
png and is stored in
the .\log\Pictures folder of
the current project.
Start Starts a page of an applica Page - name of the page of

tion. the application to start.

Wait close Waits until a page of an appli Page - name of the page to
cation is closed. use for this action.
3.1.4.15 Popup Activities
Popup activities allow interaction with the user. This can be used for displaying informational messages or
prompting the end user for input. This input can be used during the execution of the scenario, such as asking
for a number of loops, for a file name, or to take alternative action based on their response.
MsgBox Displays a message box. If Name - Unique name of the

the “Wait closing” option is popup to create and to dis
ticked, waits until the end play.
user closes it.
Title - Title of the popup to
create and to display.
Message - Main message

text that is displayed in the
popup window. HTML tags
can be used, such as:
• <br/> to insert a
breakline
• <b>text</b>
to put the text in bold
• <H4>My message
header</H4> to
mark a header
Template - Name of the tem

plate to use for popup crea
tion.
Wait closing - If true, wait

until this popup is closed by
the user.
Close Closes a popup. Name - Name of the popup

to close.

Tooltip Shows a tooltip box, which is Name - The unique name of

a small information box. the popup to create and to
display.
 Note
Title - The title of the popup
Be sure to use a timeout to create and to display.
value to dismiss the tool
Message - Main message
tip box, otherwise it will
text that is displayed in the
remain on the screen.
popup window. HTML tags
The end user cannot
can be used, such as:
close a tooltip box - it
disappears by itself. • <br/> to insert a
breakline
• <b>text</b>
to highlight the text in
bold
• <H4>My message
header</H4> to
mark a header
Background color - The

color of the background of
the tooltip.
Icon - The icon displayed in

the tooltip.
Closing delay - The delay

(in milliseconds) before auto-
close of the tooltip.
3.1.4.16 SAP GUI Activities
Activities for GuiComboBox
Set Focus Sets focus on an item. Item
Get Gets item value. Item
Where to store result
Set Sets value of an item. Item
Value

Get Icon Name Gets icon name. Item
Get List Returns the entries in ComboBox. Item
Get Key Returns the selected key in Combo Item

Box.
Set Key Sets the key as selected item in Item

ComboBox.
Key
Get Value Returns the selected value in Com Item

boBox.
Set Value Sets the value as selected item in Item

ComboBox.
Value
Activities for GuiCtrlCalendar
Get date Returns the selected date in Item

"YYYYMMDD" format.
Get date range Returns selected date range in Item

"YYYYMMDD" format, with the
From date and the To date sepa Where to store result
rated by a comma.
Select date Selects date given in "YYYYMMDD" Item

format.
Date
Select date range Selects date range given in Item

"YYYYMMDD" format, with the
from date and the to date sepa From date
rated by a comma.
To date

Activities for GuiCtrlGridView
Click cell Clicks on a table cell. Item
Row number
Column code
Click button cell Clicks a button that is in a table cell. Item
Row number
Column code
Deselect all rows Deselects all selected rows in the Item

control.
Get all visible rows Item
Get cell Gets a value from a table cell. Item
Row number
Column code
Get columns Gets the list of active column head Item

ers in the table.
Get row Gets the data in an entire row . Item
Row number
Get row count Gets the number of rows in the ta Item
ble.
Get rows Gets all rows of values in the table, Item

starting from the Start Row Index.
Start row index
Number of rows
Get rows by column Gets all rows of values in the given Item
column, starting from the Start
Start row index
Row Index.
Number of rows
Column ID
Select all rows Selects all rows in the control, Item

whether or not they are visible.

Select cell Selects a cell in the table defined by Item

the Row number and the Column
Code. Row number
Column code
Select row Selects the specified row. Item
Row number
Select toolbar menu item by ID Clicks a toolbar menu item. Item
Select toolbar menu item by Clicks a toolbar menu item. Item

position
Menu item's position (0 indicates the
first item)
Select toolbar menu item by text Clicks a toolbar menu item. Item
Menu item's text
selectContextMenuItemByText Selects a context menu item of a Item

selected cell or row by it's text.
itemText (string and case sensitive).
 Note
You must use a Select
Cell or Select Row activity
to select a cell or row
before using this activity,
SelectContextMenuItemByText
selectContextMenuItemByID Selects a context menu item of a Item

selected cell or row by it's ID.
itemID (string). The ID of a menu item.
 Note  Note
You must use a Select The ID of a menu item can be fetched using
Cell or Select Row activity the Recording and Playback option in the
to select a cell or row SAPGUI application.
before using this activity,
Record only the step of selecting the re
quired menu item from the context menu.
The generated VB script will have a select

ContextMenuItem call with the ID next to it.

selectContextMenuItemByPosition Selects a context menu item of a Item

selected cell or row by it's position
in the list. itemPosition (number). The position of a
menu item (0 if it is a first item).
 Note  Note
You must use a Select If there are SEPERATOR lines in the mid
Cell or Select Row activity dle of the context menu list, they must be
to select a cell or row counted to get the accurate position of the
before using this activity, required menu item.
If the SEPARATOR is ignored while count
ing, the menu item selection will be incor
rect or fail to work.
Selected column Gets the selected column from the Item

GuiCtrlGridView control.
Selected row Gets the row number of the cur Item

rently selected cell or cells in the
table.
Set cell Sets the value of a table cell. Item
Value to be set in the cell
Row number
Column code
Activities for GuiMainWindow
Set automation connection Page

Activities for GuiSession
Create session Creates a new session that is then Page

visualized by a new main window.
End transaction
 Note Page
This activity is defined at page

level and is not applicable to an
item. It enables switching from
the current page to the previ
ous page.
Get system name Gets system name from Sessio Page

nInfo.
Get application server Gets application server from Ses Page

sionInfo.
s
Get client name Gets client name from SessionInfo. Page
Get user name Gets user name from SessionInfo. Page
Get transaction Gets Transaction from SessionInfo. Page
Get program Gets Program from SessionInfo. Page
Get screen number Gets Screen Number from Sessio Page

nInfo.
Get system number Gets System Number from Sessio Page

nInfo.
Get session number Gets Session Number from Sessio Page

nInfo.
Maximize page Maximizes the page. Page

Minimize page Minimizes the page. Page
Restore page Restores the page. Page
Start transaction This activity is defined at page level Page

and is not applicable to an item.
The transaction ID must be passed, Transaction ID
and the appropriate page is opened
on the basis of the transaction ID.
Activities for GuiStatusBar
Get message ID Retrieves the name of the message Item

class used in the ABAP message
call. Where to store result
Get message number Retrieves the name of the message Item

number used in the ABAP message
call. It will usually be a number, but Where to store result
this is not enforced by the system
Get message type Retrieves the message type: Suc Item

cess, Warning, Error, Abort, Infor
mation (or empty string would be Where to store result
returned if something is wrong.
Activities for GuiTableControl
Deselect a given row Deselects a given row. Item
 Note Row number
The scroll moves to the given

row number while deselecting
the row, making it the first in
the list of visible rows.

Deselect all visible rows Deselects all visible rows. Item
Deselect visible row Deselects a given visible row. Item
 Note Row number
No scrolling takes place.
Get all visible rows Gets all the visible rows present in Item
the table.
Get column names Gets the list of the column names Item
present in the table. If the column
contains an icon instead of text, the Where to store result
icon name is returned.
Get row Gets the values from a given row Item

number.
Row number
 Note
The table scrolls to the position
of the desired row.
Get visible row count Gets the count of the visible rows in Item
the table.
Get maximum vertical scroll offset Gets the maximum value up to Item
which scrolling is possible with the
table. Where to store result
Get the vertical current position of Gets the current position of the Item
scrollbar scrollbar.
Scroll down by one row Scrolls down one row at a time and Item
a new row appears in the lower part
of the table.
Scroll to a particular position Scrolls to a given scroll bar posi Item

tion.
Position as a number
Scroll to next page Scrolls to the next set of rows in the Item
GUI table control.
ScScroll to previous pagee Scrolls to the previous set of rows Item

in the GUI table control.

Scroll up by one row Scrolls back up one row at a time. Item
Select a given row Selects a given row. Row number
 Note
The scroll moves to the given
row number while selecting the
row, making it the first in the
list of visible rows.
Select a visible row Selects a given visible row. Item
 Note Row number
No scrolling takes place.
Select all visible rows Selects all specified visible rows. Item
Activities for GuiTextField
Set caret position Item
Caret position
Activities for GuiTree
Check Item
Node key
Item position (column)
Click node item link Item
Node key

Collapse node Collapses a folder node. Item
Node key
Double-click node item Item
Node key
Double-click node Item
Node key
Get node item checkbox state Item
Node key
Get node item text Item
Node key

Get node key by path Get the node's key using its path. A Item
node path is constructed using the
position of all the nodes that are Node path
traversed to reach your target node
in the same sequence appended by
'/'. Position (starts with 1) is simply
the position of the node at that level
in the tree.
 Note
For bigger trees that are dy
namic and where node posi
tions tend to change, it is rec
ommended to use the follow
ing approach when creating the
bot:
• In the SAPGUI application,

select the node
• o Launch the debugger in
Desktop Studio.
• In the code tester, ex
ecute SAPLogon750.pSA
PEasyAccess.oSAPTable
TreeControl.selected() to
get the key
Get node key by text Get key of the node using text. Item
 Note Node text
Recommended for smaller Where to store result

trees subject to dynamic
change in the position of no
des. For trees with a greater
number of nodes, use Get node
key by path for better perform
ance
Get selected node Item

Press node item button Item
Node key
selectContextMenuItemByPosition Select a context menu item of a se selectContextMenuItemByPosition (nodeKey,

lected cell or row by it's position in itemPosition, columnPosition)
the list.
Item
nodeKey (string).
itemPosition (number). The position of a

menu item (0 if it is the first item).
 Note
If there are SEPERATOR lines in the mid
dle of the context menu list, they must be
counted to get the accurate position of the
required menu item.
If the SEPARATOR is ignored while count

ing, the menu item selection will be incor
rect or fail to work.
columnPosition (number)
 Note
For tree types other than Column Tree, the
columnPosition parameter is not re
quired as it is not applicable.
In case of Column Tree, the

columnPosition parameter is manda
tory to decide the node Item’s context
menu that needs to be opened.

selectContextMenuItemByText Select a context menu item of a se selectContextMenuItemByText (nodeKey,

lected cell or row by it's text. itemPosition, columnPosition)
Item
itemText (string and case sensitive).
nodeKey (string).
columnPosition (number)
 Note


selectContextMenuItemByID Select a context menu item of a se selectContextMenuItemByID (nodeKey,

lected cell or row by it's ID. itemPosition, columnPosition)
Item
nodeKey (string).
itemID (string).
 Note
The ID of a menu item can be fetched using
the Recording and Playback option in the
SAPGUI application.
Record only the step of selecting the re

quired menu item from the context menu.
The generated VB script will have a select

ContextMenuItem call with the ID next to it.
ColumnPosition (number).
 Note

Select node Item
Node key
Select/Unselect (true/false)
Select node item Item
Node key
Uncheck Item
Node key

Activities for GuiUserArea
Scroll to next page If there is a vertical scroll bar, Item

scrolls down to bring into view con
tent that is below the screen level.
Scroll to previous page If there is a vertical scroll bar, Item

scrolls up to bring into view content
that is below the screen level.
3.1.4.17 SAP UI5 Activities
Component Subfolder Activity Properties
Action Select Open Item
File Browser Browse File

Item: Name of the item in which action need to
This activity provides the ability to perform.
browse a file from file system.
Source data: File path including the file
name and format.
For example, "C:\\Users\\Docu

ments\\CV\emailList.xlsx"
Add item
Calendar Item
Appointment title
Appointment subtitle
Appointment type
Start date
End date
Creation status
Carousel Next Item
Previous Item

Combobox Add item Item
Source data
Get items Item
Feed Context Get alt text Item
Get numeric Item
Get subheader Item
Press Item
Set content text Item
Enter content text
Set numeric Item
Set numeric value
Set subheader Item
Enter subheader

Menu Open Item
Navigation List Add item Item
Source data
Get items Item
Search Field Search Item
Source data
Set Item
Source data
Segment Button Add item Item
Source data
Get items Item
Suggestion Search Field Suggestion search Item
Source data
Table Select row Item
Source data

Clear selection Item
Row count Item
Row data Item
Source data
Select all Item
Table data Item
TAccount Add credit Item
Source data
Add debit Item
Source data
Get credit Item
Get debit Item
Toggle Button Check Item

Is checked Item
Uncheck Item
Tree Grid Expand Item
Source data
Upload Collection uploadFile

Item: Name of the item in which action need to
SAPUI5 Upload Collection is a con This activity provides the ability to perform.
trol for attachment management upload single or multiple files.
Source data: File path including the file
that provides the ability to upload
 Note name and format.
various types of files.
You can upload multiple files For example, "C:\\Users\\Documents\

using the loop control or \test.pdf"
theuploadFile activity multiple
Upload URL (Optional): Optional Pa
times.
rameter.
You can upload the bank state
This can be used in an exceptional. For example,
ments.
"../../../upload"
3.1.4.18 Scenario Activities
Start Starts a specified scenario. The Scenario - Name of the scenario to start.
data to use and manipulate with the
Data used with the scenario - This is an expres
scenario can also be specified.
sion. Use:
The “Wait end” option will launch
• “…” to use a constant value (example: “my
a scenario and wait until the sce
Value”),
nario terminates successfully. Once
the scenario terminates, execution
• … to use a user variable (example: my
Data).
continues with the next action.
Wait end - If true (in other words, if the option is
ticked), wait until the scenario ends.
Wait semaphore - Set a wait semaphore to wait

for the end of different scenarios.

End Ends the current scenario.
 Caution
within a scenario.
Error Defines a dedicated error handling

for a scenario
Timeout Defines a dedicated time-out man

agement for a scenario.
Disable timeout Used to disable step timeout.
3.1.4.19 Setting Activities
Declare Declares a setting. Setting name
Comment
Storage - local (false) or server (true)
Get Retrieves the value of the setting. Setting name
Setting value
Set Sets the value of the setting. Setting name
Setting value

3.1.4.20 System Activities
System activities are used to perform basic system functions.
Set clipboard Places the specified text on the Message - the text message to be copied to
clipboard. The previous clipboard the clipboard. Use:
content is not saved.
• $data$ to use data from the context,
• “…” to use a constant value (example: “My
message”),
• … to use a user variable that must be de
clared beforehand (example: myMsg).
Set context Assigns a value to a variable of the Variable - name of the variable of the con
current defined context, and to up text to use for this action.
date it during a run. To set it to an
initial value, simply put the number Value - value to assign to the variable. This is
or text in the “Value” field. an 'expression'. Use:
• $data$ to assign data from the context

• “…” to use a constant value (example:
“OK”),
• … to set numerical value or to use an user
variable (example: myData).
Diagnostics Performs complete and advanced

diagnostics. Collects data about
desktop information, running envi
ronment, installed programs, Java
Script context and XML context.
This can be used for many pur
poses, such as to help troubleshoot
issues and to perform local or re
mote analytics. The diagnosis file,
named *.diagnostic.pscl, is
stored in the project's log folder .

Kill process Forces a running program to close. Process - The name of process to kill all run
All instances of a running process ning instances of. For example: iexplore.exe
are killed. The process to kill is
determined via the program filen
ame. If possible, use the close com
mand for an application or a page
because this allows the program to
shut down gracefully. “Kill process”
will shut the program down without
saving any changes or data. To use
this activity, the WMI library must
be included in the project.
Log Provides a method of adding your Message - the text message that is saved
entries to the log file and in the de to log and shown in the debug window. Only
bug window, with a severity level. strings are supported.
This can be used for many pur
poses, such as debugging scripts Level - The severity level of the message to be
and recording information. logged.
Read registry Reads a setting from the Windows Variable - name of the variable in which for
system registry. store the read result.
Registry key - the entire key, including

the top-level and final key name, should be
constructed. For example: HKEY_LOCAL_MA
CHINE\\SOFTWARE\\Microsoft\\Internet Ex
plorer\\Version
Restart Shuts down Desktop Agent and re

starts it with the same current run
ning project. No user intervention is
required.
Screenshot Takes a full-screen screenshot.

The image format is Windows Bit
map (.BMP). The captured image
is stored in the “.\Log\Pictures”
folder of the current project.
Shutdown Shuts down Desktop Agent. No

user intervention is required. No
user intervention is required.
Sleep Freezes the execution of the cur Delay - the time interval for which execution is
rent thread until a time-out interval to be suspended, in milliseconds.
elapses.

Unlock In unattended mode, unlocks a

locked session if any mouse click or
keystroke activities are necessary.
Automatically relocks 10 seconds
after the action.
3.1.4.21 Web Service Activities
Call SAP web service Calls an SAP web service. Source URL - the URL of the web service to
be called.
Input data - the input data of the web serv

ice.
Output data - the variable to store the re

sult in.
Data content type
Web service call method
Call web service Calls a web service. Source URL - the URL of the web service to
be called.
Input data - the input data of the web serv

ice.
Output data - the variable to store the re

sult in.
Data content type
Web service call method
3.1.4.22 Word Lib Activities
Open Word Word filename - the word full file path and
name of the Word file.

Init Word
End Word
Release Word
Close Word
Replace all Text to find - the search string
Text to replace
advancedParameters - can be use to re

place only one occurrence, or to search
with 'match case' or to search with 'match
Whole Word'. To activate all advanced pa
rameters, here is an example: {“replace
mentType” : e.word.WdReplace.wdReplaceOne,
“matchCase” : true, “matchWholeWord” : true}.
Save as Word Word filename - the word full file path and
name of the Word file.
Save Word
Set bookmark Set a bookmark with a value. Bookmark - the defined bookmark to set.
Value- the value to set in the bookmark
Formatting
Format bold Activate bold - true to activate bold, false

to remove it.
Format font size Font size - the font size is a positive integer.
Format highlight Highlight color - this must be selected

from e.word.WdColorIndex enumeration.
Format italic Activate italic - true to activate italic,

false to remove it
Clear formatting

3.1.4.23 PDF Activities
Open PDF Opens the text-searchable PDF PDF filename - the full file path and name
document of the text-readable PDF file, surrounded by ' ',
such as 'C:\path\to\folder\MyPDF.pdf'.
Release PDF Closes the PDF document and re

leases the associated resources
Get number of pages Retrieves the number of pages in Variable - name of the variable of the con
the document text in which to store the result.
Get page dimensions Gets the dimensions of a given

PDF page number- optional, defaults to
page
page 1 if not supplied.
Variable - name of the context variable in

which to store the retrieved page dimensions
(width and height). The context variable is best
created as a folder containing two items for the
two dimensions.
Get text Retrieves the complete text of the Variable - name of the context variable in
PDF document, or the subset of the which to store the retrieved text. Mandatory.
document defined by the Filter, if
used.
Extract text with Regex Applies a regular expression to

Regular Expression - example: /Order
search for and extract the desired
text No.: ([A-Z0-9]+)/. Capturing groups are
supported. In this example, the parentheses
surrounding the second part of the regex denote
a capturing group, and only what comes after
"Order No.: " will be extracted and returned.

which to store the extracted text. Mandatory.

Create filter for text extraction Creates a filter for use in an extrac Page Range - the page or pages on which to
tion activity to restrict the opera apply the operation. Mandatory. Examples: "2"
tion of that activity to a specified for the second page, multiple pages: "1,3-7,10".
page range or a defined area of the
PDF page. Top offset - distance of the extraction area
or bounding box from the top of the page
Left offset - distance of the bounding box

from the left edge of the page
Width - width of the bounding box
Height - height of the bounding box

which to store the filter generated by this activ
ity for use in other PDF activities. Mandatory.
3.2 Scenario Overview
Sequences can be easily controlled using the ‘waiting’ patterns (see Waiting [page 343]).
Controlling complex sequences implies specific requirements:
• Structure your code:

Controlling complex sequences requires more complicated code. It is important to structure your code to
improve readability and facilitate maintenance.
• Implement algorithms (loops, conditional switches, and so on):
Complex sequences are often non-linear. You may have to implement patterns such as loops or conditional
switches.
• Manage timeouts:
During a control sequence, you must stop the control sequence if the application runs out of the planned
sequence. You need to implement timeout management to detect these cases.
To fulfill these needs, Desktop SDK implements the concept of scenarios.
A scenario allows you to split a single complex control sequence into several simple sequences, called steps.
Splitting a sequence into steps enables you to:
• Structure code on the basis of functional parts

• Reuse control sequences
• Implement algorithms: loop on a control sequence, conditionally execute control sequences, and so on
In addition, scenarios enable you to implement:
• Timeout management
• Centralized error management

3.3 Control Sequences
Once you have defined the entities in our project (see The Declaration Phase: General Information [page 240]),
you need to design the control sequences.
Basically, sequence control consists in concatenating control actions on one or more controlled (supervised)
applications. This includes:
• Writing a value to a field

• Clicking a button
• Reading the value of a field
Waiting
Occasionally, a control action generates processing in the controlled application. Desktop Agent has to wait
until this processing is ended before executing the next action of the sequence. In other words, Desktop Agent
needs to synchronize with the application execution and continue with its own execution only when the target
application is ready to receive the next action in the control sequence.
Example 1 – Navigation
Here is a typical control sequence:
Functional description
1. Once page1 has been loaded, click the open_page2 button on page1
2. The application then loads page2
3. Get the value of the name field on page2
Technical description
1. Once page1 has been loaded, click the open_page2 button on page1
2. WAIT UNTIL page2 IS LOADED
3. Get the value of the name field on page2
Here are two types of implementation:
Incorrect implementation: without wait (synchronize)
 Sample Code
page1.open_page2.click() ;
page2.name.get() ;
This control sequence will fail, because it is executed synchronously. After executing the click on the
open_page2 button, Desktop Agent will not automatically wait for page2 being loaded before executing the
get on the name field. So, you need to explicitly wait for page2 to be loaded before executing the next command
Correct implementation: with wait

 Sample Code
page1.open_page2.click() ;
page2.wait() // wait until page2 loads (pseudo-code)
{
page2.name.get() ;
}
In this case, Desktop Agent clicks the open_page2 button and then waits for page2 to be loaded before
executing the get on the name field, which is coded in the callback part of the wait() method.
Example 2 - page with dynamic behavior
Functional description
1. Once page1 has been loaded, fill the zipcode field of page1
2. The application processes this value to get the corresponding city name and fill the cityname field
3. The then get the value of the cityname field on page1
Technical description
2. WAIT UNTIL THE cityname field has been computed
Incorrect implementation: with no wait
 Sample Code
page1.zipcode.set(zipcode_value) ;
page1.cityname.get() ;
This control sequence will fail, because it is executed synchronously. After executing the set on the
zipcode field, Desktop Agent will not automatically wait for the application to compute the cityname before
executing the get on the cityname field.
So, you need to explicitly wait until the cityname field has been computed before executing the next
command.
There are different solutions to address this case:
Good implementation: wait for some time
You can wait for some time before getting the value of the cityname field:
 Sample Code
ctx.wait(some_time) // wait for some_time(pseudo-code)
{
}
This is a good solution, but not very reliable because you can't be sure you have waited long enough:
• If the wait is too short, you won't get the value of the cityname field if the application being controlled is
slow

• If the wait is too long, controlling will be too slow.
Best implementation: wait for an event:
 Sample Code
page1.cityname.events.CHANGE.on() // wait until 'cityname' has
changed(pseudo-code)
{
}
This is the best solution: we wait until the application notifies that the cityname field content has changed.
3.4 Designing Control Sequences
Design - Splitting a Sequence into Synchronous Control Blocks
Background
The first task when designing a control sequence consists of:
• Detecting the sequences' waiting (synchronization) needs.

• Establishing the available technical events for meeting these needs.
• Splitting the sequence into blocks of control actions that will be executed sequentially.
Consider the following sequence:
1. On the SearchPage, Desktop Agent enters the search criteria and clicks the Search button, which opens
the ResultPage.
2. Desktop Agent collects the search result from the ResultPage.
Once Desktop Agent has clicked the Search button, it must wait until the ResultPage is opened before
collecting the results on this page. We will design the following sequence:
 Sample Code
• Start control sequence

◦ …
• Wait until the SearchPage loads
◦ Fill in the search criteria
◦ Click the Search button
• Wait until the ResultPage loads
◦ Collect the search result in the ResultPage.
Detect Waiting (Synchronization) Needs

Most of the time, waiting (synchronization) needs are easy to detect:

• Wait until a page loads before controlling it.
• Wait until a page closes before continuing the sequence.
• Wait until the user clicks a button before starting or continuing the sequence.
Sometimes, waiting needs can be more difficult to identify (see Controlling Pages with Event-Driven UI Updates
[page 273]):
• Wait until an item gains focus before setting its value.

• Wait until an item value changes before getting its value.
Once you have detected your sequence's waiting needs, you must find the best way to implement 'waiting'
code:
• The best way is to wait for a technical event notified by the controlled application.
• If you don't receive any appropriate technical event, you can wait by implementing polling (explained later).
• Finally, if polling is not available, you will have to use the wait some time method (explained later).
Technical Events
Synchronization is managed by waiting for receipt of a technical event. Technical events are notifications sent
by an application being controlled, resulting from events fired inside that application.
The flow of notified technical events depends on the running application workflow. It is not possible to
determine what and when technical events are notified by a supervised application. You can merely decide
to listen for them.
Here is a list of the most useful technical events:
START Application starts
END Application ends
Page-Based Events
LOAD Page loads
UNLOAD Page closes
Item-Based Events
CLICK Item is clicked
CHANGE Item's value has changed
SETFOCUS Item has gained input focus
KILLFOCUS Item has lost input focus

Find an Appropriate Technical Event
You must find an appropriate technical event that you can use to meet each specific synchronization need.
Only tracked events on recognized elements (applications/pages/objects) can be notified:
• Application-based and page-based events are automatically tracked.

• Item-based events must be tracked explicitly.
Explicitly Track Technical Events
Each connector or technology implements its own set of technical events: Some are common to all connectors
and some are technologyspecific. A list of all trackable events is shown, for each declared element, in the
Track Events tool window (see The Explorer Perspective [page 9]. For the UI Automation connector, the
available item-based events are listed in Page-Based Events [page 96] ).
Receive Notification of Technical Events
When you track an event, the relevant connector is informed that this event is expected. That doesn't mean
that it will be notified as expected. You need to verify notification by running the project in Debug mode and
playing the sequence through manually. Notified events are displayed in the Events view or the Scenario view of
the Desktop Debugger (see Debugging and Testing with the Debugger [page 432]).
Once you have found the appropriate technical event to wait for, you can implement the corresponding wait
code.
3.5 Managing Data
The Context
The context is a data manager that maintains all data arising during execution of a scenario - internal data of
the scenario or external data sent to or received by the scenario.
The structure of the context is automatically generated each time you add a Get/Set activity on an item in a
page:
• A folder is created for the application.

• A subfolder is created for the page.
• An item is created for the automated item.
This automatic generation option can, however, be disabled by unchecking "Generate context items" on the
Workflow tab in the Desktop Studio settings. The script developer is then responsible for creating all required
context items manually.
 Note
Automatic generation of context items is recommended for less experienced scenario script developers.
In the below screenshot of the Context tool window, IO is an element of the context (in this case, a folder), and
its child elements are Customer and CreditValidation.

 Tip
By default, when generating the scenario script, the Desktop Studio automatically adds a data manager
that refers to the context in the code via a script variable called rootData. It is added both to the code that
starts the scenario and to each step in which the data manager is retrieved. This variable helps developers
within the script to interact with the data manager in the code. If a developer selects a folder for its Input
DataManager property (e.g. IO), the script variable's name is changed to rootData_IO.
The Input DataManager Property
The Input DataManager property allows a developer to declare the data manager used within a scenario. It is
used to enable scenario reusability. It is typically a folder or subfolder of the context structure, such as the IO
folder in the context shown above.
If the Input DataManager property has been provided, the scenario script can only use this folder. However, if
the Input DataManager property is left empty, the whole context structure is used in the scenario script.
 Tip
Using a custom Input DataManager means you are not moving all of the context back and forth in the cloud.
It is good practice to limit the quantity of data you send and receive in the cloud to only the data that your
project actually requires.
The Input and Output Properties
As explained above, the Input DataManager is used only for data management within a scenario. But
sometimes a bot requires the exchange of parameters between skills (see the Skills section in Designing
Processes), such as with a User Task in a Cloud Studio Process, or needs to send data to a scenario via an API
trigger or a Scheduled trigger. For this purpose, you can make entries in the Input and/or Output properties in
the Properties window (Input to receive data and Output to send data):
• If the developer has defined an Input DataManager, the dropdown lists display the elements of the context
that correspond to the Input DataManager's elements.

In this example, the Input DataManager elements IO.Customer and IO.CreditValidation have been selected
for the Input and Output properties, respectively:
If nothing is selected, the entire Input DataManager is used.

• If the developer hasn't defined an Input DataManager, the dropdown lists for the Input and Output
properties display all elements of the context (folders, subfolders and items):
If the developer doesn't select anything for the Input or Output property (and there is no defined Input
DataManager), the entire context is used for that property.
Data Structures and the Cloud Studio
Desktop Studio packages can be imported to the Cloud Studio in order to re-use the scenarios. During import,
the Cloud Studio automatically creates the required data types for each scenario in the package. The data
types are then available for various purposes, such as passing parameters between skills (scenarios, user
tasks, and processes) and for triggers and notifiers.

For more information, see Processes and Data Types.
At Runtime
When a scenario is triggered by the Cloud Factory, the Desktop Agent instantiates the Input DataManager (or
if none was defined, the context), and where applicable, initializes it with data received from the Cloud Factory
(if defined by the scenario developer in the input properties, as explained above). When the Desktop Agent
has finished executing the scenario's script, it sends data back to the Cloud Factory (if defined by the scenario
developer in the output properties, as explained above).
3.6 Designing Scenarios Through Code
Designing a scenario to control a complex sequence essentially consists of deciding how to split the sequence
into smaller subsequences. Here are some of the ways you can do this:
• Define one step for each functional step

• Define at least one step for each repetitive subsequence
• Define one step for a subsequence that can be reused
• Define one step for a subsequence that requires a special timeout delay (for example, wait for user
response)
• Define one step for a subsequence that requires special error management
To improve code readability, split large steps into smaller ones.
If you plan to reuse steps, it is important to define carefully in what state the step waits for the controlled
application and in what state it leaves it.
For example, in the following sequence:
• On the SummaryPage, select each line of the Detail list and click on the Detail button
• Wait until the application opens the DetailPage
• Collect the data in the DetailPage and go back to the SummaryPage
• Loop until you have collected the data on each line
You design your scenario as follows:
• Step st_Start
Navigate to SummaryPage
• Step st_Loop – Input : SummaryPage is loading – Output : SummaryPage is loading
Wait until SummaryPage loads
• If there are no more detail lines, jump to step st_End
• Select the next detail line
• Click the Detail button
Wait until the DetailPage loads
• Collect the data in the DetailPage

• Go back to the SummaryPage
• Jump to step st_Loop
• Step st_End
End sequence
Examples of step behaviors:
• Start an application and navigate to a given page.

• Collect data from a page.
• Search for results in an application from a given account number.
• Set data in a form and validate.
Related Information
Managing Data [page 347]
3.6.1 Managing Steps and Scenarios Using Desktop SDK
Discover how to use Desktop SDK via the links below.
Related Information
Declaring Steps with Desktop SDK [page 352]

Declaring Scenarios with Desktop SDK [page 354]
Starting a Scenario [page 357]
Managing Data Within a Scenario [page 356]
Stopping a Scenario [page 358]
Managing Loops and Conditional Switches in Scenarios [page 356]
Managing Timeouts in Scenarios [page 361]
Managing Errors [page 360]

3.6.2 Declaring Steps with Desktop SDK
Declare the Step
A step is declared in a process or an application using the step method.
 Sample Code
<application>.step({ <stName>: function(ev, sc, st)

{
// Code that will be executed when the step starts
...
}});
The parameter of this method is a callback function (named step handler), where you implement the code to
be executed when the step starts. This callback receives the following parameters:
• ev : current (last received) event

• sc : parent scenario (seClass ctx.scenarioClass )
• st : this step object (see Class ctx.stepClass )
 Note
• Step declarations can be made at a global level in your scripts.

• Within a given application or process, step names must be unique. The same name can be used in
different applications.
• You can use the st + TAB snippet to generate a step declaration
Implement the Step Code
You can implement any code inside the step handler:
• Initialization code
• Controlling code
• Event handlers
• and so forth
Make sure that code implemented outside Event handlers is executed when the step starts.
 Sample Code
myApplication.step({ stMyStep: function(ev, sc, st)

{
// executed when stMyStep starts
...
// Wait for myPage
myApplication.myPage.wait(function(ev)

{
// executed when myPage is loaded
...
});
// executed when stMyStep starts
...
}});
End the Step
You must end the step by calling the endStep method:
Calling endStep without parameter starts the next step declared in the scenario list (see Declaring Scenarios
with Desktop SDK [page 354].)
If the step is the last one in the scenario list, the scenario automatically stops
Example:
 Sample Code
myApplication.step({ stMyStep: function(ev, sc, st)

{
// make initialization
...
// Wait for myPage
myApplication.myPage.wait(function(ev)
{
// perform controlling
...
// End the step and start the next one
sc.endStep();
});
}});
 Note
• Calling endStep() synchronously starts the next step and then executes its initialization code.
• Calling endStep() ends the step but doesn’t exit from handler. Code implemented after the call to the
endStep method is executed.
• Any Event handler set inside the step is reset when the step exits (whatever it has been called or not).
There is no risk that an Event handler is called after the step has ended.
• You can force the next step started by setting it as parameter (see Managing Loops and Conditional
Switches in Scenarios [page 356]).

3.6.3 Declaring Scenarios with Desktop SDK
Declare the Scenario
A scenario is declared in a process or an application using the scenario method:
 Sample Code
<application>.scenario({ <scName>: function(ev, sc)

{
// Scenario handler executed when the scenario starts
...
}});
A scenario handler contains code that will be executed when the scenario starts. This callback receives the
following parameters:
• ev : current (last received) event

• sc : this scenario object (see Class ctx.scenarioClass )
 Note
• Scenario declarations can be made at global level in your scripts.

• Within a given application or process, scenario names must be unique. The same name can be used in
different applications.
• You can use the sc + TAB snippet to generate a scenario declaration.
Implement Your Code Inside the Handler
A scenario handler may contain:
• An optional onTimeout handler which is called if a timeout appears (see Managing Timeouts in Scenarios
[page 361]).
• An optional onError handler which is called if an error occurs (see Managing Errors [page 360]).
• Initialization code (for example, Starting mode)
• A list of steps that are concatenated and started sequentially during scenario execution.
 Sample Code
myApplication.scenario({ scMyScenario: function(ev, sc)

{
// Set Timeout handler
sc.onTimeout(30000, function (sc, st) { sc.endScenario(); });
// Set Error handler

sc.onError(function (sc, st, ex) { sc.endScenario(); });

// Set the Starting mode
sc.setMode(e.scenario.mode.noStartIfRunning);
// Set Steps list

sc.step(myApplication.steps.myFirstStep);
sc.step(myApplication.steps.mySecondStep);
sc.step(myApplication.steps.myThirdStep);
...
}});
 Note
• You may declare steps prior to setting the steps list, in order to get IntelliSense in Desktop Studio.
• You can use the stu + TAB snippet to use an existing step inside a new scenario.
Set the Starting Mode
The scenario’s starting mode determines what appends when the scenario starts. You can set the
starting mode using the setMode method. The main available modes are as follows (see Enumeration
e.scenario.mode ):
• clearIfRunning: if a scenario with the same name is running, it is cancelled

• noStartIfRunning: if a scenario with the same name is running, the new scenario is not started
• clearAll: all running scenarios are cancelled
Related Information
Managing Steps and Scenarios Using Desktop SDK [page 351]

Declaring Steps with Desktop SDK [page 352]
Starting a Scenario [page 357]
3.6.4 Managing Merge Requests
If you're using activities when designing your scenario through code, you need to follow some guidelines to
avoid merge conflicts.
Indeed, parts of code are generated from the activities. In case of localization changes (for example to use a
different language), the data generated from an activity changes, which brings a risk of conflict that can not
always be solved by the merger tool.
To avoid merge conflicts, always set manually your own step name, instead of using the default step name that
comes from the name or the description of the activity.

3.6.5 Managing Loops and Conditional Switches in Scenarios
It is possible to implement conditional jumps or loops within a scenario. You can simply do this by stating the
next step to start in the endStep method.
 Sample Code

{
sc.step(myApplication.steps.st_Start);
sc.step(myApplication.steps.st_Loop);
sc.step(myApplication.steps.st_End);
}});
myApplication.step({ st_Loop: function (ev, sc, st)

{
...
if (sc.data.myIndex < sc.data.myCounter)
{
sc.data.myIndex = sc.data.myIndex + 1 ;
sc.endStep(myApplication.steps.st_Loop) ; // Loop on st_Loop
} else {
sc.endStep() ; // Continue scenario
}
}});
3.6.6 Managing Data Within a Scenario
When starting a scenario instance, a user data object, accessible via the data property, is generated
automatically. This user data object is freely usable by developers to store data for the duration of the scenario
instance.
 Sample Code

{
...
// Initialize scenario user data
sc.data.myCounter = 20 ;
sc.data.myIndex = 0 ;
...
sc.step(myApplication.steps.myStep);
...
}});
myApplication.step({ myStep: function (ev, sc, st)

{
...
// Use scenario user data
if (sc.data.myIndex < sc.data.myCounter)
{
sc.data.myIndex = sc.data.myIndex + 1 ;
}
}});

You can initialize this user data object from outside the scenario by passing it as a parameter in the start
method.
 Sample Code
// Initialize data from outside the scenario

var myData = {
myCounter: 20,
myIndex: 0
}
// Pass data at starting
var sc = myApplication.scenarios.scMyScenario.start(myData);
In the case of sensitive information, you may not want the data to be displayed externally, for example on the
controlling page of SAP Intelligent Robotic Process Automation Factory. If so, use sc.localData instead of
sc.data in the generated code to keep the data locally.
 Sample Code
myApplication.step({ credentialStep: function(ev, sc, st) {
sc.localData.credential = {};
ctx.cryptography.credentials.SAPGUI.get(function(code,
label, credential) {
if (code == e.error.OK) {
sc.localData.credential.user =
credential.userName.get();
sc.localData.credential.password =
credential.password.get();
sc.endStep();
} else {
sc.setError( e.error.KO, "Getting credential
failed!" );
sc.endScenario( );
}
return;
});
}});
myApplication.step({ logonStep: function(ev, sc, st) {
var sUser = sc.localData.credential.user;

var sPassword = sc.localData.credential.password;
// Do login ...
}})
3.6.7 Starting a Scenario
You start a new instance of a scenario using the start method:
 Sample Code
myApplication.scenarios.scMyScenario.start([data]);

By default, a scenario execute its steps in the order of declaration:
• When a scenario starts, the first step declared in the scenario is started.
• When a step ends (‘endStep()’ is called), the next step is started.
• When the last ends, the scenario is stopped.
 Sample Code

{
...
sc.step(myApplication.steps.myFirstStep);
sc.step(myApplication.steps.mySecondStep);
...
}});
myApplication.step({ myFirstStep: function(ev, sc, st)

{
...
sc.endStep(); // ends the step and starts the mySecondStep step
}});
myApplication.step({ mySecondStep: function(ev, sc, st)
{
...
sc.endStep(); // ends the step and the scenario
}});
Related Information

Stopping a Scenario [page 358]
3.6.8 Stopping a Scenario
Stopping One Running Scenario
A scenario is automatically stopped when its last step has ended.
You can stop it explicitly using the endScenario method:
 Sample Code
sc.endScenario();

Stopping All Running Scenarios
You can stop all running scenarios for an application (or process) using the clearAll method:
 Sample Code
// *** Stop All Running Scenarios for MyAppli***

MyAppli.scenarios.clearAll() ;
You can stop all running scenarios using the runningScenarios property:
 Sample Code
// *** Stop All Running Scenarios ***

var scenRunning = ctx.runningScenarios;
for (var i in scenRunning){
scenRunning[i].endScenario();
}
 Note
<application>.scenarios will give a list of declared scenarios rather than running scenarios.
Wait Until a Scenario Ends
If necessary, you can set an onEnd handler on a scenario, which will be called when the scenario ends
 Sample Code
myApplication.scenarios.myScenario.start().onEnd( function(sc)
{
ctx.log('scenario [' + sc.name + '] has ended with code: ' + sc.code);
});
 Note
A scenario instance contains a code property with an error code:
• e.error.OK: the scenario ended successfully.

• e.error.TimeOut: the scenario ended with a timeout.
• e.error.KO: the scenario ended with an error (exception object) contains an exception object).
The onEnd method can be used to synchronize scenarios:
• To launch sub-scenarios from a parent scenario

• To concatenate multiple scenarios.

 Sample Code
// in step 'ScenarioManager.steps.MyStep', call scenario

'MyAppli.scenarios.MyScenario'
ScenarioManager.step({ MyStep: function(ev, sc, st) {
var sc2 = MyAppli.scenarios.MyScenario.start(sc.data).onEnd( function() {
...
sc.endStep();
});
}});
3.6.9 Managing Errors
Standard Error Management
In Desktop SDK, errors are managed by throwing exceptions.
WIth the Javascript try … catch pattern, you can catch exceptions for specific error management. Uncaught
exceptions are automatically caught by the Desktop SDK framework, which generates an error message in the
logs.
Managing Errors Within a Scenario
This default error management is generally not appropriated when errors occur in a control sequence. In most
cases, the required error management method is as follows:
• Inform the user that controlling is encountering a problem.

• Stop the control sequence properly.
You can easily implement this default error management by setting a default error handler in a scenario. To do
this, set the onError handler in the scenario handler:
 Sample Code

{
// Set scenario's default error handler
sc.onError(function (sc, st, ex)
{
// Error occurs : manage it
sc.endScenario();
});
...
}});

Once set, all uncaught exceptions occursing in the control sequence will be routed to this error handler. This
callback receives the following parameters:
• sc : this scenario object

• st : the step where the error occurs
• ex : the exception raised
The generated implementation of the onError handler simply stops the scenario: this behavior can be changed.
Overriding Error Management for One Step
If required in a step, you can override the scenario’s default error handler by setting a default error handler in
the step.
 Sample Code
myApplication.step({ myStep: function(ev, sc, st)

{
st.onError(function (sc, st, ex)
{
// Perform specific management
...
// Optionnaly call the scenario error handler for default management
sc.onError(sc, st, ex);
});
// ...
}});
You can call default error handler by calling sc.onError.
 Note
You can still explicitely catch exceptions in your code. These exceptions will not be routed to the default
error handler.
3.6.10 Managing Timeouts in Scenarios
Desktop SDK implements timeout management within scenarios.
 Tip
To change your timeout values, we strongly recommand setting timeout values in the Workflow Perspective.
For more information, see Setting Timeout Values [page 289].
 Caution
If you manually change the Timeout value in the Editor Perspective, the new value won't be taken into
account. Only the value you set in the Workflow Perspective will be displayed.

Tips to Manage Errors and Timeout
• Do not use onError and onTimeout to manage errors
The onError and onTimeout callbacks are technical callback, once the machine reach these callbacks it’s
too late, you must stop your automation.
Using these callbacks you always must stop the scenario with sc.endScenario(), if you try to continue the
workflow, it will cause trouble in the state machine.
Instead of using these callbacks, it's recommended to close applications, close instance of excel, and write
the error in a custom error log.
 Caution
Do not write asynchronous code or long synchronous code in these blocks, you can have inconsistent
behavior between the agent and the factory.
• Use Try Catch to manage technical errors

To manage error in a scenario that never fails or same scenario with some other actions, you must add the
step code with a try catch in every step.
 Sample Code
GLOBAL.scenario({ scMain: function(ev, sc){

var rootData = sc.data; sc.setMode(e.scenario.mode.clearIfRunning);
sc.setScenarioTimeout(600000); // Default timeout for global scenario.
sc.onError(function(sc, st, ex) \{ sc.endScenario(); }); // Default
error handler.
sc.onTimeout(30000, function(sc, st) { sc.endScenario(); }); //
Default timeout handler for each step.
sc.step(GLOBAL.steps.Custom, GLOBAL.steps.Start_scSubautomatio);
sc.step(GLOBAL.steps.Custom, GLOBAL.steps.errorManagement);
sc.step(GLOBAL.steps.Start_scSubautomatio, null);
}}, ctx.dataManagers.rootData).setId('1c6c65b9-d21b-4867-
a8da-5efc4cb0af2a') ;
// ----------------------------------------------------------------
// Step: Custom
// ----------------------------------------------------------------
GLOBAL.step({ Custom: function(ev, sc, st) {
ctx.workflow('scMain', '64848f39-2e54-4a25-a3aa-a09e9a3f5467') ;
try {
// Some code that raise an error
sc.endStep(); // Start_scSubautomatio
} catch (ex) {
sc.endStep("errorManagementStep");
}
return;
}});
• Use ctx.wait to manage timeout on step

To manage timeout, it's recommended to use ctx.wait, if you add a sc.endStep in this block the endStep
instruction of the step will not be executed.
It’s an excellent way to manage the timeout. The delay of the ctx.wait must be lower than the timeout of the
step (by default 30 seconds)
 Sample Code
GLOBAL.scenario({ scMain: function(ev, sc) {

sc.setMode(e.scenario.mode.clearIfRunning);

sc.onError(function(sc, st, ex) { sc.endScenario(); }); // Default
error handler.
sc.step(GLOBAL.steps.Custom, GLOBAL.steps.Start_scSubautomatio);
sc.step(GLOBAL.steps.Custom, GLOBAL.steps.timeoutManagement);
sc.step(GLOBAL.steps.Start_scSubautomatio, null);
sc.step(GLOBAL.steps.timeoutManagement, null);
}}, ctx.dataManagers.rootData).setId('1c6c65b9-d21b-4867-
a8da-5efc4cb0af2a') ;
// ----------------------------------------------------------------
// Step: Custom
// ----------------------------------------------------------------
GLOBAL.step({ Custom: function(ev, sc, st) {
ctx.workflow('scMain', '64848f39-2e54-4a25-a3aa-a09e9a3f5467') ;
ctx.wait(function(ev){
sc.endStep("timeoutManagement");
}, 29000);
// Some code that wait more than the timeout (30sec by default)
sc.endStep(); // Start_scSubautomatio
return;
}});
• Use sub-automations
You must add the below code on every step.
The best way to manage these errors is to use sub-automations and use the sc.code result. When you use
a sub-automation you can retrieve the result code of the sub-automation to try again or do other actions. In
the sub-automation no need to add ctx.wait or try catch, onError and onTimeout callback will be executed
in the sub-automation and the result code will be affected.
 Sample Code
GLOBAL.step({ Start_scSubautomatio: function(ev, sc, st) {

ctx.workflow('scMain', 'd03b9346-aba8-4b79-99f3-81abffb439ef') ;
// Starts a specified scenario. The data to use and manipulate via
the Scenario can also be specified. The "Wait end" option will launch
a scenario and wait until the scenario terminates successfully. Once the
scenario terminates, execution continues with the next action.
GLOBAL.scenarios.scSubautomation.start(undefined).onEnd( function(scData)
{
if(scData.code == e.error.KO)
{
sc.endStep("errorManagement");
return;
}
else if (scData.code == e.error.TimeOut)
{
sc.endStep("timeoutManagement");
return;
}
sc.endStep(); // end Scenario
return;
});
}});
Different solutions exist to manage different types of timeouts:

• Setting a Timeout for Each Step [page 364]
• Overriding Timeout for One Step [page 364]
• Handling Job Timeout in SAP Intelligent RPA Factory [page 365]
• Managing the Timeout of a Main Scenario Containing Sub-Scenarios [page 366]
• Handling Timeout in a Sub-Scenario [page 367]
• Disabling Timeout [page 368]
For more information about Error Timeout Waiting for Script Execution in SAP Intelligent RPA, see the
following note 2999270
3.6.10.1 Setting a Timeout for Each Step
You can activate it on a scenario by setting the onTimeout handler in the scenario handler:
 Sample Code

{
// Activate timeout management
sc.onTimeout(<duration>, function (sc, st)
{
// Timeout occurs : manage it
sc.endScenario();
});
...
}});
This indicate that the execution duration of any step of the scenario must not exceed the timeout delay (in ms).
If that happens, the onTimeout handler will be called. This callback receives the following parameters:
• sc: this scenario object

• st: the step where the timeout occurs
The generated implementation of the onTimeout handler stops the scenario, but you can change this behavior.
 Note
• By default, timeout management is not activated on scenarios.

• When you create a scenario using a snippet, a timeout management is added in the scenario.
3.6.10.2 Overriding Timeout for One Step
You can override scenario timeout management for one step:
• Activate timeout management for one step

• Change timeout delay for one step
• Change timeout management for one step

To set timeout management for one step, set the onTimeout handler inside the step handler:
 Sample Code
myApplication.step({ myStep: function(ev, sc, st)

{
// override the scenario timeout delay with a '60' s delay
st.onTimeout(60000, function (sc, st)
{
...
// Optionally call the scenario timeout handler for default management
sc.timeoutCallback(sc,st);
});
...
}});
You can call the default timeout handler by calling sc.timeoutCallback.
3.6.10.3 Handling Job Timeout in SAP Intelligent RPA Factory
 Note
In this case, the job timeout comes from the workflow and not from the code.
There are two ways to change default timeouts for steps and scenarios:
• Update them directly in scripts

• Update them in the properties panel of a workflow
If you change timeout values in scripts, this change is taken into account during the debug mode.
However, when the bot will be launched from the Cloud Factory (either in attended or unattended modes),
these new values will not be taken into account. The job will expire after the timeout indicated in the related
workflow (generally 10 minutes after, as this is the default value).
The best practice is to always update timeout values from the Workflow
section. If you udpate from this section, you also update scripts. New
values are thus taken into account in both debug and production executions.
Remember that timeout in the code and timeout in the workflow are different:

• Workflow timeout is the SAP Intelligent Robotic Process Automation Factory timeout
• Scenario timeout is the Desktop Agent timeout (set in the code)
When you create the workflow for the first time and as long as you keep using the merging tool, the timeout
may stay synchronized. Once you start modifying the code and especially the timeout, timeouts of the
workflow (in the UI) and of the scenario (in the code) are desynchronized.
 Sample Code
Modifications of the code never modify the workflow. So, this can lead to a possible desynchronization. If there
is no merging tool, updates of the workflow timeout may not be considered. If the Agent (script) timeout is
greater than the workflow timeout and if the effective time of the bot is greater that the workflow timeout, then
the Factory decides that the job must expire. This also means that the Agent is out of range and won’t try to
communicate with the Factory anymore. For the Factory, the Agent is disconnected.
The job may keep running on the Agent side, especially if:
• Some synchronized code keeps running. This prevents the Agent from getting news from the Factory.
• The Agent gets stuck and does not respond anymore. This prevents the Agent from getting news from the
Factory.
To make sure that your workflow timeout is properly updated, you can also check in the key.xml of the
exported version.
 Sample Code
<WORKFLOWS>
<WORKFLOW Name="synchronousLoop" Src="%workflows%\synchronousLoop.xaml"
CtxtId="082683cd-1868-4151-9552-ec7036c2b683"
DisplayName="synchronousLoop" StepTimeout="30" ScenarioTimeout="60"
GeneratedScenarioName="synchronousLoop" />
<WORKFLOW Name="asynchronousLoop" Src="%workflows%\asynchronousLoop.xaml"
CtxtId="21e817af-425f-4a1a-a3a8-1745e0b4a522"
DisplayName="asynchronousLoop" StepTimeout="30" ScenarioTimeout="600"
GeneratedScenarioName="asynchronousLoop" />
</WORKFLOWS>
3.6.10.4 Managing the Timeout of a Main Scenario

Containing Sub-Scenarios
You sometimes need to increase the timeout of your sub-scenario because it executes tasks for a long period of
time.
If you increase the timeout of your sub-scenario(s), make sure that the step timeout of the main scenario is
higher than the timeout of the sub-scenario(s). All scenario timeouts must be higher than any of their step
timeouts.

To determine the timeout of a scenario, the easiest way is to multiply the number of steps by the step timeout.
However, the best practice is to estimate the real duration of the scenario. Indeed, the default timeout of the
steps is the timeout of the bigger step. The other steps may last less time.
We do not recommended you to put a high value for step and scenario timeouts. The best practice is to have
scenarios which run in less than 10 minutes. For more information, see Disabling Timeout [page 368].
3.6.10.5 Handling Timeout in a Sub-Scenario
A timeout sometimes happens in a sub-scenario.
If the timeout of the sub-scenario is not properly managed by the main scenario, it will be ignored. Moreover,
the main scenario will continue its execution, even if this is not the desired behavior.
To avoid this behavior, you must verify in the onEnd callback function that the ev.code parameter equals OK.
If it does not equal OK, you can consider that the sub-scenario has failed, and you can perform the appropriate
behavior for the main scenario.
 Sample Code
GLOBAL.scenarios.NestedWorkflow.start(undefined).onEnd( function(ev) {
if (ev.code == "OK") {

ctx.log(“Nested workflow has finished normally”);
sc.endStep();
return;
}
else {
ctx.log("Timeout for nested scenario");
sc.endStep();
return;
}
});
3.6.10.6 Disabling Timeout
If you need the user to interact with an application, then you might wonder how long the user will take to do
this. It may be quick or take an undetermined amount of time.
In this case, it’s possible to disable the timeout for a particular step, using the disableTimeout() function.
This function disables the default timeout for this specific step.
 Sample Code
MyAppli.step({ stCRMStart: function(ev, sc, st) {

// disable timeout handler for this step
st.disableTimeout();
…
}});
In the next step, the default behavior will be reused. For steps which don’t require a user interaction, using this
function with scenarios which take a lot of time to be executed is not a best practice. You should estimate the
time of execution of the scenario and change the timeout value depending on this criterion.
Keep in mind that having scenarios which last more than 10 minutes is not a best practice. If your scenario
processes several lines of an Excel file and takes more than 10 minutes to end, you should not use the
disableTimeout() function or put a big value for the timeout. The best practice is to use several jobs to
process the Excel file.
3.6.11 Declaring Environment Variables from SAP Intelligent

RPA Factory
Context
Environment variables in SAP Intelligent RPA Factory are the properties of an environment, re-usable across
multiple projects, packages, and scenarios. Environment variables aim to retrieve common or shared elements
such as credentials for instance.

You can declare text or credential environment variables in a scenario through code.
Procedure
1. Create a text or a credential environment variable in SAP Intelligent Robotic Process Automation Factory.
For more information, see Environment Variables for the Desktop Studio.
2. In the code of the scenario, declare the text or credential environment variable using the following syntax:
 Caution
You must declare environment variables in your scenario with the exact same name than the one
defined during the creation in the Factory.
• Declare a text environment variable named MyVar, stored in an environment on the factory
 Sample Code
ctx.setting({ MyVar: {
key: ctx.cryptography.keys.none,
comment: "Test variable",
server: true
}});
• Declare a credential named MyCred, stored in an environment on the factory
 Sample Code
ctx.cryptography.credential({ MyCred: {
key: ctx.cryptography.keys.none,
comment: "Test credential",
server: true
}});
3. To retrieve the value of the text or credential environment variable, use the following:
• Text environment variable named MyVar
 Sample Code
ctx.settings.MaVar.get(function(code, label, setting) {

if (code === e.error.OK) {
// Display it in the debugger
ctx.log('>> VAR: ' + setting.value);
} else {
ctx.log('Error during setting retrieval');
}
});
• Credential environment variable MyCred

 Sample Code
ctx.cryptography.credentials.MyCred.get(function(code, label, credential) {

if (code == e.error.OK) {
// Display it in the debugger
var user = credential.userName.get();
var pass = credential.password.get();
ctx.log('>>> CODE: OK');
ctx.log('>>> user: ' + user);
ctx.log('>>> pass: ' + pass);
} else {
ctx.log('Error during credential
retrieval');
}
});
Results
3.7 Designing Scenarios Involving Citrix or RDP
SAP Intelligent Robotic Process Automation supports the automation of applications hosted in a Citrix or a
Microsoft RDP environment.
Important Information
Sometimes users need to access applications that are not available on their local machines but only in a Citrix
or Microsoft RDP environment. If you want to develop scenarios to meet this need, there are a few things you
need to know:
• It is not possible for the Cloud Factory to send a job to a specific remote session of a specific user. So the
main scenario of a job runs on the user's local machine and communicates with the job run by an agent in
the remote environment. Data can be passed between the local and remote environments, and user input
can be obtained in the remote environment.
• Desktop Agent needs to be installed on the remote machine as well as on the user's local machine.
• When you develop a scenario and capture an application that will later be executed on a Citrix or RDP
machine, you need to capture that application while it is running in the corresponding remote environment.
That means that Desktop Studio must also be installed in that environment.
• At the Cloud Factory end, you need to define a hierarchy for the user that includes a local machine and
a Citrix or RDP machine. If the user employs the same login to connect to the Citrix or RDP session and
locally, you can define a login hierarchy for the user containing just one node.
• To communicate between remote and local environments, create corresponding local and remote
processes in the project, and use the notify method to send functional events from one to other.

You can find more information in the dedicated Webinar:
Related Information
Example Project [page 371]
3.7.1 Example Project
Context
In this example project, a reference ID from a local Microsoft Excel file is passed in a loop to the CRMWinForm
application running on a Citrix server, and used by that application to search for and return address data, which
is then written to the Excel file.
 Note
Only parts of the code are provided here.
Procedure
1. Create processes for the remote and local environments.
Select Add a New Process … from the context menu in the Projects tree of the Editor perspective.
In the dialog box, you can choose to create the process in a separate project source file. If you name your
process LOCAL, for example, a file named LOCAL.pspc is created in the app folder of the project (see
Project Structure and Organization [page 60]).
The new process is added to the Scripts tree and the Project tree in the Editor perspective, and some code
is automatically generated for its context data structure.

2. In the remote session, capture the CRMWinForm application, its main page, and the necessary fields.
The automatically generated context data structure of the application is as follows:
For more information on context data structures, see Managing Data [page 347].
3. Set the application parameter Server to Citrix or RDP.
4. Create the main scenario, scReadExcelAndSearch, which will do the following:
a. Initialize the Microsoft Excel application.
b. Open an Excel file.
c. Get values from the file.
d. Set the Excel data into an array.
e. Initialize an index for looping.
f. Start the loop.
g. Read a row from the Excel spreadsheet.
h. Start the scSearchAddressCRM scenario.
i. Set values into cells.
j. Increment the index.
k. Exit the loop if the exit condition is met, or loop again.
l. Release the Excel file.
5. In the Properties window, set the Input Data Manager for scenario scReadExcelAndSearch to
CRMWinFormData.
6. Add a local functional event to the code - evSendAddress - which will be defined later.
 Sample Code
LOCAL.addEvent({ evSendAddress: ""});
7. Add and define a server event that starts the scSearchAddressCRM scenario of the local workflow and
then notifies the local server to start the evSendAddress functional event with the search data obtained.
 Sample Code
SERVER.addEvent({ evSearchAddress: ""});

SERVER.events.evSearchAddress.on(function(ev) {
var data = {};

var rootData_CRMWinFormData =
ctx.dataManagers.rootData_CRMWinFormData.create();
rootData_CRMWinFormData.pMainData.oReferenceId = ev.data.referenceId;
GLOBAL.scenarios.scSearchAddressCRM.start(rootData_CRMWinFormData).onEnd( f
unction(scSearch) {
SERVER.notify(LOCAL.events.evSendAddress, scSearch.data);
});
});
8. In the Workflow Perspective, for the scenario scReadExcelAndSearch, select the activity Start
'scSearchAddressCRM', and set the activity property Data used with the scenario to
CRMWinFormData.
9. Create a global workflow step to notify the Citrix server to run the evSearchAddress event and to pass
the Reference ID to the Citrix server. The local evSendAddress event is also defined in this step.
 Sample Code
GLOBAL.step({ Start_scSearchAddress: function(ev, sc, st) {

var rootData_CRMWinFormData = sc.data;
ctx.workflow('scReadExcelAndSearch', '3e974e84-b44f-4b49-
a9cf-5fff150a2f9e') ;
LOCAL.notify(SERVER.events.evSearchAddress,
{referenceId:rootData_CRMWinFormData.pMainData.oReferenceId});
LOCAL.events.evSendAddress.on(function(ev) {
var data = {};
sc.localData.result = ev.data.pMainData;
rootData_CRMWinFormData.pMainData =
ctx.dataManagers.rootData_CRMWinFormData_pMainData.create();
sc.endStep(); // Set_cell
});
}});
10. Define the scSearchAddressCRM scenario that will call corresponding scenario steps to start the
CRMWinForm application, set the Reference ID, click Search, and retrieve information from CRMWinForm.
 Sample Code
GLOBAL.scenario({ scSearchAddressCRM: function(ev, sc) {

var rootData_CRMWinFormData = sc.data;
sc.setMode(e.scenario.mode.clearIfRunning);
sc.onError(function(sc, st, ex) { sc.endScenario(); }); // Default
error handler.
sc.step(GLOBAL.steps.Start_CRMWinForm, GLOBAL.steps.pMain_management);
sc.step(GLOBAL.steps.pMain_management, GLOBAL.steps.Close_CRMWinForm);
sc.step(GLOBAL.steps.Close_CRMWinForm, null);
}}, ctx.dataManagers.rootData_CRMWinFormData).setId('08bc3507-694d-4fa7-
b04d-45735fb02116') ;

3.8 Business Activity Monitoring (BAM)
Business Activity Monitoring (BAM) allows you to insert statements in your scenarios with data sent by your
SAP Intelligent RPA Agent to the Cloud Factory, when the scenario runs.
Cloud Factory will allow you to download a CSV file with useful information about your running scenarios.
The Business Activity Monitoring information is different from the Monitoring view in the Cloud Factory
because it displays data that you choose to generate. For example, you may choose to display how much
time your SAP Intelligent RPA Agents spend accessing a specific application, such as SAP S/4HANA. Or you
may choose to display which machine is used most often to run a particular scenario.
Related Information
Maintain your Landscape
3.8.1 Use BAM in a Project
Procedure
1. Click Edit Project.

2. Go to the Library tab and check Monitor (or in versions of Desktop Studio prior to 1.0.4, this option was
called GalaxyWS).
3. Set any BAM options in the GLOBAL.events.start.on(): function.
4. Insert this first line of code to allow the Agent to send the notifications that are stored locally:
ctx.monitor.startLocalCacheParsing(ctx.monitor.DelayType.LocalCacheParseVeryShor
tDelay);
 Note
We strongly recommend that you insert it in the GLOBAL.events.start.on(): function.
It is mandatory for projects that use BAM.
3.8.2 BAM Statements
There are three types of statements. For a complete description of the different statements, see
Alert Statements [page 375]

Counter Statements [page 375]
Timer Statements [page 376]
3.8.2.1 Alert Statements
Alert statements allow you to send a message, a warning or an error while your scenario is running.
Prerequisites
You have entered this line of code. It is required before sending any notifications:
// sets the user name and machine name from the global context
ctx.monitor.setUserVariables(ctx.options.userName, ctx.options.computerName, '');
Insert an alert statement like the following:
 Sample Code
ctx.monitor.notifyError("Alert1", "Info", "OK", "connection done");
The parameters in brackets represent the information that will appear in the CVS file you will download in the
Cloud Factory. These parameters include:
• "name"
• Choose the name for the notification. We strongly recommend that you pay attention to the name you
give to your alert statement, in order to find it easily.
• The maximum size should be 256 characters.
• "urgency"
• Free text. For example ("Info", "Warning", "Error", … )
• "status"
• Free text. For example ("OK", "KO", "Success", "Fail" … )
• The maximum size shoud be 50 characters.
• [Optional]"data":
• Write your text data for the notification.
• There is no maximum size for this parameter. However, the total value of all the parameters together
should not exceed 50000 characters.
3.8.2.2 Counter Statements
Counter statements allow you to send a notfication about an identified counter and its value. Each time a
counter statement is sent, the given value is stored along with a timestamp. In practice, this means you can
count objects or how many times specific actions occur.
Prerequisites

You have entered this line of code. It is required before sending any notifications:
Insert a counter statement like the following:
 Sample Code
ctx.monitor.notifyCounter("ConnectionCount", "Test counter", "5", "OK");
• "name"
• Choose the name for the notification. We strongly recommend that you pay attention to the name you
give to your counter statement, in order to find it easily.
• "category"
• Choose a category, as a text string.
• "value"
• Choose a value for the counter, as a text string.
• "data":
• There is no maximum size for this parameter. However, the total value of all the parameters together
Example Use Case
You can count the number of times the scenario has gone through a certain piece of code.
3.8.2.3 Timer Statements
Timer statements allow you to start timers, reset timers, and split timers. You begin with a start timer
statement and in subsequent statements, you can split the timer or finally reset the timer.
There are 3 types of BAM timer statements
• Start Timer Statement [page 377]

• Split Timer Statement [page 378]
• Reset Timer Statement [page 379]

3.8.2.3.1 Start Timer Statement
Start timer statements allow you to start a timer. You begin with a start timer statement and you can use the
same name for subsequent timer statements (split or reset timer statements).
Prerequisites
You have entered this line. It is required before sending any notifications:
Insert a start timer statement like the following:
 Sample Code
ctx.monitor.initProcessNotification("A1", "Started", 5000, 15000);
• "name"
• Choose a name for the notification.
• "step"
• Choose a name for the step in the timer.
• "minimum"
• Set a minimum value in milliseconds. If subsequent timer statements start before this time value, there
is no notification.
• "maximum"
• Set a maximum value in milliseconds. If subsequent timer statements start after this time value, there
is no notification.
 Note
The type of information you write depends on the position of the parameter. For example, if you write the
"name" of your notification in second position, the information will be registered as the name of the "step".
 Note
Some parameters do not have a maximum size. However, the total value of all the parameters together

3.8.2.3.2 Split Timer Statement
Split timer statements allow you to send an intermediate duration for a previously started timer.
Context
The split timer allows the Agent to send a message counting how much time passes between the execution of
the start timer statement and the execution of the split timer statement.
Prerequisites
1. You have entered this line. It is required before sending any notifications:
ctx.monitor.setUserVariables(ctx.options.userName, ctx.options.computerName,
'');
2. You have set a start timer.
Insert a split timer statement like the following:
 Sample Code
ctx.monitor.sendProcessNotification("A1", "Step 1", "OK", "A1 process Step 1

complete");
• "name"
• Choose a name for the notification. The name must match a previously started timer.
• "step"
• Choose a name for the step in the timer. The name must match a previously started timer.
• "status"
• Free text. For example ("OK","KO","Success","Fail"...)
• [Optional]"data"
• [Optional]"force send"
• Enter a boolean variable. A notification is sent even if there is no initProcess.
• [Optional]"reset timestamp"
• Enter a boolean variable. It resets the timer to zero.
• [Optional]"minimum"
• Set a minimum value in milliseconds. If subsequent timer statements start before this time value, there
is no notification.
• [Optional]"maximum"
• Set a maximum value in milliseconds. If subsequent timer statements start after this time value, there
is no notification.

 Note
The type of information you write depends on the position of the parameter. For example, if you write the
name of your "step" in third position, the information will be registered as the "status" of your statement.
 Note
Some parameters do not have a maximum size. However, the total value of all the parameters together
3.8.2.3.3 Reset Timer Statement
Reset timer statements allow you to reset a previously started timer statement without sending a notification.
Prerequisites
1. You have entered this line. It is required before sending any notifications:
ctx.monitor.setUserVariables(ctx.options.userName, ctx.options.computerName,
'');
2. You have set a start timer statement.
Insert a reset timer statement like the following:
 Sample Code
ctx.monitor.resetProcessNotification("A1");
The parameter in brackets represents the information that will appear in the CVS file you will download in the
Cloud Factory. The parameter is:
• "name"
• Choose a name for the notification. The name must match a previously started timer.
3.8.2.4 Configure and send notifications
Three options allow the Agent to monitor the duration between timer statements. The Agent creates a file
locally where it stores notifications about the statements actions, before it sends them to the Cloud Factory.
 Note
To learn where to set these options, see Use BAM in a Project [page 374].

Very Short Delay
The Agent will wait until the end of the delay, send the file containing the notifications to the Cloud Factory, and
finally delete them from the local file. The default time value is 5 minutes.
To change this value, insert a code like the following and set a value in milliseconds:
 Sample Code
ctx.options.monitor.localCache.parseVeryShortDelay = 1000;
Short Delay
If one of the notifications in the file sent by the Agent to the Cloud Factory is invalid, the Agent will slow down
and use the short delay instead. The default time value is 30 minutes.
 Sample Code
ctx.options.monitor.localCache.parseShortDelay = 1000;
Long Delay
If too many messages are sent at once, the Cloud Factory notifies the Agent and protects the service from
excessive messages.. The Agent will slow down and try to send the extra messages with the long delay. The
default time value is 4 hours.
 Sample Code
ctx.options.monitor.localCache.parseLongDelay = 1000;
3.9 Script Management

3.9.1 Add a New Script
Context
By default, each new script is included in the GLOBAL process. If you want to include a new script in another
application, right-click the application node in the Project tree and select Add a new Script.
 Note
This is required for backwards compatibility; there is no particular advantage in including a script in an
application rather than in the GLOBAL process.
Procedure
1. Right-click outside any node of the script tree and select Add a new Script.
The following dialog appears in which you can enter the file name, the name that will appear in Desktop
Studio, and any comments.
If you enter an existing file name is used, the corresponding script is included in the project. The file
content remains unchanged.
To enable breakpoints to be inserted into the new script, the script must have a unique name.
2. Click Ok to validate your entries.
The new script file is physically created in the “local” subdirectory of the project (see Project Structure and
Organization [page 60]).

3.9.2 Edit a Script
Context
You can use this procedure to edit a script. If you want to edit a framework or library script, you require special
authorizations. These scripts are usually displayed in read-only mode.
Procedure
Double-click the script's node in the script tree.
If you double-click a MapItem node in a script (such as a function or scenario), the script opens in edit mode
and the system automatically navigates to the corresponding code block within the script.
If the script is already open in a code editor, the instance is brought to the front. Otherwise, a new instance is
opened with the selected script in edit mode.
3.9.3 Move a Script to Another Folder
Context
You can add a script to an existing folder or create a new folder and add your script there. The folder is not
physically created on the disk; it is a logical folder only.
 Note
You cannot add folders to other folders. Only single-level folders are supported.
Procedure
Proceed as follows:
Option Description
Add a script to a new 1. Right-click the script node in the script tree and select Create Folder.
folder

Option Description
Desktop Studio creates a new folder and moves the selected script into it.
2. Rename the folder by selecting it and pressing F2 .
Move a script to an ex Drag and drop the script to the folder node in the script tree. (To move a script out of a folder, drag
isting folder and drop it from the folder in the script tree.)
3.9.4 Rename a Script
Context
Changing the name of a script in Desktop Studio only changes the logical name. The name of the physical file
containing the script is not affected.
Procedure
1. Select the script in the script tree and press F2 .

2. Enter the new name for the script and press ENTER .
3.9.5 Exclude a Script
You can temporarily exclude a script from compilation and execution.
Procedure
1. Right-click the script node in the script tree and select Exclude Script.
2. Confirm your decision.

3.9.6 Delete a Script
You can delete a script from your project.
Context
Deleting a script doesn't delete the script file on the disk.
Procedure
1. Right-click the script node in the script tree and select Delete Script.
2. Confirm your decision.
3.9.7 Editing the XML List of Scripts
Although not recommended, you can directly edit the XML code that describes the list of scripts.
Context
 Caution
If you follow this procedure and leave the XML code open, it will not be synchronized with any further
modifications made in the project tree. To avoid losing modifications, save and close the editor as soon as
possible.
Procedure
1. Double-click the SCRIPTS node of the GLOBAL process in the project tree.
The corresponding XML code opens in a new code editor instance.

2. Edit and save the XML.
The script tree is refreshed to reflect the modifications.
3.10 Systray and Menu Bar Management

The ctx.systray class implements the systray menu and menu bar that can be created at project launch.
When creating a new SAP Intelligent RPA project with the standard template, a systray is created by default,
containing standard menus, such as Stop and About box.
Main Steps to Create and Use a Systray Object
Initialize Systray
Systray initialization is performed once the engine is started, in other words, inside a GLOBAL:START handler.
 Sample Code
// create a global object ''systray''

var systray = ctx.systray(); // you can optionally provide a name, default is
'systray'
...
GLOBAL.events.START.on(function (ev)
{
// Create systray
systray.createSystrayMenu(ctx.options.projectName, 'ICON1', 'FILE', '/bmp/
chart_pie.png');
// initialize systray here...
});
 Note
This code is automatically generated when a project is created.
Add Menu Items

Once the systray is initialized, you can add menus, sub-menus, and menu items to it using the addMenu
method:
 Sample Code
{
// menu and sub-menus
systray.addMenu('', 'MainMenu', 'Main menu');
systray.addMenu('MainMenu', 'evMenu1', 'Menu 1');
systray.addMenu('MainMenu', 'evMenu2', 'Menu 2');
});
You can load bitmaps to be added as menu icons using the loadImage method:
 Sample Code
{
systray.loadImage('stop', 'FILE', e.popup.icon16.stop);
systray.loadImage('factory', 'FILE', '/bmp/factory.png');
...
systray.addMenu('MainMenu', 'evMenu1', 'Menu 1', 'factory');
});

You can use ‘e.popup.icon16’ enumeration or a filename relative to the local folder. It is also possible to use a
SDK resource by means of a RESOURCE declaration.
 Sample Code
<RESOURCES>

...
<RESOURCE Name="factory 16px" Src="%sdk%
\templates\resources\bmp\factory.png" Dest="bmp" />
</RESOURCES>
To handle the activation of a menu item, set a menu handler using the on method:
 Sample Code
// 'Menu 1' menu handler

systray.on('evMenu1', function (ev) {
// add code here
});
If the function is simple enough, the menu declaration and the implementation can be managed in a single
function:
 Sample Code
// declaration menu and implement function

systray.addMenu('ScnAppMenu', 'evScnAppStartScn', 'Start data collection',
'', function(ev) {
var scn = ScnApp.scenarios.scCollectData.start();
});
You can add test menus that only appear in Debug mode (hidden in production mode) using theisDebug
property:
 Sample Code
if (ctx.options.isDebug) {
systray.addMenu('', 'TestMenu', 'Test Menu');
systray.addMenu('TestMenu', 'evTestVariables', 'Test Variables');
...
}

Customize the Systray At Runtime
The systray is created at project launch.
• During execution, the systray can be modified to reflect state changes using the show method:
 Sample Code
// hide systray
systray.show(false);
• The menu can be checked / unchecked using the check method:
 Sample Code
// check menu
systray.check('evScnAppStartScn', true);
• The menu can be enabled / disabled using the enable method:
 Sample Code
// disable menu
systray.enable('evScnAppStartScn', false);
• The systray icon can be changed dynamically using the createSystrayMenu method:
 Sample Code
// create systray and load two icons
var projectIcon2Enabled = false;
ctx.options.projectIcon = '/bmp/chart_pie.png';
systray.loadImage('ICON1', 'FILE', ctx.options.projectIcon);
systray.loadImage('ICON2', 'FILE', '/bmp/record.png');
systray.createSystrayMenu(ctx.options.projectName, 'ICON1');

...
// add a menu to toggle systray
systray.addMenu('', 'evChangeSystrayIcon', 'Change systray icon',
'ICON1', function(ev) {
projectIcon2Enabled = !projectIcon2Enabled;
var icon = (projectIcon2Enabled ? 'ICON2' : 'ICON1');
systray.createSystrayMenu(ctx.options.projectName, icon);
});
});
Systray Balloons
A tooltip balloon can be displayed above the Desktop Agent systray icon using the showBalloon method:
 Sample Code
// show balloon
systray.showBalloon(ctx.options.projectLabel
, 'Ready for testing...'
, e.systray.iconType.Warning
, 10000);
 Note
Tooltip balloons can be disabled or hidden by the user at runtime. That means tooltip balloons should not
be used for important information, but only for progress indications, for example.
Menu Bar
A menu bar is a basic Windows menu displayed at the top of the screen.
It contains buttons or menus on the left and a label on the right:
Creating and managing a menu bar is similar to a systray:
• The main difference is to create the object by calling createBarMenu instead of createSystrayMenu.
• Adding and modifying menus is then done the same way
• The text of the Label can be modified by using the setTitle method.
 Sample Code
// *** menuBar object ***

var menuBar = ctx.systray('menuBar');
...
{
// initialize bar menu here
menuBar.createBarMenu(ctx.options.projectName, 'ICON1');
// add menu items
menuBar.addMenu('', 'evVersion', 'About... ', 'about');
...
});
3.11 Display Message Boxes
You can easily display various types of message box using Desktop SDK popups. For a detailed description of
using Desktop SDK popups, see Managing Popups With Desktop SDK [page 397].
There are various use cases, as described below.
Display a Popup with a Simple Message and an OK Button
The following sample allows you to:
• Display a popup with a simple message.

• Wait until the user closes the popup to continue controlling.
 Sample Code
// create the popup using the 'e.popup.template.Ok' template

var myPopup = ctx.popup('pMyPopup', e.popup.template.Ok) ;
// display the popup, setting title and message
myPopup.open({ title: 'my Title', message: 'my message'});
// wait until user closes the popup
myPopup.waitResult(function(res)
{
// user has closed the popup, continue controlling
....
});

Display a Popup with a Rich Message
• Display a popup with a message in rich format and an icon.

• Wait until the user closes the popup to continue controlling.
A rich formatted message can be displayed using HTML tags.
 Sample Code
// create the popup using the 'e.popup.template.Ok' template

var myPopup = ctx.popup('pMyPopup', e.popup.template.Ok) ;
// Build the formatted message

var myMessage = "<H4>My message header</H4>"
+ "Project Version: <b>3.1</b><br/>"
+ "Product Version : <b>3.0.4.1</b><br/>" ;
// display the popup, setting title and message

myPopup.open({ title: 'my Title', message: myMessage
, icon: '/bmp64/hello128.png'});
// wait until user closes the Popup
{
// user has closed the popup, continue controlling
....
});
Display a Popup with a Question and Yes and No Buttons
• Display a popup with a question

• Wait until the user closes the popup
• Continue controlling depending on the user’s choice.
 Sample Code
// create the Popup using the 'e.popup.template.YesNo' template

var myPopup = ctx.popup('pMyPopup', e.popup.template.YesNo) ;
myPopup.open({ title: 'my Title', message: 'my question'});

// wait until the popup closes
{
if (res == e.popup.button.Yes)
{
// user clicked on 'Yes' button : continue controlling
}
});
Display a Popup with Customized Buttons
• Display a popup with a question and customized buttons.

• Wait until the user closes the popup.
• Continue controlling depending on the user’s choice.
 Sample Code
// create the Popup using the 'e.popup.template.OkCancel' template

var myPopup = ctx.popup('pMyPopup', e.popup.template.OkCancel);
myPopup.open({title: 'my title',message: 'Go where ?',
buttons: {
here: {label: 'Go here'} ,
there: {label: 'Go there'}
}
}) ;

{
if (res == 'here') {
// user clicked on 'Click Here' button : continue controlling
}
});

Display a Waiting Message in Screen Corner
• Display a popup with a waiting message in the bottom right corner, with sliding effect.
• Execute controlling.
• Close the popup when controlling is finished.
 Sample Code
// create and display the tooltip using the 'e.popup.template.Tooltip'

template
ctx.popup('pProgress').open({
template: e.popup.template.Tooltip,
icon: e.popup.gif.loader4,
message: "<b>Automation in progress.</b><br/>Please wait...",
color: e.popup.color.Orange
});
// Execute controlling
....
// closes the popup when controlling has finished

ctx.popup('pProgress').close() ;
Display a Popup with Dynamic Content
• Display a popup with customized HTML content including javascript code and links.
• Wait until the user closes the popup by clicking on one link.
 Sample Code
// build HTML content

var label = "<script>function cl(element) { close(element.id); }</script>";
label = label + "<p>Choose one of the following options :<br/><br/>";
label = label + "<a href='javascript:void(0)' id='Option1'
onclick='cl(this);' > ";
label = label + "<b> Option 1 </b> </a><br/>";
label = label + "<a href='javascript:void(0)' id='Option2'
onclick='cl(this);' > ";
label = label + "<b> Option 2 </b> </a><br/></p>";
// Create and open the popup

var pMyPopup = ctx.popup('myPopup', e.popup.template.NoButton) ;
pMyPopup.open({ message: label }) ;
// wait until user closes the popup

pMyPopup.waitResult(function(res)
{

ctx.log('Clicked button: ' + res);
});
Display a Popup with Customized Content
• Display a popup with customized content.

• Wait until the user closes the popup.
 Sample Code
var myPopup = ctx.popup('pTestBootbox', e.popup.template.OkCancel);

myPopup.open({
title: 'Bootbox title 2',
titleIcon: e.popup.icon16.agent,
header: '<img src=\"../bmp32/dice.png\"/> Custom dialog',
message: 'I am a custom dialog, <b>designed for test</b><br/><img src=\"../
bmp64/comp2.png\"/><img src=\"../bmp64/comp3.png\"/>',
buttons: {
main: {
label: 'Click Here',
icon: e.popup.buttonIcon.check
}
}
}) ;

{
ctx.log("pTestBootbox : '" + res + "' was clicked");
});

3.12 Display Tooltips
You can easily display various types of tooltips using the tooltip method.
There are various use cases, as described below.
Display a Tooltip with Help Message Associated with a Field
• Display a tooltip associated with the ‘myField’ field of the ‘myPage’ page
• Highlight this field
• Automatically close the tooltip and remove the highlight after three seconds
 Sample Code
myAppli.myPage.myField.tooltip({
message: "<b>Equipent type</b><br/>Select some equipment",
icon: e.popup.icon32.user,
color: e.popup.color.Blue,
autoClose: 3000,
highlightColor: ctx.rgb(20, 20, 150)
});
Highlight a Field with an Error
• Display a tooltip with an error message associated with the ‘myField’ field of the ‘myPage’ page
• Highlight this field with a red border
• Automatically close the tooltip and remove the highlight after three seconds
 Sample Code
var timer=3000;
// Display the tooltip with error message

myAppli.myPage.myField.tooltip({
message: "<b>Error here</b><br/>Add extra information below",
icon: e.popup.icon32.error,
autoClose: timer,
highlight: false,
color: e.popup.color.Red
});
// Highlight
myAppli.myPage.myField.highlight(timer);
Display Tooltips with Maps or StreetView Content
 Sample Code
timer = 10000;
var color = ctx.rgb(0, 0, 0x80);
var address = data.address + ' ' + data.ZIPCode + ' ' + data.city;
CRM.pCRM.edAddress.tooltip({
template: e.popup.bootbox.Maps,
maps: {
zoom: 14,

address : address
},
fade: 1000,
autoClose: timer,
XRelative: e.popup.position.Right,
YRelative: e.popup.position.Top,
highlightColor: color
});
CRM.pCRM.edZIPCode.tooltip({
template: e.popup.bootbox.Maps,
maps: {
streetview: true,
zoom: 1,
width: 500,
height: 350,
address : address
},
fade: 1000,
autoClose: timer,
XRelative: e.popup.position.Right,
YRelative: e.popup.position.Bottom,
highlightColor: color
});
CRM.pCRM.edCity.highlight(timer, true, true, color);
3.13 Managing Popups With Desktop SDK
Desktop SDK allows you to manage various types of popup:
• Simple message boxes

• Simple or sophisticated input forms
• Tooltips
• Application bars
HTML-Based Content
Desktop SDK popup content is an HTML page.
To meet specific needs, it is necessary to develop a custom HTML page.
Desktop SDK implements the concept of a popup template. This overcomes the need to develop an HTML page
whenever you require a popup.
Using Popup Templates

A popup template is a Desktop SDK popup based on a predefined customizable HTML page.
Desktop SDK provides a set of predefined popup templates:
• Message box templates

• Input form templates
• Tooltip templates
• Application bar templates

To display the popup, you simply create it based on the right template and customize it to meet your
requirement. You can customize:
• Its title and the message displayed

• The icon displayed
• Its size and position
• Its HTML content
Main Steps to Create and Use a Popup Oobject

Here is the general way to display a popup:
• Create a popup instance from the right template

• Customize this popup instance to match the specific needs
• Open it and wait for the user to close the popup
• Get result data from the popup
3.13.1 Create a Popup
Popup management is implemented via the ctx.popup class.
A popup instance is created using the ctx.popup method.
 Sample Code
var popup = ctx.popup('<popup name>'[, <template name>]) ;
where:
• <popup name> is the name given to the popup,

• <template name> is the name of a template (optional).
If a popup instance with the same popup name has already been created, this existing instance is returned.
 Note
• Be careful when using popup names. If you use the same name for all popups, you create only one
popup instance. Customization made for one popup remains unchanged for the next one until it is
modified
• A template name can be provided later, using the init or the open methods,
• You can use the ctx.popup + TAB snippet to automatically generate code.
3.13.2 Customize the Popup
A popup can be customized by setting some of its properties values using the init method (or directly using the
open method)

 Sample Code
var myPopup = ctx.popup('myPopupName') ;

myPopup.init(
{
<propertyName> : <propertyValue>,
...
<propertyName> : <propertyValue>
}
);
where:
• <propertyName> is the name of a ctx.popup property

• <propertyValue> is its new value
Customize the Popup Container
The popup container can be customized by setting the following properties:
Title bar attributes title, titleVisible, canClose, etc.
Position X, Y, CX, CY, resizable, canMove, etc.
Effects (fading / sliding) XSlide, YSlide, fade, etc.
Misc. attributes modal, topMost, showToolbar, etc.
 Note
If the popup size and position are not set, they are automatically calculated by the Desktop SDK.
Customize the Content of a Popup Based on a Desktop SDK Template
The set of properties available to customize the display inside the popup depends on the template used. Here
is a subset of available properties:
Attributes Description
message HTML message to be displayed
header HTML title to be displayed in the header part of the popup
icon path of the icon to be displayed on the left of the message

Attributes Description
color popup background color
buttons list of buttons to be displayed
form form description
Customize the Content of a Popup Based on an External HTML Page
As mentioned early, you can use a specific HTML page instead of the predefined Desktop SDK Templates.
This is done by setting the <url >property with the path of the specific HTML page:
 Sample Code
url: '/popup/myPopup.html',
To use parameters from the SAP Intelligent RPA script inside the HTML page:
• In the HTML page, implement the initialize JavaScript method,

• In the SAP Intelligent RPA script, set the required parameters as properties of the popup object.
When the HTML page is loaded inside the popup, the properties set on the popup object are transmitted to the
HTML page so that content is initialized.
In the SAP Intelligent RPA script:
 Sample Code
var myPopup = ctx.popup('pMyPopup') ;

myPopup.init(
{
template: e.popup.bootbox.None,
url: '/popup/myPopup.html',
title: 'my Title',
myParam: 'my Param value'
});
In the myPopup.html page:
 Sample Code
function initialize(properties)
{
var myParamValue = properties.myParam ;
// Customize myPopup.html content base on myParamValue
...
}

Samples
Customizing a Simple Message Box
 Sample Code
var myPopup = ctx.popup('pMyPopup', e.popup.bootbox.Ok) ;

myPopup.open({
title: 'my Title',
message: '<H4>Project Version: <b>3.1</b><br/></H4>'
});
For more examples for Message Boxes, see Display Message Boxes [page 390].
Customizing a Login Form
 Sample Code
var myPopup = ctx.popup('pLogin', e.popup.bootbox.FormSubmit);

myPopup.open(
{
title: 'Bootbox Login form',
message: '<b>Set your login and password</b></br></br>',
form: {
id: 'inputForm',
group: [
{
label: {value: "Username",width: 3},
text: {name: "username",width: 9}
},{
label: {value: "Password",width: 3},
password: {name: "password",width: 9}
}
]
}
});

For more details, see Manage Input Forms
3.13.3 Open the Popup
You open a Popup using the open method:
 Sample Code
var myPopup = ctx.popup('myPopupName') ;

myPopup.init({...}) ;
myPopup.open(
[{
<propertyName> : <propertyValue>,
...
<propertyName> : <propertyValue>
}]
);
where:
• <propertyName> is the name of a ctx.popup property

• <propertyValue> is its new value.
 Note
• You can customize the popup using the init method or using the open method.
• If you call the open method on a popup that is already open, the popup is simply updated with the new
property values.
Modal or Modeless Mode
The mode of how the popup is opened (modal or modeless) is set by the ‘modal’ property:
• In Modal mode, the JavaScript code is blocked on the open call until the popup closes
• In Modeless mode, the open call returns immediately; an asynchronous handler can detect window
closure. The method popup.waitResult(…) is called in an asynchronous style.
The ‘Modal mode’ is not recommended because it locks any SAP Intelligent RPA treatment until the popup is
closed.
 Note
• An open modeless popup can be closed at any time using the close method.
• A modal popup cannot be closed by code as SAP Intelligent RPA treatment is blocked on the ‘open’
call.

Bring Popup to Top
It is not possible to force a popup to be on the top of a specific application. However, you can force a popup to
be on the top of all applications using the ‘topmost’ property:
 Sample Code
var myPopup = ctx.popup('pMyPopup', e.popup.bootbox.Ok) ;

myPopup.open({
topmost: true,
title: 'my Title',
message: 'my Message'
});
3.13.4 Wait Until the Popup Closes and Get the Popup Result
You can wait until the popup closes using the waitResult method:
 Sample Code
myPopup.open();
{
// myPopup has closed : make treatments
...
});
By calling the waitResult method, you set a callback that will be called when the popup is closed. If the popup is
already closed when calling the waitResult method, the callback is triggered immediately.
The callback receives an object as parameter. It contains the popup result. This result depends on the template
used:
• For a Display popup, the result is the id of the clicked button.

• For an Input form, the result is an object with input values.

4 Managing Custom Pages With UI
Designer
UI Designer Overview
Desktop Studio includes a UI Designer perspective. This perspective makes it possible to graphically design:
• Input Forms
• Custom pages
• Application bars
For simplicity's sake, all these types of UI will be referred to as custom pages.
For a complete description of this perspective, see The UI Designer Perspective [page 33]
Principles
UI Designer is a graphical wrapper based on the Bootstrap-3 framework.
Using UI Designer, every custom page is an empty HTML page whose content is dynamically built using
JavaScript code. When you edit a custom page, UI Designer displays it graphically in an embedded Internet
Explorer window (the Design view[2]).
Graphic/JavaScript Design
When you graphically design your page, UI Designer automatically generates the JavaScript code in the
settings.js file.
This file contains the description of all created items.
If you prefer, rather than editing the page graphically, you can edit the settings.js file [3]. When you save it, the
Design view and the Resource tree are automatically updated to reflect your changes.

404 PUBLIC Managing Custom Pages With UI Designer
Edit this file with care:
• If you make errors in JavaScript code, rendering will fail with scripting errors.
• You then have to find your error(s) to be able to continue your design.
Use a Custom Page in the Workflow Designer

You can integrate your custom pages into your workflows using the Workflow Designer.
Custom pages are displayed in the Activities window, in the Pages tab item, under the POPUPS application. To
be displayed there, a custom page must first be captured ( ).
Manage Custom Pages By Script

Custom pages designed by UI Designer can be managed by script like any other Web page:
• you set item value using the set method:
 Sample Code
POPUPS.myPopup.myItem.set(theValue);
• you get item value using the get method:
 Sample Code
var theValue = POPUPS.myPopup.myItem.get();
• you click an item using the click method:
 Sample Code
POPUPS.myPopup.myItem.click();
Main Steps in Designing a Custom Page
The main steps involved in designing a custom page are:
1. Create a new popup

2. Set the popup's properties
3. Design the grid
4. Create items
Create a New Popup
Create the Popup

Create a new popup and choose the right template, depending on requirements. Popup templates are provided
by the Desktop SDK, and new templates will be added in the future.

Managing Custom Pages With UI Designer PUBLIC 405
Here are the most commonly used templates:
• Empty Appbar: to create a custom page embedded in a Windows Appbar

• Empty Popup: to create from scratch any other custom page
After validation, UI Designer:
• Creates, if necessary, a subdirectory for the new page in the ‘local’ folder of your project.
• Creates the following files in this subdirectory:
• Popup.html: This is the empty HTML page
• Settings.js: This is the javascript file containing the design of the page
• ‘Popup.js’ and ‘Popup.css’: allows you to customize the page behaviour and the style sheet (see
Advanced Techniques for Custom Page Design [page 417])
Set Popup Properties

If necessary, you can change the popup properties by:
• Right-clicking it in the Resource tree and selecting the ‘Edit’ menu

• Changing the desired properties in the ‘Properties’ window
Here are the most commonly used properties:
• Position
• CX, CY: width and height of the page. A red rectangle is displayed in the Design View [2] to make it easy
to set these properties.
• Display: when using multiple screens, this allows you to choose on which screen the page is displayed
For an AppBar, the most commonly used property is:
• Html content:
• template : choose ‘AppBarHorizontal’ for a horizontal AppBar, or ‘AppBar’ for a vertical one
Design the Grid
Bootstrap Grid System

According to the Bootstrap-3 framework, a page is considered to be a grid of rows, with each row having a
width of 12 units.
A row can contain columns, each column having a width of between 1 and 12 units.
Create the Grid
With Design mode active ( ), right-click within the page to add container items (containers, rows, columns,
and so forth).
Each new item is added to the Resource tree [1], under the Items node. The item subtree reflects the structure
of the grid.
You can change this grid structure via drag&drop in the Resource tree.
Set Column Width

To complete the grid, you must change the width of some columns (see Set Item Properties).

 Note
A column has four different width properties, one for each type of computer
You can set a different width value for each property. Alternatively, you can only set one value, leaving the
others as 0. This way, UI Designer will then use this value for all types of computer.
Create Items
Create the Items
With Design mode active ( ), right-click within the page to add items (such as a button). Each item is mapped
to a Bootstrap component).
Each new item is added out of the grid, under the Items node. The Item subtree reflects the item hierarchy in
the page.
You can move the new item in the grid under a container item via drag&drop in the Resource tree.
Set Item Properties

If necessary, you can change an item’s properties by:
• Right-clicking it in the Resource tree and selecting the Edit menu

• Changing the desired properties in the Properties window
If you change one property, the change is automatically reported in the Design view.
Here are the most commonly used properties:
• General properties
• id: the item's unique ID
• parent: ID of the row or column which contains the item
• auto-declaration: If checked, the item can be managed using the standard methods (such as get
and set)
• Display properties
Main Steps in Managing a Custom Page
Instantiate a Popup
Popup management is implemented via the ctx.popupclass class.
A popup instance is created using the open method:
 Sample Code
// Instantiate myPopup
POPUPS.myPopup.open() ;

where:
• POPUPS is the predefined application name for all popups designed using UI Designer,
• myPopup is the name of your popup.
Fill the Popup Items

Once you have instantiated a popup, you can initialize as follows:
 Sample Code
// Wait until myPopup opens

POPUPS.myPopup.wait(function(ev)
{
// Set myPopup item's value
POPUPS.myPopup.myItem1.set(myData1);
});
Test Your Page

The settings.js file contains an onTest method which is called when the popup loads. You can add your
own javascript code to test your popup (for example, set item value).
 Sample Code
POPUPS.myPopup.onTest(function(popup)
{
// TODO : add your tests here
});
Wait until the Popup Closes and Get the Popup Result
You can wait until the popup closes using the waitResult method:
 Sample Code
// Wait until myPopup opens

POPUPS.myPopup.wait(function(ev)
{
// Set myPopup item's value
});
POPUPS.myPopup.waitResult(function(res, ev)
{
if (res == "myBtOk")
{
// user has clicked on myBtOk : collect data
myData1 = POPUPS.myPopup.myItem1.get();
myData2 = POPUPS.myPopup.myItem2.get();
// and continue automation
sc.endStep();

}
else if (res == "myBtCancel")
{
// user has clicked on myBtCancel : ... cancel automation
sc.endScenario();
return ;
}
});
By calling the waitResult method, you set a callback that will be called when the popup is closed. If the
popup is already closed when the waitResult method is called, the callback is triggered immediately.
The callback receives an object as a parameter. This contains the popup result. The result depends on the
template used:
• For a Display popup the result is the ID of the clicked button.

• For an Input form the result is an object containing the input values.
4.1 The UIDesigner Perspective
The UIDesigner perspective is where you design user interfaces, such as input forms or custom pages. When
you select the UIDesigner perspective tab, Desktop Studio displays the UIDesigner perspective panel:
• The Resources tree (1)

• The popup editor zone (2)
• Various tool windows (3, 4) that can be docked around it.

The Resources Tree
The Resources tree displays a list of the popups included in the project. It allows you to:
• Manage the popups included in the project

• Manage the list of files used by the popup
• Manage the list of items of a popup
Manage the Popups Included in the Project
Add a new popup: To create a new popup, right-click the POPUPS root node of the Resources tree and select
Add a new Popup … from the context menu. This displays a dialog where you have to:
• Enter the name of the popup – this name must be unique among the popups of the project
• Choose the template that best meets your needs
Edit a popup: To edit a popup, right-click the corresponding Popup node in the Resources tree and select Edit
from the context menu. A new editor then opens in the popup editor zone.
 Note
If the popup editor is not yet open, the properties of the popup are displayed in the Properties tool window.

Delete a popup: To delete a popup, right-click the popup node in the Resources tree and select Delete from the
Manage the List of Files Used by the Popup
Each popup subtree displays the list of files used by the popup:
• Popup.html: the HTML page

• Settings.js: the JavaScript file containing the page design
• Popup.js and Popup.css: let you to customize the page behavior and style sheet (see Advanced
Techniques for Custom Page Design [page 417])
This list automatically includes all of the project files in the page subdirectory found in the local folder of your
project.
Add a new file: To add a new JavaScript or CSS file:
• Right-click the popup node in the Resources tree and select Add a new file … from the context menu
• Enter the name and the type in the displayed popup and validate
• It is added to the Resources tree, which means you can edit it in the UI Designer
•  Note
The new file is automatically included in the popup.html file.
You can also manually add any existing file (for example, an image) as follows:
• Copy the file to the page subdirectory

• Refresh the Resources tree by selecting Refresh file list from the context menu
The added file appears in the Resources tree, allowing you to edit it in the UI Designer.
 Note
In this case, the added file is not included in the popup.html file. If necessary, update the file manually.
Edit a file: To edit a file:
• Right-click the file node in the Resources tree

• Select Edit from the context menu
• If necessary, the associated popup is then opened in the popup editor zone
• The file is opened for editing in its editor zone
Delete a file: To delete a file, you need to remove it manually in Windows Explorer. If necessary, manually
update the popup.html file to remove any “include” clauses.
Manage the List of Items of a Popup
The Popup subtree also contains an Items node that contains a hierarchical view of the popup items.
Add a new item: You cannot add a new item using the Resources tree. You must do it in the Designer view.
Edit an item: To edit an item, right-click the Item node in the Resource tree and select Edit from the context
menu. The item properties are then displayed in the Properties window, where you can edit them.

Move an item in the hierarchy: Some items are container items that accept other items as children. This
enables you to build a hierarchy of items.
You can move an item within the hierarchy using drag&drop in the Resources tree.
Delete an item: To delete an item, right-click the Item node in the Resources tree and select Delete from the
 Caution
If you delete a container item that has children, the children will be deleted too.
Popup Editor Zone
The popup editor zone allows you to design popups. It can contain one or more popup editors, each of
which lets you design one popup. You can switch between them using the document selector (see The Editor
Perspective [page 23]). Each popup editor instance consists of the following:
• The designer view (1)

• The editor zone (2)
The Designer View
The designer view displays the popup in an embedded Internet Explorer window. This allows you to graphically
design your popups. The toolbar contains the following items:
• : Refresh the design view from the settings.js JavaScript file
• : Switch design mode on/off
• : Switch test mode on/off
• : Open the popup in an external Internet Explorer browser
• : Capture the popup to make it available in the workflow designer
• : Replace the popup
Design Mode
When design mode is active, each item is surrounded by a dotted rectangle with the Name property in the
top-right corner. In this mode, you can:
• Add new items

• Select an item to edit its properties
Add new items:
With design mode active ( ), right-click in the page:
• A context menu is displayed showing all available items (button, edit, table, and so on). Each item is
mapped to a bootstrap component.
• Select the desired item type and validate.
• The new item is added to the Resources tree, under the Items node.
Edit an item:
With design mode active ( ), click the item in the designer view. The item properties are then displayed in the
Properties window, where you can edit them.
Set the position of an item:
UI Designer uses the Bootstrap-3 framework to manage popups. That means that you cannot simply set (X,Y)
properties to choose the position of an item. Instead, you have to create a grid using row and columns items.
With design mode active ( ), right-click within the page in the design view:
• Expand the Insert grid menu item and choose a grid item to add (such as containers, rows, columns).
• The new grid item is added to the Resources tree [1] under the Items node.
The Items subtree reflects the structure of the grid. You can change this grid structure using drag&drop in the
Resources tree.
For a full description of how to design a grid, see Managing Custom Pages With UI Designer [page 404].
To set an item position, simply drag&drop it to the right grid cell.

 Note
This is not possible in design view. You must do it in the Resources tree.
Delete an item:
You cannot delete an item in design view. You have to do it in the Resources tree.
The Editor Zone
The editor zone allows you to edit the text files associated with the popup: settings.js, popup.html, and so on.
You can open multiple files at the same time and switch between them using the document selector (see The
Editor Perspective [page 23]).
Each file is opened in an editor that provides a wide range of features, including syntax highlighting, unlimited
undo/redo, IntelliPrompt, outlining, and zoom. For a complete description of these features, see The Code
Editor section in The Editor Perspective [page 23].
 Note
By editing the settings.js file, you can change the design of your popups in JavaScript.

The Tool Windows
The UI Designer perspective contains the following tool windows:
• Properties
• Code Map (see Navigation Features [page 44])
• Find Results (see Search Features [page 48])
Properties Tool Window
The Properties tool window allows you to change the properties of popups and their items. The toolbar contains
the following items:

• : Manually refresh the design view with the new properties value
• : Switch auto-refresh mode on/off
Edit Properties
You can edit the properties of a popup or an item in different ways:
• From the Resources tree, right-click the corresponding node and select Edit from the context menu.
• From the design view, either select the item in design mode, or right-click the item and select Edit Item or
Edit Popup from the context menu.
The properties are then displayed in the property grid.
Refresh Mode
If auto-refresh mode is on, the design view is automatically updated each time you validate a property change
in the property grid. If not, you need to update the design view manually using the button.
Manage Complex Items
Most properties are simple to edit. But some items, such as radio buttons and checkboxes, have complex
properties that are editable as arrays of objects.
For these properties, you can:
• Add a new object to the array using the + button (1).

• Remove an object from the array using the - button (2).
 Note
You can also edit these properties in the settings.js file
Docking Management
The layout of the UI Designer perspective is a DockSite comprising:
• Four tool window zones at the left, right, top and bottom
• One documents zone in the center. This zone can be split into multiple documents zones.
As in the editor perspective, the layout can be modified and saved (see Docking Management in the The Editor
Perspective [page 23]).
Related Information
Managing Custom Pages With UI Designer [page 404]

4.2 Advanced Techniques for Custom Page Design
If necessary, you can use advanced techniques to customize your custom page:
Customize the Empty Popup.html File
The initial content of the empty HTML page is as follows:
 Sample Code
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta http-equiv="Content-type" content="text/html; charset=utf-8"/>
<div id="includes">
<includes/>
</div>
<LINK href="popup.css" rel="stylesheet" type="text/css" />
<script src="settings.js"></script>
<script src="popup.js"></script>
</head>
<body>

</body>
</html>
You can freely edit it to:
• Include your own HTML components under the ‘body’ node.

• Change the content of the ‘head’ nod.e
 Caution
Take care to leave the ‘includes’ node unchanged: it is replaced at build time by the list of required included
files (bootstrap scripts, css, and so forth).
Customize the Popup.js or Popup.css File
You can freely edit the popup.js and popup.css files, to include any required customization.

Include Custom Files
UI Designer automatically includes in the project all the files present in the page subdirectory, in the local folder
of your project.
To add a new javascript or css file, you can add it using the context menu in the Resource tree:

• It is added to the Resource tree, which allows to edit it in the UI Designer
• It is automatically included in the popup.html file
You can also manually add any existing file (for example, image) as follows:
1. Copy the file in this subdirectory

2. Refresh the Resource tree using the context menu
The added file then appears in the Resources tree, allowing you to edit it in the UI Designer
 Note
In this case, the added file is not included in the popup.html file. If necessary, manually update the
popup.html file.

5 Testing and Deploying Your Project
In this chapter we will explain how to test, deploy and troubleshoot your project. At the early stage of
your project and specifically when making your application capture, it is recommended to test the behavior.
Typically, you need to check how the application responds to event you send (set, click...) or retrieve (get).
Once done, you can make end-to-end testing with the scenario you designed on your workstation.
To deploy the project and the scenario for unattended or attended usage, you simply need to export the
project. Import the zip file generated to Cloud Factory.
Tip: To successful execute a project in unattended mode, you need to define an environment and allocate time
for unattended within the hierarchy definition. For more information, please refer to the corresponding topic.
5.1 Building a Project for Testing
Desktop Studio helps you to build a solution by:
• Synchronizing SDK libraries and resources (HTML, bitmaps, and so forth) to the local execution folder
• Compiling and minimizing JavaScript (based on Google Closure Compiler),
• Completing XML declarations and checking consistency
The project is rebuilt before each launch for testing. Once it has been developed and tested, the project can be
exported as an archive for deployment purpose.
5.1.1 Compiling a Project
Desktop Studio automatically compiles the project before running it. The project can also be manually
compiled using the button in the Debugger toolbar.

Testing and Deploying Your Project PUBLIC 419
During compilation, the following checks are performed:
• Application/Page/Items declaration completion Verify application / page / item recognition criteria.

Note that only criterion completion is checked during compilation. Recognition is performed at runtime.
• Javascript code compilation A full code compile is performed, including JavaScript syntax, variable
control, and function calls.
• XML code compilation: The XML code is checked with regard to application, page, or item names or XPath
usage. However, consistency checks are not performed.
The results of compilation are displayed in the Error List Tool Window.
 Note
• Compilation errors prevent the project from being executed. This can be bypassed by checking Allow
Run with Compile Errors in the Debugger Settings.
• Some compilation errors can be qualified in compilation warnings using the CompilerFilters entry in
the SDK.xml file (where the SDK configuration is stored.)
5.2 Exporting a Project for Deployment
Overview
Once compilation is completed, Desktop Studio generates project output in the bin directory (see Typical
Structure of a Project [page 61]).

420 PUBLIC Testing and Deploying Your Project
The following operations are performed:
PSC File Generation

• Collects all the PSCP and PSC files of the various declared applications and places them in a single
compiled PSC file. The compiled file is generated in the bin directory.
Collection of Project Files

• Collects all files stored in the local directory of the project and copies them to the bin directory
• Local sub-directories are also collected and copied to the same bin subdirectory tree.
Collection of SDK Files

• Collects all SDK files referenced by the project and copies them to the same bin relative subdirectory
tree. For example: <SCRIPT Src="%sdk%\lib\utils\fso.js" /> will copy the fso.js SDK file to the
bin\lib\utils subdirectory.
• The destination subdirectory can be modified using the Dest attribute of the SCRIPT node. For example:
<SCRIPT Src="%sdk%\lib\utils\fso.js" Dest="test" /> will copy the fso.js SDK file to the bin\test
subdirectory.
Collection of Resource Files

• Collects all resource files and directories referenced by the project and copies them to the
bin directory. Subdirectories are also collected and copied to the same bin subdirectory tree
For example: <RESOURCE Src="%sdk%\templates\resources\bmp\" /> will copy all the %sdk%
\templates\resources\bmp files and subdirectories to the bin directory.
• The destination subdirectory can be changed using the Dest attribute of the RESOURCE node. For
example: <RESOURCE Src="%sdk%\templates\resources\bmp\" Dest="bmp" /> will copy the resource
files to the bin\bmp subdirectory.

The Error List Window
The Error List window in the Editor perspective displays the compilation results. Lines are grouped by script file
or XML block.
Each line can contain a warning or an error.
By double-clicking a line, you can navigate to the corresponding line in the script file or the XML block.

Output Window
The Output window in the Editor perspective displays the output generated by Desktop Studio:
• Compilation output
• Export output
• Project execution output
This output is for information only.
5.2.1 Exporting a Project
When you export a project, a new export output folder is generated in the export subfolder. Based on the
project structure, the output folder contains:
• The local folder in an output ZIP file if the compression option was selected before generation. If the
compression option was not selected, all files from the local folder are copied as raw data files.
• The server folder
• The key.xml markup file
The name of the export output folder has the following structure: <project name>_<project version>
The markup file ensures the integrity for:
• All file names

• All data files
• Properties from the XML <Properties> section in the main project file
If any of these conditions are invalid, the export will not work.
 Note
The export action also produces a raw ZIP file in the root export folder. The name of the ZIP file is:
<project name>_<project version>.zip.

 Note
Once exported, you can import your project to the Cloud Studio as 'read-only'. To edit your Desktop Studio
project in the Cloud Studio, you must convert [page 424] it first.
5.2.2 Converting a Project
Converting a project from the Desktop Studio enables you to use and edit it into the Cloud Studio.
Check the dedicated Procedure to learn how to convert a project from the Desktop Studio.
5.2.3 Deploy
SAP Intelligent Robotic Process Automation is composed of different elements:
Desktop • Is a software component that is installed on a user's workstation and leverages the user
Agent session. It executes a set of scripts (the project archive) to optimize business processes.
• When launched and whenever the local project cache is empty or outdated, it retrieves the
project archive which is stored on Cloud Factory.
Desktop • Is installed on one or more development workstations that have access to the client
Studio applications to integrate the business processes.
• Is the tool for authoring all process automation aspects.
Cloud • Is a software component that runs and is hosted on SAP BTP (Business Technology
Factory Platform).
• Centrally manages all common resources related to SAP Intelligent Robotic Process
Automation.
Project files • An archive previously imported and available on Cloud Factory.

• The archive is downloaded and unzipped to a local cache each time a new version is
detected on the Factory. The cache is protected to prevent any local modifications.
• Composite Web pages can be embedded in the archive.
Once the project is ready for deployment, an archive is generated by Desktop Studio in the form of a
compressed file and a validation file in XML format. You use Cloud Factory to import the archive and
configuration for attended or unattended usage.
5.3 Debugging

5.3.1 Debugging Your Code with Script Debugger
Desktop Studio helps you to test and troubleshoot your project. You can set breakpoints in your code to enable
step-by-step execution, view the values of local and watch variables, and execute code on the fly.
Start a Project in Debug Mode
A project can be started in two different ways:
• From Desktop Studio

• Via a shortcut
Start via a Shortcut

This is the standard way to launch an application in Production.
The shortcut generated by Desktop Studio (at export time) starts the Engine in Release mode.
Alternatively, it can be started in Debug mode by adding the command line argument: -t 512 to the shortcut
arguments (see the Installation Guide for details of command line options).
If the project is started in Debug mode via a shortcut, Desktop Studio is not required. In this case, however,
interaction with Desktop Studio is disabled. Debugging will then be performed via the Control Pane.
Start from Desktop Studio

To start a project via Desktop Studio, you can use one of the following commands from the Main menu or from
the Debugger toolbar:
 Run Starts the project in Release mode

(without debugger)
Debug Starts the project in Debug mode
Debug in Export mode Starts the project from the Export re
sult in Debug mode
Working Directory
The working directory is mandatory to launch the project in Release or Debug mode. This working directory
must be write-enabled in order to host the log files. If the working directory is missing, the launch of Desktop
Agent will fail.
By default, Desktop Studio sets the working directory in the folder containing the project file.
If the project file is opened from a Web URL or if it is located in a read-only directory, Desktop Studio uses a
temporary working directory. For example: C:\Users\<user login>\AppData\Local\Temp\
Manage Debug Options

You can manage debug options when starting a project in debug mode. To do so, choose Debug Manage
Debugging Options from the main menu or debugger toolbar.

The Manage Debugging Options dialog is displayed.
The Debugger tab lets you choose the Debugger that will be used:
• Debugger in Popup or Embedded mode (see Debugging and Testing with the Debugger [page 432])
• Control Pane
This dialog also lets you specify whether you wish to automatically minimize Desktop Studio when running.
The Trace options tab lets you choose the trace level:
• Trace level for the log files:

• Trace events
• Detailed tracking of orders
• Simplified tracking of orders
• Tracking of the context data
• Tracking of the “Extend Pilots”
• Trace objects

• Trace all Event Win
• Trace messages (MESSBOX)
• Trace level for the framework:
• Log framework trace in file
• Capture screenshots
The Technical options tab lets you choose the technical trace level.
A technical trace provides information from Desktop Studio connectors.
Step-By-Step Execution
Desktop Studio supports step-by-step execution. This enables code to be executed line by line.
To enter step-by-step execution, execution must break on a breakpoint.
Manage Breakpoints
Breakpoints are set or removed on a script or XML block line in the Code Editor using the Toggle Breakpoint
command from the Main menu or from the Debugger toolbar:
• If a breakpoint already exists on this line, it is removed.

• Otherwise, it is set.
When a breakpoint is set, the icon  is set in the margin and the line is highlighted in red:
The Breakpoint tool window in the Editor Perspective displays a list of breakpoints that have already been set.

Right-click to:
• Navigate to the selected breakpoint

• Delete the selected breakpoint
• Delete all breakpoints
Step-by-Step Debugging in the Code Editor

When a breakpoint is reached:
• Execution is suspended.
• The script or XML block containing the line with the break is automatically brought to the front.
• A indicator is set in the Indicator Margin and the Running line is highlighted in yellow:
• The Call Stack, Locals, and Watch tool windows are refreshed.
To resume execution, use one of the following commands from the Main menu or the Debugger toolbar:
Debug Commands
Resume F5 Continue execution until an

other breakpoint is reached
 Toggle Breakpoint F9 Toggle a breakpoint on the

current line
Step into F11 If we are on a line containing

a method call, this command
will enter the method and
break again on the first line
of code inside the method.
Use Step Into to see what
happens inside a method call

Debug Commands
Step over F10 Executes the entire method

call and break on the next
line of code in the current
method. Use Step Over to ex
ecute the entire method and
continue in the current code
block
Step out SHIFT + F11 Executes the rest of the cur

rent method and return to
the calling method. Execu
tion will break at the return
point in the calling function
Run and Break SHIFT + F10 Continue execution up until

another line of your code is
executed. This command is
particularly useful to break
execution when a callback
function is called
Break All
It is possible to break execution even if no breakpoint is reached. To do this, use the Break all command from
the Main menu or from the Debugger toolbar:
 Break all Breaks execution on the next executed

line.
This command is particularly useful when you want to find out what code is currently being executed (in other
words, in infinite loops).
Manage Watches
The Watches tool window in the Editor perspective displays a list of watched
variables.

A line is displayed for each variable. It shows the following information:
• The variable name

• The variable value
• The variable type (Integer, Boolean, String, Object, Array, and so forth).
The value and type data are only filled when the project is running in debug mode and when execution is
halted at a break.
Each variable line is preceded by an indicator that shows its type:
Simple Variable
Object or Array
Properties or Method
Undefined
By right-clicking the desired value, you can :
• Delete a watch
• Copy the variable value to the clipboard
To add a watch to the Watch tool window:
• Select the code block to watch in the Code Editor

• Right-click the selected code block
• Select the Add Watch command
 Note
A watch can be added at any time, whether or not the project is running.
View Local Variables
The Locals tool window in the Editor perspective automatically displays a list of variables local to the current
execution context.

It is only filled when the project is run in Debug mode and when execution halts at a break.
A line is displayed for each variable. It shows the following information:
• The name
• The value
• The type (Integer, Boolean, String, Object, Array, and so forth)
Each variable line is preceded by an indicator that shows its type:
Simple Variable
Object or Array
Properties or Method
Undefined
Right-click the desired value to:
• Add a variable to the watches

• Copy the variable value to the clipboard
Use the Call Stack
When execution halts on a break, the Call Stack tool window in the Editor perspective displays the call stack.
The call stack is the set of nested function calls that are currently running and waiting to return.
The Call Stack window displays the name of each function:
• The line number where the call occurs

• The function name (if known)
• The script file containing the function.
By double-clicking a function’s line, you can navigate to the corresponding line in the script file.

5.3.2 Debugging and Testing with the Debugger
The Debugger allows you to view:
• Technical and functional events exchanged during execution

• Application and page evolutions
• Scenarios and steps executed
When you start a project in Debug mode, and depending on the chosen debug options, the Debugger is
launched in:
• A popup window if the popup mode option is selected
• A Debug perspective if the embedded mode option is selected

Debugger Components
Regardless of the chosen mode, the Debugger is composed of the following parts:
• A main menu (popup mode only)

• A tab control with the following views:
• The Events view – displays the events history and the execution trace
• The Pages view – displays the loaded pages
• The Scenarios view – displays the executed scenarios
• The Filter view – lets you filter the views
• The Tester view – lets you execute code on the fly,
• The Screenshots view – displays screenshots made during execution
• The Page Viewer view – displays page captures
• The Details view – displays the events or actions details,
• The Context view – displays the context within the scope of the engine
Main Menu
Menu ‘File’

Save DebugSession Save the whole event history on disk. The event history can
be saved at any time and it will get automatically saved when
execution stops. Saving Debug session enables to debug
offline (see Debug offline with DebugSessions ).
Embed in Desktop Studio Embed the Debugger in Desktop Studio.
Menu ‘Debug’
Refer to Desktop Studio Commands Reference for a descrip

tion of ‘Debug’ items.
Menu ‘Settings’
Topmost If checked, allows keeping the Debugger in the foreground

position of the existing windows on the screen.
Event history
Show all events Displays the whole events history in the Events view
Show last 30s Displays only the last 30 seconds of the events history in the
Events view
Show last minute Displays only the last minute of the events history in the
Events view
Show last 2 minutes Displays only the last two minutes of the events history in
the Events view
Menu ‘view’
Status Bar Hides/shows the Status bar
Replay Toolbar Hides/shows the Replay toolbar
Debug Toolbar Hides/shows the Debug toolbar
ToolWindows
Events Hides/shows the Events view
Pages Hides/shows the Pages view
Scenarios Hides/shows the Scenarios view
Filter Hides/shows the Filter view
Tester Hides/shows the Tester view
Screenshots Hides/shows the Screenshots view

PageViewer Hides/shows the PageViewer view
Details Hides/shows the Details view
Context Hides/shows the Context view
Layout
Save Saves the current layout
Restore Restores the previously saved layout
Events View
The Events view displays all the events generated by Desktop Agent during execution. All events are time-
stamped, the oldest at the beginning of the list and latest at the end of the list. The timestamp can be hidden
using the Show timestamp context menu item.
Icons at the head of each line indicate the type of the line, as follows:
Event not handled by Project code
Event handled by Project code. Double-click on such events

expands the line to display executed actions
 Log information messages
 Log warning messages

 Syntax errors or log error messages
Command executed in the Debugger. Double-clicking these

events expands the line to display executed actions
Context Menu
The Events view has a contextual menu allowing the following actions:
Menu Item Description
Show event detail Displays the event’s detail in the Detail view
Show in Scenario View Selects the event’s handler in the Scenarios view
Show/hide actions Expand/collapse the selected line to display the associated

code trace lines
Hide all actions Collapse all the lines to hide the associated code trace lines
Show/hide out of search events
Show timestamp Show/hide the line timestamp
Show in Page Viewer Display the page captures associated with the event
Insert code in Tester Insert corresponding code in the Tester view
Insert code in Tester with Instances Insert corresponding code in the Tester view with instance
values
Replay from this event
Clear list Deletes all of the events displayed in the list
Clear list before this event Deletes all of the events before the selected event
Show all events Displays the entire events history
Limit the List of Events Displayed
There are three ways to limit the list of displayed events:
• Using the Event history duration

• Using the Scopes
• Using the Filters
Using the Event History Duration
Using the Settings/Event historic item on the Main menu, you can limit the history duration displayed:
• To the last 30 seconds

• To the last minute

• To the last two minutes
Each time a new event is received, the list gets updated in order to reflect the selected history duration.
Via the context menu, you can
• Remove all of the events from the list

• Remove all of the events before the selected event
 Note
Events that have been removed from the display are not actually deleted. They can be displayed again via
the Show all events item from the context menu.
Using the Filter View
Using the Filter view, you can filter the list of events displayed:
• Based on the application

• Based on the event name.
 Note
A filtered event is never displayed, even if it matches the current scope. The only way to display a filtered
event is to change the filter.
Display Actions
Icons at the head of each line indicate the type of action:
Code Instruction
 Code instruction
Messages

 Log information messages
 Log warning messages
 Syntax errors or log error messages
Framework Status Notifications
Scenario start
Scenario end
Step start
Step end
 Handler run
 Handler set or reset
 Other
Search Events or Actions

We can search events or actions in the Events view using the Search bar:
To find a text:
1. Enter the search text in the entry field

2. Click the  button.
The events list is filled with the search result:
• Found events or actions are highlighted in green

• Other events are hidden (you can show/hide them using the Show All button),
• If an action is found, other actions executed on the same event are disabled

 Note
The search is performed within the scope of the list of events displayed. For example, a filtered event will
never be found, even if it matches the search
To cancel the search, click the  button.

Display Event or Action Details
You can display details of an event or an action by selecting Show Details from the context menu. The Details
view displays:
• For an event, the data associated with the event

• For an action:
• The action’s parameters
• The return value
• The item on which the action is executed.
If the Details view is already visible, simply select an event or action to display its details.

Display Screenshots
In order to automatically capture screenshots, check the Capture screenshots option in the Manage Debug
options. In this case, Desktop Agent automatically captures a screen image during execution based on page
LOAD and UNLOAD events.
To display the screenshot associated to an event, display the Screenshots view and select the desired event. If
the Screenshots view is already visible, simply select an event or action to display its associated screenshot.
 Note
• If an event has no associated screenshot, the screenshot of the previous event is used.
• Unlike page captures, the screenshots are simple images. It is impossible to select components in
screenshots.

Display Page Capture
If an event or action is associated with a page, you can display the page capture associated with the page in
the Page Viewer view. If the Page Viewer view is already visible, simply select the event or action to display its
associated page capture.
If it is associated with a page item, the corresponding recognized items are highlighted in the page capture.

Pages View
About This View
This view displays the tree of the applications, pages and items declared in the project. For each element of the
tree, the following color code is used to display the loading status:
Green The element is loaded
Gray The element has never been loaded
Black The element has been loaded but is now unloaded
 Note
• This view can be filtered using the Filter view.

• For items, the element is disabled until the Display Items Values operation has been performed on the
page.
Context Menu
The view provides a shortcut menu that offers the following actions:
Goto definition Navigate to page/item declaration in Explorer Perspective
Show in Page Viewer Display the page captures associated with the page or Item
Show in Page Tester Display the page captures associated with the page or Item
Start Start a new instance of the page
Update Items values Display item values
Highlight Highlight the recognized page in the controlled application
Highlight Items Highlight the recognized items in the controlled application

Search in Events view Search in the Events view for the events received for this
page, and display handling actions
Insert code in Tester Insert corresponding code in the Tester view
Insert code in Tester with Instances Insert corresponding code in the Tester view with instance
values
Hide never loaded Applis/Pages Hide/show never loaded (gray) applications and pages
Copy Name Copies the name of the selected item, page or application to
the clipboard
Copy Value Copies the value of the selected item to the clipboard
Display Item Values
To display item values, open the context menu on the item or on the page and select Update item values.
For simple items, the item’s value is captured from the page and displayed after the item’s name.

 Sample Code
[Item name] = [value]
For multiple items:
• The Item’s count is captured and displayed before the item’s name (1)
• The value of the item's first s occurrence is displayed after the item’s name
• For multiple WEB Items, the count can’t be captured without capturing all of the values. To show this, [??]
is displayed instead of the count value
You can display all the of a multiple item's values by double-clicking the item. A subtree opens (2) displaying all
of the values with the corresponding index values.
If more than one instance of the page is loaded, select the desired instance in the Instances combobox to
display the values of its items (see Multi-instance management).
 Note
• The running project may describe items that are not present in the running application. In this case, the
view displays the following message:
>[Item name] = [Pilot name] – ERROR ...
• Using the ‘Update Items values’ command generates a line in the Events view. By double-clicking this
line, you can display all the actions performed in response to this command.
Multi-Instance Management
This view displays information about multiple instances of applications or pages:
• For applications, the current and max number of running instances of the application (1) are displayed
• For pages:
• The current number of running instances (2) of the page, across all running instances of the
application

• The maximum number of running instances of the page in the same running instance of the
application
• A combobox that lets you select the page instance used to display item values (3)
 Note
The current and max values are only displayed if they are greater than 1.
Scenarios View
About This View
The Scenarios view in Desktop Studio displays a tree that shows the running or ended scenarios (1), steps (2)
and handlers (3). It also displays, for each handler, the log messages and a trace of executed commands (4):
• Scenario and step items display the scenario or step name, its internal Id and its starting timestamp.
• Handler items display events handled within each step. The special 'Init' handler display commands
executed at the start of steps or scenarios.
• Command items display the automatic trace generated by the framework.
• Log and error items display script trace generated via the ctx.log command.

Each item has an icon and colors indicating the item type and status (see below for details). You can navigate
within the script to the code corresponding to an item using Goto Definition/Code from the context menu.
 Note
• Handlers executed outside the scope of a step (for example: 'GLOBAL.Start' handlers) are displayed in
the second column.
• The visibility of log items is managed in a special way.
• You can show or hide the timestamp by clicking  in the toolbar.
• Command items icons can be hidden using the  button in the toolbar.
Column Management
The Scenarios view displays data in a structured way using columns. It can display several scenarios executing
simultaneously, by displaying each scenario in a separate column (see columns (3), (4) and (5)).
You can manage columns using the column header. You can show or hide a column by clicking the arrow, and
you can change the column widths by dragging the splitter between the columns.
The first two columns have a special meaning:
• The Events column (column 1) lets you display/hide technical events (1).

• The OutOfScenario column (column 2) lets you display/hide out-of-scenarios handlers (2) (for example,
GLOBAL.Start handlers).
 Note
• The Events column and the OutOfScenario column have independent widths. All other columns
(scenario columns) have a uniform width.
• It is sometimes difficult to reduce column widths. If this problem occurs, simply reset the column width
using the  button in the toolbar and then expand the desired columns.
Navigate to Code
Within a script, you can navigate to the code corresponding to an item using Goto Definition/Code from the
context menu:
• ‘Goto Code’ on a scenario item navigates to the scenario definition

• ‘Goto Code’ on a step item navigates to the step definition
• ‘Goto Code’ on a handler item navigates to the handler's ‘set’ command (such as wait, on, once, waitClose)
• ‘Goto Code’ on a command or log item navigates to the command
Take care: this navigation is rather approximate. Trace items and code in scripts are not linked by script line
number, but by search in the script's code map. To minimize navigation errors, use unique scenario and step
names.
 Note
‘Goto Code’ on an item searches for the first matching entry in the script's code map. For example, if there
are two ‘ctx.log’ commands in the same handler, ‘Goto Code’ on the second log item will navigate to the
first ‘ctx.log’ command in the handler.

Log and Errors Display
Command items are only displayed if their corresponding handler’s item is expanded. The visibility of log and
error items can be managed in two different ways:
• An error item is always visible if the item of the scenario in which the error occurs is visible (even if
collapsed)
• A log item is visible if the item of the scenario in which the log is generated is expanded. You can display log
items the same way as you display error items: using the  button in the toolbar.
This way of displaying log and error items provides a useful view of the log generated plus quick access to the
handler where the log message occurred.
You can display the execution context of a log message using Display executing context from the context menu
or by clicking its icon (1). The executing handler/step/scenario are expanded to display the log item within its
execution context.

Meaning of Item Icons and Colors
For each item in the tree, the following color code is used to display the activity status:
Gray background (1) The Scenario has ended
Red text (2) The item (scenario, step, or handler) is in error
Green background (3) The scenario is running
Italic font (4) The scenario or step has ended
Normal font (5) The scenario or step is running
The icons at the head of each item in the tree indicate the item type:
Scenario, step, handler items
 Scenario
 Step
 Handler
Command items
Start scenario
End scenario

End step
Set handler
Framework Command
 Script Command
Log items
 Information
 Warning
 Error
 Question
 Data
 Other
Toolbar
The view has a toolbar that lets you do the following:
 Expand All
 Collapse All
 Reset column width
 Stop all running scenarios
 Show/hide scenario history
 Show/Hide timestamps
 Show/Hide Log
 Show/Hide icons
 Find text inside the View

Context Menu
The view has a shortcut menu that lets you do the following:
Show event detail Displays the event’s detail in the Detail view
Show in Page Viewer Displays the page captures associated with the event
Show in Page Tester Select the corresponding page or item in the Tester view
Goto Definition/Code
Insert code in Tester Insert the corresponding code in the Tester view
Insert code in Tester with Instances Insert the corresponding code in the Tester view with in
stance values
Replay from here
Restart this Scenario Start an ended scenario
Stop all running Scenarios Stop all currently running scenarios
Stop this running Scenario Stop the selected running scenario
Stop this running Step Stop the selected running step
Hide Scenario history Hide/show all ended scenarios. Running scenarios remain
visible
Show in Page Viewer Displays the page captures associated with the event waited
by the handler
Set Scope in Events view Set the current scope in the Events view
Display actions in Events view Search in the Events view for the events that run the handler
and display handling actions
Search sets in Events view Search in the Events view the actions that change the items
activity status
Insert code in Tester Insert the corresponding code in the Tester view

Insert code in Tester with Instances Insert the corresponding code in the Tester view with in
stance values
Restart this Scenario Start an ended scenario
Stop all running Scenarios Stop all currently running scenarios
Stop this running Scenario Stop the selected running scenario
Stop this running Step Stop the selected running step
Clear Scenario History Clear all ended scenarios. Running scenarios remain visible
Show Scenario history
Tester View
About This View

This view displays all the applications and processes declared in the project. Select the Applications tab item to
filter on applications or processes. You can:
• Check applications or processes you wish to exclude

• Uncheck all of the applications or processes to remove filters by clicking the Exclude none button
• Check all of the applications or processes by clicking the Exclude all button
There is no need to validate as the current filter is automatically applied when options are modified. Choices
are saved in the .user project file.
Filter on Events
To filter on Events, select the Events tab item. The view then display all the events received during execution of
the project. You can then:
• Check the events you want to exclude

• Uncheck all events to remove filters by clicking the Exclude none button

• Check all the events by clicking the Exclude all button
There is no need to validate as the current filter is automatically applied when you change the checks. Your
choices are saved in the .user file of the project.
Context View
This view display the internal context of the Desktop Agent engine. To update data, choose Refresh from the
context menu. When you select a node, the corresponding JavaScript command that lets you get the node
value is displayed (1).
Insert code in Tester Insert the corresponding code into the Tester view
Copy value Copy the value of the selected node
Refresh Update the data displayed

Layout Management
Tool windows can be docked anywhere by dragging and dropping their titlebars. Some of them can be closed
using the cross button on the titlebar.
 Caution
If the debugger is in topmost state, the docking guide will not be displayed. To view the docking guide while
dragging and dropping, temporarily disable topmost mode.
All available tool windows are listed in the View\Tool Windows menu. You can show or hide a tool window by
checking or unchecking it in this menu.
You can save a customized layout via View\Layout\Save on the main menu. This layout will then be
restored the next time you launch the debugger. To restore the layout without restarting the debugger, use
View\Layout\Restore from the main menu.
5.3.3 Debugging Offline with Debug Sessions
A debug session is a set of trace lines shown in JSON format. There is one line for each:
• Event received by the Desktop Agent engine

• Framework action performed by the project's scripts
• Scenario, step or handler status change
The session can also include .PNG files that correspond to the screenshots captured during execution.
The Debug Perspective
When a debug session is loaded into Desktop Studio, a new debugger instance is launched in a new debug
perspective:

Manage Debug Sessions
Save a Debug Session
The current session can be saved via the File Save last Debug Session option from the menu.
The first time it is saved, Debugger asks for the file path and the name of the file to save the debug session in.
Debugger will then automatically save the complete debug session in this file when execution ends.
Use the Last Debug Session
When execution ends, Desktop Studio automatically keeps the last debug session in the memory.
It can be opened using the File Open last Debug Session item from the Desktop Studio menu.
Load a Debug Session
A previously saved debug session can be loaded using the File Open Debug Session item from the
Desktop Studio menu.
The debug session can also be loaded by:
• Double-clicking the corresponding file in Windows Explorer

• Dragging & dropping the file from Windows Explorer to the PSC Tree of Desktop Studio.

5.3.4 Offline Debugging – Trace Management
SAP Intelligent RPA components generate different types of trace, depending on the configuration.
Desktop SDK Basic Trace
Content
In Release mode (not started from Desktop Studio), Desktop SDK systematically generates
a trace file containing ‘ctx.log’ verbs. Traces are generated in the ‘Traces.pscl’ file
located in the following directory: %localappdata%/SAP/Intelligent RPA/Projects/id/Log/
log.<login>.<machine>.<timestamp>.
Each running session of Desktop Agent generates one such directory.
Analyze
Basic trace can be manually collected and displayed using the Desktop Studio Debugger. Log messages are
simply displayed in the Events view or in the Scenario view.
 Note
Basic trace doesn’t provide any information about running scenarios, technical events, and so on. To get
such information, Detailed traces must be enabled (see below).
Desktop SDK Detailed Trace
Content
The Desktop SDK Detailed trace file includes:
• All technical events

• Scenario, step, or functional Events
• SDK calls
• diagnosis data (project/machine context, and so on)
Traces, in JSON format, are generated in the Traces.pscl file located in the following directory:
%localappdata%/Projects/id/Log/record.<login>.<machine>.<timestamp> (Release mode)
or projectPath/Log/record.<login>.<machine>.<timestamp> (Debug mode)
Each session running Desktop Agent generates one such directory.
Optionally, screenshots can be generated by Desktop SDK on LOAD/ACTIVATE events of the declared pages.
These PNG generated files are located in the same directory as the Traces.pscl file.

Release Mode
In Release mode, the detailed trace file is generated on demand (see Manually Record Detailed Trace or
Auto-Recording Mode). After collection, the file can be loaded and analyzed in a Debug perspective of Desktop
Studio (see Debugging Offline with Debug Sessions [page 455]).
Debug Mode
In Debug mode, the detailed trace is automatically collected and loaded in the Debugger at start time. The
Traces.pscl file can be generated on demand by Debugger (see Save DebugSession).
Screenshots collection can be activated before running the project via the Manage Debug options.
Analyze
Detailed trace is analyzed using the Debugger:
• Technical events are displayed in the Events or Scenario view.

• Scenario/Step/Handler status are used to build the Scenario view.
• Desktop SDK calls are displayed in the Scenario view by expanding handler entries.
• Screenshots are displayed in the Screenshots view.
• Each diagnosis message is displayed as Technical events in the Events view or the Scenario view. diagnosis
data is displayed in the Details view.
SAP Intelligent RPA Components Technical Trace
Content
Technical trace files are generated by Desktop Agent and its connectors. There is
one file per tracing component. For example, CtxtRun.exe_CxAppWeb3.dll_10980.log or
iexplore.exe_CxAppWeb3.dll_10312.log.
They are generated in the following directory:
%localappdata%Low\SAP\Intelligent RPA\Desktop Agent
Note that collecting Technical Trace can be time-consuming and generates large files. It must ONLY be
performed at the request of SAP Intelligent RPA Support.
• Release Mode
In Release mode, Technical Trace files can be generated on demand (see Record Technical Trace).
• Debug Mode
In Debug mode, Technical Trace files generation can be activated before running the project via the
Manage Debug options of Desktop Studio .
• Any Mode
In any mode, Technical Trace files generation can be activated using the TraceViewer external tool (see
Using TraceViewer [page 466]).
• Analyze
Technical trace files contain technical information generated by the connectors or the engine. This
information can only be analyzed by SAP Intelligent RPA Support.

Debug Mode
In Debug mode, Interactive trace detail level can be adjusted via the Manage Debug Options of Desktop
Studio.
Analyze
Interactive trace files are simple text files: They cannot be analyzed using Desktop Studio. You can also use
any text editor for this job.
5.3.5 Offline Debugging – Audit and Diagnoses
Desktop SDK implements a set of features to help with troubleshooting issues and to carry out local or remote
analytics.
These features let you collect data to establish diagnoses and trace information from an SAP Intelligent
RPA script running in production mode.
The collection process can be started by the user manually, or automatically by Desktop Agent if an error or
timeout occurs (see Auto-recording mode).
Once implemented, the following menu items are added to the project systray:
Diagnosis Data
Diagnosis data is a snapshot containing information about the workstation running the script, the state of the
running project, and so forth. The default content of diagnosis data includes:
Desktop workstation state
comment Free comment as entered by user
screenshot A screenshot
desktop A set of desktop collected data (hardware and software):

CPU, RAM, disks, network, OS, and so on

programs The list of installed programs (if the option ctx.options.diag
nostic.savePrograms is set)
eventViewer The last error events from the Event Viewer
Project state
options The content of ctx.options object
counters Internal counters: verbs, scenarios
runningScenarios The list of running scenarios
requests The list of declared requests
applications The content of the declared applications
pages The values, information and screenshot of the running pages
context XML context (useful for projects written completely or parti

ally in language v2)
 Note
Some options in the SAP Intelligent RPA script allow you to customize the content of diagnosis data:
• ctx.options.diagnostic.savePrograms = true : Include the list of installed programs in the archive

• ctx.options.diagnostic.saveEventViewer = true : Include the list of errors in Windows Event viewer
• ctx.options.diagnostic.saveCrashDumps = true : Include the crash dump files in the archive
Start Collecting Diagnosis Data
Once the script is started, the user can trigger the collection of diagnosis data using the Report an incident
menu item in the systray.
The following popup opens allowing the user to enter a free comment describing the incident, before clicking
the Submit button:

Desktop SDK:
• Collects diagnosis data and stores it in the trace file %localappdata%/projectname/Log/

record.<login>.<machine>.<timestamp>/Traces.pscl (‘%localappdata%’ can be replaced by
the folder name containing the extracted project package)
• Creates a ZIP archive containing trace files: %localappdata%/projectname/Log/
record.<login>.<machine>.<timestamp>.zip
• Displays a confirmation popup when the archive is ready (if the option ctx.options.diagnostic.displayPopup
is set)
The Open button opens the Windows Explorer and automatically selects the archive file.
Collect the ZIP Archive
The ZIP archive must be collected on the production workstation in order to be analyzed on a development
workstation using Desktop Studio.
By default, the ZIP archive is collected by manual copy. Alternatively, the ZIP archive can also be collected by
one of the following methods:
• Sending archive by mail (using Outlook)
 Note
You need to ensure the ‘ctx.outlook’ library is included in the project and that Outlook is correctly
setup on the desktop
 Sample Code
ctx.options.diagnostic.outlookSend.enabled = true;
ctx.options.diagnostic.outlookSend.destination = 'support@sap.com'
• Copying archive on a shared network (Note that we need to provide a write access on the shared folder)
 Note
You need to provide a write access on the shared folder
 Sample Code
ctx.options.diagnostic.archiveCopy.enabled = true;
ctx.options.diagnostic.archiveCopy.remoteFolder = "\\\\IntranetServer\
\test\\archive";
• Uploading archive with FTP (Note that you need to enable write access on the FTP site)

 Note
You need to enable write access on the FTP site
 Sample Code
ctx.options.diagnostic.archiveFTP.enabled = true;
ctx.options.diagnostic.archiveFTP.site = "ftp.server.net";
ctx.options.diagnostic.archiveFTP.remoteFolder = "home/archive";
 Note
Diagnosis messages can be shown in Desktop Debugger:
Manually Record Detailed Trace Before Collecting Diagnosis Data
Introduction
If necessary, detailed trace can be activated before collecting diagnosis data by means of the recording
feature.
In order to do this, once the script is running, the user starts recording by using the Record traces menu item in
the systray:
• The following popup is displayed:

• The user can include screenshots in the recorded trace by checking the Include screenshots option,
• Clicking the Start button starts Trace recording. The following popup is then displayed:
• During recording, the user can insert comments to help later analysis, by filling the entry field and clicking
the Comment button.
• When finished, the user clicks the Stop button. Diagnosis data is automatically collected. The ZIP archive is
then generated and can then be collected.
Record Detailed Trace from Desktop Agent Startup

If required, the user can start recording detailed Trace from Desktop Agent startup by setting the following
trace option in the project shortcut:
 Sample Code
-t 4096
Screenshots can be added to the detailed Trace by setting the following trace option in the project shortcut:
 Sample Code
-t 8192
When recording is enabled by this method, diagnosis data is automatically collected when Desktop Agent
stops. The ZIP archive is then generated and can then be collected.
 Note
In this case, for performance reasons, only partial diagnosis data is collected.
Auto-Recording Mode
Auto-recording mode allows the user to collect detailed Trace and Diagnosis data every time an error or
a timeout occurs. This collection doesn’t require any user action apart from for ZIP archive collection, if
automatic collection has not been parametrized.
Auto-recording mode works as follows:
• When the first scenario starts, Desktop SDK automatically starts recording detailed trace,
• When the last scenario terminates, Desktop SDK automatically deletes the recorded detailed trace,
• When an error or a timeout occurs in a running scenario, diagnosis data is automatically collected. The ZIP
archive is then generated and can then be collected.

Auto-recording mode cannot be activated by the user. Instead, it can be activated in one of the following ways:
• Activation by script
You can activate auto-recording mode explicitly in the script using the following option:
 Sample Code
ctx.options.trace.autoRecording = true;
• Activation by command line

You can activate auto-recording mode from the command line by adding the following option to the project
shortcut:
 Sample Code
-o trace.autoRecording=true
• Activation by file
It is possible to selectively activate auto-recording mode for specific users by providing the users.csv
file. This file will contain the list (one per line) of UserId(s) that have auto-recording mode enabled. It must
be delivered along with the project package and deployed on the delivery server. It will be downloaded by
Desktop Agent every time the project starts.
Record Technical Trace Before Collecting diagnosis Data
If requested by SAP Intelligent RPA Support, the user can also record Technical Trace before collecting
diagnosis data.
Technical trace is generated by Desktop Agent and its connectors (see Offline Debugging – Trace Management
[page 457]).
Technical Trace can be activated by setting the following options in the project shortcut:
 Sample Code
-comp WEBWIN -r %localappdata%Low
where:
• -comp WEBWIN indicates the list of technical components permitted to generate a trace (the WEB and
WIN connectors in this example). The list will be provided by SAP Intelligent RPA Support.
• -r %localappdata%Low indicates the directory where this trace will be generated.
In order to generate diagnosis data, use one of the preceding methods. The resulting ZIP archive will
automatically include the generated Technical Trace files.

Manually Update the Project to Implement diagnosis Features
• Ensure the following libraries are included in the project: ctx.fso.js, ctx.wmi.js, ctx.wscript.js,
ctx.diagnostic.js:
 Sample Code
<SCRIPTS>
<SCRIPT Name="Constants" Src="%sdk%\lib\common\ctx.enum.js"
Folder="Framework" />
...

<SCRIPT Name="FSO library" Src="%sdk%\lib\utils\fso.js"
Folder="Libraries" />
<SCRIPT Name="WMI library" Src="%sdk%\lib\utils\wmi.js"
<SCRIPT Name="WScript library" Src="%sdk%\lib\utils\wscript.js"
<SCRIPT Name="Ctx Diagnostic" Src="%sdk%\lib\ctx\ctx.diagnostic.js"
...
</SCRIPTS>
• Ensure the following icon is added in resources:
 Sample Code
<RESOURCES>

...
<RESOURCE Name="record 16px" Src="%sdk%
\templates\resources\bmp\record.png" Dest="bmp" />
...
</RESOURCES>
• Include shortcuts and/or menus in the project:
 Sample Code
GLOBAL.labels.set({
...
menu: {
reportIncident: { en:"Report an incident", fr:"Soumettre un incident",
de:"Report an incident" },
recordTraces: { en:"Record traces", fr:"Enregistrer des traces",
de:"Record traces" }
}
});
systray.loadImage('ICON2', 'FILE', ctx.options.resourceURL + '/bmp/
record.png');
// add a shortcut (Ctrl+Shift+D) and menu to display diagnosis

ctx.regHotKey(e.key.Ctrl + e.key.Shift + 'D',
GLOBAL.events.evShowDiagSubmit);
systray.addMenu('', 'evReportBug', GLOBAL.labels.menu.reportIncident +
' (Ctrl+Shift+D)', 'ICON2', function(ev) {
GLOBAL.notify(GLOBAL.events.evShowDiagSubmit);
});
// add a shortcut (Ctrl+Shift+R) and menu to display recorder

ctx.regHotKey(e.key.Ctrl + e.key.Shift + 'R',
GLOBAL.events.evShowDiagRecorder);
systray.addMenu('', 'evRecordTraces', GLOBAL.labels.menu.recordTraces +
' (Ctrl+Shift+R)', 'ICON2', function(ev) {
GLOBAL.notify(GLOBAL.events.evShowDiagRecorder);
});
});
GLOBAL.addOn({ evShowDiagSubmit: function(ev) {

ctx.diagnostic.showSubmitPopup();
}});
GLOBAL.addOn({ evShowDiagRecorder: function(ev) {

ctx.diagnostic.showRecordInitPopup();
}});
The above code adds the following menu items to the systray:
5.4 Using TraceViewer

TraceViewer is an external tool used to enable Components Technical Trace.
General Principles
Location of Trace Files

You are strongly advised to use a specific subdirectory of your AppData LocalLow directory, as that directory is
guaranteed to be:
• Write-enabled, even for a low level privilege process such as Internet Explorer in protected mode
• Local (tracing on a network drive is not recommended)
Unfortunately, there is no simple, standard way of knowing where that directory is located. The
CxTraceViewer.exe tool lets you locate it (see Specify the Trace Directory).
Usually, the directory is %userprofile%\AppData\LocalLow. We recommend naming the subdirectory

‘Desktop Studio’.
 Note
The Trace directory must exist; it will not be created by the Desktop Studio Trace tools.

Tracing by Component
You need to choose which components will effectively trace, as tracing everything would be too slow and would
produce too much data.
Each component is identified by a trigram code. The available trigrams are:
Trigram Component
ACT The ICtxActApp interface
AUI Desktop Agent Localization
BAE Desktop Studio Discovery
BAR Desktop Studio AppBar
DBG JavaScript debugging from Studio
DES Desktop
HLL HLLAPI Applications
HTM Some Desktop Studio HTML Popups
NSD NSDK Applications
RIX Citrix and RDP Applications
RUN Launching and initializing Desktop Agent
SCR The Scripting Host
STU Desktop Studio
SWG Java Applications
UIA UI Automation Applications
WEB Web Applications
WIN Windows Applications
WRK The Core: The “Work Manager”
Using CxTraceViewer.exe
Background
The CxTraceViewer.exe program is located in the Desktop Studio directory, which is typically C:\Program
Files (x86)\SAP\Intelligent RPA\Desktop Studio

Use the Trace Parameters... menu option to access the Trace Parameters dialog box:
Specify the Trace Directory

The Trace Directory must be entered in the Trace Directory input box. We recommend using the Set To Temp
button (which should be labeled Set To AppData LocalLow) and adding \Agent to the string.

 Note
You must ensure that the directory exist. If not, the tools will not create.
Specify the Component List

For each component:
1. Select the component trigram from the list box

2. Check the File Only radio button
Here is an example for the Java Applications component:
When you have selected each component (and checked File Only for that component), click OK to close the
Parameters dialog box.
Note:
• Do not close the Trace Viewer program during your trace session. You can, however, minimize the program.

5.5 Recognition Error Cases
Page Recognition Error Cases
A page is wrongly recognized as MyPage

A page is wrongly recognized as the declared MyPage. In other words, the page unintentionally matches the
MyPage recognition criteria.
Solution 1 – Improve MyPage recognition criteria:
Try to modify ‘MyPage’ recognition criteria so the wrongly recognized page doesn’t match the criteria.
Solution 2 – Declare MustExist or MustNotExist Item(s)
Try to detect some components which are only present in MyPage, and declare them as MustExist Items (see
MustExist Method [page 284] or MustNotExist Method [page 284]).
Solution 3 – For desktop applications
• Try declaring MyPage as a subpage of another page (see the description of subpages in Declaring a Page
[page 243])
• Try using Root Item Method [page 284] (UI Automation only)
A page is wrongly recognized as MyFirstPage instead of MySecondPage

A page that should be recognized as MySecondPage is wrongly recognized as MyFirstPage, declared
previouslz.
This means that the page matches the MyFirstPage recognition criteria.
Solution 1 – Check the declaration of MyFirstPage
Try modifying the declaration of MyFirstPage so that MySecondPage doesn’t match its recognition criteria
Solution 2 – Declare ‘MySecondPage’ before ‘MyFirstPage’
Move MySecondPage so that it is aboveMyFirstPage in the project tree. MySecondPage will then be tested
BEFORE MyFirstPage is tested
A Web page is not recognized as MyWebPage in MyApplication but as _Undefined_ in

MyOtherApplication
A Web page that should be recognized as MyWebPage in MyApplication is wrongly detected as _Undefined_ in
MyOtherApplication. The solution depends on the declaration order of MyApplication and MyOtherApplication.
If MyApplication is declared BEFORE MyOtherApplication:
Solution – Change ‘MyApplication’ recognition criteria.
If MyApplication is declared AFTER MyOtherApplication:
Solution 1 – Change ‘MyOtherApplication’ recognition criteria: Try modifying the declaration of

MyOtherApplication so the page in question doesn’t match its recognition criteria

Solution 2 – Declare MyApplication before MyOtherApplication: Move the declaration of MyApplication so that
it is above the declaration of MyOtherApplication in the project tree. MyApplication will then be tested BEFORE
MyOtherApplication.
A Page declared using UI Automation is not always recognized

A page declared using UI Automation is recognized if the target page is opened when Desktop Agent starts. But
it is not recognized if the target page opens after Desktop Agent has started.
This means that recognition criteria are correct, but recognition is not refreshed after Desktop Agent has
started.
Solution – Change the page's Refresh mode:
Set the page’s Refresh mode to Window or Polling so that page recognition is performed after Desktop Agent
has started (see Subpage Recognition [page 109])
Item Recognition Error Cases
A component is wrongly recognized as MyItem

MyItem targets the wrong component.
Solution 1 – Improve MyItem recognition criteria: Try improving the recognition criteria for MyItem so the right
component is targeted.
Depending on the technology, you can use one or more of the following methods:
• Add criteria on other properties or change existing criteria

• Use Items Pattern Method [page 286] (available for Web and UI Automation technologies)
• Use Ancestor Method [page 285]
• Use Labelled By Method [page 285](available for Win and UI Automation technologies)
Solution 2 – Use the ‘Occurs’ method: Declare ‘MyItem’ as a multiple item (for details, see Item Definition
[page 263]), and use the right index to target the right component (see Controlling a Multiple Item [page 228] )
MyItem is not recognized at LOAD time, but is recognized later

When MyPage loads, MyItem is not recognized. After a whilte, it is recognized. This probably means that the
content of MyPage is loaded dynamically. At load time, the targeted component is not yet present in MyPage.
Solution 1 – Set MyItem as MustExist
Try setting MyItem as MustExist (see MustExist Method [page 284]). You will then receive MyPage’s LOAD
Event only after MyItem has been created.
Solution 2 – Wait until MyItem is present using the Polling pattern:
Use the Polling pattern to wait until ‘MyItem’ is present (see The ‘Polling’ pattern here: Control Sequences
[page 343])
MyItem is never recognized

MyItem is never recognized in MyPage. This means that the recognition criteria don’t match.

Solution – Check the recognition criteria for MyItem:
• Make a new capture of MyPage

• Try to change MyItem recognition criteria to target the desired component
I have to manage two versions of the same application

I have to control two versions of the same application. MyItem is recognized in one version, but not in the other.
If you cannot find recognition criteria that match in the two versions, you must declare two version of MyItem.
Solution 1 – Change MyItem recognition criteria to match the two versions
• Make a new capture of MyPage with the second version of the application
• Try to change MyItem recognition criteria to target the desired component in both versions
Solution 2 – Declare two versions of MyItem
• Make a new capture of MyPage with the second version of the application
• Declare MyItem_2 with recognition criteria to target the desired component in the second version
• In your script, test which version is present:
 Sample Code
if (MyAppli.MyPage.MyItem.exist()) MyAppli.MyPage.MyItem.set(myValue) ;
else if (MyAppli.MyPage.MyItem_1.exist())
MyAppli.MyPage.MyItem_1.set(myValue) ;
I have to manage a multilingual application

I have to control a multilingual application. MyItem is declared using a criterion on a label which changes when
current language changes.
If you cannot find recognition criteria that are language-independent, update the criteria to match the different
languages.
Solution – Change MyItem recognition criteria to match the different languages
• Make a new capture of MyPage for each language

• Change the MyItem criterion on the label by adding the different translations using the OR operator

6 References
In this section, get information about:
• Commands [page 474]

• Code Snippets [page 484]
• File and folder management [page 487]
• Multilingual management [page 490]
• Registry management [page 494]
• XML/JSON management [page 496]
• Clipboard management [page 497]
• Cryptography management [page 499]
• Microsoft Office Excel library [page 500]
• Microsoft Office Outlook library [page 502]
• PDF Library [page 506]
• Single sign on management [page 508]
• Managing external parameters [page 511]
• Web service calls and remote file download [page 514]
• Asynchronous and synchronous processes [page 517]
• Managing technical events using the Desktop SDK [page 524]
• Customizing a Windows application [page 530]
• Customizing a web application [page 531]

References PUBLIC 473
6.1 Commands Reference
6.1.1 Main Window Commands
Project Commands
Project Commands
 New project Creates a new project
 Open project Opens an existing project
Close project Closes the current project
 Archive project Creates an archive of all developments

files (script sources, screen captures,
…)
 Export project Export and packages the complete sol

ution prior to delivery for testing or pro
duction
 Save Saves the current file
Save all Save all the currently opened files
Open Debug Session... Open a DebugSession file from disk in a

new Debug Perspective
Open Last Debug Session Open the last DebugSession from

memory in a new Debug Perspective
 Save Last Debug Session... Save the last DebugSession from mem
ory to disk
 Generate Diagnosis
Build criteria doc. Creates an HTML document with tech

nical description of each app, page, and
item criterion)
 Settings Access to Studio settings

474 PUBLIC References
Project Commands
Recent projects List of recently opened projects
 Exit Closes Desktop Studio
Compile and Run Commands
Compile and Run Commands
 Build CTRL + B Compile the Project
Rebuild CTRL + SHIFT + B Clear the ‘bin’ directory and

Compile the Project
 Run CTRL + F5 Starts the Project in Release

mode (without debugger)
Debug F5 Starts the Project in Debug

mode
Debug in Export mode Starts the Project from the

Export result in Debug mode
 Stop SHIFT + F5 Stops the Project execution
View Commands
View Commands
FullScreen SHIFT + ALT + ENTER Toggle the Studio full screen

mode
Open linked docksite Open the linked docksite, al

lowing you to use a double-
screen
 Save Layout Save current layout
 Restore Layout Restore current layout
Tool Windows Lets you show/hide each tool

window

View Commands
Theme Lets you change Studio’s cur

rent theme
Help Commands
Help Commands
Language Reference Open the 'Language Referen

ce' help
Desktop Studio Developer Open the ‘Studio User Guide’

Guide help
About Desktop Studio Opens About box
Related Information
Project Management [page 63]

Debugging and Testing with the Debugger [page 432]
Docking Management [page 30]
6.1.2 Code Editor Commands
Find and Replace Commands
 Find CTRL + F Finds the currently selected

word in the current script
Quick Find Next CTRL + F3 Quickfinds the next occur

rence of the currently se
lected word

Quick Find Previous CTRL + SHIFT + F3 Quickfinds the previous oc

currence of the currently se
lected word
 Find and Replace CTRL + SHIFT + F Finds files anywhere in the

project
 Find Next F3 Finds the next occurrence
 Find Previous SHIFT + F Finds the previous occur

rence
Replace in Files CTRL + F2 Replaces throughout the

project
Clipboard Commands
Clipboard Commands
 Cut CTRL + X Cut the selected text to clip

board
 Copy CTRL + C Copy the selected text to

clipboard
 Paste CTRL + V Paste text from clipboard
 Delete DEL Delete the selected text
 Select All CTRL + A Select all the text
 Undo CTRL + Z Undo last change
 Redo CTRL + Y Redo last change
Duplicate CTRL + D Duplicate the current selec

tion

Editing Commands
Editing Commands
Format Document Reformat all of the text
Format Selection Reformat the selected lines
Indent Lines TAB Indent the selected lines
Outdent Lines SHIFT + TAB Outdent the selected lines
Comment Lines CTRL + SHIFT + Q Comment the selected lines
Uncomment Lines CTRL + SHIFT + K Uncomment the selected

lines
Add Watch Add to Watch window
Navigation Commands
Navigation Commands
 Goto Definition F12 Toggle a bookmark on the

current line
Show in Page Viewer F8 Toggle a bookmark on the

current line
 Toggle Bookmark CTRL + F2 Toggle a bookmark on the

current line
Next Bookmark F2 Navigate to the next book

mark
Previous Bookmark SHIFT + F2 Navigate to the previous

bookmark
 Navigate Backward CTRL + . Navigate backwards in the

Navigation History

Navigation Commands
 Navigate forward CTRL + SHIFT + . Navigate forwards in the Nav

igation History
Show in Code map Navigate from your code into

the Code map
Show in Code tree Navigate from your code into

the Code tree
Debugging Commands
Debug Commands
Resume F5 Continue execution until an

other breakpoint is reached
 Toggle Breakpoint F9 Toggle a breakpoint on the

current line
Step into F11 If we are on a line containing

a method call, this command
will enter the method and
break again on the first line
of code inside the method.
Use Step Into to see what
happens inside a method call
Step over F10 Executes the entire method

call and break on the next
line of code in the current
method. Use Step Over to ex
ecute the entire method and
continue in the current code
block
Step out SHIFT + F11 Executes the rest of the cur

rent method and return to
the calling method. Execu
tion will break at the return
point in the calling function

Debug Commands
Run and Break SHIFT + F10 Continue execution up until

another line of your code is
executed. This command is
particularly useful to break
execution when a callback
function is called
Help Commands
Help Commands
 Help F1 Open contextual Help
Show Quick Info CTRL + F1 Display QuickInfo tooltip
Select Snippet Select Snippet to insert in

code
Auto Complete Opens IntelliSense list rela

tive to the caret context.
Rebuild IntelliSense Rebuild IntelliSense data.
Related Information
Search Features [page 48]

The Code Editor [page 26]
Navigation Features [page 44]
Debugging and Testing with the Debugger [page 432]
Code Editor Help Features [page 53]

6.1.3 Project Tree and Script Tree Commands
Project Nodes
Project Nodes (no node)
Explorer Perspective only
Add a new Application Declare a new application
Editor Perspective only
Add a new Process Declare a new process
 Add a New Script Add a new script
Process Nodes
Process Nodes
 Add New Script Add a new script to the process
 Delete Process Delete the process
Application Nodes
Application Nodes
Capture a new Page Declare a new page
Delete Application … Delete the application and all of its pa

ges.

Application Nodes
Edit Application Edit the application in the Explorer Per

spective
 Add New Script Add a new script to the application
All Perspectives
 Edit XML Opens the XML code of the application

for editing. Take care, this is a low-level
view. It is never refreshed, even if the
code is modified elsewhere.
Edit Resources XML Opens the XML description of the ap

plication for editing. Take care, this is
a low-level view. It is never refreshed,
even if the description is modified else
where.
Page Nodes
Page Nodes
Make a new capture of this Page Replace the current capture by a new
one or add a new capture
Add a Subpage Adds a subpage
Duplicate Page Duplicate the page and all of its items
Move Page (top, up, down, bottom) Move the page in the list of the applica
tion’p Pages
Delete Page Delete the page and all of its subpages

and items
Edit Page Edit the page in the Explorer Perspec

tive
 Create Folder Create a new folder, and store the page

in it

Page Nodes
All Perspectives
 Edit XML Opens the XML code of the page in

the Editor Perspective, for edition Take
care, this is a low-level view. This view
is never refreshed, even if the code is
modified elsewhere.
Edit Resources XML Opens the XML description of the Page

in the Editor Perspective, for edition
Take care, this is a low-level view. This
view is never refreshed, even if the de
scription is modified elsewhere.
Item Nodes
Item Nodes
All Perspectives
Delete Item Delete the item
 Create Folder Create a new folder, and store the item

in it
Move Item (top, up, down, bottom) Move the item in the list of the item’s
page
Duplicate Item Duplicate the item
Copy Item Copy the item to the clipboard
Paste Item Paste the item from the clipboard after

the last item of the page
Edit XML Opens the XML description of the item

in the Editor Perspective for editing
Take care, this is a low-level view. This
view is never refreshed, even if the de
scription is modified elsewhere.

6.2 Code Snippets Reference
Overview
A snippet is a programming term for a set of re-usable source code. Snippets are often used to minimize the
repeated use of the same code.
Desktop Studio can generate code to avoid tedious and repetitive operations, simplify maintenance, and
improve productivity. Snippets complement other ways to generate code:
• Application / page / item declarations

• Scenario management
• Structure declarations
• and so on
Snippet Generation
The functionality is accessible:
• Via the context menu from an editor view

• Via the context menu from the Page viewer, Project view
Some parameters are reserved and can be dynamically replaced, depending on the entity selected:
• app: application name

• page: page name
• item: item name
Predefined Snippets
Types of Snippet
Snippet templates are defined in configuration files, which can evolve and be enriched. They are grouped by
category:
'Language' Basic Snippets for the various Desktop Studio language

verbs
‘Menus’ Snippets used to edit ‘systray’ menu: add/remove, and so

on

‘Item’ Snippets used for item declarations
Page’ Snippets used for page declarations
‘Scenario’ Snippets used for scenario declarations
Menu Snippets
Add Tray Menu Item
Name Description
Usage Add a new menu in the systray menu.
Filter None.
Parameters
Function Function name Default value : current function,
Name Internal menu ID Default value: ‘evStart<function name>’
Caption Display label Default value: ‘Function < function name >’
Result Creates < function name > if it doesn’t exist, • Adds ‘ev
Start<function name>’ menu declaration, • Adds a new
CASE to handle ‘evStart<function name>’ event.
Item Snippets
Start function on clicking a button
Name Description
Usage Create an application event which is called when clicking an

item.
Filter Item node
Parameters
Function Function name
Default value : current function
Source
Application Application
Default value: application containing the selected node, oth

erwise empty.

Name Description
Page Page
Default value: page containing the selected node, otherwise

empty.
Item Object
Default value: name of the selected node.
Event Event to be called.
Default value: 'ev<function name >'.
Result Creates ‘<function name>’ if it doesn’t already exist,
creates event in application,
creates a notification to ‘Application:Event’ when object ‘Ap

plication:Page:Item’ is clicked.
Editing Snippets
Global Structure
Snippet declaration files are located in the ‘snippets’ sub-folder. This folder can contain any number of files, as
long as each one complies with the correct structure.
The format of a snippet file is based on standard snippet format from Microsoft.
Each file contains:
• The structure in term of menus / sub-menus for organizing the snippets

• Some section declarations used to display parameters per category (called ‘property groups’)
• A collection of snippets:
• A name and ID
• A filter (to display snippet only on specified nodes)
• An icon
• A list of parameters to be edited by user
• a list of code parts to be generated and inserted into the project
 Sample Code
<?xml version="1.0" encoding="ISO-8859-1" ?>

<snippets_definition>
<!- property groups -->

<property_groups>
...
</property_groups>
<!- snippet ... -->

<snippet id="..." text="...">
...
</snippet>
<!- snippet ... -->

<snippet id="..." text="...">
...
</snippet>
<!- menu declaration ... -->

<snippets_access>
...
</snippets_access>
</snippets_definition>
Associated Icons
A set of icons is provided to be optionally associated with each snippet: The icon is added by mentioning its
(zero-based) index.
6.3 File and Folder Management
The File System Object (FSO) Library
This library provides a collection of functions for accessing and manipulating files and folders. It is
automatically included in new projects.
The FSO library is structured in different classes:
• Class fso.file to manipulate files

• Class fso.folder to manipulate folders
• Class fso.drive to manipulate drives
• Class fso.ftp to manipulate files through FTP sites
It uses the following ActiveX components:
• File System Object (FSO)

• ADODB.Stream

Manage the FSO Library
The FSO library provides two methods to initialize and end usage of the library:
init Initializes the FSO Library
end Ends Ueage of the FSO Library
The call to the init method instantiate the ‘FSO ActiveX’.
The call to the end free the ActiveX. None of these calls is required anymore as they are automatically called, if
needed, by other methods.
Manage Files
Here are the main functions provided by the FSO library for managing files.
Read / Write a File

The FSO library provides functions to read / write the content of a file:
read Reads the entire content of a file
write Overwrites the content of a file
Manipulate Files
The FSO library provides functions to manipulate files:
openDialog Opens an Explorer dialog to select a file or folder
create Create an empty text file
exist Check whether the file exists
copy Copies the file
move Moves the file
remove Removes the file
deleteInFolder Deletes all files in the folder
Manipulate Filepaths
The FSO library provides functions to parse the filepath:
getBaseName Gets the basename of the file

getExtensionName Gets the extension of the file
getFileName Gets the full name of the file
getParentFolderName Gets the name of the parent folder
Copy a Set of Files

The FSO library provides functions to copy a set of files:
Copies a set of files in asyncronous mode, using ‘roboco

robocopy py’ tool
xcopy Copies a set of files in asyncronous mode, using ‘xcopy’ tool
Zip Files
The FSO library provides functions to manipulate ZIP files:
zip ZIPs a set of files or folders
unzip UNZIPs a ZIP file into a given folder
Manage Folders
The FSO library provides functions to manipulate folders:
exist Checks whether the folder exists
create Creates the folder
copy Copies the folder
getFileCollection Gets the collection of files in a folder
getFolderCollection Gets the collection of sub folders in a folder
move Moves the folder
remove Removes the folder

Manipulate Drives
The FSO library provides functions to manipulate drives:
exist Checks whether the drive exists
get Gets the pointer to drive object
getName Gets the letter of the drive
Access Files Through FTP Sites
The FSO library provides functions to access files through FTP sites:
init Initializes FTP informations
list Lists remote files
download Downloads files from an FTP site
upload Uploads files to an FTP site
6.4 Multilingual Management
Applications and processes implement a multilingual label manager in the ‘ctx.labelManager’ object:
• English, French and German are provided by default, and other languages can be added later.
• English is the default language.
In order to manage all labels in a centralized manner, it is recommended to use the label manager for all
projects, including monolingual ones.
Define Labels
Some labels are predefined when creating the project (standard buttons, ‘About’ popup, ‘Close’ popup, etc.):
 Sample Code
/** String table (English/French/German) */

GLOBAL.labels.set({
menu: {
about: { en:"About...", fr:"A propos...", de:"Uber..." },

restart: { en:"Restart", fr:"Redémarrage", de:"Wieder starten" },
stop: { en:"Shutdown", fr:"Arrêt", de:"Schließen" },
main: { en:"Main Menu", fr:"Menu principal", de:"Hauptmenü" },
...
},
aboutPopup: {
title: { en:"About...", fr:"A propos...", de:"Uber..." },
projectLabel: { en:"Project", fr:"Projet", de:"Projekt" },
projectVersion: { en:"Project version", fr:"Version projet",
de:"Projektversion" },
...
},
...
});
Labels can be added on any application or process by using ctx.labelManager.set() method.
 Sample Code
MyAppli.labels.set({
messages: {
confirm: { en:'Please confirm', fr: 'Veuillez confirmer' },
cancel: { en:'Do you want to cancel ?', fr: 'Voulez vous annuler ?' },
close: { en:'Do you want to close ?' fr: 'Voulez vous fermer ?' }
}
});
For mono-language projects, you can use simplified declarations without specifying the language:
 Sample Code
messages: {
confirm: 'Please confirm',
cancel: 'Do you want to cancel ?',
close: 'Do you want to close ?'
}
});
Select the Current Language
The current language can be selected by using the ctx.labelManager.setLanguage() method.
 Sample Code
// selects English as default language

GLOBAL.labels.setLanguage(e.language.English); // or
GLOBAL.labels.setLanguage('en');
To change the language on all the applications, use a loop on the ‘ctx.app’ object (application container).
 Sample Code
// selects English as default language

for (var id in ctx.app) {

ctx.app[id].labels.setLanguage(e.language.English);
}
Use Labels
To use labels in the code, just type the object name (with IntelliSense help):
 Sample Code
var txt = GLOBAL.labels.menu.about;

// value is "About...", "A propos..." or "Uber...", depending on the current
language
Add a Supplementary Language
A new language can be added by using the ctx.labelManager.addLanguage() method. The new language must
be declared in all applications in which labels are managed.
 Sample Code
// add Dutch to all applications, and select it as default

for (var id in ctx.app)
{
ctx.app[id].labels.addLanguage({ Dutch: 'nl' });
ctx.app[id].labels.setLanguage(e.language.Dutch);
}
The new language must be added to existing labels:
 Sample Code
GLOBAL.labels.set({
buttons: {
yes: { nl:"Ja" },
no: { nl:"Niet" },
ok: { nl:"Ok" },
cancel: { nl:"Annuleren" },
...
}
...
});
New labels can be added in the languages required:
 Sample Code
messages: {
confirm: { en:'Please confirm', nl:'Bevestig alstublieft' },
cancel: { en:'Do you want to cancel ?', nl:'Heeft u wilt annuleren ?' },

close: { en:'Do you want to close ?' nl:'Heeft u wilt sluiten ?' }
}
});
Automatically Select the Current Language
A language can be automatically detected by checking a label value. If the label value exists, the corresponding
language is already defined and can be used as the current language.
 Sample Code
MyAppli.pSearch.events.LOAD.on(function(ev) {
if (this.btSearch.get().indexOf('Opzoeken klanten') != -1) {
// select Dutch language
{
ctx.app[id].labels.setLanguage(e.language.Dutch);
}
} else {
// select French language
{
ctx.app[id].labels.setLanguage(e.language.French);
}
}
});
Ask the User to Select the Current Language
The user can be asked to select the current language. Once selected by the user (via a popup), the information
is stored in the HKCU registry and restored at each time Desktop Agent restarts.
 Sample Code
// set the language

// Check whether registry already has the information
var language = ctx.registry.get("Software\\SAP\\Intelligent RPA\\CtxtRun\
\Settings\\language");
if (language != '' && language != undefined) {
ctx.app[id].labels.setLanguage(language);
}
} else {
// display a popup asking for language decision
var popup = ctx.popup('pFormMisc', e.popup.template.FormSubmit).open({
title: 'Choose your language',
CX: 600,
CY: 155,
form: {
id: 'inputForm',
group: [{
labelLanguage: {
type:'label',
value: "Language",

width: 2
},
lang: {
type:'radio',
value: "fr",
options: {
fr : 'Français',
nl : 'Nederlands'
},
width: 9
}
}]
}
});
popup.waitResult(function(res) {
if (res && res.lang) {
// store language in registry
ctx.registry.set("Software\\SAP\\Intelligent RPA\\CtxtRun\\Settings\
\language",res.lang);
ctx.app[id].labels.setLanguage(language);
}
}
});
}
6.5 Registry Management
Manage Registry Using Desktop SDK
Desktop SDK provides the ctx.registry class to access the Windows registry.
Read a Value from the Registry

You read a value from the Registry by using the ctx.registry.get method:
 Sample Code
// read values in 'HKEY_LOCAL_MACHINE' or in ''HKEY_CURRENT_USER''

var key = "SOFTWARE\\Microsoft\\Internet Explorer\\Main\\Enable Browser
Extensions" ;
var ebe = ctx.registry.get(key, e.registry.root.LocalMachine);
if (!ebe) { ebe = ctx.registry.get(key, e.registry.root.CurrentUser); }
The following syntax can also be used:
 Sample Code

Extensions" ;
var ebe = ctx.registry.get("HKLM\\" + key);

if (!ebe) { ebe = ctx.registry.get("HKCU\\" + key); }
Create a Key or Update a Value in the Registry
You create a key or a value in the Registry by using the ctx.registry.set method:
 Sample Code
// create or update values

// (implicitely, registry root is 'e.registry.root.CurrentUser' and type is
'e.registry.type.String')
var key = "Software\\SAP\\Intelligent RPA\\CtxtRun\\Settings\\SSO\
\MyApplication\\";
ctx.registry.set(key + "Login", myLogin);
ctx.registry.set(key + "Password", myPassword);
ctx.registry.set(key + "Enabled", 1, e.registry.root.CurrentUser,
e.registry.type.Number);
 Note
Standardly, without administration rights:
• Only the ‘current user’ registry (//HKEY_CURRENT_USER//) is edit-enabled.

• The ‘local machine’ registry (//HKEY_LOCAL_MACHINE//) is read-only.
Delete a Key or Value from the Registry
You delete a key or value from the Registry by using the ctx.registry.del method:
 Sample Code

Extensions" ;
ctx.registry.del(key, e.registry.root.CurrentUser);
Encrypt Values in Registry
Desktop SDK provides the ctx.cryptography class allowing to encrypt data (see Cryptography Management
[page 499]).
This makes it possible to mask sensitive data stored in the registry. For example, you can encrypt a login/
password used in a Single Sign On (SSO) mechanism.
The ctx.cryptography class performs symmetric encryption using keys specific to the PC and the user session.
This means that these values cannot be encrypted from another PC and/or user session.

Save encrypted data
You can encrypt data using the ctx.cryptography.protect method:
 Sample Code

\MyApplication\\";
var val = ctx.cryptography.protect(myLogin);
ctx.registry.set(key + "Login", val);
Read encrypted data

You can decrypt data using the ctx.cryptography.unprotect method:
 Sample Code

\MyApplication\\";
var val = ctx.registry.get(key + "Login");
obj.login = ctx.cryptography.unprotect(String(val));
6.6 XML/JSON Management
The ctx.xml and ctx.json libraries implement XML and JSON management functions:
• ctx.xml:
• IXMLNode object serialization / unserialization
• XML / JSON transcoding functions
• And more
• ctx.json:
• encapsulates JSON object: Javascript object serialization / unserialization
• CSV file reading
• And more

6.7 Clipboard Management
Manage Clipboard Using Desktop SDK
Desktop SDK provides basic methods to manage the clipboard via the ctx.clipboard class:
ctx.clip Get the

 Sample Code
board.get() clip
board var txt = ctx.clipboard.get();
content
(in text
format)
ctx.clip Set the

 Sample Code
board.set() clip
board ctx.clipboard.set('Hello world');
content
To receive a notification whenever the clipboard content changes, use the ctx.clipboard.enableTrack method:
 Sample Code
// enable clipboard tracking

ctx.clipboard.enableTrack(true, 'evClipboard');
...
GLOBAL.addOn({ evClipboard: function(ev)

{
...
}});
'Smart Clipboard’ Management
Desktop SDK also provides a high-level tool named ‘Smart Clipboard’.
The ‘Smart Clipboard’ tool makes it possible to memorize data collected during a control sequence. The data
collected is displayed in a popup on demand. The user can choose what data to paste.

To use the memorized data, the user:
• Puts the input focus on any field of an application where the user wants to paste the data
• Hits the parametrized shortcut ('Ctrl+Shift+V' for instance): this displays the popup
• Clicks the desired link : the value is inserted.
Implement the ‘Smart Clipboard’
‘Smart Clipboard’ is available via the ctx.smartClipboard class.
Here is how to use the ‘Smart Clipboard’ tool in an SAP Intelligent RPA project:
At startup
• Initialize the memorized data structure using the ctx.smartClipboard.init method. For each field, the
following information must be provided:
• An identifier,
• A label,
• An optional initial value,
• An optional icon (if the path is relative, the path is : ctx.options.resourceURL + ‘/bmp/’ + icon + ‘.png’).
 Sample Code
ctx.smartClipboard.init({
id: { label:'Id', value:'', icon: 'key' },
name: { label:'Name', value:'', icon: 'user' },
firstname: { label:'Firstname', value:'', icon: 'user' },
email: { label:'Email', value:'', icon: 'mail2' },
mobile: { label:'Mobile', value:'', icon: 'phone' },
street: { label:'Street', value:'', icon: 'mail_yellow' },
number: { label:'Number', value:'', icon: 'mail_yellow' },
zip: { label:'Zip', value:'', icon: 'house' },
label: { label:'City', value:'', icon: 'house' }
});
• Initialize the shortcut or systray menu used to display the popup
 Sample Code

{
// add the shortcut 'Ctrl+Shift+V' for smart clipboard
ctx.regHotKey(e.key.Ctrl + e.key.Shift + 'V',
GLOBAL.events.evShowSmartClipboard);
});
During control sequence

If necessary, when sequence starts, clear the ‘Smart Clipboard’ data using the ctx.smartClipboard.clear
method:
 Sample Code
ctx.smartClipboard.clear();
Memorize data simply by setting ctx.smartClipboard.data fields
 Sample Code
ctx.smartClipboard.data.id = ...;
ctx.smartClipboard.data.name = ...;
ctx.smartClipboard.data.firstname = ...;
ctx.smartClipboard.data.email = ...;
ctx.smartClipboard.data.mobile = ...;
...
When the user hits the parametrized shortcut

Display the ‘Smart Clipboard’ popup using the ctx.smartClipboard.show method:
 Sample Code
GLOBAL.addOn({ evShowSmartClipboard: function(ev)

{
ctx.smartClipboard.show();
}});
When the user clicks a link

The paste action is managed automatically by Desktop SDK.
6.8 Cryptography Management
The ctx.cryptography class implements a set of cryptographic functions to be used in projects. These include:
• User session data protection

• Data encryption/decryption using private/public keys or certificates
• Signature generation/verification using private/public keys or certificates

6.9 Microsoft Office Excel Library
The ctx.excel library implements a set of functions used to facilitate Microsoft Excel automation for
accessing and manipulating Excel files.
Microsoft Excel Integration
Including the Library
Ensure the ctx.excel library is included in the project:
 Sample Code
<SCRIPTS>

...
<SCRIPT Name="Excel library" Src="%sdk%\lib\office\excel.js"
...

...
</SCRIPTS>
Excel Class: Instance and Options
Global variables and functions used to handle the Excel instance: start, maintain and stop the Excel engine.
Options for the ctx.excel Library
newXlsInstance {true, false} Create a new Excel Instance
displayAlerts {true, false} Allow to display alerts
visible {true, false} Allows the excel application to be visible
traceLevel {e.trace.level} Set the trace level
Attention must be paid to the management of the Excel instance used during a process. The Excel library offers
a variety of options, enabling you to design and realize many functional scenarios.
• Create a new Excel instance, use it to manipulate Excel file and quit it at the end of process.
• Use an existing Excel instance created manually by the user, with the ability to manipulate Excel documents
that are already open.
• Release the instance that is currently in use for the user. In this case, the Excel process is still running and
the user has to end it.

Example:
 Sample Code
// Set the excel options
// Set the new excel instance option: allows you to initialize the Excel
library using an existing Excel instance if found
ctx.options.excel.newXlsInstance = false;
// Set the new excel instance option: allows you to initialize the Excel
library with a new Excel instance
ctx.options.excel.newXlsInstance = true;
// Set the display alerts option: allows you to display excel alerts
ctx.options.excel.displayAlerts = true;
// Set the visible option: allows the excel application to be visible

ctx.options.excel.visible = true;
// Set the trace level option: sets the level of trace

ctx.options.excel.traceLavel = e.trace.level;
Initialize the Excel Instance

Before Excel files, workbooks, and worksheets can be manipulated, the Microsoft Excel Library must be
initialized using the ctx.excel.initialize method.
initialize Initializes the Excel library
Once an instance of Excel is initialized, all of its workbooks are accessible to the Excel library and can be
manipulated.
getWorkbook Get the workbook referenced by the workbookName
getWorkbooks Get a reference to the Excel application and a list of the

names of all open workbooks associated with the Excel in
stance
getWorkBookName Returns the name of the Excel WorkBook currently being

edited
getWorkBooksLength Returns the number of available WorkBooks associated with

the Excel instance
Example:
 Sample Code
ctx.excel.initialize();
var list = ctx.excel.getWorkbooks();
var nbWB = ctx.excel.getWorkBooksLength();
ctx.log('There is '+nbWB+' workbooks associated to the current Excel
instance.');
for (var i=1; i<=nbWB;i++){

ctx.log('Workbook n°'+i+' is named: '+list[i-1]);
}
Output:
End the Excel Process
end Ends the Excel library
At the end of excel processing, the Excel instance used must be ended properly.
Example:
 Sample Code
ctx.excel.end();
Release the Excel Instance
release Releases the Excel library
At the end of Excel processing, sometimes the developer has to release the Excel instance and let the user
manage the Excel instance. The user then decides whether or not to end the Excel process. The user must end
the Excel process explicitly and properly.
Example:
 Sample Code
ctx.excel.release();
6.10 Microsoft Office Outlook Library
The Microsoft Office Outlook integration library is a collection of functions used to manage Microsoft Outlook.
For more details, see Microsoft Outlook Extension.
Including the Library
Make sure the library ctx.outlook is included in the project:
 Sample Code
<SCRIPTS>

...
<SCRIPT Name="Outlook library" Src="%sdk%\lib\office\outlook.js"
...
...
</SCRIPTS>
Initialize the Outlook Application
To enable the manipulation of Outlook mails, Microsoft Outlook Library must be initialized using the
ctx.outlook.init() method.
init Initializes the Outlook Application
 Sample Code
ctx.outlook.init();
Once an instance of Outlook is initialized, all methods are accessible and can be used.
End the Outlook Process.
end Ends the Outlook library
At the end of Outlook processing, the Outlook application used should be ended properly.
 Sample Code
ctx.outlook.end();
Retrieve Mails
To retrieve mails from Outlook application, the following steps must be performed:
resetMailCollection The mails will be stored in the working mails list, so it's
important to reset this list and make that it’s empty, because
the working mails list may contain mails searched for previ
ously.

search Search mails using filter containing the details of searching
for mails.
getFilteredTable Gets the filtered table that contains the searched mails but
without full details of each mail.
retrieveMail Retrieves mails stored in the filtered table using the “En
tryID” and “StoreID”, and then builds the working mails list
with the retrieved mails.
The following example shows how to retrieve the Unread Mails from Outlook using the methods mentioned
above and complying with the steps involved in mail retrieval.
 Sample Code
function retrieveUnreadMails() {
var mails = [];
var i = 0;
// Initializes “Microsoft Outlook” application.

ctx.outlook.init();
// Resets the working mails list.
ctx.outlook.mail.resetMailCollection();
// Sets a filter to retrieve all unread mails (with max set to 10).
try {
ctx.outlook.mail.search({
filter : "\"" + "urn:schemas:httpmail:read" + "\"" + "= 0",
maxRow : 10
});
} catch (ex) {
ctx.log("no email found");
return e.error.KO;
}
// Retrieves the result of search.
mails = ctx.outlook.mail.getFilteredTable();
if(mails.length) {
// Build the working mails list by retrieving the detail of each mail.
for(i=0; i<mails.length; i++)
try {
ctx.outlook.mail.retrieveMail({EntryID : mails[i]['EntryID'], StoreID :
mails[i]['StoreID']});
} catch (ex) {
ctx.log("could not retrieve an email");
}
// Displays some information of each mail in debug prints.
ctx.log("---------------------------------------------------------");
for(i=0; i<ctx.outlook.mail.getCollectionLength(); i++) {
ctx.log("Mail n°" + i);
ctx.log("From: " + mails[i]['Sender']);
ctx.log("Subject: " + ctx.outlook.mail.getSubject(i));
ctx.log("Importance: " + ctx.outlook.mail.getImportance(i));
ctx.log("---------------------------------------------------------");
}
}
// Ends “Microsoft Outlook” application.
ctx.outlook.end();
}

 Note
As a best practice, always wrap up the functional methods with a try...catch statement.
The following example is about how to retrieve mails received between “January 21, 2018” and “February 12,
2018” and sent by “hismail@example.com” using the searchByCriteria function.
 Sample Code
function retrieveMails() {
var mails = [];
var i = 0;

ctx.outlook.init();
// Resets the working mails list.
ctx.outlook.mail.resetMailCollection();
// Sets a criteria to retrieve mails (with max set to 10).
try {
ctx.outlook.mail.searchByCriteria({
fromEmail : "%hismail@example.com%",
date : {after : new Date("01/21/2018"),before : new Date("02/12/2018")},
maxRow : 10
});
} catch (ex) {
ctx.log("no email found");
return e.error.KO;
}
mails = ctx.outlook.mail.getFilteredTable();
// Build the working mails list by retrieving the detail of each mail.
for(i=0; i<mails.length; i++) try {
ctx.outlook.mail.retrieveMail({EntryID : mails[i]['EntryID'], StoreID :
mails[i]['StoreID']});
} catch (ex) {
ctx.log("could not retrieve an email");
}
// Displays some information of each mail in debug prints.
ctx.log("---------------------------------------------------------");
for(i=0; i<ctx.outlook.mail.getCollectionLength(); i++) {
ctx.log("Mail n°" + i);
ctx.log("From: " + mails[i]['Sender']);
ctx.log("Subject: " + ctx.outlook.mail.getSubject(i));
ctx.log("Importance: " + ctx.outlook.mail.getImportance(i));
ctx.log("---------------------------------------------------------");
}
}
ctx.outlook.end();
}
 Note

Send Mails
To send mails from Outlook, you need to use the following methods:
create Creates a new mail using object as parameter and pushes it

to mail collection
send Sends mail and removes the mail from the working mail
collection.
 Sample Code
function sendBasicMail() {
ctx.outlook.init();
// Creates a basic mail.
ctx.outlook.mail.create({To:'name@company.com', Subject:'Test mail from
SAP', Body:'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
laborum.'});
try {
// Sends the mail.
var res = ctx.outlook.mail.send(0);
} catch (err) {
ctx.log("Sending of “Microsoft Outlook” mail in failure (" +
err.description + ").");
return e.error.KO;
}
ctx.outlook.end();
}
 Note
6.11 PDF Library
The ctx.pdf library enables data to be extracted from text-searchable PDF documents within the scope of
Desktop Studio projects.
 Note
This PDF library for Desktop Studio has some limitations regarding the documents it can read. They must
be smaller than 15MB and contain fewer than 100 pages or 10,000 words. Failure to comply with these
limits results in an error.
Both methods and activities are available to handle text-searchable PDF documents:

• For full details of the methods, see PDF Extension.
• For details of the activities and their properties, see PDF Activities [page 341].
Tips for Using PDF Activities
Start with Open PDF and End with Release PDF

As soon as you drop a PDF activity onto the workspace of theDesktop Studio Workflow Perspective, the PDF
library is automatically included in your project. For this reason, it is advisable to use the Open PDF activity, for
example, rather than to use only custom activities to handle PDF files.
We recommend ending your PDF-related workflow with the Release PDF activity in order to release all
resources associated with it.
Code Examples
 Sample Code
Extract the complete text of the Ticket document
ctx.pdf.openPdf('..//Ticket.pdf', function(error) {
if (error) {
ctx.log("FAILURE: Opening Ticket.pdf failed");
}
var completeText = ctx.pdf.getText();
ctx.log("Complete Text in pdf :" +completeText);
ctx.pdf.release();
});
 Sample Code
Extract text on page 2
ctx.pdf.openPdf('..//Invoice.pdf', function(error) {
if (error) {
ctx.log("FAILURE: Opening Invoice.pdf failed");
}
var filter = ctx.pdf.createFilter('2');
var textPage2 = ctx.pdf.getText(filter);
ctx.log("Text on Page 2:" +textPage2);
ctx.pdf.release();
});
 Sample Code
Extract the Order Number from the Ticket document
ctx.pdf.openPDF('..//Ticket.pdf', function(error) {
if (error) {
ctx.log("FAILURE: Opening Ticket.pdf failed");
}
var extractedTextRegEx = ctx.pdf.extract(/Order Number: ([A-Z0-9]+)/);

ctx.log("Extracted Order Number:" +extractedTextRegEx);
ctx.pdf.release();
});
In the above example of calling the extract method, the regular expression /Order Number: ([A-
Z0-9]+)/ includes a capturing group, which is denoted by parentheses. As a result, only the string that meets
the criteria and comes after "Order Number: " is returned. If the parentheses are omitted, the entire matching
string is returned.
6.12 Single Sign On Management
The ctx.sso class implements a set of functions to enable Single Sign On in any declared application.
To setup an SSO mechanism on a specific application, various pages must be declared:
• One ‘login’ page with login/password items,

• One or more target pages to navigate to when you succeed to log in.
The mechanism is implemented in the following way:
• When the login page appears for the first time, the login/password are manually inserted by the user. As
soon as a target page is reached, the SSO library captures and stores this information as cyphered data in
the user registry base (HKCU).
• The next times the login page appears, the login/password are automatically inserted by the SSO library
from the cyphered data in the registry base.
• If the login fails (due to an invalid username or an incorrect password, for example), the mechanism aborts
and the user needs to log on manually. Once this is achieved, the new login/password are stored in the
registry base.
Including the SSO Library
Ensure the SSO library is included in the project:
 Sample Code
<SCRIPTS>
<SCRIPT Name="Constants" Src="%sdk%\lib\common\ctx.enum.js"
...
<SCRIPT Name="SSO library" Src="%sdk%\lib\ctx\ctx.sso.js"
...
...
</SCRIPTS>

Declaring the Login Page
Declare the login page with specific items:
• A login item (enable ‘CaptData’ property to ensure data reading when the page is closed),
• A password item (enable ‘CaptData’ property to ensure data reading when the page is closed),
• A button item clicked to login to application (optional),
• An error item displayed when login fails (optional).
Example
• Declare Mantis.pLogin page and items:

• Mantis.pLogin.oUsername: username item,
• Mantis.pLogin.oPassword: password item,
• Mantis.pLogin.btLogin: login button,
• Mantis.pLogin.oWarning: error item.
• Declare other pages (Mantis.pHome, Mantis.pMyDisplay, etc.) as target pages.
Enabling the SSO Mechanism
The SSO mechanism gets enabled by using the ctx.sso.setup method with the following items:
itLogin {ctx.item} Page item for setting the login name
itPassword {ctx.item} Page item for setting the password
[callback] {function(ctx.event)} Callback function called after creden

tials were set
[failCallback] {function(ctx.event)} Callback function called if credentials

could not be set
 Sample Code
// Setup SSO on Mantis.pLogin

ctx.sso.setup(Mantis.pLogin.oUsername, Mantis.pLogin.oPassword, function(ev) {
// *** success callback ***
// click on login button if there is no warning displayed

if (!Mantis.pLogin.oWarning.exist()) {
Mantis.pLogin.btLogin.click();
}
}, function(ev) {
// *** failure callback ***
// display a popup to ask user to set his login/password
ctx.popup('pMantisLogin').open({
template: e.popup.template.TooltipAlert,
icon: e.popup.icon32.info,
message: "<br/>Please provide login and password<br/>",
autoClose: 10000
});
});
Skip the SSO Mechanism When Logging Out
When a user explicitly logs out from the application (in order to login with another credentials/account
for example), the SSO mechanism must be skipped. Otherwise, the application will immediately login
automatically with the SSO mechanism credentials.
In order to avoid this behavior, the click event on the Logout button in the application should be detected in
order to call the ctx.sso.disable method. Here’s how to implement this:
• Declare the Logout item and set a COMMAND or CLICK track event on this item.
• Once the login page is reached, the mechanism is skipped once and then re-enabled for the next
occurrences.
 Sample Code
Mantis.pHome.btLogout.events.COMMAND.on(function(ev) {
// if user logs off explicitly (for example. to logon with another login),
disable auto-login
ctx.sso.disable(Mantis.pLogin);
});
If there are multiple pages containing a Logout button, declare all items with the same name, and use a generic
event handler:
 Sample Code
Mantis.events.COMMAND.on(function(ev) {
if (ev.itemName == 'btLogout') {
// if user logs off explicitly (for example to logon with another login),
disable auto-login
ctx.sso.disable(Mantis.pLogin);
}
});

6.13 Managing External Parameters
Most SAP Intelligent RPA projects have to manage data which must be parametrizable, such as:
• URLs to start Web applications

• Timeout values of scenarios
• Functional reference tables
• Functional conversion tables
It is good practice to manage this data via JavaScript variables so that:
• They can be initialized in one place and used in multiple places

• Their declarations can be provided at the same place
It’s also good practice to initialize these variables with values coming from outside of the scripts, so that:
• These values can be changed without any knowledge of the scripts.

• Different values can be tested without changing the scripts.
Desktop SDK does not provide a standard mechanism to initialize variables from an external source. It does,
however, provide basic features that allow custom management.
This chapter explains the two main methods used for this purpose in most projects.
Initialize Parameters From an External Parameters File
The most frequently used method of managing external parameters is to store their initial values in an external
parameters file.
Content of a Parameters File
The content of a parameters file is free and depends on your project's external parameters. You can use any
format you want for the parameters file.
Desktop SDK provides tools to manage the following formats:
• JSON format,
• XML format,
• CSV format
Using the Parameters File
At runtime, you load the content of the file as a string using the fso.file.read method.
You can then interpret the return string depending on the format used in the file :
JSON format

You can interpret a string in JSON format by using the ctx.json.parse method:
 Sample Code
var strContent = fso.file.read(pathFile) ;

var oParameters = ctx.json.parse(strContent);
Here is an example of a parameters file content:
 Sample Code
{
"Param1" : "value1",
"Param2" : "value2"
}
How to use it:
 Sample Code

var oParameters = ctx.json.parse(strContent);
if (oParameters.Param1 == "value1")
...
 Note
Don’t forget any quotation marks in your JSON file, otherwise the ctx.json.parse method will return
null.
XML format
You can interpret a string in XML format by using thectx.xml.xml2object method:
 Sample Code

var oParameters = ctx.xml.xml2object(strContent);
 Sample Code
<PARAMS>
<Param1>value1</Param1>
<Param2>value2</Param2>
</PARAMS>}
How to use it:
 Sample Code

var oParameters = ctx.xml.xml2object(strContent);

if (oParameters.PARAMS.Param1 == "value1")
...
CSV format
You can interpret a string in CSV format using the ctx.json.CSV2Object method:
 Sample Code

var oParameters = ctx.json.CSV2Object(strContent);
 Sample Code
Param1,Param2
value1,value2
value3,value4
How to use it:
 Sample Code
strContent = fso.file.read(pathFile) ;
var oParameters = ctx.json.CSV2Object(strContent);
if (oParameters[0].Param1 == "value1")
...
Localization of the Parameters File

The parameters file must be available to Desktop Agent at runtime. The simplest way to ensure this is to
include the file in the delivery package of the project.
There are two options:
• Store the parameters file in the ‘local’ subdirectory of your project

If you store the parameters file in the ‘local’ subdirectory of your project, it is included in the delivery
package at export time. Note that its content is protected by the key.xml file and cannot be changed
without redelivering the package.
To load the parameters file, use ctx.options.path.local in your path:
 Sample Code
var strContent = ctx.fso.file.read(ctx.options.path.local + "\

\MyLocalParameters.txt") ;
This way, the parameters file is loaded:

• From the ‘local’ subdirectory when you run your project from Desktop Studio .
• From the delivery package when the user runs your project from his / her workstation.
• Store the parameters file in the ‘server’ subdirectory of your project
If you need to update the parameters file content without having to deliver a new package, store it in the
‘server’ subdirectory of your project.

This way, the parameters file is only copied at export time in the package directory, in addition to the
package. Its content is not protected by the key.xml file, so it can be changed without redelivering.
To load the parameters file, use ctx.options.path.server in your path:
 Sample Code
var strContent = ctx.fso.file.read(ctx.options.path.server + "\

\MyLocalParameters.txt") ;
This way, the parameters file is loaded:

• From the ‘server’ subdirectory when you run your project from Desktop Studio .
• From the delivery package directory when the user runs your project from his / her woprkstation.
 Note
• The parameters file is reloaded from the delivery package directory each time the user runs your
project.
• If you modify the parameters file outside the project, be careful not to overwrite the modified the
parameters file when you make a new delivery.
Manage Parameters via the Command Line of the Shortcut
Another way to initialize external parameters is to pass initial values via the -o option of the command line:
 Sample Code
CtxtRun.exe ... -o "param1=value1|param2=value2|...|paramN=valueN" ...
At runtime, you can obtain the provided values using the following method:
 Sample Code
var strData1 = ctx.options.param1 ; // strData = value1

var strData2 = ctx.options.param2 ; // strData = value2
...
var strDataN = ctx.options.paramN ; // strData = valueN
This way, you can initialize predefined options or define and initialize your own custom options.
6.14 Web Service Calls and Remote File Download
Desktop SDK provides a set of features that help implement Ajax mechanisms and HTTP requests.

These features are implemented by the ctx.ajax class which:
• Provides ‘HTTP request’ management,

• Is mainly used to implement Web Service calls and remote file download.
By default, a web service call is driven in an asynchronous style (recommended).
Call a Web Service
Web Service calls are implemented using the ctx.ajax.call method that encapsulates HttpRequest
management, including:
• REST GE, PUT, POST, and DEL request types

• SOAP calls
• Asynchronous response analysis
• Header/body formatting (form- or Json-based)
• Optional user/login management
The main parameters to consider are:
Name Description Note
method ‘GET’/’PUT’/’POST’/… method type (see ‘GET’, if omitted
e.ajax.method )
url URL to be called mandatory
data Optional data
async Asynchronous / synchronous call asynchronous, if omitted
contentType Data type : ‘form’, ‘json’, ‘xml’, … (see e.ajax.con ‘json’, if omitted
tent )
success Callback called when the call is successfully ter mandatory to get a result
minated
error Callback called in case of error optional
For a complete description of all possible parameters, see the ctx.ajax.call method.
Example : Call REST Web Service (get method)
Search in your CRM all accounts in the Technology industry
 Sample Code
var data = {
filter: "Industry='Technology'",
sort: '-Name'
}

ctx.ajax.call({
method: e.ajax.method.get, // it is implicit
url: 'https://mycrm.com/accounts',
data: data,
contentType: e.ajax.content.form, // input data are added
in URL: '...?...&...'
success: function(res, xhr) {
// res contains an array of accounts
for (var i in res) {
var account = res[i];
//...
}
},
error: function(res) {
ctx.log(' ctx.ajax.call error: ' + res);
}
});
Example : Call REST Web Service (post method)
Create a new account in your CRM.
 Sample Code
var data = {
Name: "SAP SE",
Phone: "+33 1 69 29 82 32",
Type: "Technology Partner",
Website: "www.sap.com",
Industry: "Technology"
};
ctx.ajax.call({
method: e.ajax.method.post,
url: 'https://mycrm.com/accounts',
data: data,
contentType: e.ajax.content.json, // add input data in
request body (JSON format)
ctx.log(res);
},
error: function(res) {
ctx.log(' ctx.ajax.call error: ' + res);
}
});
Download a File
As for Web Service calls, file downloads are implemented using the ctx.ajax.call method.
The main parameters to consider are:
url File URL to be downloaded mandatory

localFile Local file URL mandatory
success Callback called when the download is success mandatory to get a result
fully terminated
error Callback called in case of error optional
Example : Download a set of logos on the Web
 Sample Code
var files = [
{src: 'https://upload.wikimedia.org/wikipedia/fr/9/9e/
Google_Chrome_logo.png', dest: ctx.options.currentDir + '\\chrome.png' },
{src: 'https://upload.wikimedia.org/wikipedia/commons/thumb/c/c9/Intel-
logo.svg/2000px-Intel-logo.svg.png', dest: ctx.options.currentDir + '\
\intel.png' }
];
// launch parallel download
for (var id in files) {
ctx.ajax.call({
url: files[id].src,
localFile: files[id].dest,
ctx.log(res, e.logIconType.Info, 'evTestAjax done: ' + xhr.status);
},
error: function(res, obj) {
ctx.log(obj, e.logIconType.Error, 'evTestAjax failed: ' + res);
}
});
}
Related Information
AJAX Call Samples
6.15 Understanding Asynchronous and Synchronous

Processes
Desktop Agent is a process that performs controlling on an application running in another process.
Most of time, you can develop projects without this knowledge, but it can be useful to understand the concept
of asynchronism and multitasking implemented in Desktop Agent.
This article briefly describes the multitasking architecture of Desktop Agent. It then presents some questions
submitted by developers, where the answers relate to asynchronism and multitasking.

Desktop Agent Multitasking Architecture
Desktop Agent consists of the following components:
• A Listener thread that listens for technical events notified by Desktop Agent connectors
• Received events are stored in an Events queue
• A Dispatcher thread which peeks events from the Events queue and injects them into the JavaScript
engine
• A JavaScript engine which receives injected events and executes associated Event handlers
Use Cases
What Happens when Desktop Agent Starts?

When Desktop Agent starts:
• It injects all JavaScript files of your project into the JScript engine
• JScript engine then executes all the global code (code outside functions) written in the injected scripts
• It triggers the GLOBAL.START event in the Desktop SDK
• Desktop SDK then executes all of the Event handlers associated with this event, one by one
Example:
 Sample Code
// Code executed at startup

GLOBAL.labels.setLanguage('en'); // Choose language
GLOBAL.events.START.on(function (ev) // Set handler on GLOBAL.START event

{
// Code executed when GLOBAL.START event is triggered
ctx.systray().addMenu('', 'evCtxtAbout', GLOBAL.labels.menu.about,
'about'); // Add About menu item in systray
}) ;
What Happens when Desktop Agent Receives a Technical Event?

When Desktop Agent receives a technical event from a Desktop Agent connector:
• It stores the event in its internal Events queue

• The Dispatcher thread waits until an event is available in the internal Events queue When an event is
available:
• It synchronously inject this event into the Desktop SDK running in the JScript engine
• Desktop SDK then executes all the event handlers associated with this event, one by one
• It waits until the Desktop SDK stops handling the event
Can I be Interrupted During Code Execution?

Is there a risk that a piece of code (that is, handling of an event) will be interrupted by the execution of
another piece of code (for example, handling of another event, timeout) ?

The JavaScript engine is mono-tasked, so a sequence of code can never be interrupted.
Generally speaking, only one callback is executed at one time. You must return from a callback before another
callback can be executed.
Example:
In the following example:
 Sample Code
MyAppli.MyFirstPage.wait(function(ev)
{
ctx.log('Before MySecondPage.wait') ;
// Suppose that MySecondPage exists
MyAppli.MySecondPage.wait(function(ev)
{
ctx.log('In MySecondPage.wait') ;
}, 0);
ctx.log('After MySecondPage.wait') ;
}, 0);
You will see log messages in the following order:
 Sample Code
- Before MySecondPage.wait
- In MySecondPage.wait
- After MySecondPage.wait
Are Functional Events Delivered Synchronously?

When a Functional event is notified using the notify method, is the Functional event handler executed
synchronously or asynchronously?
Functional events are delivered asynchronously.
That means that the Functional event handler is not executed during execution of the notify method.
Sometimes, Controlling Fails Although the Page Exists

Occasionally, control action on MyPage.MyItem fails, stating that MyPage is unknown, while
MyPage.exist() returns true.
When the Desktop Agent connector detects that a declared MyPage closes, it immediately notifies an UNLOAD
event.
This event is processed by the Framework, which updates its list of living MyPage instances. A call to
MyPage.exist() method then returns false.
As mentioned above, processing of the UNLOAD event is delayed until the previously received events have been
processed completely. During processing, a call to MyPage.exist() method returns true, while MyPage doesn’t
exist any more.
 Note
The UNLOAD event doesn’t appear in the Debugger's Events view (see Events View [page 435] until it is
treated by the Desktop SDK. When this kind of problem happens, you generally find the MyPage UNLOAD
event just after the error message.

Can I Miss Events During Step Transition?
In a scenario, I open a page in one step and wait until this page opens in the next step. Can I miss the
reception of the LOAD event during step transition?
The endStep method synchronously executes the next step callback.
An Event handler set in this callback will be armed before you exit the current handler. This ensures that you
handle the LOAD event.
Example:
 Sample Code
// ------ Step stMyStep_1

MyAppli.step({ stMyStep_1: function(ev, sc, st)
{
...
{
// Click on btOpenMyPage_2 button to open MyPage_2
MyAppli.MyPage_1.btOpenMyPage_2.click() ;
// Ends the step and synchronously executes stMyStep_2 callback
sc.endStep(stMyStep_2);
}
}});
// ------ Step stMyStep_1

MyAppli.step({ stMyStep_2: function(ev, sc, st)
{
// Wait until MyPage_2 loads
MyAppli.MyPage_2.events.LOAD.on(function(ev)
{
});
}});
Are control actions Executed Synchronously?
When I perform a control action (get, set, and so on), is it executed synchronously? Must I wait between
two control actions?
When you perform a control action:
• Desktop Agent transmits this action to the Desktop Agent connector and waits until it returns.
• The Desktop Agent connector receives the action, executes it, and then returns
So, generally speaking, all the control actions are executed synchronously. There is one exception with the
click() action.
In some applications, clicking a button can lead to long processing times:
• Load a large amount of data

• Perform a long calculation process
• And similar
To avoid Desktop Agent being locked while waiting for the end of the processing, Desktop Agent connectors
execute the click() action asynchronously and return immediately.
So, after a click(), it is not recommended to execute control actions without waiting until the controlling
application has finished its job.

What is the Best Method to Delay control actions?
What is the best method to wait some small time between control actions? Is it not recommended to use
ctx.sleep method to wait?
Desktop SDK provides two methods for waiting for a given time:
• The ctx.wait method waits asynchronously for a given time:
 Sample Code
MyAppli.MyPage.MyFirstItem.set(myValue1) ;
// Waits for 100 ms before continuing
ctx.wait(function(ev)
{
// Wait has elapsed: continue
MyAppli.MyPage.MySecondItem.set(myValue2) ;
...
}, 100);
• The ctx.sleep method waits synchronously for a given time:
 Sample Code
...
MyAppli.MyPage.MyFirstItem.set(myValue1) ;
// Waits 100 ms before continuing
ctx.sleep(100) ;
MyAppli.MyPage.MySecondItem.set(myValue2) ;
...
The drawback of using the ctx.sleep method is that Desktop Agent is frozen during the waiting time:
• No event can be received by Desktop Agent.

• Any Desktop Agent connector that wants to notify a technical events is locked.
Using the ctx.wait method doesn’t freeze Desktop Agent: it is the safest and recommended way to wait for a
given time.
If you want to use ctx.sleep(), make sure that:
• You wait for a short time to let the controlled application do its job
• No Technical event is generated during this time
Otherwise, you may encounter the well-known Server busy message.
I Sometimes Get the ‘Server Busy’ Message

I sometimes get the 'Server busy' message. Where does it come from, and why?
Communication between Desktop Agentand its connectors takes place synchronously using the COM protocol:
• Desktop Agent sends control actions to perform to its connectors

• The connectors send technical events to Desktop Agent
If an exchange takes too long, the COM protocol falls in timeout and the ‘Server busy’ message is displayed.
If you encounter this message, check whether the last executed control order does not take too long:
• The ctx.sleep() call

• Controlling an item that takes time to be recognized (see Controlling Entities Using the UI Automation
Connector [page 110])
• and so on
What is the Best Method to Implement a Waiting Loop?

I need to implement a waiting loop to wait until something happens in the controlled application. What is
the best way to do that?
Because your waiting loop may take a significant amount of time, you must use an asynchronous method to
implement your waiting loop.
1 – Use the ctx.polling method
The best way is to use the ctx.polling method provided by the Desktop SDK.
The ctx.polling method implements an asynchronous polling loop:
 Sample Code
// Implement an asynchronous loop, which repeats 10 times max, with a delay

of 100ms between each repeat
ctx.polling({delay: 100, nbMax: 10
, test: function(index)
{
// Test if MyAppli is ready for next control actions
if (....) return true ;
else return false;
},
done: function()
{
// MyAppli is ready: continue controlling
...
},
fail: function()
{
ctx.log('Polling failed') ;
}
});
When you call the ctx.polling method:
• Desktop SDK calls your ‘test’ callback:

• If it returns true, it calls your ‘done’ callback
• Else, it starts a timer with the given delay
• When the timer ends, Desktop SDK calls your ‘test’ callback:
• If it returns true, it calls your ‘done’ callback
• Else, if the nbMax turns is raised, it calls your ‘fail’ callback
• Else, it starts a timer with the given delay
During the delay between the start and the end of the timer, Desktop Agent is free to receive and manage
events.
2 – Use a Functional event

If, for any reason, you cannot use the ctx.polling method, you can implement an asynchronous loop using a
functional event:
 Sample Code
MyAppli.addEvent({ MyFuncEvent: ''});
// Start the loop by posting MyFuncEvent

MyAppli.notify(MyAppli.events.MyFuncEvent, 0) ;
// The loop
MyAppli.events.MyFuncEvent.on(function(ev)
{
// Get the turn count
var iCount = ev.data ;

if (....)
{
// Test if MyAppli is not ready : loop by posting MyFuncEvent with a
delay of 100ms
MyAppli.notify(MyAppli.events.MyFuncEvent, iCount+1, 100) ;
return ;
}
// Test if max turns is reached
if (iCount > 10)
{
return ;
}

...
});
This pattern was used before the ctx.polling method existed. It is still efficient and given here for your
information, but using ctx.polling is easier.
3 – Don’t use ctx.sleep() method
Event if you are tempted, don’t use the ctx.sleep() method:
 Sample Code
for (var index = 0; index < 10; index++)

{
if (....)
{
...
// Don't forget to return here, otherwise you continue the loop
return ;
}
// Wait 100ms before the next test
ctx.sleep(100) ;
}
// max repeats have been reached
This pattern has several drawbacks, the most severe being that it locks Desktop Agentfor the entire duration of
the loop. In any case, don’t use this pattern (otherwise there may be problems).

6.16 Managing Technical Events Using the Desktop SDK
The Desktop Studio development model is an event-driven model. This means that all of the controlling code
(except for global code) must be associated with technical or functional events, and implemented within
callback functions (termed event handlers).
Defining Event Handlers

When Desktop Agent receives a technical event or delivers a functional event, the framework executes the
corresponding registered event handler.
Implementing Event Handlers

To be callable, an event handler must be registered to the Desktop Agent entity that will receive the desired
event. This is done using the following syntax:
 Sample Code
// Register an event handler which will be called when <event> will be

triggered by <entity>
<entity>.events.<event>.once(function (ev)
{
// <event> has been triggered by <entity> : execute code
});
 Sample Code
// Register an event handler which will be called when user clicks on myButton
myAppli.myPage.myButton.events.CLICK.once(function (ev)
{
// user has clicked on myButton : execute control actions
});
 Note
• In Desktop Studio projects, event handlers are implemented using JavaScript closures. A complete
description of these can be found on the Web.
• Event handlers can be registered to applications, pages and items.
Event Handler Parameters
An event handler receives a parameter corresponding to the triggered event. This parameter is an instance of
the ctx.event class whose members provide access to event properties:
 Sample Code
myAppli.myPage.events.LOAD.on(function(ev)
{
... = ev.appliName; // 'myAppli'
... = ev.pageName; // 'myPage'
... = ev.appliInst; // 26541
... = ev.pageInst; // 1547
... = ev.data; // ...
... = ev.appli; // myAppli application object

});
For a complete list of ctx.event class members, see the Desktop SDK Reference Guide.
Modes of Registration
There are multiple ways to register an event handler:
• Wait once for a technical event

To wait once for a technical event, set a handler on this event by using the once method:
 Sample Code
<object>.events.<event>.once(function(ev)
{
// continue controlling
});
 Sample Code
// wait one time until user clicks on myButton

myPage.myButton.events.CLICK.once(function(ev)
{
// user has clicked on myButton : continue controlling
...
});
 Note
Once the handler has been run, the handler is removed and the callback will not be re-executed the
next time the event arises.
To quickly generate the once method syntax in your code, use an appropriate snippet or type
<object>.events.<event>.once and hit the tab key in the Desktop Studio Editor.
• Wait permanently for a technical event

To wait permanently for a technical event, set a handler on this event using the on method:
 Sample Code
<object>.events.<event>.on(function(ev)
{
});
 Sample Code
// wait until myPage loads

myPage.events.LOAD.on(function(ev)
{
// myPage is loaded : continue controlling
...
});

 Note
Once the handler has been run, the handler is automatically rearmed, and the callback will be re-
executed the next time the event arises.
To quickly generate the on method syntax in your code, use an appropriate snippet or type
<object>.events.<event>.on and hit tabl key in Desktop Studio Editor
• Wait until a page is present

To wait until a page is present, set a handler on this page by using the wait method:
 Sample Code
<page>.wait(function(ev)
{
});
 Sample Code
// wait until pMonAffichage is present

Mantis.pMonAffichage.wait(function(ev)
{
// pMonAffichage is present : continue controlling
...
});
 Note
• If the page already exists, the callback is called immediately, else a 'once' handler is set on the
LOAD event of the page
• To quickly generate the on method syntax in the code, use an appropriate snippet or type
<page>.wait and hit the Tab key in Desktop Studio Editor
• You can use the waitAll method instead. In this case, an on handler is set instead of a once
handler.
• Wait until any page is present

To wait until any page is present, set a handler on the application using the waitPages method:
 Sample Code
<appli>.waitPages(function(ev)
{
});
 Sample Code
// wait until a Mantis page is present

Mantis.waitPages(function(ev)
{
// Mantis has a declared page loaded: continuing our action
...
});

 Note
If a page already exists, the callback is called immediately. Otherwise, a 'once' handler is set on the
'LOAD' event of any page of the application.
• Wait until a page is closed

To wait until a page is closed, set a handler on this page using the waitClose method:
 Sample Code
<page>.waitClose(function(ev)
{
});
 Sample Code
// wait until pMonAffichage is closed

Mantis.pMonAffichage.waitClose(function(ev)
{
// pMonAffichage is closed : continue controlling
...
});
 Note
• If the page is already closed, the callback is called immediately, else a 'once' handler is set on
the 'UNLOAD' event of the page
• To quickly generate the on method syntax in the code, use appropriate snippet or type
<page>.waitClose and hit the tab key in Desktop StudioEditor.
• Wait until a systray menu item is clicked

This pattern is a little different from the preceding ones because a 'systray' object doesn't have an 'events'
attribute.
To wait until a systray menu item is clicked, you can set a handler when the menu item is created:
 Sample Code
// Add 'My item' menu item in the systray

systray.addMenu('', 'ev_MyItemClicked', 'My item', '', function(ev)
{
// 'My item' menu item has been clicked : execute code
});
You can also add the menu item in the systray, then set a handler on the associated event:
 Sample Code
// Add 'My item' menu item in the systray

systray.addMenu('', 'ev_MyItemClicked', 'My item', '');
...
// Wait until 'My item' menu item is clicked
systray.on('ev_MyItemClicked', function(ev) {

// 'My item' menu item has been clicked : execute code
});
 Note
• The handler set is a permanent one ('on' handler)

• To quickly generate the first syntax in the code, use an appropriate snippet or type
systray.addMenu and hit the tab key in Desktop Studio Editor
Registering an Event Handler Alone Doesn't Wait for the Event

It's important to understand that registering an Event handler doesn't block code execution until this Event is
triggered.
 Sample Code
myAppli.myPage.events.LOAD.on(function (ev)
{
// register an event handler which will be called when user clicks on
myButton1
myAppli.myPage.myButton1.events.CLICK.on(function (ev)
{
// user has clicked on myButton1 : execute control actions
});
// immediately register an event handler which will be called when user

clicks on myButton2
myAppli.myPage.myButton2.events.CLICK.on(function (ev)
{
// user has clicked on myButton2 : execute control actions
});
});
• Event handlers on myButton1.CLICK and myButton2.CLICK are not registered until myPage.LOAD is
triggered.
• When myPage.LOAD is triggered, myButton1.CLICK and myButton2.CLICK handlers are both registered.
Only One Event handler is Executed at a Time

At any time, Desktop Agent can receive technical events from supervised applications. The internal
architecture of Desktop Agent ensures that:
• Only one event handler is executed at a time

• Execution of an event handler is completed before another event handler is executed.
For more technical information on this topic, see Understanding Asynchronous and Synchronous Processes
[page 517]

Implementing Waits Without Technical Events
The Polling Pattern

Consider this example of a page with dynamic behavior:
2. WAIT UNTIL THE cityname field has been computed
The best implementation consisted in waiting for a CHANGE event on the zipcode field before continuing
to control the page. This implies that this technical event is notified when the zipcode field is filled. If this
implementation is not successful, you must use the following Polling pattern:
Perform asynchronous polling every xx ms until ending condition is satisfied, then continue controlling.
Here is the implementation in this specific case:
 Sample Code
// Make polling
ctx.polling({
delay: 10, // every 10 ms
test: function()
{
// until 'cityname field is filled
return (page1.cityname.get() != '') ;
},
done: function()
{
// then, continue controlling
var data = page1.cityname.get() ;
...
},
}
 Note
• The ctx.polling method is asynchronous. This mean that event handlers can be executed during
the waiting delays (see Understanding Asynchronous and Synchronous Processes [page 517])
• To quickly generate the polling pattern syntax in your code, use an appropriate snippet or type
ctx.polling and hit the tab key in Desktop Studio Editor.
No Detectable Ending Condition - The 'Wait some time' Pattern

Using the 'Polling pattern' implies that we can detect an ending condition. If this is not possible, you must use
the final waiting pattern: 'Wait some time'.
As explained in Example 2 - page with dynamic behavior,this solution is not very reliable because you can't be
sure that you have waited long enough:
• "Some time" can be too short if the application being controlled is slow
• If "some time" is too long, controlling will be too slow.
But it is a solution that you can use if no other meets your needs.
To wait for 'some time', use the ctx.wait method:

 Sample Code
// wait 50 ms
ctx.wait(function(ev)
{
// 50 ms later: continue controlling
...
}, 50);
 Note
• The ctx.wait method is asynchronous. This mean that event handlers can be executed during the
waiting delays.
• The ctx.sleep method is recommended instead; it is synchronous and blocks execution of Desktop
Agent (see Understanding Asynchronous and Synchronous Processes [page 517])
• To quickly generate the pattern syntax in the code, type ctx.wait and hit the TAB key in Desktop
Studio Editor
6.17 Customizing a Windows Application
Desktop Agent can enrich Windows applications by inserting objects. Compared to Web applications, the
possibilities are limited, however.
Possible customizations include:
• Insert new objects (buttons, static labels, edit boxes)

• Delete inserted elements
For further details, see the ctx.page class.
 Sample Code
// create a button with label 'Start scenario' with size (150, 20), at
position (10, 100) relative to CRM.pCRM.btSearch
CRM.pCRM.createButton(
6002, // Windows numeric identifier
'Start scenario', // label
10, 100, 150, 20, // position (X, Y, CX, CY)
CRM.pCRM.btSearch // position relative to this object
);
 Sample Code
// create an edit box with default text label 'Name...' with size (200, 20),
at position (10, 100) relative to CRM.pCRM.btSearch
CRM.pCRM.createEditbox(
'Name...', // default label
10, 100, 200, 20, // position (X, Y, CX, CY)
);

 Sample Code
// create a static text with text label 'Name : ' with size (200, 20), at
position (10, 100) relative to CRM.pCRM.btSearch
CRM.pCRM.createStatic(
'Name:', // label
10, 100, 200, 20, // position (X, Y, CX, CY)
);
6.18 Customizing a Web Application
Web technology provides additional customization possibilities, as a DOM structure can be modified in a page
on the fly.
Possible customizations include:
• Execute functions in a page, or on given items

• Modify existing objects in the page
• Insert new elements (buttons, images, and so forth) in a page, change classes
For further details, see the ctx.page class.
 Sample Code
// insert a button with id 'myButton', label 'My Button', after item

ELI.pELI.btSearch
res = ELI.pELI.insertButton(
'btMyButton', // id
ELI.pELI.btSearch, // adjacent item
'My Button', // text
{ // attributes to be modified
"class":"btn",
"style":"width:260;height:24"
},
e.htmlPosition.afterEnd, // position relative to adjacent item
ELI.events.evOnClickMyButton // event to be sent when object is clicked
);
// callback called when the button is clicked

ELI.on({ evOnClickMyButton: function(ev) {
ctx.log("'My Button' was clicked !");
}});
 Sample Code
res = Mantis.pMonAffichage.insertLink(
'myLinkSAP', // id
Mantis.pMonAffichage.oLoginText, // adjacent item
'http://www.sap.com', // link to be triggered
'SAP Web Site' // label
);

Example: start an application and call function initialize(obj) when the page is loaded:
 Sample Code
var obj = {
color: e.popup.color.Blue,
buttons: {
...
}
}
// *** Launch using IE ***

Bootbox.pMain.start();
Bootbox.pMain.wait(function(ev) {
Bootbox.pMain.execScript('initialize', obj);
});
Example: inject JavaScript functions inside the Web page, to be called on items
 Sample Code
// create a function to change attributes

function changeObject(element, obj) {
if (element) { for (var id in obj) { element[id] = obj[id]; } }
}
// inject function in the page
ELI.pELI.injectFunction(changeObject);
// call the function
res = ELI.pELI.oLogo.execScript('changeObject', {src: ..., alt : ...});

7 Best Practices for the Desktop Studio
When using the Desktop Studio, you may face some limitations.
Here is a list of these limitations and the best practices to solve them:
• You can find here Knowledge Base notes and How-tos for the Desktop Studio: Desktop Studio.
• You may face errors with the screen lock and the Virtual Desktop Infrastructure. For more information
on how to solve these errors, see: Best Practices for Screen Lock and Disconnected Virtual Desktop
Infrastructure.
• You may face errors when using the PDF Library. For more information on how to solve these errors, see:
Best Practices for PDF Library.
• You may face errors when using web service calls. For more information on how to solve these errors, see:
Best Practices for Web Service Calls.

Best Practices for the Desktop Studio PUBLIC 533
Important Disclaimers and Legal Information
Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:
• Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:
• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.
• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using
such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.
Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.
Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.
Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.
Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities,
genders, and abilities.

534 PUBLIC Important Disclaimers and Legal Information
Important Disclaimers and Legal Information PUBLIC 535
www.sap.com/contactsap
© 2023 SAP SE or an SAP affiliate company. All rights reserved.
No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP
affiliate company. The information contained herein may be changed
without prior notice.
Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.
National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.
SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.
Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.
THE BEST RUN

SAP Help - Desktop Stu Dev Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SAP Help - Desktop Stu Dev Guide

Uploaded by

Copyright:

Available Formats

Developer Guide | PUBLIC

Document Version: 1.0.0 – 2023-04-30

Desktop Studio Developer Guide

THE BEST RUN

1 Developer Guide Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Capturing, Declaring and Controlling Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Desktop Studio Developer Guide

3 Designing Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Desktop Studio Developer Guide

4 Managing Custom Pages With UI Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404

5 Testing and Deploying Your Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

Desktop Studio Developer Guide

7 Best Practices for the Desktop Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

Desktop Studio Developer Guide

1.1 Architecture Overview

SAP Intelligent Robotic Process Automation is composed of different elements:

Desktop Studio Developer Guide

• Is a software component that is installed on a developer's workstation

1.2 About Desktop Agent

1.2.1 How Desktop Agent Works

Here's how it works:

Desktop Studio Developer Guide

1.2.2 Software Architecture of Desktop Agent

Desktop Agent has several components:

• An application launcher that starts processes and downloads project files

1.3 About Desktop Studio

• The Explorer Perspective [page 9] used to declare applications

The Desktop Studio Integrated Development Environment

Desktop Studio Developer Guide

• The Menu bar (1)

1.3.1 The Explorer Perspective

• Perform screen captures (including screenshots and internal page structures).

Desktop Studio Developer Guide

• The Capture Panel [page 15]

Tool Windows in the Explorer Perspective

The Explorer Perspective contains the following tool windows:

These tool windows are described below.

Desktop Studio Developer Guide

The Parameters Tool Window

• A parameters panel (1)

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

Desktop Studio Developer Guide

The Subtree Tool Window

Desktop Studio Developer Guide

The Text Tool Window

• For Windows, it is the text of the component

• Associate the component with a new item

The Criteria Tool Window

• A criteria tree (1)

The Captured Data Tool Window

Desktop Studio Developer Guide

• Of the application or page selected in the project tree

• Copy the property value to the clipboard

The Recognition Tool Window

1.3.1.1 The Project Tree

• Select a declared element to see its captured and declared properties

Elements of the tree are colored as follows:

• Green if the element has been recognized

Desktop Studio Developer Guide

1.3.1.2 The Capture Panel

• The Application view if you selected an application

The Application View

In this view, you can:

The resize panel can be hidden/shown using the Hide but