Previous Next

In the form designer, you can build constraint, relevance, and calculation expressions using simple wizards that are built right into the designer. Using the wizards in the form designer is the easiest way to ensure that all of your expressions are written in the correct syntax and will function properly.

You can also edit expressions by hand, in which case the following reference materials will come in handy. Even when you're editing spreadsheet form definitions directly, you can use the constraint-builder, the relevance-builder, and/or the calculation-builder, all of which are available as tools in the Your forms and datasets section of your server's Design tab.

Referencing current values

${fieldname}

Refers to a different field's current value (entry, selection, or calculated value). This returns the value exactly as it will appear later in your submitted data.

Example

${age} will return the exact value that was entered in the field named age.

.

For constraints, "." refers to the user's proposed entry or selection for the current field.

Example

. < 3 checks to see if the new proposed value for the current field is less than 3.

Comparison operators

Operator	Operation	Example	Example answer
=	Equal	${fieldname} = 3	true or false
!=	Not equal	${fieldname} != 3	true or false
>	Greater-than	${fieldname} > 3	true or false
>=	>-or-equal	${fieldname} >= 3	true or false
<	Less-than	${fieldname} < 3	true or false
<=	<-or-equal	${fieldname} <= 3	true or false

Logical operators

or

Returns true if either the expression before or after evaluates to true.

Example

${age} = 3 or ${age} = 4
will return true if the age is either 3 or 4.

and

Returns true only if both expressions evaluate to true.

Example

${age} > 3 and ${age} < 5
will return true if the age is between 3 and 5.

not()

Returns true if the expression inside () does not evaluate to true.

Example

not(${age} > 3 and ${age} < 5)
will return true if the age is not between 3 and 5.

Working with strings

How to include literal strings

Please note that literal strings within your expressions should always be enclosed in single-quotes, as in 'Male' or ' ' for a single space. An exception to this is if you want to include single-quotes in your literal string. For example:
if(${yesno} = 1, "a string with 'single quotes' in it", "no single quotes here") will work, but
if(${yesno} = 1, 'a string with 'single quotes' in it', 'no single quotes here') will not work.
Additionally, beware of smart quotes, which will break your expressions. Many rich text editors will automatically convert your straight quotes ("" or '') into smart quotes or curly quotes (“” or ‘’).

string(field)

Converts field to a string.

Example

string(34.8) = '34.8'

string-length(field)

Returns the length of the string field.

Example

string-length(.) > 3 and string-length(.) < 10
can be used as a constraint expression to make sure the current field is between 3 and 10 characters.

substr(fieldorstring, startindex, endindex)

Returns a substring starting at startindex and ending just before endindex. Indexes start at 0 for the first character in the string.

Example

substr(${phone}, 0, 3)
will return the first three digits of a phone number.

concat(a, b, c, ...)

Concatenates fields (and/or strings) together.

Example

concat(${firstname}, ' ', ${lastname})
will return a full name by combining the values in the firstname and lastname fields.

linebreak()

Returns a linebreak character.

Example

concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3})
will return a list of three field values with linebreaks between them.

lower()

Converts a string to all lowercase characters.

Example

lower('Street Name')
will return "street name".

upper()

Converts a string to all uppercase characters.

Example

upper('Street Name')
will return "STREET NAME".

Working with select_one and select_multiple fields

count-selected(field)

Returns the number of items selected in a select_multiple field.

Example

count-selected(.) = 3
can be used as a constraint expression to make sure exactly three choices are selected.

selected(field, value)

Returns true or false depending on whether the value indicated in the second parameter was selected in the select_one or select_multiple field indicated in the first parameter.

Example

selected(${gender}, 'Male')
can be used as a relevance expression to only show a group or field if the respondent selected Male as their gender.

Please note: the second parameter to the selected() function should always specify the choice value, not the choice label. In other words, always use the value from the value column in the choices worksheet of the form definition.

