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).

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.

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

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.

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

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;
}

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).

//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.