1. Home
  2. Iterop Design
  3. Use a script
  4. General Scripting Information

General Scripting Information

Usage and use of scripts in Iterop

Scripting tasks are automatic tasks that allow Iterop to perform internal calculations (as opposed to service tasks which are automatic tasks to connect to third party information systems).

Scripting task

Writing scripts in Iterop is done in the scripting task configuration in Iterop Design by clicking on “Edit Script”.

We will  be able to use scripting tasks in the following cases :

  • Changing the value of a variable in the process
  • Modification of Iterop repositories (lists, business repositories)
  • Launch multiple instances of processes from a master process
  • Perform calculations on process variables (delays between two dates, case disjunction…)

Iterop uses a JavaScript engine for script execution. This engine only embeds native JavaScript libraries to which Iterop functions have been added.

Astuce

In a script task you can use the right click which will give you a context menu allowing you to access the identifiers of variables, tasks, lists, dependency tables and Iterop functions.

Very simple use case of a script

Here is a very simple process where we enter the number of items we have in stock and its unit price. The purpose of the script will be to automatically calculate and record the total market value of the stock so that it can later be displayed or processed.

Step 1 “Define stock” (Human Task) : 
The user enters the quantity and unit price of the material manually.

Step 2 “Calculate stock value” (Script Task) : 
The script multiplies the number of items in stock by its unit price.

var js_ quantite = definirStock_quantite;
var js_valeurUnitaire = definirStock_valeurUnitaire;
var js_valeurStock = js_quantite * js_valeurUnitaire;
execution.setVariable("valeurDuStock", js_valeurStock);

Step 3 “Display quantity and stock value” (Human Task) :
The result is displayed in a task.

Typical structure of a script

Information

This part provides you with good practices for writing scripts in Iterop. It is not mandatory to follow them, but it is strongly recommended, in particular to ensure their legibility and maintainability.

It is advisable to structure your Iterop script by following these steps:

  1. Retrieving process variables from local script variables
  2. Processing on previously created local variables
  3. Updating process variables from local script variables

Retrieving process variables from local script variables

This step consists in retrieving the process variables that the script will manipulate.

Bonne pratique

To avoid any confusion it is preferable to prefix the local variables you create with the prefix “js_”.

Depending on the type of variable in the process (text field, date, boolean, number) the type retrieved in the javascript will be different. The table below gives the correspondence between the type of variables in Iterop processes and the type that is retrieved in JavaScript.

Iterop type

Type in JavaScript

Boolean

boolean

Text Field, Text Block, Rich Text, Password, Value List, Users, Multi-User, Group, Multi-Group, Compound Variable, Complex

string

File

string (file id)

Date, Date and Time

object

Integer, Decimal number

number

Compléments

If a variable is not filled in a form then its value is “null” in javascript except in the case of compound variables where the value is the string “[]”. On the other hand, if it is not displayed on a form (existence of a display condition on this variable) then its type is “undefined” in JavaScript.

In order to carry out the processing that one wishes in JavaScript, it is necessary to transform the recovered variables into variables that can be exploited in JavaScript. The following script gives common examples of variable retrieval (by convention, variables from the process are prefixed with “start_”): 

//Récupération d'une date 
var js_date = new Date(start_date.getTime()*1);
//Transformation d'une liste en Array JavaScript
var js_tableauItemListe = start_liste.split("##");
//Récupération d'une variable composée en json
var js_jsonVariableComposee = JSON.parse(start_variableComposee);
//Récupération d'une variable retour de service en JSON
var js_retourService = JSON.parse(tacheService_out);

Processing on previously created local variables

This is where we’re going to write our script. The use of JavaScript functions is recommended when writing a script for reuse.

The following code gives an example of how to use a function:

var js_dateA = new Date(start_dateA.getTime());
var js_dateB = new Date(start_dateB.getTime());
//Appel de la fonction JavaScript
var js_delai = calculDelaiDates(js_dateA,js_dateB)

function calculDelaiDatesJours(dateA,dateB){
//Cette fonction renvoie le nombre de jour entre une dateB et une dateA
	var delai = (dateB.getTime()-dateA.getTime())/(1000*60*60*24);
	return delai;
}
Attention

Any modification of a process variable in a script is not taken into account until the statement execution.setVariable(“variableId_process”,value) is called.

The JavaScript executed in Iterop refuses to create constants with the “const” statement.