selected-at(field, number)

When the passed number is 0, returns the first selected item in a select_multiple field; when the passed number is 1, returns the second selected item; etc.

Example

selected-at(${fieldname}, 0) = 'Shona'
can be used as a relevance expression to only show a group or field if the first selected choice is Shona.

Please note: the returned value will be the choice value, not the choice label. In other words, this function will return the value from the value column in the choices worksheet of the form definition.

choice-label(field, value)

Returns the label for a select_one or select_multiple field choice, as defined on the choices worksheet of the form definition.

Example

choice-label(${selectonefield}, ${selectonefield})
will return the choice label for whatever choice is currently selected in the field named selectonefield.

Example

choice-label(${selectmultfield}, selected-at(${selectmultfield}, 0))
will return return the label for the first selected choice in the field named selectmultfield.

Please note: this function will only retrieve labels from the choices worksheet, so will not work for dynamically-loaded choice options. For options loaded from pre-loaded data, use the pulldata() function in a calculate field to directly pull the label from the appropriate column of the external data.
Please note: this is a similar, but improved version of the old jr:choice-name() function.

Click here to learn more about displaying choice labels.

Working with repeated data

In SurveyCTO, if you want to ask the same question(s) multiple times, you can put a field inside a repeat group. This results in multiple instances of the same field. The following functions can help you deal with these repeated fields, and the repeated data that they produce. See the help topic on repeating fields for more details.

join(string, repeatedfield)

For a field within a repeat group, generates a string-separated list of values. The first parameter specifies the delimiter to use to separate the values.

Example

join(', ', ${hh_member_name})
will generate a single comma-separated list from all entered names.

join-if(string, repeatedfield, expression)

Functions exactly like join(), except that it will check each instance in repeatedfield's repeat group using the supplied expression. If the expression evaluates to false, the item will be omitted from the output.

Example

join-if(', ', ${hh_member_name}, ${age} >= 18)
will generate a single comma-separated list from the names of only adult household members (those with ages 18 and over).

count(repeatgroup)

Returns the current number of times that a repeat group has repeated.

Example

count(${repeatgroupname})
will return the number of 'instances' of the group.

count-if(repeatgroup, expression)

Functions exactly like count(), except that it will check each instance in repeatgroup using the supplied expression. If the expression evaluates to false, the item will be omitted from the output.

Example

count-if(${hhmembers}, ${age} >= 18)
will return the count of adult household members, based on the age field within the hhmembers repeat group.

sum(repeatedfield)

For a field within a repeat group, calculates the sum of all values.

Example

sum(${loan_size})
will return the total value of all loans.

sum-if(repeatedfield, expression)

Functions exactly like sum(), except that it will check each instance in repeatedfield's repeat group using the supplied expression. If the expression evaluates to false, the item will be omitted from the output.

Example

sum-if(${loan_size}, ${loan_size} > 500)
will return the total value of all loans that are over 500. Smaller loans will be ignored.

min(repeatedfield)

For a field within a repeat group, calculates the minimum of all values.

Example

min(${hh_member_age})
will return the age of the youngest member in the household.

min-if(repeatedfield, expression)

Functions exactly like min(), except that it will check each instance in repeatedfield's repeat group using the supplied expression. If the expression evaluates to false, the item will be omitted from the output.

Example

min-if(${hh_member_age}, ${hh_member_age} >= 18)
will return the age of the youngest adult in the household. Those younger than 18 will be ignored.

max(repeatedfield)

For a field within a repeat group, calculates the maximum of all values.

Example

max(${hh_member_age})
will return the age of the oldest member in the household.

max-if(repeatedfield, expression)

Functions exactly like max(), except that it will check each instance in repeatedfield's repeat group using the supplied expression. If the expression evaluates to false, the item will be omitted from the output.

Example

max-if(${hh_member_age}, ${hh_member_age} >= 18)
will return the age of the oldest adult in the household. Those younger than 18 will be ignored.

