Documentation

https://www.frenchautomation.com/img/logo_fa.png

French Automation IT ™

Introduction

This documentation is dedicated to developers of Open Source RPA/RDA French Automation applications.

Getting Started

1. Concepts

Please refer to Website : Concepts

2. Project methodology

Please refer to Website : RPA

3. Architecture

Please refer to the Architecture section on Website for more explanations.

https://www.frenchautomation.com/img/fa_big_picture.png

4. Installation

Please refer to French Automation Website :

Automated process

1. How to set up an automated process ?

  • Create a new Orchestrator application in Newmips Studio (see 4. Installation). Application has 2 modules: “home” and “administration”

Home module

  • Add a simple entity with a Nodea instruction (call it entity “Request” for instance). This entity wil be the entry to post a request to your robots:

    create entity Request
    add field Name
    
_images/snap_01.png
  • Add a status component with a Nodea instruction

    add component status with name Status
    

Administration module

Go in Administration module of your application:

  • Create API credentials for robot
_images/snap_02.png
  • Register your robot and assign API credentials
_images/snap_03.png
  • Define available status for your “Request” entity: “Initial” > “Todo” > “Done” (use the tab “Next status” to create a chain)
_images/snap_08.png
  • Create a new program with name “My Program v1.0”
_images/snap_06.png
  • Create a new process with name “My first automated process” and select program “My Program v1.0” that you have just set
_images/snap_05.png
  • Create a new media with type “Media task” and title “Media - Automated task”

    Select the following values :

    • Target entity “Request”

    • Task name “Request - {f_name}”

    • Task type “Automatic”

    • Process “My first automated process”

    • Data flow (for instance)

      {
              "f_name": "{field|f_name}",
              "f_login": "robot",
              "f_password": "passwordrobot"
      }
      

    Adapt your data flow with data you need from your “Request” entity to execute task.

_images/snap_07.png

2. Designing the program

Go in Administration module of your application:

  • Display program “My Program v1.0” and tab “Steps”
  • Create a new step (with type “Script”) and define “Start URL” to call first Web page of process ; or simply indicate operations to be done in snippet (with type sequence)
  • Create new steps and order them to control robots
_images/snap_09.png

3. Tools

  • RobotJS
  • Clipboard
  • Recorder

Scripts

1. Variables

There are 2 ways of manipulating variables in scripts:

  • Environment variables that comes from the data flow of task

Syntax:

env.myVariable

For instance, if data flow is set with JSON value:

{
        "isbn": "12345689"
}

Then, script variable “env.isbn” will have value “123456789”

  • SessionData variables that are shared in all steps of program

Syntax:

sessionData.myVariable

For instance, if sessionData is set with values:

{
        "book_name": "King Arthur"
}

Then, variable “sessionData.book_name” will have value “King Arthur”

Another example, if you want to store a variable in session for future reuse at the end of your script, simply return your variable to the robot

(_ => {
        // Initialize Session variable to set list of "invoices"
        var data = [];
        data['invoices'] = [];
        $("tbody > tr").each(function () {
                let invoice = {};
                invoice.id = $(this).find('td:eq(0)').text();
                invoice.f_reference = $(this).find('td:eq(1)').text();
                invoice.f_date_invoice = $(this).find('td:eq(3)').text();
                invoice.f_amount = $(this).find('td:eq(5)').text();
                data['invoices'].push(invoice);
        });
        return data;
})();

You can then access it in next sequence by referencing “utils.sessionData.invoices” (respectively “sessionData.invoices” in a script).

2. Action buttons

Action buttons provide native script instructions to execute simple actions in Web pages. You can access it when creating or editing a step of program.

Fill in forms

Complete fields with the following methods:

