FlowScript

Compatibilità:IdSurvey 7IdSurvey 8

Le logiche del flusso del questionario possono essere gestite con un linguaggio di programmazione chiamato FlowScript. 

FlowScript è parte integrante di IdCode con cui condivide le funzionalità e parte della sintassi ma estendendone enormemente le possibilità di applicazione.

Si può aggiungere un FlowScript in qualsiasi pagina del questionario. Gli script vengono eseguiti al salvataggio della pagina, cioè quando il rispondente clicca il bottone “Avanti”.

FlowScript consente di eseguire tutti comandi disponibili in IdCode permettendo però condizioni di qualsiasi complessità. È inoltre possibile utilizzare le istruzioni else e l’istruzione while. 

FlowScript è composto da diversi elementi, quali:

Comandi

I comandi sono le istruzioni da eseguire all’esecuzione del FlowScript, come ad esempio un “salto” a una determinata pagina (goto), “vai fuori target” (ot) oppure l’assegnazione di un valore ad un campo del nominativo.

Condizioni

Una condizione determina in quale caso un comando deve essere eseguito. Ad esempio, se la condizione è vera esegui questo comando.

Funzioni utilizzabili nelle condizioni

IdSurvey mette a disposizione numerose funzioni utilizzabili sia in FlowScript che in IdCode. Le funzioni utilizzabili nelle condizioni permettono di eseguire dei controlli su domande del questionario, sui campi del nominativo o sullo stato delle quote. Ad esempio, controllare quante risposte sono state selezionate ad una domanda con opzioni di risposta multiple oppure controllare se una determinata quota è chiusa, ecc.

Altre funzioni speciali

Queste particolari funzioni possono esse sfruttate sia nelle condizioni che all’interno di comandi. Le funzioni speciali sono generalmente necessari solo per FlowScript particolarmente complessi.

Dettagli

I comandi sono le istruzioni da eseguire all’esecuzione del FlowScript. È possibile inserire uno o più comandi, con o senza condizione. Ogni comando deve terminare con il carattere “;” (punto e virgola).

I comandi possibili sono:

  • Funzione GoTo (salto)
  • Funzione GoToRnd (salto random)
  • Funzione Ot (fuori target)
  • Assegna valore a campo del nominativo 
  • Assegna risposte
  • SetVariable (assegnazione campi nominativo e risposte avanzata)

GoTo

Salta alla pagina o domanda specificata.

Esempio salto semplice:

goto(P3);

salta alla pagina P3.

Esempio salto con sequenza:

goto(P3, P5, P10);

salta alla pagina P3, poi alla pagina P5 e pi alla pagina P10.

Nota

  • Il salto semplice garantisce l’integrità del questionario: questo significa che effettuando un salto ad una pagina successiva, eventuali risposte delle domande saltate, saranno cancellate. Se invece la condizione di salto atterra su una domanda precedente, i dati non saranno cancellati. In questo caso, l’intervista proseguirà riproponendo le domande ad una ad una con le risposte già compilate. In entrambi i casi l’intervista sarà sempre popolata dalle sole risposte alle domande realmente poste, seguendo le regole di condizioni di visualizzazione e di salto impostate (se una domanda è filtrata o saltata significa che non deve essere visualizzata durante l’intervista e pertanto ci si aspetta che le relative risposte siano vuote). È comunque possibile evitare che le risposte vengano ripulite utilizzando un salto con sequenza senza specificare la seconda pagina del salto, cioè aggiungendo gli apici senza nessun codice contenuto, ad esempio GoTo (Q15, '').

GoToRnd

Propone le pagine o domande specificate in ordine casuale, concludendo sempre con la pagina o domanda specificata come ultimo parametro.

Per esempio:

gotornd(P5, P6, P10);

Propone le pagine P5 e P6 in ordine casuale poi conclude con la pagina P10.

Ot

Manda il nominativo in corso di intervista fuori target.

Esempio fuori target con condizione:

if(Q1==1 && Q2==3) ot();

Se alla domanda Q1 è selezionata la risposta con codice 1 e alla domanda Q2 è selezionata la risposta con codice 3, vai fuori target

Assegna valore al campo del nominativo

Consente di assegnare un valore ad un qualsiasi campo del nominativo.

Esempio:

{MarcaAuto} = Jaguar;

Assegna “Jaguar” al campo del nominativo MarcaAuto.

Esempio con condizione:

if (Q1==3 && Q2==1) {Abbonamento} = Netflix;

Se alla domanda Q1 è selezionata la risposta con codice 3 e alla domanda Q2 è selezionata la risposta con codice 1, assegna “Netflix” al campo del nominativo Abbonamento.

Assegna risposta

Consente di assegnare una risposta ad una qualsiasi risposta del questionario.

Esempio selezione risposta:

Q15 = 3;

Seleziona la risposta con codice 3 della domanda Q15.

Esempio selezione risposta multipla:

Q15 = '3,4,8';

Seleziona le risposta con codici 3, 4 e 8 della domanda Q15

Esempio valorizzazione risposta aperta di una domanda:

[Q12] = 'sono molto soddisfatto';

Valorizza la risposta aperta della domanda Q12.

Assegna valoreAssegna il valore ad un campo del nominativo.{MarcaAuto} = Jaguar;

 Assegna il valore Jaguar sul campo del nominativo “MarcaAuto”. 
Assegna rispostaAssegna il codice risposta ad una domanda.Q15 = 3;

 Seleziona la risposta con codice 3 della domanda Q15.

Q15 = '3,4,8';

 Seleziona le risposta con codici 3, 4 e 8 della domanda Q15.

[Q12] = 'sono molto soddisfatto';

 Valorizza la risposta aperta della domanda Q12.
GoTo

(singolo)
Salta alla pagina o domanda specificata.

Per garantire l’integrità dell’intervista, eventuali domande seguenti a cui si è già risposto vengono ripulite.

goto(P1);

Salta alla pagina P1.
GoTo

(multiplo)
Salta alle pagine o domande specificate.goto(P1, P2);

Salta alla pagina P1 e poi alla pagina P2.
GoToRndSalta alle pagine (o domande) specificate in ordine casuale, finendo sempre con la pagina (o domanda) specificata come ultimo parametro.gotornd(P5, P6, P10);

Propone le pagine P5 e P6 in ordine casuale poi conclude con la pagina P10.
Ot

(fuori target)
Manda fuori target il nominativo in corso di intervista.ot();
SetVariablePermette di impostare il valore di una variabile costruendone il nome dinamicamente.setVariable('{nome_figlio_'+{ifiglio}+'}', Antonio);

Ottiene il valore della variabile “ifiglio” (ad esempio 3) e lo usa per comporre il nome della variabile “nome_figlio_3” su cui poi scrive il valore “Antonio”.
RecStartAvvia la registrazione audio in background su interviste CAPI.recStart();

Avvia la registrazione audio in background (compatibile solo con interviste da app CAPI).
RecStopInterrompe la registrazione audio in background su interviste CAPI.recStop();

Interrompe la registrazione audio in background (compatibile solo con interviste da app CAPI).
sendMailInvia una mail.sendMail('email@mittente.com', {Email}, 'Oggetto della mail', 'Testo della mail');

Invia una email da email@mittente.com all’indirizzo presente nel campo email del contatto, con l’oggetto e il testo specificato.