index()

Called within a repeat group, returns the index number for the current group or instance.

Example

index()
when this calculate expression is within a repeat group, will return 1 for the first instance of the repeat, 2 for the second, and so on.

Please note: you should use index() instead of the ODK function position(..). While position(..) will function similarly to index() in some cases, it will fail if you use it in a non-repeating group that is inside a repeating group.

indexed-repeat(repeatedfield, repeatgroup, index)

References a field or group that is inside a repeat group, from outside that repeat group. The first parameter specifies the repeated field or group in which you are interested; the second specifies the repeat group within which the field or group of interest is located; and the third specifies the instance number, within the repeat group, to use. For two examples, see Rosters: Two methods for repeated questions.

Example

indexed-repeat(${name}, ${names}, 1)
will return the first name available when the name field is inside a prior repeat group named names.

Example

indexed-repeat(${name}, ${names}, index())
From inside a later repeat group, this calculate expression will pull the xth name from the prior repeat group, where x is the instance number of the current repeat group (e.g., if currently in the fourth instance of a repeat group, it will return the fourth name from the earlier repeat group).

If you need to reference a field or group within multiple nested repeat groups, you can supply additional parameters to indicate the instance numbers to use for each level of nesting.

Example

indexed-repeat(${name}, ${families}, ${familynumber}, ${names}, ${membernumber})
will pull a particular family member's name when family member names are inside a repeat group that is itself inside a repeat group of families.

Please note: when the passed-in instance number is invalid, an instance number of 1 will be automatically used instead (so the first instance will be returned for such cases).

To learn more, check out our support article Using and referencing repeated data.

rank-index(index, repeatedfield)

Calculates the ordinal rank of the specified instance of a repeated field for use outside the repeat group. The rank of 1 is assigned to the instance with the highest value, the rank of 2 to the instance with the next-highest value, and so on.

Example

rank-index(1, ${random_draw})
will calculate the rank of the first instance, based on the value of its random_draw field as compared with other instances' values.

Instances with the same value are ordered arbitrarily (they are not given the same rank, so every instance will have a unique rank). If you pass an invalid index or an index to an instance with a non-numeric value, a rank of 999 will be returned.

rank-index-if(index, repeatedfield, expression)

Functions exactly like rank-index(), except that it will check each instance in repeatedfield's repeat group using the supplied expression. If the expression evaluates to false, the item will be omitted from the calculation.

Example

rank-index-if(1, ${age}, ${age} >= 18)
will calculate the age rank within the set of adults.

Please note: the index used is the index from the full set of instances, before evaluating the expression for each instance. If you pass an index for an instance which was ignored because it did not satisfy the expression, that is considered an invalid index so a rank of 999 will be returned.

Working with lists of items

count-items(string, field)

Returns the number of items in a list of items separated by string.

Example

count-items(',', ${list_of_addresses})
if the list_of_addresses field contains a comma-separated list, this will return the number of addresses.

Please note: empty items are counted. For example, the comma-separated list `item1,item2,,item4` contains 4 items, even though the 3rd item is empty.

item-at(string, field, number)

Returns the item at index number from a list of items separated by string.

Example

item-at(',', ${list_of_addresses}, 0)
if the list_of_addresses field contains a comma-separated list, this will return the first address in the list.

Please note: empty items are counted. For example, the comma-separated list `item1,item2,,item4` contains 4 items, even though the 3rd item is empty.

item-index(string, field, value)

Returns the index of the value you specify from a list of items separated by string. This is essentially the inverse of item-at(). If value is not found, this will return -1. If value occurs more than once in the list, this will return the index of the first occurence.

Example

item-index(',', ${list_of_names}, ${name})
if the list_of_names field contains a comma-separated list, this will return the index of the first time ${name} occurs.

Please note: empty items are counted. For example, the comma-separated list `item1,item2,,item4` contains 4 items, even though the 3rd item is empty.

