Documentation¶
French Automation IT ™
Introduction¶
This documentation is dedicated to developers of Open Source RPA/RDA French Automation applications.
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
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
- Save the robot settings and assign API credentials
- Define the available status for your “Request” entity: “Initial” > “Todo” > “Done” (use the “Next status” tab to create a workflow)
- Create a new program called “My Program v1.0”
- Create a new process called “My first automated process” and select the “My Program v1.0” program that you have just created
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.
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
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¶
- 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');
- 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...
}
}