Robotics plugins · WorkFusion Documentation

Robotics plugins provide possibilities to click through desktop or web applications using commands in Web-Harvest scripts. The configuration of where the script is executed is performed on the RPA Windows server side.

robotics-flow

The plugin can contain the robot tags as well as script ones. For each robot tag, a new roboticsDriver is created.

The structure of robotics plugins looks as follows:

<robotics-flow fleet="Office">

        <!-- Internet explorer driver -->
        <robot name="roboticsDriver" driver="internet explorer" close-on-completion="false" start-in-private="true">
            <capability name="javascriptEnabled" value="true"/>
            <script><![CDATA[
                ieDriver = roboticsDriver.getWrappedObject();
                ...
            ]]></script>
        </robot>

        <!-- desktop driver -->
        <robot name="roboticsDriver2" driver="desktop" close-on-completion="true">
            <script><![CDATA[
                desktopDriver = roboticsDriver2.getWrappedObject();
                ...
            ]]></script>
        </robot>

        <!-- universal driver -->
        <robot name="universalDriver" driver="universal" close-on-completion="true">
            <script><![CDATA[
                enableTypeOnScreen();
                openAndFocus("notepad.exe", 3000, 250);   // desktop automation
                sendKeys("New File");
                openFirefox("https://cnn.com");           // browser automation
            ]]></script>
        </robot>        
        
        <!-- Internet explorer driver -->
        <robot name="roboticsDriver" driver="internet explorer" close-on-completion="true" start-in-private="true">
            <script><![CDATA[ ... ]]></script>
        </robot>

</robotics-flow>

The plugin includes the following attributes:

Name	Default	Description
`fleet`	`shared`	Used for distribution of tasks and their routing. For more information, refer to Distribute tasks.

warning

Dynamic fleet attributes are not supported yet. Thus, the code with a dynamic fleet attribute doesn't work.

Dynamic fleet attribute example–not supported yet

<var-def name="fleetVariable">
        <template>SAP</template>
</var-def>

<robotics-flow fleet="${fleetVariable}">
        <robot driver="universal">
        </robot>
</robotics-flow>

robot

The plugin manipulates with the roboticsDriver object (defined in the name attribute) and should have a script child section.

note

All the robot sections inside one robotics-flow are executed on the same RPA Bot Unit one after another.

The plugin includes the following attributes:

Name	Required	Default	Description
`driver`	yes		Defines the driver used for executing robotics instructions: Universal Desktop Chrome Internet Explorer Microsoft Edge (Chromium-based: the driver is available though not supported; use it at your discretion) Firefox (BETA VERSION)
`name`	no		Can be any string; the driver is accessible in the `script` section by this name.
`close-on-completion`	no	true	Specifies whether to close a driver window on plugin completion. If you set this attribute to `false`, a robot session is not closed, and RPA Bot Unit remains occupied.
`start-in-private`	no	false	If `true`, the browser starts in the private mode.
`block-images`	no	false	Blocks images to speed up the page load.
`maximize-on-startup`	no	true	Maximizes the browser window on startup.

Robotics object creation:

sDriver = roboticsDriver.getWrappedObject();  // this object is provided in the context of robot plugin - defined in the "name" attribute

You can include one or several script sections (Groovy language) inside the robot plugin and manipulate with the roboticsDriver object.

Example

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config" scriptlang="groovy">
    <robotics-flow fleet="SAP">
        <robot name="robotDriver" driver="universal">
            <script><![CDATA[

                timeouts(40 * 1000);
                open("https://mail.google.com");

                $("#identifierId").val("tuk.tuk.rpa@gmail.com").pressEnter();
                $(byXpath("//*[@name='password']")).val("work4WorkFusion");
                $("#passwordNext").click();

                $(byText("COMPOSE")).click();            

                $(By.name("to")).val("tuk.tuk.rpa@gmail.com").pressTab();
                $(by("placeholder", "Subject")).val("Robotics API demo").pressTab();

                $(".editable").val("We are not afraid of ajax anymore.").pressEnter();
                $(byText("Send")).click();

                $(withText("Your message has been sent.")).shouldBe(VISIBLE);

            ]]></script>
        </robot>
    </robotics-flow>

    <export include-original-data="false"/>
