FlowScript

Compatibilità:IdSurvey 5IdSurvey 6IdSurvey 7
XX

You can manage the logic of the flow on IdSurvey by using a programming language called FlowScript. 

You can use the FlowScript both to control the flow and to set the dynamic values. It is also possible to use a FlowScript after having saved the questions in each page. 

Elements of the language

The language consists of different elements. They are as follows: 

Instruction

An instruction is an order to perform something, such as jumping to a specific page, going Off Target, assigning values. 

Condition

A condition is a truth value that can be true or false. 

Expression

An expression is a value (string or numeric) that can be assigned to an answer or displayed by the user. 

Factors

Factors are the values that create the language. They can be strings, numbers, questionnaire values etc.

Entry areas

There are different areas of the questionnaire in which you can enter the scripts. Each area requires a specific element of the FlowScript: 

  • End of page script (instructions) 
  • Logic conditions (conditions) 
  • Goto (conditioned goto) 
  • Loop index (expression)
  • Open-ended question default value (expression) 
  • Update contact field value (expression) 
End of page script

Among the page options you have the possibility to run a script. The script will be run after having saved the questions. The values of the previous page can therefore be used too. 

Conditions

The conditions of the questionnaire elements (sections, pages, questions, answers) are conditions that, if verified, will show the element to which they are referring to. 

The syntax is as follows: 

if( condition )

Where ‘condition’ means a FlowScript condition.

Goto

On the answer options it is possible to set a skip condition. The syntax is as follows:

if ( condition ) goto ( expression, expression ... )

Were ‘condition’ and ‘expression’ mean condition and expression of the FlowScript. The condition is not mandatory and you can also use the gotornd function in addition to the goto function. 

Loop index

It is possible to repeat a section of the questionnaire by setting an index on the section. The syntax of the index is that of a FlowScript expression. 

Open-ended question default value

The default value of an open-ended question can be set as an expression of the FlowScript. If the preset value completes an expression correctly, you can use the preset value as it is. Otherwise, you will have to use the string as it was previously entered. 

Update contact field value

The value on the Update contact field can be set as an expression of the FlowScript. If the preset value completes an expression correctly, you can use the preset value as it is. Otherwise, you will have to use the string as it was previously entered. 

Syntax of the FlowScript

The syntax of the FlowScript language is inspired to C syntax. The language is very intuitive, especially when writing simple expressions. This feature causes some specificities when used to write complex expressions: 

Instructions

The possible instructions are: 

  • Assignments 
  • Functions calls
  • Alternatives (if-then-else) 
  • Loops (while) 

Each instruction must end with the ; symbol. 

Assignments

With the assignment instructions you can assign contact fields and answers. 

Examples: 

D1= 1;

Assigns 1 as the answer to question D1

{Surname}= Doe;

Assigns ‘Doe’ as the contact’s surname. 

Assignments on loops

On IdSurvey it is possible to repeat sections of the questionnaires (see Loops). In order to assign a question to a specific loop you will have to use square brackets to specify the index. 

D1[2]= 2;

Functions calls

On the FlowScript you can call functions that change the flow of the questionnaire. Such functions are: setVariable, GoTo, GoToRnd and Ot (out of target). 

For example: 

goto(P1);

gotornd(P1, P2, P3, Q1);

ot();

Alternatives

The alternative instruction (if-then-else) allows you to perform instructions if the condition is verified and to give other instructions if the condition is not verified. 

The syntax is as follows: 

if(condition)
instruction1;
else
instruction2;

Example:

if( D1 == 1)
goto(P2);
else
gotornd(P3, P4, P5, Pend);

If the instructions to be performed on the then or on the else are more than one, you will have to put the entire set of instructions in curly brackets. 

Example: 

if( D1 == 1 && D2==1) {
{field1}=1;
{sample}=YES;
}
else {
{sample}=NO;
ot();
}

Loops

The iterative construct has the following syntax: 

while(condition) instructions

You can replace the instruction on the while body with a set of instructions enclosed in curly brackets. In order to avoid deadlocks, the while cycle is limited to 1000 repetitions. After that, the cycle will be interrupted. 

Example:

while ({j}<= {i})
{
{total}= {total}+[P2.Q1][{j}];
{j}++;
}

Conditions

A condition is a truth value that can be true or false. 

Conditions are used on the filters of the elements of the questionnaire and can be used to condition a skip. For example: 

D1 == 1;

If the expression on the left of a condition is a free string (which means without quotes), it can be interpreted as “response codes to question D1”, so it is equal to: 

responsesCodeOf('D1') == 1;

Logic Conditions

The logic conditions that can be used in the expressions are: 

  • == equal to
  • != different from 
  • < less-than 
  • > greater-than 
  • <= less-than or equal to
  • >= greater-than or equal to 
Logic Operators

You can combine the logic conditions by using the following logic operators: 

  • ! 
  • && and 
  • || or 

