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 the website : Concepts

2. Project methodology

Please refer to the website : RPA

3. Architecture

Please refer to the Architecture section on our website for more explanations.

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

4. Installation

Please refer to the French Automation Website :

Automated process

1. How to set up an automated process ?

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

Home module

  • Add a simple entity with a Nodea instruction (name it entity Request for instance). This entity wil be the entry point to post a request to your robot:

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

    add component status with name Status
    

Administration module

Go to the Administration module of your application:

  • Create API credentials for the robot
_images/snap_02.png
  • Save the robot settings and assign API credentials
_images/snap_03.png
  • Define the available status for your “Request” entity: “Initial” > “Todo” > “Done” (use the “Next status” tab to create a workflow)
_images/snap_08.png
  • Create a new program called “My Program v1.0”
_images/snap_06.png
  • Create a new process called “My first automated process” and select the “My Program v1.0” program that you have just created
_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 any data you need from your “Request” entity to execute the task.

_images/snap_07.png

2. Designing the program

Go to the Administration module of your application:

  • Display the “My Program v1.0” program and click on the “Step” tab
  • 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 any new steps and re order them to control the robots
_images/snap_09.png

3. Tools

  • RobotJS
  • Clipboard
  • Recorder

Scripts

1. Variables

There are 3 kinds of variables in scripts:

  • Step variables that comes from the step currently executed. Currently “stepIndex” and “serialNumber” are defined.

Syntax:

stepData.stepIdx // Index of step in programme
stepData.serialNumber // Displayed order in programme (which is equals by default to: stepIdx + 1)

For instance, during process script variable “stepData.isbn” will have value 5 and “stepData.serialNumber” will have value 6

  • 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 this 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 a session for future re-use 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 the 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).

Grab 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 provides 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 from 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 assume 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 a program

Exit a 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 the orchestrator

The first sequence example explains how to update an entity (entity “Product” in this case) in the Orchestrator application 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

The second sequence example enables to use a Libre Office spreadsheet with a 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...

        }
}