Operators provide a sophisticated set of commands that can be incorporated into a form'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 fields. Most operators can be embedded directly into the field's display text and will be evaluated when the field 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].


Operators are not displayed on the handset when the form is being conducted.


Referencing Fields

For operators that reference another field in the form, you can reference the field in one of two ways:


It might be more readable to use field identifiers to refer to fields but you will have to remember to update your references if the field's identifier is ever modified. Referencing a field by it's system-assigned field ID is safer because each ID is unique and will always refer to the same field, even if the field identifier changes.


Below is a list of operators available to you:

  • Mathematical operators
  • Date operators
  • Referential operators
  • Logic flow operators
  • Field modification operators


Mathematical operators


Operator

Purpose/function

Syntax

AVG

Returns the calculated average (mean) of two or more values.

__{AVG(value1,value2,...)}__

SUM

Returns the sum (addition) of the specified values.

__{SUM(value1,value2,...)}__

SUB

Returns the result of the subtraction of one or more specified values from an initial value.

__{SUB(initial,value1,...)}__

DIV

Returns the result of the division of an initial value by one or more values.

__{DIV(initial,value1,...)}__

MUL

Returns the calculated multiplication (product) of two or more values.

__{MUL(value1,value2,...)}__

ROUND

Returns the result of a fractional value rounded to a specified number of decimal places.

__{ROUND(value,decimal_places)}__

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)}__



Example 1:

I want to calculate the average systolic blood pressure measurement based on three measurements I recorded in my form.

  • Set up the field that will contain the calculation of the average value. In this example an instruction was used to display the average value to the fieldworker. The operator can also be added to a variable field type if you do not want the value to display to the fieldworker (but do want to have access to it for analysis purposes later) or to any other field type, and can also be used in combination with other operators. 
  • In this example, the system-generated field IDs were used to reference the three values you want to calculate the average for. You could also have used the field identifiers (names) instead. 






Example 2:

The average of three values must be rounded to 2 decimal places.






Date operators


Operator

Purpose/function

Syntax

DATENOW

Returns the current date (based on the handset's internal calendar) in the format d-m-yyyy.

__{DATENOW}__

DATEADD

Returns the date result when the specified number of days is added to the specified date.

__{DATEADD(date,days)}__

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 fields captured, static dates (e.g. 31-1-2013), or the current date (DATENOW operator).
__{DAYSBETWEEN(start_date,end_date)}__



Example 1

The fieldworker must record the date of the interview. Validation must be added to ensure that no date in the future is accepted for this field. 

  • Add a new constraint to the field. 
  • As the value of the constraint, use the DATENOW operator.




  • This is what it would look like in the designer:





Example 2

A follow-up appointment must be scheduled for 3 months after the interview date (as captured in Example 1 above).




Referential operators

Referential operators are used to refer to previously captured responses.



Operator
Purpose/funciton
Syntax
COUNT
Returns the number of selected options for the specified multi-select field.
__{COUNT('field_name')}__
__{COUNT(field_id)}__

COUNTOPTIONS
Returns the number of available options for the specified select field.
__{COUNTOPTIONS('field_name')}__
__{COUNTOPTIONS(field_id)}__

ID
Returns the unique system-assigned question ID of the field.
__{ID}__
INDEX
Returns the current iteration value of a repeating region. During the first execution of the section this will return 1.

__{INDEX}__
LABEL
Returns the label for the option matching the specified value.
__{LABEL('field_name',option_value)}__
__{LABEL(field_id,option_value)}__

MENUACTION
Renders a shortcut to the specified menu item from the field'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)}__
OPTIONVALUE
Returns the value of the option based on the specified field 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('field_name',index)}__
__{OPTIONVALUE(field_id,index)}__

Q
Returns the response value stored for the specified field. The optional second parameter defines the value to be returned if the specified field was skipped.
__{Q('field_name',value_if_skipped)}__
__{Q(field_id,value_if_skipped)}__

QI
Returns the response stored for the specified field in a repeating section. Repeat indexing starts at 1, i.e. the first repeat instance will have an index of 1 not 0.
__{QI('field_name',index)}__
__{QI(field_id,index)}__



Example 1:

After entering the household head's name, the fieldworker must capture the date of birth of the household head.

  • In this example, the field identifier (name) was used to refer to the relevant field. You could also have used its system-assigned field ID.





  • This is what it would look like in the designer:





Example 2

After entering the number of household members that lives in a household, a repeating section is used to capture the name and age of each member. The fieldworker needs to keep track of which household member they are currently capturing information for. 




  • Once the household member's name is captured you can refer to the person by name to capture their age. 



  • This is what it will look like on the designer:



  • When completing the form on the handset, “__{INDEX}__” will be replaced by the iteration number, starting at 1.


Logic flow operators

Logic flow operators do not return a result and must be used within a special field type called a variable operator. This is created by adding a new field, selecting the 'Variable' field type, and then selecting 'Operator' as the v

ariable type.



Operator

Purpose/function

Syntax

GOTO

Skips directly to the specified field.

__{GOTO('field_name')}__
 __{GOTO(field_id)}__

REPROCESS
Re-evaluates the specified field to account for parameters which might have changed since the response to the field was captured. This can be used to create a "while" loop when combined with a repeating section.
__{REPROCESS('field_name')}__
 __{REPROCESS(field_id)}__

SET
Sets or overwrites the value of a previous response to the specified value.

__{SET('field_name',value)}__
 __{SET(field_id,value)}__

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 form capture a REPROCESS would need to be called before using this SET functionality on a value within the repeat.

__{SET('field_name',value,optionalRepeatIndex)}__
 __{SET(field_id,value,optionalRepeatIndex)}__



Example 1

If a participant is not available for an interview, the reason should be captured and then all fields should be skipped in order to capture a rescheduled date at the end of the form. 

  • Add a variable operator field type.



  • In the 'Default value' tab, add the operator's instructions - to go to the field with name 'reschedule'.


  • This is what it will look like in the designer:





Example 2

The participant's BMI must be calculated by dividing the participant's weight (in kgs) the participant's squared height (in meters squared). 


There are many instances of using the SET variable in this example. We will highlight the one instance - setting a variable to height squared.

  • Create a variable that will store the result of the participant's height squared.



  • Create a variable operator field type to perform the calculation.


  • In this case, select 'Next' to open the Default Value tab. Add the SET operator as default value as shown below.


 

  • The complete BMI calculation will look like this in the designer:



Field Modification Operators

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



Operator

Purpose/function
Syntax
ADDOPTION
Adds an option (with specified label and value) to the field(s) specified (can be a list of field IDs or field identifiers). The specified field can be either single or multiple select fields.
__{ADDOPTION(optionLabel,optionValue,'field_1','field_2')}__
 __{ADDOPTION(optionLabel,optionValue,field_id,field_id)}__

REMOVEOPTION
Removes the option (identified by the option value provided) from the field(s) specified (can be a list of one or more field IDs or field identifiers). To remove all options from the list, leave the first parameter blank.
__{REMOVEOPTION(optionValueToRemove,'field_1','field_2')}__ __{REMOVEOPTION(optionValueToRemove,field_id,field_id)}__