For example:

(D1== 1 ||D1==2)&&(D2==1||D2==2)

(!S0==1)||((D1== 1 ||D1==2)&&(D2==1||D2==2))

The logic operator && takes precedence over the || operator. The unary operator ! takes precedence over all of the other operators. 

Expressions

The factors can be combined by using the usual arithmetic operators in the expressions. For example: 

{field16} + [D2] *7

[D1.1]+[D1.2]-[D1.3]

([D1.1]+[D1.2])*[D4]

Arithmetic operators are + – * / and %. The latter represents the module or “the remainder of the whole division”. Multiplication and division (and therefore modules too) take precedence over additions. You can use round brackets to indicate the order of the operations. 

Sum and concatenation

The operator + carries out the algebraic sum between two factors if both are numbers. If one of the two is a string that cannot be connected to a number, the operator will carry out the concatenation. 

For example 3+2is 5 while a+2 is a2. This makes it impossible to chain numbers with a + between them. In this case, please use the join function.

Factors

The values that form each FlowScript expression are called factors. These factors can be: 

  • A string 
  • A value related to the questionnaire 
  • A function 
  • A conditional operator 

A factor can also be an expression in round brackets. This allows you to write expressions as complex as you want. 

Strings

Strings are sequences of letters and numbers. They are enclosed in simple quotes ““. 

If you need to enter a simple quote in the string you have to write the backlash symbol “\” before it. If you need to enter a backlash, you have to write another backlash before it. 

Examples: 

'this is a string'

'this is a \'string\' that contains quotes'

'this is a string that contains a \\ backslash'

Free strings

In order to make the language easier, you can enter “free” strings. It means strings with no blanks and no need to use quotes. 

In this case you can only use a limited set of characters, such as: 

  • Letters of the english alphabet
  • Numbers 
  • Underscore _ (NOT the minus sign)
  • Full stop . 

This set of characters is exactly the same set of characters that is accepted as question or response codes. Therefore, you can write each question or response code without using quotes. Please note that accented characters, blank spaces, punctuation marks, parenthesis, letters of non-English alphabets and special characters are NOT part of this list and can NOT be used on a free string. You must therefore put the strings that contain such characters in single quotes. 

The minus sign (or dash) “-“ and the division symbol (or forward slash) “/“ are not included in the list. This would make it difficult to enter dates or negative number, so that is why we provided specific exceptions for this string category. 

Examples: 

{region}=Tuscany;

{user}='senior user‘;

Dates and negative numbers

Strings referring to dates and negative numbers can be written without quotes if they follow the following formats: 

The negative number must be written as: “dash” “numbers from 0 to 9”. The decimal part is optional. Blanks will NOT be admitted inside numbers in free format. 

Examples: “-23” or “-23.77”

Dates must be written in ISO format: Year-Month-Day 

Example: “2017-12-10”

Values related to the questionnaire 

You can recall values of the questionnaire in the FlowScript in order to work with them or to compare them. Such values are: 

  • Contact fields
  • User fields
  • Answers to questions 

Contact fields
Contact fields recall each other by putting them in curly brackets ({}). The same characters of the free strings are admitted as fields identifiers (letters, numbers, full stop and underscore). Example: “{Name}”, “{home_address_of_the_mother_on_her_fifteenth_birthday}”.

