Skip to main content


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

Windows application properties

Updated on October 19, 2022

Windows applications have the following properties that can be defined to control how an application works with Pega Robot Studio.

You can access design properties from the Property Grid or in the Application tab of the Application Designer, as shown in the following figure:

Application Designer
Application Designer showing Property grid and Application tab.

Properties

PropertyDescription
Path

Set the path for the application. Enter the full path to the executable (for example: C:\Program Files\Pegasystems\CRM Setup\CRM.exe.)

Use the Folder sub-property when the executable is in a different folder on Runtime workstations which will be running the deployed solution than on the Studio workstation. The Folder property lets you select a system folder for the executable which Runtime uses to open the application in the runtime project. You select these folders from a menu with options such as Deployment, Temporary, Personal, and so on.

If the solution is using an application that launches other applications which will be interrogated, use the Path property to set the path for the launching program and use the TargetPath property to set the path for the application to be interrogated. Set the HookChildProcesses property to True if multiple applications are launched and these applications are interrogated.

StartMethodUse this property to define whether the Studio project launches the adapter application, or whether Studio waits for an external actor to launch it. For more information, see Start methods for Windows applications.
StartOnProjectStartSets whether or not the selected application should start when the project runs.
CredentialsSet the application credentials for assisted sign-on. Click the More menu to open the Credential Collection Editor and add credential properties.
FriendlyNameThe friendly name of the application that displays for users in StartMyDay.
StartMyDay

Use this property to specify how this adapter participates in Start My Day functionality. For instance, choose Automatic if you want the adapter to start automatically or Manual if you want the user to start the adapter. The default is None, which indicates the adapter does not participate in Start My Day functionality.

When you choose Automatic or Manual, the StartOnProjectStart property is updated to reflect your choice.

ReadyForRobotWork

Use this property to control whether an RPA robot receives new work from Robot Manager. If set to True, which is the default, the property indicates that the application is loaded, logged into, and ready for the robot to begin its work.

The heartbeat messages from the robot communicate a Ready/NotReady status to Robot Manager.

If an application fails when processing robot work assignments, change its ReadyForRobotWork value to False and use the ReasonRobotNotReady property to describe the failure.

For example, in Robot Manager you would see a message similar to the following example if ReadyForRobotWork is set to False and ReasonRobotNotReady is set to “Cannot access applications.”:

Robot not ready. Cannot access applications.

If at least one application in the loaded solution is set to not ready, then the robot is not ready and does not request new work assignments from Robot Manager.

ReasonAdapterNotReadyUse this property to display a message that describes why the robot could not perform the work.
AdvancedConfigurationAdvanced options that should only be used when directed by Support.
ApplyTimeoutToAllControlsSpecifies if the ControlTimeout value should be used for all controls.
ArgumentsUse the Arguments property to enter command-line arguments for an executable file shortcut. For example, you could enter a file name here so when a program launched via a shortcut starts, it opens that file. Also use this property when working with Java applications to specify the Java class name.
CloseTimeout

Specifies the amount of time, in milliseconds, to wait for the process to exit after the Stop method has been called. The TerminateTimout value applies when the CloseTimeout expires. After the CloseTimeout expires, Robot Studio attempts to terminate the process. The TerminateTimout value sets the amount of time to wait for the process to terminate. If this TerminateTimout value is exceeded, the process is most likely hung and Robot Studio leaves the process running.

The CloseTimeout and TerminateTimout properties apply to each process monitored by the adapter.

ControlTimeoutSpecifies the amount of time in milliseconds to wait before timing out, if ApplyTimeoutToAllControls is set to True.
EnableMactchingProcessSet to True to improve matching performance by executing matching within a target process, when available.
EnableRuntimeSelfHealingIf X-ray Vision is disabled, it does not assigne PegaIDs to new controls and disables attribute change detection at runtime.
EnableX-rayVision

Set this property to True to enable the X-ray Vision feature. (The default is True.)

X-ray Vision automatically identifies controls in the application that you are automating. As you interrogate an application, if new controls become available when you navigate through the application, or a screen change makes new controls appear, Robot Studio adds the new controls to the X-ray database file and assigns a PegaId to each control.

This numeric PegaId serves as the match rule for the control in your automation. For more information, see X-ray Vision.

ExcludedProcessesUse this property to identify processes that are not required by your project. For more information, see Excluding processes in projects.
FullNameGets the fully qualified name of the application or control.
HideApplicationAtRuntime

Determines whether the application window displays while the project and corresponding application is running. Set this property to True to hide the application during project runtime. If you set this to True on the Properties Grid at design time, you can use the adapter's Show method in an automation to display the application while the project is running. You can also hide the application by calling the application's Hide method.

For reparented applications, this property is not applicable when the application is selected to display in the TabbedReparentContainer control. If the application is selected in the DesignComponentConfiguration property for the TabbedReparentContainer, the application displays even if the HideApplicationAtRuntime property is set to True. Also, you cannot hide the reparented application by calling the Hide method on the adapter.

