Flow Expressions

Flow is an expression that allows you to insert data based on respondent input (as is or after performing some operations) into specific places in the survey for validation, displaying this data, calculations, etc.

Flow expression can be used wherever you see the 𝑓 symbol.

For example, you can enter a Flow expression in the question description:

round(${Q1[1]} / 12, 2)

which corresponds to the following:

  • take the answer from question Q1, answer option with ID 1
  • divide by 12
  • round to 2 decimal places using the round function

Or another example, in the “Maximum” field of a numeric answer option write:

${Q1[1]} + ${Q2[3]}

which corresponds to the following:

  • take the value from the answer option with ID 1, from question Q1
  • add the value from the answer option with ID 3, from question Q2
  • the result will be used as a check for the maximum value in the current answer option

A Flow expression can be of any length, and use parentheses to define the order of operations.

(${Q1[1]} + ${Q2[3]}) * 2

First, the value from answer option 1, question Q1 will be added to the value from answer option 3, question Q2. Then, the result of the addition will be multiplied by 2.

Data Types

There are 5 data types in Flow:

  • Number
  • String
  • Logical (boolean)
  • Date
  • Time

Numeric Type

1000 - integer

1.00001 - floating-point number

Comma cannot be used to denote a floating-point number.

String

“string” or ‘string’

Strings are enclosed in single or double quotes. Any characters within single or double quotes are considered a string, including numbers. Example: ‘1.001’ is a string.

Logical

true - true

false - false

The case of the value does not matter. Possible notations:
true True TRUE false False FALSE

Date

Cannot be entered directly. Dates can only be used through substitutions.

Time

Cannot be entered directly. Time can only be used through substitutions.

Substitutions

Substitutions are used to obtain values based on data collected from users during survey participation.

A substitution structure looks like this:

${target|method}

Target is what the substitution is addressing.
Method defines what exactly is to be retrieved from the target.

Target

Possible target notations:

  • Question
    Q7 - refers to the question with ID Q7.
  • Answer option
    Q7[3] - refers to the answer option with ID = 3, for the question with ID = Q7.
  • Matrix question (row)
    Q7[2, q] - refers to a matrix question. Q7 - question ID; 2 - matrix question (row) ID; q - indicates that the reference is specifically to a matrix question.
  • Matrix answer (column)
    Q7[2, a] - refers to a matrix answer option. Q7 - question ID; 2 - matrix answer option (column) ID; a - indicates that the reference is specifically to a matrix answer option.
  • Matrix cell
    Q7[1][2] - refers to a cell (intersection of question and answer option) in the matrix. Q7 - question ID; 1 - matrix question (row) ID; 2 - matrix answer option (column) ID.

Method