item-present(string, field, value)

Checks a list of items separated by string to see if value is present. Returns true if one of the items matches string, otherwise returns false.

Example

item-present(',', ${list_of_addresses}, '')
if the list_of_addresses field contains a comma-separated list, this will check to see if any items in that list are empty.

Please note: empty items are counted. For example, the comma-separated list `item1,item2,,item4` contains 4 items, even though the 3rd item is empty.

de-duplicate(string, field)

Removes duplicates from a list of items separated by string.

Example

de-duplicate(' ', ${fieldname})
will remove duplicate values from the space-separated list contained in the field named fieldname.

Example

Say you had a repeated multiple-choice field. Outside the repeat group itself, you might want to join all selections together into one calculated list, which you could do with the expression join(' ', ${repeatedfield}), but that list might then contain the same selections multiple times. The calculate expression:
de-duplicate(' ', join(' ', ${repeatedfield}))
would join together all of the selections, and remove duplicates. You could then use count-items(), item-at(), etc. on the combined list in the calculated field.

rank-value(value, list)

Calculates the ordinal rank of a given value relative to a space-separated list of numeric values. The rank of 1 is assigned to the highest value in the list, the rank of 2 to the next-highest value, and so on.

Example

rank-value(3, '4 2 1 9 3 7')
will calculate the rank of 3 in the given list. Since 3 is the 4th highest value, this expression will return 4.

Working with geographical data

distance-between(point1, point2)

Returns the distance, in meters, between two geopoint fields.

Example

distance-between(${start_gps}, ${end_gps})

Please note: (1) keep in mind that the accuracy of the distance calculated will depend on the accuracy of the GPS readings, so try to be sure to get accurate GPS readings; and (2) if non-GPS values are passed into this function, the form will give an error that will prevent the submission from being finalized and submitted. Please ensure that any calculate field that calls this function has a relevance condition set such that the field only executes if both parameters are actual GPS coordinates.

area(setofgeopoints)

Returns the area enclosed, in square-meters, within a series of GPS coordinates. You can pass in either a geoshape or a geotrace field. Alternatively, you can pass in a geopoint field that's within a repeat group.

Example

area(${gps_reading})
Call this expression from outside the repeat group that contains the gps_reading geopoint field to calculate the total area between all the points.

Please note: the accuracy of the area calculated will depend on the accuracy of the GPS readings, so try to be sure to get accurate GPS readings.

geo-scatter(geopointfield, range)

Adds a predefiend amount of error to a GPS coordinate captured with a geopoint field. For each of the lat, long, and elevation values, a random distance up to range meters is either added or subtracted from the original value. This can be used for anonymizing GPS locations, if the exact location is not needed.

Example

geo-scatter(${location}, 20)
This will take the GPS point stored in the location field and move it to a random point within 20 meters of the original point.

short-geopoint(geopointfield)

Returns a string containing the GPS location with only the longitude and latitude (separated by a space), no altitude or accuracy. You might use this if publishing data to outside systems that are confused by altitude or accuracy.

Example

short-geopoint(${location})

Working with numbers

Operator	Operation	Example	Example answer
+	Addition	1 + 1	2
-	Subtraction	3 - 2	1
*	Multiplication	3 * 2	6
div	Division	10 div 2	5
mod	Modulus	9 mod 2	1

number(field)

Converts field to a number.

Example

number('34.8') = 34.8

int(field)

Converts field to an integer.

Example

int('39.2') = 39

min(field1, ... , fieldx)

If more than one non-repeating field is passed to min(), then the minimum of the passed fields will be returned. (See further above for the version that accepts a single repeated field.)

Example

min(${father_age}, ${mother_age})
will return the age of either the mother or the father, whichever is smaller.

max(field1, ... , fieldx)

If more than one non-repeating field is passed to max(), then the maximum of the passed fields will be returned. (See further above for the version that accepts a single repeated field.)