HookChildProcessesUse this property to specify how Robot Studio interacts with any processes spawned by the adapter application. Set this property to True to have Robot Studio inject into spawned processes, thereby enabling interrogation spawned application targets. For more information, see Using HookChildProcesses.
IdleTimeoutSets the amount of time before the application becomes idle.
IeRematchEventsFor Internet Explorer, this is a comma-separated list of events that notify a Web page to rematch. To avoid excessive matching, use only when advised by Support.
IgnoreJavaScriptFramesSet to True to improve matching performance on pages that use numerous JavaScript frames (frames whose source property begins with "javascript". This is known to cause matching issues for applications such as Siebel.
IgnoreMainBrowserIndicates whether Robot Studio should ignore hooking the Web browser. This property only applies to adapters that load the MicrosoftHTMLFactory.
IsStartStoppable

Controls how the project reacts when the application has been stopped and then restarted, such as when the user closes the application and then restarts it. Your options are:ul

  • True: If the application is stopped and then restarted while the project is running, Robot Studio will hook the application again so that automations or event monitoring can continue.
  • False: If the application is stopped and then restarted while the project is running, Robot Studio will not attempt to hook the application. The controls within the application will no longer be matched and therefore the project's automations/event monitoring that use the application's controls will fail. The adapter's Start method will not restart the application. You must stop and start the project for Robot Studio to hook the application again.
JavaInvokeTimeoutThis property only applies when automating Java applications. Set to the number of milliseconds to wait for the Java UI to become responsive before timing out. Set to 0 to not time out.
ResolvePath

Use this property with the Path property at design time to help resolve the full qualified path of the application automatically. Set the ResolvePath property to True if the application path is part of the system environmental path and you want the Designer to auto-complete the Path property.

Set the ResolvePath property to False if you want to manually select the location of the executable or you are using the MonitorAll StartMethod on the adapter. When using MonitorAll, the executable name is the only required value in the Path property.

SendMessageTimeoutSets the amount of time Robot Studio waits for an acknowledgment message before sending the timeout message.
SensitiveSet to true if this control has sensitive values that should be masked in design blocks and logs. For more information, see Sensitive data.
StartMyDayControls

Indicates which controls are used by the StartMyDay component to locate the application using the following methods:

  • OrganizeApplication
  • GetApplicationPositionAndSize
  • SetApplicationPositionAndSize

The system lists eligible interrogated controls in the Collection dialog. Select all windows, web pages, or screens that are required to locate the application for the StartMyDay component.

Note: If there is no matching StartMyDayControl available when an Organizing method is called, the application is not affected.

StartOnProjectStartSets whether or not the selected application should start when the project runs. For more information, see Start methods for Windows applications.
StartTimeoutSets the interval, in milliseconds, that the adapter waits for the application to start before Robot Studio issues a timeout message.
StopMethod

Sets how Robot Studio stops the application when the Stop method is called on the adapter. Your options are:

  • None: Stops the application, but leaves the process running.
  • ForceClose: For each process monitored by the adapter, Robot Studio sends the message WM_CLOSE to each top-level window in the process and waits up to the CloseTimeout value for the process to exit. If the CloseTimeout is exceeded, Studio leaves the process running.
  • SimulateClose: For each process monitored by the adapter, Studio sends the message WM_SYSCOMMAND (with parameter SC_CLOSE) to each top-level window in the process and waits up to the CloseTimeout value for the process to exit. This simulates the user clicking the X on each form’s title bar. If the CloseTimeout is exceeded, Studio leaves the process running.
  • ForceCloseThenTerminate: Same as ForceClose, except Studio waits up to the CloseTimeout value for the process to exit. When the CloseTimeout period expires, Studio attempts to terminate the process and waits up to the TerminateTimeout value for the process to exit. If the process does not terminate within the TerminateTimeout it is likely hung and Studio leaves the process running.
  • SimulateCloseThenTerminate: Same as SimulateClose, except Studio waits up to the CloseTimeout value for the process to exit. When the CloseTimeout period expires, Studio attempts to terminate the process and waits up to the TerminateTimeout value for the process to exit. If the process does not terminate within the TerminateTimeout it is likely hung and Studio leaves the process running.
  • Terminate: This setting does not attempt to gracefully close the process. For each process monitored by the adapter, Studio attempts to terminate the process immediately and waits up to the TerminateTimeout value for the process to exit. If the process does not terminate within the TerminateTimeout it is likely hung and Studio leaves the process running.
SuppressForegroundWindows

Set to True to prevent an application from creating top-most windows or bringing windows into the foreground when it is not the active application. The default is False.

For example, when automating a Windows application in the background, the application may create top most windows that show over the top of foreground windows disrupting user activity.

Setting this property to True prevents the application from creating new topmost windows, converting existing windows to topmost, and bringing windows into the foreground.

TargetPathSets the reference path to the application or document. For more information, see Using the TargetPath property.
TerminateTimeout

Use this property when the Stop method is called on the adapter. This property is related to the StopMethod property and the ForceCloseThenTerminate, SimulateCloseThenTerminate, and Terminate options. The TerminateTimout value applies when the CloseTimeout expires.

After the CloseTimeout expires, Robot Studio attempts to terminate the process. The TerminateTimout value sets the amount of time to wait for the process to terminate. If the TerminateTimout value is exceeded, the process is most likely hung and Robot Studio leaves the process running. The TerminateTimeout property applies to each process monitored by the adapter.

UniqueIDIndicates the unique identifier of the adapter object.
WorkingDirectoryDefines the working directory of the application interrogated by Studio. Robot Studio determines the location of the working directory using the Path property.
WPFIdleTimeoutThis property only applies when automating .NET WPF applications. It sets the amount of time before the WPF UI becomes idle and is processed. Set to 0 to disable this timer. Not used if X-ray Vision is enabled.

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us