List of available methods:
Method Description Return Type Support on Mobile App (Android)
count The number of answer options selected by the user to the question number +
sum Sum of numeric values entered in numeric open-ended responses number +
answertext User's response to the question. If an answer option includes an input field, the user's entered value will be used; otherwise, the answer option's description will be used. If multiple selections are allowed, the responses will be listed comma-separated. string +
id ID of the selected answer option (for single selection only) number +
answerimage User's response to the question (image). If multiple selections are allowed, images will be displayed sequentially string +
answers Returns the total number of responses to this question across the entire project (Regardless of whether the question is single, multiple, informational, or a matrix - it is counted as one response per interview). An informational question is also counted as one response if it was shown to the user. Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number
minanswers Returns the ID of the answer option with the minimum number of responses to this question/answer option across the entire project. Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number
minanswersq Returns the ID of the matrix row with the minimum number of responses to this question across the entire project (Regardless of whether the question is single or multiple - it is counted as one response per interview). Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number
Method Description Return Type Support on Mobile App (Android)
value Returns the value entered by the user in the field Equals the answer option type +
listtext Textual value of the selected item in an open-ended "List" answer option string +
description Returns the description of the answer option string +
image Returns the image of the answer option string +
selected Returns true if the answer was selected by the user, false otherwise bool +
selectedn Returns 1 if the answer was selected by the user, 0 otherwise number +
valuenull Returns the value entered by the user in the field. If the value is absent, returns 0 Equals the answer option type +
answers Returns the number of responses to this question/response option across the entire project. Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number
Method Description Return Type Support on Mobile App (Android)
description Returns the description of the matrix question (row) string +
answertext User's response to the question. If an answer option includes an input field, the user's entered value will be used; otherwise, the response option's description will be used. If multiple selections are allowed, the responses will be listed comma-separated. string +
id ID of the selected answer option (for single selection only) number +
answerimage User's response to the question (image). If multiple selections are allowed, images will be displayed sequentially string +
sum Sum of numeric values entered in numeric open-ended answer options in the matrix question (row) number +
answers Returns the number of responses to this question/matrix row (regardless of whether it is multiple or single selection, counted as one response per interview). An informational question is also counted as one response if it was shown to the user. Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number
Method Description Return Type Support on Mobile App (Android)
description Returns the description of the matrix answer option (column) string +
image Returns the image of the matrix answer option string +
answers Returns the number of responses to this question/response option across the entire project. Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number
count Returns the number of user responses to the response option (column) in the matrix number +
Method Description Return Type Support on Mobile App (Android)
value Returns the value entered by the user Equals the matrix cell type +
listtext Textual value of the selected item in an open-ended "List" answer option string +
selected Returns true if the cell was selected by the user, false otherwise bool +
selectedn Returns 1 if the response was selected by the user, 0 otherwise number +
valuenull Returns the value entered by the user in the field. If the value is absent, returns 0 Equals the matrix cell type +
answers Returns the number of responses to this question/matrix row/response option across the entire project. Only successful working interviews are counted, excluding those with a validation status of "Rejected". Online only number

Functions

Functions take data, perform calculations, and return a result.

A function can take several parameters. Function parameters are separated by commas.

An example of the round function, which rounds a floating-point numerical value to a specified number of digits after the decimal point:

round(100.223113, 2)

round - function name;
100.223113 and 2 - parameters, separated by a comma;
The result of the function will be: 100.22

Available functions:
Name Description Return Type and Value Description Support on Mobile App (Android)
date Returns the date from the string if a string is provided. If no string is provided, it returns today's date

Parameters:
1 (string) - Date string
2 (string) - String format
 date - Date from the string or today's date if no string is provided +
day Returns the day of the date from 1 to 31

Parameters:
1 (date) - Date
 number - Day in numeric form +
dayw Returns the day of the week from 1 to 7. The first day of the week depends on the settings. Usually, the first day of the week is Monday

Parameters:
1 (date) - Date
 number - Day in numeric form +
month Returns the month of the date from 1 to 12

Parameters:
1 (date) - Date
 number - Month in numeric form +
year Returns the year in YYYY format

Parameters:
1 (date) - Date
 number - Year in numeric form +
currdate Returns the current date

Parameters:
 date - Current date +
subday Subtracts a number of days from the date

Parameters:
1 (date) - Date
2 (number) - Number of days
 date - Modified date +
addday Adds a number of days to the date

Parameters:
1 (date) - Date
2 (number) - Number of days
 date - Modified date +
dateformat Formats the date

Parameters:
1 (date) - Date
2 (string) - Date format. Acceptable formats: dd - day 01..31, mm - month 01..12, yyyy - full year. For example, "dd.mm.yyyy" would result in 31.01.2023
 date - Modified date +
currtime Returns the current time

Parameters:
 time - Current time +
concat Concatenation of strings

Parameters:
1 - String 1
2 - String 2
 string - Concatenated strings +
round Rounding

Parameters:
1 (number) - Value to round
2 (number) - Number of decimal places
 number - Rounded number to the specified number of decimal places +
pow Exponentiation

Parameters:
1 (number) - Value to exponentiate
2 (number) - Power
 number - Value raised to the power +

Operators

The following operators are available: !, *, /, %, +, -, <, <=, >, >=, ==, !=, &&, ||

