Browse
 
Tools
Rss Categories

 Featured
Operators overview

Reference Number: AA-00375 Last Updated: 2016-07-06 15:15

Operators provide a sophisticated set of commands which can be incorporated into a survey's design to set variables, perform calculations, control logic flow and format data.

Operators can be nested within one another and, when applicable, can accept both constant values or responses to previous questions. Most operators can be embedded directly into the question's display text and will be evaluated when the question is displayed. To indicate the use of an operator, the operator is wrapped with __{OPERATOR}__ (two underscores and the left brace "{" and right brace "}" respectively). 

Question Identifiers

For operators which reference another question in the survey, you can reference the question by its short name (an identifier assigned by the survey designer during question setup) or by its system-assigned question ID. Use single quotes when referring to the question by its 'short name' and without quotes to reference it by its numeric system-assigned identifier.

It is much more readable to use short names to refer to questions but ensure you update your references if the question's short name is ever modified. Referencing a question by its short name is only supported by version 5.3.0 and above of the mobile application/plugin.

Mathematical Operators

Operator Purpose / Function Syntax  Availability
 AVG Returns the calculated average (mean) of two or more values.   __{AVG(value1,value2,...)}__  version 4.1.0+
 DIV Returns the result of the division of an initial value by one or more values.  __{DIV(initial,value1,...)}__  version 4.1.0+
 MUL Returns the calculated multiplication (product) of two or more values.  __{MUL(value1,value2,...)}__  version 4.1.0+
 RANDOM Returns a random number (integer or decimal value) between two specified values. By specifying a "c" or "d" for the third argument the result can be continuous (fractions) or discrete (integers only).  __{RANDOM(fromvalue,tovalue,cd)}__   version 4.7.1+
 ROUND Returns the result of a fractional value rounded to a specified number of decimal places.   __{ROUND(value,decimal_places)}__  version 4.7.1+ 
 SUB Returns the result of the subtraction of one or more specified values from an initial value.   __{SUB(initial,value1,...)}__  version 4.1.0+
 SUM Returns the sum (addition) of the specified values.   __{SUM(value1,value2,...)}__  version 4.1.0+

Date Operators

Operator Purpose / Function Syntax  Availability
 DATEADD Returns the date result when the specified number of days is added to the specified date.   __{DATEADD(date,days)}__  version 4.7.1+ 
 DATENOW Returns the current date (based on the handset's internal calendar) in the format d-m-yyyy.  __{DATENOW}__   version 4.7.1+
 DAYSBETWEEN Returns the number of days between the start date and end date, excluding the end date. The date parameters can either reference previous date questions captured, static dates (e.g. 31-1-2013) or the current date (DATENOW operator).  __{DAYSBETWEEN(start_date,end_date)}__  version 4.7.1+ 

Referential Operators

Referential operators are used to refer to previously captured responses. 

Operator Purpose / Function Syntax  Availability
 COUNT Returns the number of selected options for the specified multiselect question.   __{COUNT('question_name')}__
 __{COUNT(question_id)}__
 version 4.7.1+
 COUNTOPTIONS Returns the number of available options for the specified select question.  __{COUNTOPTIONS('question_name')}__
 __{COUNTOPTIONS(question_id)}__
 version 4.11.0+
 ID Returns the unique system-assigned question ID of the question currently in scope.  __{ID}__  version 4.10.0+
 INDEX Returns the current iteration value of a repeating region. During the first execution of the section this will return 1.   __{INDEX}__  version 2.0.0+
 LABEL Returns the label for the option matching the specified value.   __{LABEL('question_name',option_value)}__
 __{LABEL(question_id,option_value)}__
 version 4.7.1+ 
 MENUACTION Renders a shortcut to the specified menu item from the question's Options menu. When the fieldworker taps on the shortcut, the associated menu action is executed. The menu item is identified by its label as it appears in the Options menu.  __{MENUACTION(menuLabel,shortcutLabel)}__  version 4.13.2+ (Android only)
 OPTIONVALUE Returns the value of the option based on the specified question and option index. Option indexing starts at 1, i.e. the first option in a list will have an index of 1 not 0.   __{OPTIONVALUE('question_name',index)}__
 __{OPTIONVALUE(question_id,index)}__
 version 4.11.0+
 Q Returns the response value stored for the specified question. The optional second parameter defines the value to be returned if the specified question was skipped.  __{Q('question_name',value_if_skipped)}__
 __{Q(question_id,value_if_skipped)}__
 version 4.11.2+ 
 QI Returns the response stored for the specified question in a repeating section. Repeat indexing starts at 1, i.e. the first repeat instance will have an index of 1 not 0.  __{QI('question_name',index)}__ 
 __{QI(question_id,index)}__ 
 version 4.11.0+

Logic Flow Operators

Logic flow operators do not return a result and must be used within a special question type called a variable operator.

Operator Purpose / Function Syntax  Availability
 GOTO Skips directly to the specified question.   __{GOTO('question_name')}__
 __{GOTO(question_id)}__
 version 4.7.1+ 
 REPROCESS Re-evaluates the specified question to account for parameters which might have changed since the response to the question was captured. This can be used to create a "while" loop when combined with a repeating section  __{REPROCESS('question_name')}__
 __{REPROCESS(question_id)}__
 version 4.7.1+
 SET Sets or overwrites the value of a previous response to the specified value.   __{SET('question_name',value)}__
 __{SET(question_id,value)}__
 version 4.1.0+
 SET
 (in repeat)
Sets or overwrites the value of a previous response within a specified repeating section to the specified value.  
Note: If the repeating value of a repeating section has been updated during survey capture a REPROCESS would need to be called before using this SET functionality on a value within the repeat.
 __{SET('question_name',value,optionalRepeatIndex)}__
 __{SET(question_id,value,optionalRepeatIndex)}__
 version 4.14.0+

Question Modification Operators

Question modification operators can be used to alter certain aspects of a question - such as the list of available options - based on data entered during the conduction of the survey. Note that any modifications apply only to the survey whilst it is in progress. Once it completes (or is restarted), modifications are discarded and the survey reverts to its original design.

Operator Purpose / Function Syntax  Availability
 ADDOPTION Adds an option (with specified label and value) to the question(s) specified (can be a list of question IDs or short names). The specified questions can be either single or multiple select questions.  __{ADDOPTION(optionLabel,optionValue,'question_1','question_2')}__
 __{ADDOPTION(optionLabel,optionValue,question_id,question_id)}__
 version 4.11.0+ 
 REMOVEOPTION Removes the option (identified by the option value provided) from the question(s) specified (can be a list of one or more question IDs or short names). To remove all options from the list, leave the first parameter blank.  __{REMOVEOPTION(optionValueToRemove,'question_1','question_2')}__
 __{REMOVEOPTION(optionValueToRemove,question_id,question_id)}__
 version 4.11.0+

Rss Comments
  • There are no comments for this article.