{email_result}=sendMail('email@mittente.com', {Email}, 'Oggetto della mail', 'Testo della mail’);

Invia la mail e salva l’esito nel campo email_result del nominativo.
sendSMSInvia un sms.sendsms('Company', {cellulare}, 'Bravo! Hai completato il questionario');

Invia un SMS con mittente “Company” al numero di telefono presente nel campo Cellulare del nominativo.

{sms_result}=sendsms('Company', {cellulare}, 'Bravo! Hai completato il questionario');

Invia l’SMS e salva l’esito nel campo sms_result del nominativo.

Le condizioni permettono di specificare il caso in cui uno o più comandi devono essere eseguiti. Una condizione, nella sua forma più semplice, è costituita dall’istruzione if e da un’espressione di confronto ed è poi seguita dal comando da eseguire nel caso che la condizione risulta vera.

if(Q1==1) ot();

Se alla domanda Q1 è stata selezionata la risposta con codice 1, vai fuori target.

È possibile utilizzare diversi simboli di confronto e gli operatori logici per concatenare più condizioni.

if(Q1>5 && Q2!=1) goto(P5);

Se alla domanda Q1 è stata selezionata una risposta con codice maggiore di 5, e alla domanda Q2 non si è selezionata la risposta con codice 1, vai alla pagina P5.

È possibile utilizzare espressioni con più fattori per effettuare calcoli algebrici o per concatenare testo di risposte aperte, campi del nominativo e stringhe.

if([Q1]+[Q2]<100) goto(P5);

Se la somma del numero inserito alla risposta aperta delle domande Q1 e Q2 è minore di 100, vai alla pagina P1.

Note

  • Le espressioni con più fattori possono essere utilizzate sia prima che dopo del simbolo di confronto.
  • La sintassi delle condizioni di FlowScript è identica a quella di IdCode.

Approfondiamo tutti gli argomenti necessari per costruire condizioni di ogni complessità.

  • Simboli di confronto
  • Operatori logici
  • if…then (per specificare comandi da eseguire su condizione vera)
  • if…then…else (per aggiungere comandi da eseguire su condizione falsa)
  • while (esegue i comandi fino a che la condizione non diventa vera)
  • Elenco funzioni utilizzabili nelle condizioni

Simboli di confronto

I simboli di confronto utilizzabili nelle espressioni delle condizioni sono:

  • == uguale
  • != diverso
  • < minore
  • > maggiore
  • <= minore uguale
  • >= maggiore uguale

Operatori logici

Le condizioni possono essere combinate tra loro utilizzando le parentesi e gli usuali operatori logici:

  • && e
  • || o
  • ! negazione

 

Esempio:( Q1==1 || Q1==2) && ( Q2==1||Q2==2 )

Se alla domanda Q1 è stata selezionata l’opzione con codice 1 oppure con codice 2, e alla Q2 è stata selezionata la risposta con codice 1 oppure 2.

( !Q1==1 ) || ( (Q2== 1 || Q2==2) && (Q3==1||Q3==2) )

Se la condizione “Q1 uguale a 1” non è vera, oppure se alla domanda Q2 è stata selezionata l’opzione con codice 1 oppure con codice 2, e alla Q3 è stata selezionata la risposta con codice 1 oppure 2.

Note

  • L’operatore && ha la precedenza sull’operatore ||. Questo significa che in assenza di parentesi vengono validate prima le condizioni in AND e quindi le condizioni in OR. L’operatore di negazione ! ha la precedenza su tutti gli altri operatori.

If…then

L’istruzione if…then consente di impostare la condizione in cui uno o più comandi devono essere eseguiti.

if(condizione) comando;

Se la condizione è vera esegui il comando.

Esempio:

if(Q8==3 && [Q2]<18) ot();

Se alla domanda Q8 è stata selezionata l’opzione con codice 3 e alla risposta aperta della domanda Q2 è stato indicato un valore minore di 18, vai fuori target.

Esempio di condizione con più comandi:

if(Q2==3 && Q2!=1) { {Auto_Posseduta}=nessuna; ot(); }

Se alla domanda Q2 è stata selezionata l’opzione con codice 3 e alla domanda Q2 non è selezionata l’opzione 1, valorizza il campo del nominativo “Auto_Posseduta” con nessuna, poi vai fuori target.

Note

  • Dopo ogni condizione è possibile aggiungere un gruppo di comandi racchiudendole fra parentesi graffe. FlowScript processa fino ad un massimo di 1000 istruzioni per gruppo.

If…then…else

L’istruzione if…then…else consente di estendere le possibilità dell’istruzione if…then permettendo l’aggiunta di comandi da eseguire nel caso che la condizione risulti falsa.

La sintassi è la seguente:

if(condizione) {comando su condizione vera} else {comando su condizione falsa}

Ad esempio:

if(Q1==1) goto(P2); else goto(P5);

Se alla domanda Q1 è stata selezionata la risposta con codice 1, vai alla pagina P2, altrimenti (ossia se la condizione è falsa), vai alla pagina P5.

While

While consente di ripetere uno o più comandi fino a che la condizione è vera. L’istruzione while permette quindi di fare loop nel FlowScript. Il suo utilizzo è generalmente limitato a necessità particolarmente complesse. Questa funzione non va confusa con i cicli di sezione del questionario.

La sintassi è la seguente:

while(condizione) comando;

Ad esempio:

{j}=0; 
while ({j} <= {i})
	{
		{totale}= {totale}+[Q1][{j}];
		{j}++;
	}

Assegna alla variabile j il valore 0.

Se il valore della variabile j è minore del valore della variabile i, valorizza il campo totale sommando il valore precedente del campo totale + la cifra inserita alla domanda aperta Q1 di j, quindi incrementa il campo j di 1.

Note

  • In questo esempio abbiamo chiamato “variabili” quelli che abitualmente vengono definiti “campi del nominativo”. Tecnicamente non c’è nessuna distinzione fra variabili e campi del nominativo. In IdSurvey i campi del nominativo possono essere usati come vere e proprie variabili, in modo del tutto simile a quanto è possibile fare in qualsiasi linguaggio di programmazione.
CountCodePermette di contare il numero di opzioni selezionate.if(CountCode (Q1) >= 3)

Controlla se alla domanda Q1 sono state selezionate 3 o più opzioni.
ResponsesCodeOfRestituisce i codici delle risposte selezionate ad una domanda.if(Q2==responsesCodeOf(Q1))

Controlla se la risposta selezionata alla domanda Q2 ha lo stesso codice di quella selezionata alla domanda Q1.
CountResponsesWithCodePermette di contare il numero delle domande a cui si è risposto con un determinato codice risposta.if(CountResponsesWithCode(Q1,Q2,Q3,Q4,Q5,Q6,99) >= 3)

Controlla se è stato risposto codice 99 ad almeno 3 fra le domande Q1, Q2, Q3, Q4, Q5 e Q6.
CountResponsesWithTextPermette di contare il numero delle domande in cui si è risposto con un determinato testo o numero.if(CountResponsesWithText (Q1,Q2,Q3,Q4,Q5,Q6,'mare') >= 3)

Controlla se la parola “mare“ è presente in almeno 3 delle risposte di testo nelle domande Q1, Q2, Q3, Q4, Q5 e Q6. 
CheckQuotaPermette di conoscere se una certa quota è aperta o chiusa.if(CheckQuota ('Genitori') == 1)

Controlla se la quota “Genitori” è chiusa. 
CompareDateConfronta due date.
Restituisce -1 se la prima data è inferiore (precedente) alla seconda, 0 se sono uguali e 1 se la prima data è maggiore (successiva) della seconda
if(compareDate({data_di_nascita}, '2010-10-01') == -1)

Controlla se la data nel campo “data_di_nascita” è precedente alla data specificata. 
ModuleRestituisce la stringa CATI, CAWI o CAPI a seconda del modulo in cui è attualmente somministrata l’intervista.if(module()==cawi)

Controlla se l’intervista è attualmente somministrata con il modulo CAWI.
ContainsTextPermette di verificare la presenza di un determinato testo all’interno di una risposta aperta.if(ContainsText ([Q1],'mare')==1)

Controlla se la risposta di testo della domanda Q1 contiene la parola “mare”.
StartWithTextConfronta l’inizio di una stringa con una stringa specificata.if(StartWithText({Telefono},'+39')==1)

Controlla se il campo telefono inizia con “+39”.
EndWithTextConfronta la fine di una stringa con una stringa specificata.if(EndWithText({Identificativo},'123')==1)

Controlla se il campo identificativo finisce con “123”.

Queste funzioni sono state sviluppate per la gestione di alcune particolari eccezioni e sono utilizzabili sia all’interno di condizioni che all’interno di comandi. Il loro utilizzo è generalmente limitato a necessità particolarmente complesse.

GetVariablePermette di ottenere il valore di una variabile (sul nominativo o una domanda) costruendo dinamicamente il nome della variabile stessa.getVariable('{data_di_nascita_figlio_'+{ifiglio}+'}')

Ottiene il valore della variabile “ifiglio”  (ad esempio 3) e lo usa per comporre il nome della variabile “data_di_nascita_figlio_3” e ottiene il relativo valore.
JoinPermette di forzare la concatenazione di stringhe evitando che queste vengano interpretate come numeri. Ad esempio 10+02+12 restituisce 24, mentre join(10,02,12) restituisce 100212.join(10,02,12)

Compone la stringa 100212

join(testo,02,[Q1])

Compone la stringa testo02rispostaApertaQ1
RandomGenera un numero casuale compreso fra il numero minimo e il numero massimo indicato.

È possibile specificare un nome per salvare il numero generato in modo da poterlo riutilizzare in un secondo tempo.

random(1, 10)

Genera un numero random compreso fra 1 e 10. 

random(1, 10, 'il mio numero random')

Genera un numero random compreso fra 1 e 10 e lo salva con il nome specificato.
Riutilizzando la stessa identica sintassi (nel FlowScript di una qualsiasi pagina del questionario) verrà richiamato il numero salvato e generato la prima volta.
ReplaceSostituisce il testo specificato all’interno di una stringa.

(Disponibile da IdSurvey 8.1)

Replace([Q1], 'macchina', 'automobile')

Restituisce la stringa della risposta aperta della domanda Q1 sostituendo la parola “macchina” con “automobile”. 

Replace({telefono}, '+39', '')

Restituisce il campo telefono senza il prefisso +39.
GetItemByRankingRestituisce l’etichetta o il codice dell’item in base alla posizione di classifica.

(Disponibile da IdSurvey 8.1)

GetItemByRanking(Q1, 1, label)

Restituisce la label dell’elemento messo in prima posizione nella domanda ordinamento drag&drop (oppure, per le griglie, restituisce il testo della riga in cui è stata selezionata la risposta con codice 1). 

GetItemByRanking(Q15, 3, code)

Restituisce il codice dell’elemento messo in terza posizione nella domanda ordinamento drag&drop (oppure, per le griglie, restituisce il codice della riga in cui è stata selezionata la risposta con codice 3).

GetItemByRanking(Q1, 1, auto)

oppure
GetItemByRanking(Q1, 1)

Restituisce la label dell’elemento messo in prima posizione nella domanda ordinamento drag&drop. Se la label non è presente viene riportato il codice.
getResponseRestituisce la risposta selezionata (in formato stringa) e consente di specificare il dato da recuperare e la formattazione del separatore delle risposte multiple.

(Disponibile da IdSurvey 8.1)

getResponse(Q1)

oppure
getResponse(Q1, auto)

Restituisce l’aperta (se disponibile) o la label della risposta selezionata alla domanda Q1. In caso di risposte multiple vengono riportate tutte le risposte separate dal carattere pipe “ | ”. 

getResponse(Q1, auto, ', ')

Come il precedente ma in caso di risposte multiple vengono riportate separate da una virgola seguita da uno spazio.

getResponse(Q1, opentext)

Restituisce la risposta aperta della domanda Q1.

getResponse(Q1, label)

Restituisce la label della risposta selezionata della domanda Q1.

getResponse(Q1, code)

Restituisce il codice della risposta selezionata alla domanda Q1. In caso di risposte multiple viene restituita la stringa formata dai codici risposta separati dal carattere pipe “ | ”.

getResponse(Q1, code, ', ')

Restituisce il codice della risposta selezionata alla domanda Q1. In caso di risposte multiple viene restituita la stringa formata dai codici risposta separati da virgola seguite da uno spazio.

getResponse(Q1, commentbox)

Restituisce il testo inserito nell’area di commento (testo dopo domanda).

Shorthand if…then…else

In FlowScript è possibile utilizzare l’istruzione if…then…else anche nella forma detta “shorthand”. Questa forma è indispensabile per utilizzare le condizioni all’interno di altri comandi o per inserire il testo dinamico nei testi del questionario. Tecnicamente, la forma if “shorthand”, permette di inserire una condizione all’interno di funzioni che accettano solo espressioni. Nonostante la diversa sintassi la logica e il funzionamento non differiscono dal normale funzionamento dell’ if…then…else.

condizione ? espressione_condizione_vera : espressione_condizione_falsa

Ad esempio:

(Q1==1)?'privato':'azienda'

Se alla domanda Q1 è selezionata l’opzione con codice 1, restituisci la stringa “privato”, altrimenti “azienda”.

(Q1==1)?{codice_fiscale}:{partita_iva}

Se alla domanda Q1 è selezionata l’opzione con codice 1, restituisci il valore del campo del nominativo “codice_fiscale”, altrimenti restituisci il valore del campo “partita_iva”.

([Q1]>1)?'quanti anni hanno i tuoi figli':'quanti anni ha tuo figlio'

Se alla risposta aperta della domanda Q1 si è scritto un numero maggiore di 1 (numero di figli), mostra il testo della domanda al plurale, altrimenti al singolare.

In questo esempio viene mostrato come comporre condizioni if else “shorthand” annidate.

( [Q1]>=4 ) ? 'positivo' : ( [Q1]<=2 ) ? 'negativo' : ( [Q1]==3 ) ? 'neutro' : ' '

Se alla risposta aperta della domanda Q1 è stato inserito un valore maggiore o uguale 4, restituisci la stringa “positivo”, altrimenti controlla se è stato inserito un valore minore o uguale 2 e in questo caso restituisci la stringa “negativo” altrimenti controlla se è stato inserito il valore 3 e in questo caso restituisci la stringa “neutro” altrimenti restituisci la stringa vuota.

Il FlowScript privilegia la velocità di scrittura e la semplicità delle espressioni a discapito dell’ortodossia del linguaggio. Questo causa alcune particolarità che  possono confondere gli utenti che hanno esperienza con altri linguaggi di programmazione.

Stringa con o senza apici, quali sono le differenze?

La sintassi completa e corretta delle stringhe prevede l’utilizzo di apici. Se la stringa è formata da una singola parola (ossia senza spazi), gli apici possono essere omessi.

Pertanto la sintassi [D1]==Marco è equivalente a [D1]=='Marco'.

La condizione [D1]=='molto soddisfatto' non può essere scritta senza apici in quando sono necessari per determinare l’inizio e la fine della stringa.

Asimmetria dei confronti

Gli elementi che si confrontano nelle condizioni (vale a dire gli elementi prima e dopo l’operatore di confronto) NON sono identici. Quello dopo l’operatore di confronto è interpretato sempre come stringa, mentre quello che precede l’operatore, se è una stringa libera (ovvero senza apici), è interpretato come codice domanda.

Per esempio la condizione D1==1 significa “verifica se alla domanda con codice D1 è stata data una risposta con codice 1”. Se inverto l’ordine degli elementi ottengo la condizione 1==D1 che significa “verifica se alla domanda con codice 1 è stata data una risposta con codice D1” che è radicalmente diverso.

Per cui bisogna sempre considerare che i confronti NON sono, in generale, invertibili.