</config>

capability

With the help of the capability plugin, you can define requirements or parameters for the machine where your Bot Task is executed. For example, you define <capability name="browserName" value="firefox">. When this config is grabbed from a pool, the following actions are performed:

Bot Manager tries to find all available RPA Bot Relays that support the "browserName" capability.
If RPA Bot Relay(s) is found, Bot Manager tries to find all available RPA Bots that have the "browserName":"firefox" capability in the configuration JSON.
If RPA Bot Relay(s) is found, Bot Manager routes your config to be executed on this particular Bot supporting the "browserName":"firefox" capability.
If RPA Bot Relay or Bot is not found, the config execution fails with an exception.

The capability is a child plugin of robotics-flow or robot plugins; you can create several capabilities.

The plugin includes the following attributes:

Name	Required	Default	Description
`name`	yes		Capability name
`value`	no		Capability value

To learn more, refer to the capability reference.

note

The capability inside the robot plugin overrides the capability inside the robotics-flow plugin. See the code example.

Example

<robotics-flow username="" password="">
    <capability name="cleanSession" value="true">

     <robot browser="chrome" ...>
          <capability name="javascriptEnabled" value="true"/>
 
          <!-- This capability overrides the robotics-flow child capability-->
          <capability name="cleanSession" value="false"/>

          <script>...</script>
     </robot>

</robotics-flow>

Configure keyboard, mouse, and window modes

There are cases when you need to automate some legacy applications or software that respond to user interactions with significant delays. Such applications do not support fast typing and can render their window content after some pause.

To handle such situations, you can tweak the delays for robot mouse clicks, keypress events, and window activations.

Robot keyboard: Used to set typing speed and delay. For example, set a delay between keypresses and duration of the keypress:

<capability name="extra.autoit.options">
     <script return="optionsMap"><![CDATA[
         optionsMap = ['SendKeyDelay':20,'SendKeyDownDelay':55]
     ]]></script>
</capability>

Robot mouse: To prevent undesired hover events while bot mouse movements, you can disable the default Smart Mouse Move mode and switch to the Teleport mode. You can also tweak mouse click delays if your application has a significant response time. See an example of setting mouse click delays and disabling Smart Mouse Move (enabling Teleport):
```
<capability name="extra.autoit.options">
    <script return="optionsMap"><![CDATA[
        optionsMap = ['MouseClickDelay':10,'MouseClickDownDelay':20, 'MouseSmartMove':false]
    ]]></script>
</capability>
```
Windows wait delay: You can alter how long a bot should pause after a successful window-related operation. The default value is 300 milliseconds. The example enables to wait 500 milliseconds after each window focusing:
```
<capability name="extra.autoit.options">
    <script return="optionsMap"><![CDATA[
        optionsMap = ['WinWaitDelay':500]
    ]]></script>
</capability>
```

All options are enumerated in the table below:

Option name	Description	Default value	Example
`WinWaitDelay`	Alters how long a script should briefly pause after a successful window-related operation. Time in milliseconds to pause.	300	`optionsMap = ['WinWaitDelay':500]`
`SendKeyDelay`	Alters the delay between typing consequent keystrokes. Time in milliseconds to pause.	55	`optionsMap = ['SendKeyDelay':20]`
`SendKeyDownDelay`	Alters the length of time a key is held down before released during a keystroke. For applications that take a while to register keypresses (and many games), you may need to raise this value from the default. Time in milliseconds to pause.	20	`optionsMap = ['SendKeyDownDelay':55]`
`MouseSmartMove`	Specifies whether the robot moves mouse smoothly (true), or "teleports" cursor (false).	true	`optionsMap = ['MouseSmartMove':false]`
`MouseClickDelay`	Alters the length of the brief pause in between mouse clicks. Time in milliseconds to pause.	300	`optionsMap = ['MouseClickDelay':10]`
`MouseClickDownDelay`	Alters the length of time a click is held down before release. Time in milliseconds to pause.	30	`optionsMap = ['MouseClickDownDelay':20]`
`SendCapslockMode`	Specifies if the library should store the state of capslock before a `Send()` function and restore it afterward. `IGNORE (0)` = don't store or restore. `IGNORE_AND_RESTORE (1)` = (default) store and restore. `CONSIDER (2)` = don't store or restore. Consider the capslock state when sending capital-noncapital keystrokes by adding a shift key.	1	`optionsMap = ['SendCapslockMode':1]`
`DumpsDirectory`	Specifies the directory to store dump files.	. (dot - means current application directory)	`optionsMap = ['DumpsDirectory':'C://dumps']`
`ClipboardRetryDelay`	Specifies a delay in milliseconds between consequent attempts to access the clipboard.	10	`optionsMap = ['ClipboardRetryDelay':30]`
`AcceptableSizeDeviation`	Specifies the maximum control size and position deviation (expected versus actual) in pixels while actual control geometry is still considered as expected.	3	`optionsMap = ['AcceptableSizeDeviation':4]`
`PreTypingDelay`	Ability to set a delay before typing starts. Some applications require time to become ready to accept keyboard events after their window is activated. If keyboard events are sent immediately after window activation, a few first events can be lost, causing skipping the first characters during typing. To handle such situations, you can configure the delay between window activation and typing start.	200	`optionsMap = ['PreTypingDelay':200]`

Tree Walker capability

In some cases, script execution may fail with 0x80131505 or 0x8007000E error codes in RPA worker logs. A target application, as well as RPA worker, may even crash. This behavior can be observed for windows with a lot of UI elements, for example, massive tables. The actual capability option helps to resolve this issue.

Option name: UseTreeWalker Default value: false

Example

    <capability name="extra.autoit.options">
         <script return="optionsMap"><![CDATA[
                 optionsMap = ['UseTreeWalker':true]
                 ]]></script>
    </capability>

note

By enabling the option, the overall performance of Bot Tasks execution can fall. Thus, it is not recommended to enable this option by default.

Desktop driver-specific capabilities

Capability name	Default value	Description
`SEARCH_ALL_WINDOWS`	`true`	By default, the desktop driver can only switch to windows opened in the driver session. To be able to switch to any existing window or window launched outside the driver session, set the `SEARCH_ALL_WINDOWS` capability to `true`.
`CLOSE_ALL_WINDOWS`	`false`	By default, the desktop driver closes all the windows to which it switched, including external windows that were opened outside the driver session. To close external windows, set the `CLOSE_ALL_WINDOWS` to `true`.
`imageSimilarityThreshold`	`0.7`	Can take double values from `0.0` to `1.0`. For surface-based automation, you can set the `imageSimilarityThreshold` capability to solve complicated cases where images should strictly match. For more details, refer to Apply surface-based Robotics driver.

Capabilities for proxy usage

If your IE browser is configured to use a proxy, add the following code into your Bot Tasks. See more details here.

Example

<capability name="ie.usePerProcessProxy" value="true"/>

<!-- Choose one of the following proxy options depending on its type -->


<capability name="proxy">
    <script return="proxyValue"><![CDATA[
        proxyValue = new org.openqa.selenium.Proxy().setAutodetect(true);
    ]]></script>
</capability>


<capability name="proxy">
    <script return="proxyValue"><![CDATA[
        proxyValue = new org.openqa.selenium.Proxy().setProxyType(org.openqa.selenium.Proxy.ProxyType.SYSTEM);
    ]]></script>
</capability>


<capability name="proxy">
    <script return="proxyValue"><![CDATA[
        proxyValue = new org.openqa.selenium.Proxy().setProxyAutoconfigUrl("proxyAutoconfigUrl");
    ]]></script>
</capability>


<capability name="proxy">
    <script return="proxyValue"><![CDATA[
        proxyValue = new org.openqa.selenium.Proxy().setHttpProxy("httpProxy");
        proxyValue.setSocksUsername("userName").setSocksPassword("password");
    ]]></script>
</capability>

warning

You can add only one of the capability name="proxy" blocks from the code block above.