Simplified Robotics API · WorkFusion Documentation

RPA developers can create lighter weight, clearly readable robotics scripts using WorkFusion Simplified API, and temporary files are automatically cleaned up after bot execution.

The Robotics Simplified API provides a wrapper library with a lightweight and succinct jQuery-like syntax, encapsulating best practices into the most frequent functions and hiding the complexity from the end user. As a result, the amount of code is significantly reduced and the code itself becomes clearly readable.

Simplified API reference Java docs are as follows:

The packages are as follows:

Compare API samples

Simplified API:

Expand to view code

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config" scriptlang="groovy">
    <robotics-flow>
        <robot name="roboticsDriver" driver="firefox" close-on-completion="true" start-in-private="true">
            <script><![CDATA[                                    
                timeouts(40 * 1000);
                open("https://mail.google.com");
                            
                $("#identifierId").val("tuk.tuk.rpa@gmail.com").pressEnter();
                $(byXpath("//*[@name='password']")).val("work4WorkFusion!1");
                $("#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>

Original Selenium API sample:

Expand to view code

<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config">

    <script><![CDATA[
        import com.thoughtworks.selenium.*;
        import com.thoughtworks.selenium.webdriven.WebDriverBackedSelenium;
        import org.openqa.selenium.*;
        import org.openqa.selenium.remote.RemoteWebDriver;
        import org.openqa.selenium.interactions.Actions;
        import java.util.concurrent.TimeUnit;
    ]]></script>

    <robotics-flow>
        <robot name="roboticsDriver" driver="internet explorer" 
         close-on-completion="true" start-in-private="true">
            <script><![CDATA[
                ieDriver = roboticsDriver.getWrappedObject();
                
                ieDriver.manage().timeouts()
                    .implicitlyWait(1, TimeUnit.MINUTES)
                    .pageLoadTimeout(1, TimeUnit.MINUTES);
                
                ieDriver.get("https://mail.google.com");
                
                ieDriver.findElement(By.id("identifierId")).sendKeys(new String[]{"tuk.tuk.rpa@gmail.com"});
                ieDriver.findElement(By.id("identifierNext")).click();
                                
                ieDriver.findElement(By.xpath("//*[@name='password']")).sendKeys(new String[]{"work4WorkFusion"});
                ieDriver.findElement(By.id("passwordNext")).click();
                
                ieDriver.findElement(By.xpath("//div[text()='COMPOSE']")).click();
                
                WebElement to = ieDriver.findElement(By.name("to"));
                to.click();
                to.sendKeys(new String[]{"tuk.tuk.rpa@gmail.com"});
                
                WebElement subject = ieDriver.findElement(By.name("subjectbox"));
                subject.click();
                subject.sendKeys(new String[]{"Test message"});
                
                WebElement body = ieDriver.findElement(By.xpath("//div[@aria-label='Message Body']"));
                body.click();
                body.sendKeys(new String[]{"Hello World!"});
                
                ieDriver.findElement(By.xpath("//div[text()='Send']")).click();                                                           
            ]]></script>
        </robot>
    </robotics-flow>

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

The simplified API code is clear and can be understood without deep knowledge of Robotics API:

open("https://workfusion.com");              // Open website in driver's browser
$(byName("username")).val("johny");          // Enter text into field          
$("#submit").click();                        // Click submit button
$(".loading_progress").should(DISAPPEAR);    // Wait until element disappears
$("#username").shouldHave(text("Welcome!")); // Wait until element gets text

Working Examples

Here, you can find some examples of using the Robotics Simplified API:

Automating webpage with AJAX and iframe

Expand to view code

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config"
    scriptlang="groovy">

    <robotics-flow>
        <robot driver="firefox" close-on-completion="true" start-in-private="true">
            <script><![CDATA[
                
                timeouts(40 * 1000);
                
                open("https://www.w3schools.com/xml/tryit.asp?filename=tryajax_first");
                switchTo().frame("iframeResult");
                
                $("#demo h1").shouldHave(text("The XMLHttpRequest Object"));
                $(byText("Change Content")).click();
                
                $(byXpath("//div[@id='demo']/p[1]")).shouldHave(text("AJAX is not a programming language."));
                $("#demo p:nth-child(3)").shouldHave(text("AJAX is a technique for accessing web servers from a web page."));
                
            ]]></script>
        </robot>
    </robotics-flow>
    
    <export include-original-data="true"></export>

</config>

Automating Invoiceplane - web CRM

Expand to view code

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config" scriptlang="groovy">

    <var-def name="client_name">Abbble Inc.</var-def>
    <var-def name="invoice_date">10/02/2016</var-def>
    <var-def name="products_and_prices">{"products_and_prices":[{"product":"Wooden Table","quantity":"2","price":"140"},{"product":"Printer Ink","quantity":"1","price":"30"},{"product":"Paper Rim","quantity":"3","price":"60"}]}</var-def>
    
    <robotics-flow>
        <robot name="roboticsDriver" driver="firefox" close-on-completion="true" start-in-private="true">
            <script><![CDATA[
                                
                timeouts(40 * 1000);
                Map rpaVariables = new HashMap();
                
                open("https://invoiceplane.workfusion.com");
                
                $("#login").click();
                $("#email").val("wf-robot@mail.com");
                $("#password").val("freedom4ROBOTS");
                $(byName("btn_login")).click();
                
                $(byXpath("//*[@id='ip-navbar-collapse']/ul[1]/li[4]/a")).click();                              
                $(byLinkText("Create Invoice")).click();
                $(byClassName("select2-selection--single")).click();

                try {
                    $(byXpath("//*[contains(text(), '" + client_name.toString() + "')]")).click();
                } catch(e) {
                    $(byXpath("//*[@id='select2-client_name-results']/li[2]")).click();
                }
            
                $("#invoice_date_created").val(invoice_date.toString());
                $("#invoice_group_id").sendKeys(Keys.DOWN, Keys.ENTER);
                $("#invoice_create_confirm").click();
                
                Map items = new com.google.gson.Gson().fromJson(products_and_prices.toString(), Map.class);
                List itemsList = items.get("products_and_prices");
                invoice_number = $("#invoice_number").getAttribute("value");

                for (int i = 0; i < itemsList.size(); i++) {
                    Map item = itemsList.get(i);
                    $(byXpath("//*[@id='item_table']/tbody[last()]/tr//input[@name='item_name']")).sendKeys(item.get("product"));
                    $(byXpath("//*[@id='item_table']/tbody[last()]/tr//input[@name='item_quantity']")).sendKeys(item.get("quantity"));
                    $(byXpath("//*[@id='item_table']/tbody[last()]/tr//input[@name='item_price']")).sendKeys(item.get("price"));
                    $(byXpath("//*[@id='item_table']/tbody[last()]/tr//input[@name='item_discount_amount']")).sendKeys("0");

                    if (i < itemsList.size() - 1) {
                        $(".btn_add_row").click();
                    }
                }
                
                $("#btn_save_invoice").click();
                
            ]]></script>
        </robot>
    </robotics-flow>

    <export include-original-data="true">
        <single-column name="invoice_number" value="${invoice_number}"/>
    </export>

</config>

Desktop automation: Notepad, Clipboard, Download file

Expand to view code

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config" scriptlang="groovy">

    <robotics-flow>
        <robot name="C3PO" driver="desktop" close-on-completion="true">
            <script><![CDATA[
                String downloadLink = "https://pub_demo.s3.amazonaws.com/trainings/new.txt";
                String filePath = "C:\\temp\\test.txt";
                String filePathOnAgent = downloadFileOnAgent(downloadLink, filePath);
            
                open("notepad.exe");
                switchTo().window("[CLASS:Notepad]");
                sendKeys("foo");

                // select all and copy
                pressCtrlA();
                pressCtrlC();
                sys.defineVariable("clipboard", clipboardText());

                // paste
                sendKeys(Keys.HOME);
                pressCtrlV();

                // select all and copy
                sys.defineVariable("entire_text", selectAllTextAndCopy());
                
                // undo - redo
                pressCtrlZ();
                pressCtrlShiftZ();
                
                // open file downloaded from s3
                sendKeys(Keys.chord(Keys.CONTROL, "o"));
                
                // select "Do not save" option
                switchTo().window("[TITLE:Notepad]");
                $("[CLASS:Button; INSTANCE:2]").click();
                
                switchTo().window("[TITLE:Open]");
                sendKeys(filePathOnAgent);
                pressEnter();
                
                switchTo().window("[CLASS:Notepad]");
                sys.defineVariable("downloaded_text", selectAllTextAndCopy());
                sleep(3000);
                
             ]]>
            </script>
        </robot>
    </robotics-flow>

    <export include-original-data="false">
        <single-column name="clipboard" value="${clipboard}"/>
        <single-column name="entire_text" value="${entire_text}"/>
        <single-column name="downloaded_text" value="${downloaded_text}"/>
    </export>
</config>

Simplified API has a lot of classes and methods. We suggest you to stop reading, open your WorkFusion Studio IDE and start typing.

Type $ or $(selector)., and IDE suggests you all the available options.

Automatically imported classes

The com.workfusion.rpa.helpers. RPA class represents a simplified API for RPA. Static methods and variables from this class and the following classes are automatically included into Bot configs:

The following classes are also automatically imported into Bot configs. They are accessible by their short-class-name, for example, RemoteWebDriver:

RemoteWebDriver
Action
Actions
Mouse
Keyboard
Wait
FluentWait
WebDriverWait
ExpectedCondition
ExpectedConditions
Coordinates
ApiUtils
PointedCoordinates
RobotsMouse
UiElement
UiElementCollection
UiCondition
UiCollectionCondition

Classes from the following packages also are automatically imported into Bot configs:

org.openqa.selenium.*

Important API methods

tip

WorkFusion Studio IDE supports autocomplete for all the simplified API methods.

The main simplified methods are as follows:

driver(): accessing a current driver instance.
keyboard(): a current driver keyboard.
mouse(): a current driver mouse.
$(By): finds the first element matching given descriptor. With a UIElement instance, you can either do action with it (click, copySelectedText) or check a condition: shouldHave(text("abc")). Both trigger the search of the elements in DOM or desktop.
$$(String): find all elements matching a given descriptor.

Other important simplified methods are as follows:

sendKeys(CharSequence...): sends a string to a current window using the keyboard.
open(String): opens a specified URL or application.
window(String): switches to a window with a specified title or descriptor.
timeouts(long): sets the maximum amount of time to wait for condition, page load, script to execute, element search.

The following additional methods are implemented for desktopDriver:

executeGroovyScript(String)
clipboardText()
copySelectedText()
selectAllTextAndCopy()
sendToAgent(String)
downloadFileOnAgent(String downloadLink, String filePath)
downloadTextFileFromAgent(String)
deleteFileOnAgent(String)

The methods to manipulate Files or Folders and Excel are as follows:

Finding window handles by criteria
Identifying process ID when starting program
Clicking on element with offset
Excel class
Files and folders - the resource class
Script class
Working with S3 inside the robot plugin

Method chaining examples

Note that practically all Simplified API methods support chaining because they return a driver, keyboard, mouse, window, UiElement, or UiElementCollection. Therefore, you can use the following examples with chaining:

Selecting elements, checking conditions

$$(".errorMessage").first().shouldBe(visible, enabled)
$$("td").shouldHaveSize(5)
$$(".edit").getTexts()
$("#myInput").waitUntil(hasPartialValue("John"), 5000)

Mouse driver, browser actions

mouse().doubleClick(20, 40).contextClick(100, 78)
openLinkInNewWindow(byCssSelector(".container a.create-new")).switchTo()

Windows handling, keyboard driver, typing

switchTo().window("[CLASS:Notepad]").maximize()
keyboard().sendKeys(Keys.TAB)
window().close()

Console automation, typing and copying text

window("[CLASS:PuTTY]")
sendKeys("vim 123.txt", Keys.ENTER)
copyPuttyWindowText()