Interviewer fields
You can recall Interviewer fields by including them between hashtags (#). The same characters of the free strings are admitted as fields identifiers (letters, numbers, full stop and underscore). Example: “#Name#”, “#Surname#” 

Answers to questions
You can recall different response values: 

  • Response codes 
  • Value entered in an open-ended question (text, numeric, assisted, rating, slider, etc.) 
  • Text entered in a “text field after the question”

The response codes can be easily recalled by writing the code of the question on the left of a comparison. For example, in the comparison “D1==1”, the free string “D1” indicates the response codes to question D1. If you need to recall response codes that are in a different place and not in the comparison, you can use the function responsecodeof( ). 

You can recall the value entered in an open-ended question by putting it in square brackets ( [ ] ). The same characters of the free strings are admitted as fields identifiers (letters, numbers, full stop and underscore).

You can recall the text entered in a “text field after the question” by putting it between asterisk and pipe ( *| |* ). The same characters of the free strings are admitted as fields identifiers (letters, numbers, full stop and underscore). Example: *|open-ended question|*

Example:

[P1.Q1]

Example:

*|D4.1|*

Functions

You can collect a value by using one of the functions that can be recalled by the language. The parameters of the functions must be separated by commas and put in round brackets. For example:

ContainsText(Q1,'sea')

The parameter of a function can be any expression, including an additional function. 

The functions available at the moment are:

ContainsText
It allows you to verify the presence of a specific text inside an open-ended question. 

if(ContainsText (Q1,'sea')==1)

It verifies whether the text response of question Q1 contains the word “sea”. 

CountCode
It allows you to count the number of selected options in a multiple choice question. 

if(CountCode (Q1) >= 3)

It checks whether 3 or more options were selected in question Q1. 

CountResponsesWithCode
It allows you to count the number of questions to which a response code was given as an answer. 

if(CountResponsesWithCode(Q1,Q2,Q3,Q4,Q5,Q6,99) >= 3)

It checks whether the code 99 was given as an answer to al least 3 of the questions Q1, Q2, Q3, Q4, Q5 and Q6. 

CountResponsesWithText
It allows you to count the number of questions to which a specific text or number was given as an answer. 

if(CountResponsesWithText (Q1,Q2,Q3,Q4,Q5,Q6,'sea') >= 3)

It checks whether the word “sea” was present in at least 3 of the text responses in questions Q1, Q2, Q3, Q4, Q5 and Q6. 

CheckQuota
It allows you to learn whether a specific quote is open or closed. 

if(CheckQuota ('Parents') == 1)

It checks whether the quote “Parents” is closed

if(CheckQuota ('Parents') == 0)

It checks whether the quote “Parents” is open

CompareDate
It compares two dates, for example: 

compareDate({date_of_birth}, '2010-10-01')

The function gives -1 if the first date is minor than (preceding) the second, 0 or if they are the same. It gives 1 if the first date is greater than (following) the second. 

GetVariable
The function getVariable allows you to collect the value of a variable (in a contact or in one of the questions) by dynamically generating the name of the variable itself. For example: 

getVariable('{son_date_of_birth_'+{son}+'}')

Join
The join function allows you to connect the strings, for examplejoin(10,02,12) gives back the string 100212. Since the strings that can recognized as numbers are summed by the + operator by default, the join function allows you to connect this type of strings. 

Module
It gives back the string CATI, CAWI or CAPI according to the module you’re using. 

For example: 

if(module()==cawi)
{sample}=A;

SetVariable
It allows you to set the value of a variable by dynamically generating its name. 

For example: 

setVariable('{son_date_of_birth_'+{son}+'}', Antonio);

GoTo
It skips to the page indicated as parameter. 

For example goto(P1); jumps to page P1,  goto(P1, P2); jumps to page P1 and then to page P2.

PLEASE NOTE: the goto with only one parameter are “disruptive”. This means that they delete all the questions between the starting point and the end point of the jump, while the goto with more than one parameter are “conservative”, which means that they do not delete anything in between. In order to make a single “conservative” jump, make sure to use the syntax goto(P1, ''), where the empty string after P1 orders not to delete the pages in between. 

GoToRnd
It jumps to the pages indicated as parameters randomly. It always ends with the page indicated as the last parameter. 

For example  gotornd(P1, P2, P3); jumps to page P1 and then to page P2 or to page P2 and then to page P1. It always goes to page P3 afterwards.  

Ot
It marks the person who is completing the interview as out of target (screen out). 

Example: 

if(D1==1) && (D2==3)
ot();

PLEASE NOTE: the functions setVariable, goto, gotornd and ot are to be considered “special” since they change the flow of the questionnaire instead of giving a value back. This is why such functions are not meant to be used in filters, text-piping and in the default values of open-ended questions. 

Conditional operator

You can use a conditional operator that works as an if-then-else set as a factor. The syntax uses the question mark and the colon just like in the C language. For example: 

(D1==1)?{social_security_number}:{vat_registration}

({numberofchildren}>1)?'how old are your children?':'how old is your child?'

(module()==cawi)?'capi text':'text for other modules with user'

The syntax is the following: (condition)?expression:expression where ‘condition’ means a FlowScript condition and ‘expression’ means a FlowScript expression. 

Language specificity

The FlowScript favors the writing speed and the simplicity of the expressions at the expense of the language orthodoxy. This causes a few specificities that can confuse the users that are used to other programming languages. 

Free string or string, is there any difference?

Therefore, the syntax D1 == 1 is equal to D1 == ‘1’ since we expect to have a value on the right side of the equal sign, but that is not equal to ‘D1’ == 1, since the string with quotes on the left indicates that D1 is to be intended as string D1 and not as response codes to questions D1. 

As a remainder that the function responsesCodeOf gets the response codes back, the syntax D1 == 1 is equal to ResponsesCodeOf(‘D1’) == 1

Comparison asymmetry

In the comparison operators of the condition (==, >, <, !=) the two operators are NOT the same. The operator on the right is considered a string, while if the operator on the left is a free string (therefore without quotes), it is considered a question. 

For example, the condition “D1==1” means “please verify whether to the question with code D1 was given an answer with code 1”. If I reverse the order of the operators I will get the condition “1==D1”, which means “please verify wether to the question with code 1 was given an answer with code D1”, which is completely different. 

Therefore, we have to keep in mind that comparisons are NOT, in general, reversible. 

Leave A Comment?