Properties

Description

Return type

Arguments

Use 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.

String

BrowserBitness

Use to define the bitness of the browser. The default is Only32bit. You can set it for 64-bit.

String

CloseTimeout

Use when the Stop method is called on the adapter and is related to the StopMethod property ForceClose, ForceCloseThenTerminate, and SimulateCloseThenTerminate options.

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

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

Milliseconds

Context

Indicates the context in which the Windows adapter component is loaded. Contexts generally apply to solutions running in a Citrix environment. For more information, see Citrix - Project Items.

String

DesignTime

Gets a value indicating if the control is a design time control.

Boolean

EnableX-rayVision

(19.1.73 or later)

Set this property to True to enable the X-ray Vision feature.

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 Using X-ray Vision in Pega Robotic Automation.

The default is False.

Boolean

EnableX-rayVisionEvents

(19.1.73 or later)

Pega Support uses this property to troubleshoot any issues that occur with the X-ray vision feature. Only set this property to True when instructed by Pega Support.

The default is False.

Boolean

EnableX-rayVisionTab

(19.1.73 or later)

Pega Support uses this property to troubleshoot any issues that occur with the X-ray vision feature. Only set this property to True when instructed by Pega Support.

The default is False.

Boolean

ExcludedProcesses

Use this property to identify processes that are not required by your project. For more information, see Excluding Processes for Use in Projects.

ProcessList

Extender

Use this property to specify an extender class implemented in a separate .DLL file for the project. Adapter extender classes implement IAdapterExtender and are able to contribute properties, method, and events to an adapter.

String

FullName

Gets the fully qualified name of the adapter item.

String

HideApplicationAtRuntime

Determines whether the adapter 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 adapter'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.

Boolean

HookChildProcesses

Use 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.

Boolean

IdleTimeout

Sets the amount of time before the application becomes idle.

Milliseconds

InDesign

Gets a value indicating if the control is in design mode.

Boolean

InvokeRequired

Applies when the project and adapter are referenced in code by a non-Studio project and is not used in Studio stand-alone projects. For more information on referencing Studio projects, see the Robotic Automation product page.

Boolean

IsRunning

Gets a value that indicates whether the application is running.

Boolean

IsStartStoppable

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

True – If the application is stopped and then restarted while the project is running, 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, 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 which 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 Studio to hook the application again.

Boolean

IsSuspended

Gets a value that indicates whether the adapter application execution suspended.

Boolean

IsStopping

Indicates whether the application is in the process of stopping. The IsStopping property returns a True value from the time the Stop method is called until the application is finished stopping.

Boolean

MonitoredEvents

Use this property to specify the target types and corresponding events for which event notifications are generated. Browse this property to open the Configure Monitored Events dialog for selection of the target types and events associated with each selected target type for which notifications are generated. See the Events topic for more information.

SelectedEvents

MonitorEventsMode

Use this property to specify the types of application controls for which event notifications are generated. Your options are:

None – No event notifications are generated for the adapter.

All Controls –  Event notifications are generated for any application control matching the selected target types and corresponding events. For this mode, you do not need to interrogate individual controls in the application. It is only necessary to interrogate the main application window to let Studio integrate the application, and complete the MonitoredEvents property to select the controls (target types) and corresponding events for which event notifications will be generated.

For more information, see the Events topic.

Interrogated Controls – Event notifications are generated only for controls which have been interrogated at design time.  For this mode, you must interrogate the application's controls for which you want to generate event notifications and then use the MonitoredEvents property to select the controls (target types) and corresponding events for which event notifications will be generated.

String

Name

Use this property to get or set the name assigned to the adapter.

String

OpenExternalLinksInNewProcess

Controls how web applications or pages, unrelated to the active Studio project, are opened. You can have external web applications open in the same Internet Explorer instance used by the project or force the unrelated application to open in a separate Internet Explorer instance. Your options are:

True – Any web applications/pages unrelated to the active project are opened in separate instances of Internet Explorer. For example, suppose the Studio project is automating the training application (http://training.openspan.com/) on a system using Internet Explorer. If the user opens a webpage unrelated to the project, the page opens in a new instance of Internet Explorer. Any pages opened external to the project remain open after the Studio project is stopped.

False – Any web applications/pages unrelated to the active project are opened in the same Internet Explorer process which is used by the project. For example, suppose the Studio project is automating the training application on a system using Internet Explorer. If the user opens a webpage unrelated to the project, the page opens in a new tab within the current Internet Explorer process and focus will shift to the new tab. In this case, when the Studio project is stopped, Internet Explorer is closed along with any pages opened external to the project.

This property applies regardless of whether the adapter is reparented (displayed in the TabbedReparentContainer control). Therefore, if this property is False and a page external to the project is opened, the page will display in the TabbedReparentContainer control.

Boolean

Path

Use this property to set the path to the first application launched through the adapter. Enter the full path to the executable, for example: C:\Program Files\Pegasystems\CRM Setup\CRM.exe.

If the application is in a folder that is already set in the system path, you can enter the application file name without the full path. Here is an example: Calc.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 which 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. For more information, see Using TargetPath Property.

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.

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

Boolean

ReasonRobotNotReady

Use this property to display a message that describes why the robot could not perform the work.

String

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.

Boolean

SendMessageTimeOut

Sets the amount of time Studio waits for an acknowledgment message before sending the timeout message.

Milliseconds

StartMethod

Use 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 StartMethod Property and StartOnProjectStart.

StartMethod string

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.

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

String

StartMyDayControls

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

• OrganizeApplication

• OrganizeDesktop

• 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.

String

StartOnProjectStart

Sets whether or not the selected adapter should start when the project runs. For more information, see StartMethod Property and StartOnProjectStart.

Boolean

StartTimeout

Sets the interval, in milliseconds, the adapter waits for the application to start before Studio issues a timeout message.

Milliseconds

StopMethod

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

None – Stops the adapter, but leaves the process running.

ForceClose – For each process monitored by the adapter, 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.

String

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.

Boolean

TargetPath

Sets the reference path to the application or document. For more information, see Using Target Path Property.

String

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, Studio attempts to terminate the process. The TerminateTimout value sets the amount of time Studio waits for the process to terminate. If the TerminateTimout value is exceeded, the process is most likely hung and Studio leaves the process running. The TerminateTimeout property applies to each process monitored by the adapter.

Milliseconds

This

A reference to the adapter object.

String

UniqueId

Indicates the unique identifier of the adapter object.

String

WorkingDirectory

Defines the working directory of the application interrogated by Studio. Studio determines the location of the working directory using the Path property.

String

Methods

Description

Parameters

Return Type

AddBuildReference

Use this method when the project and adapter are referenced in code by a non-Studio project and is not used in Studio stand-alone projects.

String reference

Void

BeginInvoke

Use this method when the project and adapter are referenced in code by a non-Studio project and is not used in Studio stand-alone projects.

Delegate method, Object[] args

 IAsyncResult

If you are unable to interrogate a control using Studio’s normal interrogation process, use the ClickChildBy methods when you need to click or double-click on a control. If there are multiple controls that match the criteria you specify using the parameters, the system will click the first one it finds. These methods support most .NET controls that are enabled for Microsoft UI Automation.

There are also overloaded versions of each ClickChildBy method that have only two parameters. These methods work exactly like their namesakes with the default values for the searchType (UIAutomation), clickStrategy (invokeClick), and Boolean highlight (False) parameters. This lets you include them in your automations without having to specify the other three parameters.

ClickChildByName

Use this method to click on a control based on its name value. You can verify the name values of child controls by exploring the parent control and its children using the Native Control Explorer.

Define the name value using the String name parameter. You can enter the exact value or use regex.

The default searchType is UIAutomation.

Enter SimulateClick if you want the automation to actually click the cursor on the location instead of using the control’s Invoke method. The default clickStrategy is InvokeClick.

The default for Boolean highlight is False.

The default for Boolean regex is False.

String name
SearchType (Optional)
clickStrategy (Optional
Boolean highlight (Optional)
Boolean useRegex (Optional)

Boolean

ClickChildByName
(overload)

Use this method to click on a control based on its name value. You can verify the name values of child controls by exploring the parent control and its children using the Native Control Explorer.

Define the name value using the String name parameter. You can enter the exact value or use regex.

String name
Boolean useRegex (Optional)

Boolean

ClickChildByText

Use this method to click on a control based on its text value.

Define the text value using the String name parameter. You can enter the exact value or use regex.

The default searchType is UIAutomation.

Enter SimulateClick if you want the automation to actually click the cursor on the location instead of using the control’s Invoke method. The default clickStrategy is InvokeClick.

The default for Boolean highlight is False.

The default for Boolean regex is False.

String name
SearchType (Optional)
clickStrategy (Optional
Boolean highlight (Optional)
Boolean useRegex (Optional)

Boolean

ClickChildByText
(overload)

Use this method to click on a control based on its text value.

Define the text value using the String name parameter. You can enter the exact value or use regex.

String name
Boolean useRegex (Optional)

Boolean

DoubleClickChildByName

Use this method to double-click on a control based on its name value. You can verify the name values of child controls by exploring the parent control and its children using the Native Control Explorer.

Define the name value using the String name parameter. You can enter the exact value or use regex.

The default searchType is UIAutomation.

Enter SimulateClick if you want the automation to actually click the cursor on the location instead of using the control’s Invoke method. The default clickStrategy is InvokeClick.

The default for Boolean highlight is False.

The default for Boolean regex is False.

String name
SearchType (Optional)
clickStrategy (Optional
Boolean highlight (Optional)
Boolean useRegex (Optional)

Boolean

DoubleClickChildByName
(overload)

Use this method to double-click on a control based on its name value. You can verify the name values of child controls by exploring the parent control and its children using the Native Control Explorer.

Define the name value using the String name parameter. You can enter the exact value or use regex.

String name
Boolean useRegex (Optional)

Boolean

DoubleClickChildByText

Use this method to double-click on a control based on its text value.

Define the text value using the String name parameter. You can enter the exact value or use regex.

The default searchType is UIAutomation.

Enter SimulateClick if you want the automation to actually click the cursor on the location instead of using the control’s Invoke method. The default clickStrategy is InvokeClick.

The default for Boolean highlight is False.

The default for Boolean regex is False.

String name
SearchType (Optional)
clickStrategy (Optional
Boolean highlight (Optional)
Boolean useRegex (Optional)

Boolean

DoubleClickChildByText
(overload)

Use this method to double-click on a control based on its text value.

Define the text value using the String name parameter. You can enter the exact value or use regex.

String name
Boolean useRegex (Optional)

Boolean

EndInvoke

Use this method when the project and adapter are referenced in code by a non-Studio project and is not used in Studio stand-alone projects.

IAsyncResult result

Object

GetSelectedReparentedWindow

Use this method when the project and adapter are referenced in code by a non-Studio project and is not used in Studio stand-alone projects.

None

IntPtr

Hide

Use this method to hide all processes currently running in this adapter. This method is not applicable when the Windows application is selected to display in the TabbedReparentContainer control.

If the Windows application is selected in the DesignComponentConfiguration property for the TabbedReparentContainer, you cannot hide the reparented application by calling the Hide method on the adapter.

None

Void

Invoke

Use this method when the project and adapter are referenced in code by a non-Studio project and is not used in Studio stand-alone projects. For more information, see Creating CSharp to Studio project references.

IAsyncResult result

Object

RematchChildren

Use this method to refresh matching on all objects under the adapter. Set the detach property to True to unmatch all targets before attempting to rematch.

Boolean detach

Void

ResetState

Use this method to reset all component properties to their initial values.

None

Void

Show

Use this method to show all of the processes currently running in this adapter. See the UnMatchOnHidden control property to understand how hiding an application changes control matching.

None

Void

Start

Use this method to start the application.

None

Void

Stop

Use this method to stop the associated process (and all child processes). The system uses the adapter's StopMethod property setting to determine how the Stop method is executed.

None

Void

Events

Description

AdapterLostFocus

Occurs whenever focus changes from any of the application windows to another application window (running under a different adapter or any other application on the desktop). Once the event is triggered, a Duration event argument is calculated which tallies the amount of time (in milliseconds) that the application was in focus. You can use the AdapterLostFocus event with Studio's Events feature in Generic and Custom events projects and/or directly in project automations. You can use AdapterLostFocus event with Java, Remedy Forms, Oracle Forms, and SAP GUI applications.

For more information, see Adapter Events.

ExceptionThrown

Occurs when an exception is raised by the adapter application.

Occurs when the application state changes between ready and not ready.

RobotNotReadyForWork

Occurs when the ReadyForRobotWork property is set to False to indicate that the robot is not ready to perform work.

Started

Occurs when the application is started.

Starting

Occurs when the application is starting

Stopped

Occurs when the application exits.

Stopping

Occurs before Stop is called on the application.

Terminated

Occurs when the application is terminated.