Operators can be applied to certain types. The types to which an operator is applied must be identical. That is, comparing a numerical value and a string will lead to an error, for example: “1” == 1 will result in an error “Data types for operator ‘==’ are not identical”.

List of operators:
Operator Description Applicable to types Return type Examples
! Logical negation Logical (boolean) Logical (boolean) !(1==1)
Result: false

!true
Result: false
* Multiplication Number Number 5*20 Result: 100
/ Division Number Number 100/5
Result: 20
+ Addition Number Number 100+20
Result: 120
- Subtraction Number Number 100-20
Result: 80
< Less than Number
Date
Time 		Logical (boolean) 1 < 100
Result: true

25.01.2002 < 30.01.2002*
Result: true

13:30 < 16:00*
Result: true
<= Less than or equal to Number
Date
Time 		Logical (boolean)
> Greater than Number
Date
Time 		Logical (boolean)
>= Greater than or equal to Number
Date
Time 		Logical (boolean)
== Equal to Number
Date
Time
String
Logical (boolean) 		Logical (boolean) 1 == 1
Result: true

25.01.2002 == 25.01.2002*
Result: true

13:30 == 13:30*
Result: true

"a" == "a"
Result: true

true == true
Result: true
!= Not equal to Number
Date
Time
String
Logical (boolean) 		Logical (boolean)
&& Logical AND Logical (boolean) Logical (boolean) true && true
Result: true

1 < 10 && 5 > 3
Result: true

1 > 0 && 13:30 == 13:30*
Result: true
|| Logical OR Logical (boolean) Logical (boolean) 1 > 5 || 5 < 10
Result: true

* Using 13:30 or 25.01.2002 directly in Flow is not allowed. Time and date cannot be directly written in Flow; substitutions must be used.

Validation and Errors

Flow expressions are checked for syntax at the time of saving. Also, when saving Flow, the return type is determined and checked to ensure it is suitable for the specific field.

If Flow is used in fields where a specific type is required, the Flow expression must return the required type. For example, for the “Minimum” parameter in a numerical answer option, the Flow return type must be numerical. If the Flow expression returns a different type (e.g., “string”) upon saving the question, an “Invalid calculation type” error will be displayed.

Not all errors can be checked at the stage of saving Flow. For instance, the survey logic might be constructed in such a way that a question necessary for executing Flow is skipped. In this case, a “Missing value” error will occur.

Flow errors are displayed as warnings during the test run of the survey. It is recommended to check the survey using a test link before starting it in production mode.

If an error occurs in the execution of Flow while a user is taking the survey, the result of the Flow calculation is ignored, i.e., equated to a missing value. The error is not displayed anywhere.

For example, if a Flow expression is used in the “Maximum” field of a date type answer option, and an error occurs during the survey, the check for the maximum entered date will be ignored.

The following errors can occur during the check or execution of Flow expressions:

  • The element cannot be first
  • The element cannot follow after "..."
  • Cannot read the line
  • An element cannot be last
  • Regular expression error
  • The element cannot be in this position
  • Syntax error in substitution
  • Substitution not found
  • Value is empty
  • Value "..." for "..." cannot be converted to expected type "..."
  • A method must be specified for substitution "..."
  • Method "..." does not exist for substitution "..."
  • A question cannot refer to itself
  • A matrix cell cannot refer to itself for validation. Substitution "..."
  • An answer option cannot refer to itself for validation. Substitution "..."
  • Substitution "%s" cannot refer to questions that follow the original question.
  • The question type in substitution "..." does not match the actual question type (check: matrix or multiple choice)
  • The operand for operator "..." is missing or incorrect
  • Incorrect value type "..." for operator "..."
  • Operators cannot be used in this manner. Use parentheses or the && and || operators
  • Data types for %s %s %s are not identical
  • Division by zero
  • Result is infinite
  • Incorrect calculation type. Provided: "...". Required: "..."
  • Error in function "..."
  • Required parameter "..." is missing
  • Incorrect variable type for parameter "...". Expected: "...", received: "..."