Example

max(${father_age}, ${mother_age})
will return the age of either the mother or the father, whichever is larger.

format-number(field)

Formats an integer or decimal field according to the user's locale settings.

Example

format-number(${income})
This calculate expression might format "120000" as "120,000".

round(field, digits)

Rounds the numeric field value to the specified number of digits after the decimal place.

Example

round(${interest_rate}, 2)

abs(number)

Returns the absolute value of a number.

pow(base,exponent)

Returns the first parameter raised to the power of the second parameter. Each parameter could be a field, number, or expression.

log10(fieldorvalue)

Returns the base-ten logarithm of the field or value passed in.

sin(fieldorvalue)

Returns the sine of the field or value passed in, expressed in radians.

cos(fieldorvalue)

Returns the cosine of the field or value passed in, expressed in radians.

tan(fieldorvalue)

Returns the tangent of the field or value passed in, expressed in radians.

asin(fieldorvalue)

Returns the arcsine of the field or value passed in, expressed in radians.

acos(fieldorvalue)

Returns the arccosine of the field or value passed in, expressed in radians.

atan(fieldorvalue)

Returns the arctangent of the field or value passed in, expressed in radians.

atan2(x, y)

Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis, the result being in the range -pi() to pi().

sqrt(fieldorvalue)

Returns the non-negative square root of the field or value passed in.

exp(x)

Returns the value of e^x.

pi()

Returns the value of pi.

Working with dates and times

duration()

Returns the total amount of time spent, in seconds, filling or editing the current form submission.

Example

duration()
Use this expression in a regular calculate field to capture the total duration spent on the form overall.

Example

once(duration())
Use this expression in a calculate_here field to find the total time it took the user to first reach that calculate_here field. You can then subtract one captured duration from another to get the time spent in between those two fields.

To learn how this differs from using start and end fields, check out our support article Difference between duration() and end-start.

today()

Returns the current date in YYYY-MM-DD format. To return the date in other formats, use today() inside of format-date-time() like in the example below.

Example

format-date-time(today(), '%Y-%b-%e')

now()

Returns the current date and time.

Example

once(format-date-time(now(), '%Y-%b-%e %H:%M:%S'))
Use this expression in a calculate_here field to save the date and time at which a particular point in your form is first reached.

Please note: Calling now() by itself will store only the date, without the time. To return and store a value that also includes time, now() must be used with format-date-time(), like the above example.

date(string)

Converts string into a date without preserving time.

Example

${birthday} > date('2013-01-31')
Use this expression to calculate if the birthday (presumably a date field) is after Jan. 31, 2013.

date-time(string)

Converts a string into a date-time.

Example

format-date-time(date-time('2013-01-31T16:42:00'), 'at %H:%M:%S on %e %b, %Y')
Use this expression to convert a string that represents a date time into a different format. Do no use date-time() for comparisons when the time part matters, since the time part is not taken into account. Use decimal-date-time() (below) when it comes to comparisons that should also account for the time part.

decimal-date-time(string)

Converts a string (representing a date-time) to the (fractional) number of days since January 1, 1970 (the Unix Epoch).

Example

decimal-date-time(now()) < decimal-date-time('2013-01-31T16:42:00')
Use this expression to calculate if the current date and time is before Jan. 31, 2013, 4:42pm. This can be useful in relevance expressions that prevent a field from being shown after a certain date-time.

decimal-time(string)

Converts a string (representing a date-time) to a number representing a fractional day. For example, midnight is 0.0, noon is 0.5 and 6:00 PM is 0.75. "23:59:59.999" is 0.999999988.

Example

decimal-time('2013-01-31T18:00:00')
This expression returns 0.75.

format-date-time(field, format)

Converts date and/or time into a string.

Example

format-date-time(${fieldname}, '%Y-%b-%e %H:%M:%S')

You may use the following values in the format string:

%Y	four-digit year
%y	two-digit year
%m	two-digit month
%n	one-or-two digit month
%b	three-letter month
%d	two-digit day
%e	one-or-two-digit day
%a	three-letter day of week
%H	two-digit hour
%h	one-or-two-digit hour
%M	two-digit minute
%S	two-digit seconds
%3	three-digit milliseconds

Please note: the products of format-date-time() are stored as strings. This means you will be limited to using string functions on that product, unless you format the value again using functions like date-time() or int().

Working with enumerators

enumerator-name()

Returns the name of the currently selected enumerator picked by the user in the enumerator field.

enumerator-id()

Returns the ID of the currently selected enumerator picked by the user in the enumerator field.

Working with phone calls

phone-call-log()

Records an event log of all call activity that happens while filling out the form. Each event is recorded on a new line in the format:

event_name|phone_number|timestamp

In each entry, event_name describes the type of event, phone_number records the phone number (if applicable), and timestamp records the time since the form was started. The timestamp will show seconds since the start of the form and is calculated in the exact same way as the duration() function. These log entries will contain a much greater level of detail when Collect is set as the default phone app.

Example

phone-call-log()
Used alone in a calculate field, this might return something like the following:

Form started||0
Call started|5555555555|12
Form exited (call in progress)|5555555555|25
Form resumed (call in progress)|5555555555|26
Call ended|5555555555|45
Form exited||77

Please note: this function is not yet supported on iOS or in web forms. It will only work on Android. Additionally, when using Android versions 9 and higher, the phone number will only be stored if Collect is the default phone app when the call is made. The ability to set Collect as the default phone app is only available in Collect versions 2.70.4 and later.

phone-call-duration()

Returns the total number of seconds spent on a phone call during the form. This is calculated in the exact same way as the duration() function, so you can use both of these functions together to find out things like what percentage of the form was spent on a phone call.

Example

if(phone-call-duration() div duration()>0.5, 'yes', 'no')
will return 'yes' if there was an active phone call during more than half of the time spent filling out the form.

Please note: this function will only work on Android. It is not yet supported on iOS or in web forms.

collect-is-phone-app()

Returns true or false depending on whether or not Collect is currently set as the default phone app. Since some call features are either limited or unavailable when Collect is not the default phone app, this can be useful for ensuring all call features work properly. This function updates its value whenever the device's default phone app changes.

Example

collect-is-phone-app()
will return true if Collect is the default phone app.

Please note: this function will only work on Android. It is not yet supported on iOS or in web forms.

Other functions

relevant(field)

Checks to see whether or not a field is currently relevant. Returns true if the field is relevant. Returns false if the field has a relevance expression that currently evaluates to false.

Example

relevant(${followup_question})
will check to see if the followup_question field is currently relevant.

empty(field)