Action Description Implementation code
Input field Fill in an input using its name $(“input[name=’myField’]”).val(myValue);
Drop-down list Select a value in drop-down list $(“select[name=’myField’]”).val(myValue).trigger(‘change’);
Check box Click on checkbox $(“input:checkbox[name=’myCheckBox’]”).attr(‘checked’, true);
Activate Radio button Activate a radio button $(“#myRadioButton”).prop(‘checked’, true);
Submit form Submit a form using its name $(“form[name=’myForm’]”).submit();
Click element Click an element referenced by its id $(“#myElement”).click();

Read screen

Retrieve information displayed in screen with the following methods:

Action Description Implementation code
Read text Grab text value in a displayed element $(“div[name=’myElement’]”).textContent;
Read field Retrieve field value $(“input[name=’myField’]”).val();
Find element Find an element referenced by its id $(“#myRootElement”).find(myElement);

Type keys

Execute keyboard typing actions with the following methods:

Action Description Implementation code
Press Enter Press key “Enter” (same as “Return” key) Send key event with code “Enter” (13)
Press Tabulation Press key “Tab” Send key event with code “Tab” (9)
Press Backspace Press key “Backspace” Send key event with code “Backspace” (8)
Press Escape Press key “Esc” Send key event with code “Escape” (27)
Press any key Send key event with the code specified as a parameter Find your key code on https://keycode.info/

Interrupt program

Exit program with the following methods:

Action Description Implementation code
Exit program Throw error to stop the program with specific code throw ‘myErrorCode’;

Note. Action buttons covers main situations you may encounter in scripting. Unfortunately, sometimes you must adapt the code to Website implementation and specificities. Remember that script steps support JQuery usage. Please refer to JQuery API Documentation for further information on DOM manipulations - https://api.jquery.com/jquery/

3. Examples

Fill in a login form

First script example deals with a simple login form to fill and submit

(_ => {

    // Fill in a field
    $("input[name='login_user']").val(env.f_login);

    // Fill in a field
    $("input[name='password_user']").val(env.f_password);


    // Submit a form
    $("form[name='login_form'").submit();


})();

Input and button names can be found in browser using “Developer console” (press key “F12” to open it).

Pick up data in a web page

Second script is about retrieving data from a Web page and set values in session

(_ => {
        // Declare local variable
        let data = {};

        // Read text
        data.name_user = $("div[name='name_user']").textContent;

        // Read text
        data.email_user = $("div[name='email_user']").textContent;

        // Set data in session
        return data;
})();

Sequences

1. Variables

There are 2 ways of manipulating variables in sequences:

  • Environment variables that comes from the data flow of task

Syntax:

env.myVariable

For example, if data flow is set with JSON value:

{
        "isbn": "12345689"
}

Then, sequence variable “utils.env.isbn” will have value “123456789”

  • SessionData variables that are shared in all steps of program

Syntax:

sessionData.myVariable

For example, if sessionData is set with values:

{
        "book_name": "King Arthur"
}

Then, sequence variable “utils.sessionData.book_name” will have value “King Arthur”

2. Action buttons

Action buttons provide native script instructions to execute simple actions in Web pages. You can access it when creating or editing a step of program.

Download

Manually download a file at a specific URL with the following method:

Action Description Implementation code
Download Download a file located at a specific URL utils.download(‘FILE_URL’);

Downloaded files are avaible in folder “exec/downloads” of robot installation directory.

Check other download methods in the Wiki section

Upload

  1. Upload a file using user interface

Procedure is valid for HTML5 input file and clickable dropzones. It consists in:

  • Clicking on input file or dropzone (we suppose this action has been performed in previsous script step and dialog box in now opened)
  • Open filepath in dialog box (using Ctrl + “l” and removing any browser suggestion with backspace)
  • Copy and paste filepath
  • Press enter to submit the dialog form

Syntax:

var robot = require("robotjs");
robot.setKeyboardDelay(1);

const delay = require('delay');
await delay(2000);

// robot.keyTap("l", "control");
robot.keyTap('l', process.platform==='darwin' ? 'command' : 'control')
await delay(2000);

robot.keyTap('backspace', process.platform==='darwin' ? 'command' : 'control')
await delay(500);

const { clipboard } = require('electron')
clipboard.writeText(download.filePath);
robot.keyTap('v', process.platform==='darwin' ? 'command' : 'control')

await delay(2000);
robot.keyTap('enter');
  1. Upload a file on the orchestrator application:

Procedure enables to store a file in orchestrator for future reuse

Syntax:

// Upload a document
const downloads = await utils.waitDownloads();
for (const download of downloads)
    if (download.state == 'success')
        await utils.upload('API_URL', download.filePath)

Mouse events

Execute mouse actions with the following methods:

Action Description Implementation code
Move cursor Move cursor at a given position (can be obtained using Recorder - See below) robot.moveMouse(x, y);
Click Click with the left button robot.click();
Right click Click with the right button robot.click(‘right’);
Double click Click with the right button robot.click(‘left’, true);

Keyboard events

Execute keyboard actions with the following methods:

Action Description Implementation code
Type text Type text on standard output (/!\ “qwerty” keyboard only ; use copy / paste clipboard instead) robot.typeString(‘myText’);
Hit a key Type a key on standard output robot.keyTap(‘f2’);

Interrupt program

Exit program with the following methods:

Action Description Implementation code
Exit program Throw error to stop the program with specific code utils.error(‘myErrorCode’);

3. Examples

Send information to orchestrator

First sequence example explains how to update an entity (entity “Product” in this case) in Orchestrator aplication using API

module.exports = {
        execute: async utils => {

                // Test condition
                if (utils.sessionData.product) {

                        // Update server entity
                        let form = {};
                        form.f_name = product.f_name;
                        form.f_description = product.f_description;

                        utils.api.call({
                                url: '/api/product/' + utils.sessionData.product.id,
                                method: 'put',
                                orm: form
                        });
                }
        }
}

Manipulate a desktop application

Second sequence example enables to use a Libre Office spreadsheet with mouse and keyboard:

module.exports = {
        execute: async utils => {

                var cp = require("child_process");
                cp.exec("libreoffice");

                // Mouse mouse a given position
                // Open a new spreadsheet
                robot.moveMouse(256, 33);

                // Click
                robot.mouseClick();

                // Type some text
                robot.typeString('123');

                // And so on...

        }
}