Updating process variables from local script variables

When the script processing has been completed, it is necessary to insert the result of the calculation(s) in a process variable(s).

To do this, we use the instruction execution.setVariable(“start_variableProcess”, value).

Attention

The value that corresponds to the second parameter of the statement execution.setVariable(“start_variableProcess”, value) must be typed in a type understandable by Iterop.

//Insertion d'un JSON depuis une variable de processus
execution.setVariable("variablesCible_JSON", JSON.stringify(js_scriptJSON));
//Insertion d'un booléen
execution.setVariable("variablesCible_booleen", true);

Sample script : Changing the Process Identifier

It is often useful to construct the identifier of a process from data filled in the start form. In our example we will try to construct the following identifier: [Date de la demande au format JJ-MM-AAAA] – [Nom du client] – Request number [numéro Incrémental]

The following script allows you to do this.

//Exemple de script pour la modification de l'identificateur du processus
//Récupération des variables du processus
var js_numeroDeLaDemande = identificatorInstance;
var js_dateDeLaDemande = new Date(start_dateDeLaDemande.getTime()*1)
var js_nomDuClient = start_nomDuClient;
//Traitement sur les variables récupérées
var js_nouvelIdentificateur = buildDateString(js_dateDeLaDemande) + " - " +  js_nomDuClient + js_numeroDeLaDemande;
//Mise à jour des variables dans le processus
execution.setVariable("identificatorInstance",js_nouvelIdentificateur)

//Fonction
function buildDateString(date){
	//Prend une date en JS et la transforme en date au format DD/MM/YYYY
	return ("0" + date.getDate()).slice(-2)+ "-" + ("0" + (date.getMonth() + 1)).slice(-2) + "-" + date.getFullYear();
}

Summary of the JavaScript methods that can be used according to the type of the variable

JSON

List of JavaScript methods that can be used on JSON
Both methods JSON.parse() and JSON.stringify() work on Iterop.

Date

List of JavaScript methods that can be used on dates
Warning, the methods getYear(), setYear(), toGMTString() as well as toSource() do not work on Iterop because they are not maintained or standardized anymore.

String (string)

List of JavaScript methods that can be used on strings

Careful, the methods:
– fromCodePoint()
– codePointAt()
– includes()
– matchAll()
– normalize()
– padEnd()
– padStart()
– repeat()
– trimEnd()
– trimStart()

Don’t work on Iterop.

Using Iterop functions (Juel methods)

It is difficult, if not impossible, to memorize all the id of the variables in our process. This is why it is possible to retrieve them with the right-click menu.

It is also possible to access :

  • Process Variable IDs process IDs
  • JUEL methods (also called “Iterop Functions”), very useful predefined methods.
  • Task IDs, lists and dependency tables.
  • A of the operators (arithmetic and logical) as well as constants.

The JUEL methods

There are different families of methods.
The list of Iterop functions (JUEL methods) are listed here :
The different Iterop functions

All that can be done:

  • Handling Excel files
  • Verify the existence of a value, even give it one if it doesn’t have one.
  • Generate PDF files / Create files, change their name
  • Manipulate your lists (add, delete items)
  • Create and generate history or activity reports
  • Retrieve task start or end dates
  • Retrieve information about the actor of a task (email, name, login, …)
  • Retrieve information about a user (name, email, …)
    or group (name of the group, members, …)
  • Creating or retrieving a variable
  • Handling or formatting a date
  • Use and manage your business repositories
    What is a business repository?
  • Assign, manage dynamic supervisor roles

Reminder: Attention! The values retrieved by the Iterop functions will therefore be of Iterop type. This implies that prior treatment may be necessary in order to handle them properly.

Script in error

If your script has errors, it will not run correctly.

An error is then generated and can be viewed in the “Errors” tab of PLAY.

Once you have clicked on one of the errors present :

You can see the location of the error and its meaning.
For this example, it is understandable that there is a concern in line number 3, column 106.

ERREUR COURANTE

Among the most important errors is the “infinite loop” which is usually signalled by the following messages:

Timeout exeption: script execution exceeded time limit. Cause could be an infinite loop

or again:

Memory exeption: Script execution exceed memory limit. Variables will not be recorded. Cause could be an infinite loop

If you encounter one of these two messages, it means that the termination condition of your loop FOR or WHILE is never reached.

Updated on 13 November 2020

Was this article helpful?

Related Articles