Checks to see whether or not a field is currently empty (has no value). Returns true if the field is currently empty (which might be because it's not relevant; see relevant() above). Returns false if the field has a non-blank value.

Example

empty(${consent})
will check to see if the consent field is currently empty.

if(expression, valueiftrue, valueiffalse)

Returns one of two values, depending on whether an expression is true.

Example

if(selected(${country}, 'South Africa') or selected(${country}, 'Zimbabwe'), 'SADC', 'Non-SADC')
will check to see if the selected country is either South Africa or Zimbabwe. If yes, it will return SADC. If neither of those countries were selected, it will return Non-SADC.

pulldata(source, colname, lookupcolname, lookupval)

Pulls data from an attached dataset or .csv file.

Example

pulldata('hhplotdata', 'plot1size', 'hhid_key', ${hhid})
will pull a value either from an attached .csv file named hhplotdata.csv or from an attached dataset with the unique ID hhplotdata. The value will come from the plot1size column of the pre-loaded data, and the hhid field will be used to identify the matching row in the pre-loaded data's hhid_key column.

See Pre-loading data into a form for more information, or Pre-loading: Referencing pre-loaded .csv data for a working example.

once()

For use in expressions in calculate or calculate_here fields only, indicates that the enclosed expression should be calculated only once per form. If a calculated expression is not enclosed in once(), it will recalculate periodically, including each time that the form is edited and saved. In the case of random(), this would draw a new random number every time the form is edited and saved – which is not generally what you want.

Example

once(format-date-time(now(), '%Y-%b-%e %H:%M:%S'))
Use this expression in a calculate_here field to save the date and time at which the field was first reached. Enclosing the format-date-time(now(), '%Y-%b-%e %H:%M:%S') function within once() will ensure that the date-time is only recorded the first time the user reaches that field, even if they go back and revisit the field later.

Please note: only use once() on the very outside of an expression. For example: once(random()*2) is okay, but 2*once(random()) is not. To avoid potential problems, use once(...) alone in one calculate or calculate_here field, then use that field in more complex expressions elsewhere.

once(random())

Returns a random number between 0 (inclusive) and 1 (exclusive). See the sample form in Randomization: Randomizing form elements.

Example

To use random numbers in your form, create a calculate field with the expression once(random()), then refer to that field's value in other expressions in your form.

Warnings

• Never nest once(random()) directly inside another function or expression, even in constraint or calculate expressions.
• You should always call random() inside the once() function.
• Never use random() directly in a relevance expression, because you don't want to generate a new random number every time the relevance is calculated: you want just one stable random number for each filled-out form.

coalesce(field1, field2, ...)

Returns field1 if it isn't empty, otherwise returns field2, and so on. Can be used with any number of non-repeated arguments.

Example

coalesce(${id}, ${id2})

regex(field, expression)

Returns true or false depending on whether the field matches the regular expression specified. Because regular expressions can be arbitrarily complex, this function allows for construction of very advanced expressions. You may use regex() in relevance expressions, constraint expressions, choice filtering, and any other places that accept expressions. SurveyCTO uses a Java engine for evaluating expressions, but for most expressions you can use a Javascript tool like RegExr to develop and test your expressions.

Example

regex(., '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}')
will check for a valid-looking email address.

hash(fieldorvalue, ...)

Returns a hash value that represents the one or more parameters passed.

Example

hash(${name}, ${birthday})
will return a hash of the name and birthday fields, which can then be stored and used to verify a match later on, without storing any PII (personally identifiable information).

See this page for more details on hash values and their potential uses.

uuid()

Calculates a unique random ID.

Example

once(uuid())

username()

Returns the currently-configured username of the user filling in the form.

version()

Returns the version number of the current form.

device-info()

Returns information about the device that is being used to fill out the form. The format will vary slightly depending on which platform is being used.

Android	[BRAND]|[MODEL]|[ANDROID_API_VERSION_NUMBER]|SurveyCTO Collect [VERSION] ([BUILD_ID])
iOS	Apple|[DEVICE NAME]|[iOS_VERSION_NUMBER]|SurveyCTO Collect [VERSION] ([BUILD_ID])
Web forms	[browser user-agent]|SurveyCTO web forms [SERVER_VERSION]

Examples

Android:
google|Pixel 3|10|SurveyCTO Collect 2.70.1 (26c7d74)
iOS:
Apple|My iPhone|13.1.2|SurveyCTO Collect 2.70.1 (52.18)
Web Forms:
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.83 Safari/537.36|SurveyCTO web forms 2.70.2

plug-in-metadata(field)

For the field specified, returns the metadata saved by a field plug-in (or an empty string if there is none).

Example

plug-in-metadata(${counter})
will return the plug-in metadata saved in the counter field, if any.

Example

item-at(' ', plug-in-metadata(${counter}), 0)
will return the first item in a space-separated list of items in the plug-in metadata saved in the counter field, if any. See further above for more about item-at().

See this page for more about field plug-ins.

Previous Next