Set Value Rules

CONTENTS

What is a set value rule?

Set value rules auto-populate a specific value for a task response if certain conditions are met. These can be numeric values or text values based on the task type. For example, a count task must be given a numeric set value response and a short answer task must be given a text response.

Set value rules can include:

a static text value that will be submitted as a task response
a static numeric value that will be submitted as a task response
a dynamic text value that concatenates values from multiple task responses
a dynamic numeric value that calculates values from multiple task responses
a defined text or numeric value for a variable

Additionally, advanced logic rules can be written to set and clear task responses, meaning that if a specific condition is not met, the provided task response value will be cleared and set to a specified value when the mission response is submitted.

How to write a set value rule

In the advanced logic text editor, rules will be grouped under the set value category if they leverage SET VALUE in their action statement.

To write a set value rule:

Navigate to the mission builder logic tab:
Review the mission structure in the structure panel and use applicable abbreviations to reference a task or section within a rule. In this example, Task 1 (T1) and Task 2 (T2) ask for a count. Task 3 (T3) asks for a total count. A set value rule can be used to automatically populate the total count as a response for Task 3 (T3), summing the values of Task 1 (T1) and Task 2 (T2).

Rules must contain a condition, action, and event. The example rule is defined as follows:

Condition	Action	Event
IF ALWAYS	THEN SET VALUE T3 TO T1 + T2	ON RESPONSE

Translation: Always set the value of Task 3 (T3) to the sum of responses to Task 1 (T1) and Task 2 (T2) as the responses to T1 and T2 are submitted.

For more information on advanced logic rule syntax, click here.

How to write a set and clear rule

A set and clear rule can provide a set value for a task and clear out that value if the original condition is no longer met (e.g., if a user changes the answer that triggered a set value, the set value will be cleared). Set and clear can also be used to overwrite or change a selected answer to a different value.

The set value and set and clear actions have very similar syntax:

SET VALUE {target} TO {expression}
SET AND CLEAR {target} TO {expression}`

Both actions will set a task response or variable (the {target} of the action) to the value of the {expression} when the rule's {condition} is true. Both actions behave identically when their rule's {condition} is true. Their behavior differs when the {condition} is false. A set value action does nothing when the rule condition is false, while a set and clear action will clear the target value if the condition is false.

Think of set and clear as a shortcut that allows you to write fewer logic rules by hand. Every set and clear rule could be implemented as two set value rules.

IF {condition} THEN SET AND CLEAR {target} TO {expression} ON {event}

can be implemented as these two `SET VALUE` rules:

IF {condition} THEN SET VALUE {target} TO {expression} ON {event}
IF NOT {condition} THEN SET VALUE {target} TO NULL ON {event}

For more information on advanced logic rule syntax, click here.

Set value use cases

Use Case	Example Rule Syntax	Mobile User Experience
Set a string value as a task response	IF ALWAYS THEN SET VALUE T1 TO ‘Example Answer’ ON RESPONSE	User will have ‘Example Answer’ auto-populate as the response to Task 1.
Perform arithmetic to set a response value for a task	IF ALWAYS THEN SET VALUE T3 TO T1 + T2 ON RESPONSE	User will have the sum of their responses given to Tasks 1 and 2 automatically populate as the response value to Task 3.
Set value for a variable used in a calculation rule	IF ALWAYS THEN SET VALUE ‘example_variable’ to ‘Example Value’ ON START	User will see ‘Example Value’ wherever the variable has been piped into the Mission.
Set and clear a given answer to a different string value	IF T1.A1 THEN SET AND CLEAR T2 to ‘Example Value’ ON RESPONSE	If a user answers Task 1 with answer option 1, Task 2 will auto-populate with ‘Example Value’, overwriting any other answer given.

Set value constraints

Set value and set and clear actions follow the same constraints as user input.

When logic rules set the value of a task response, through a set value or set and clear action, the value of the {expression} must adhere to the same constraints as manually entered values.

Example: If T2 is a MultipleChoice task asking who is your favorite Beatle, the answer must be one of John, Paul, George, or Ringo. An answer of Susan makes no sense for T2, so an action of SET VALUE T2 TO 'Susan' can't be allowed.

Why doesn't the mission builder report invalid SET actions immediately?

The {expression} component of a set value or set and clear action is dynamic. It can be influenced by values that aren't known at build time, including other task response values or user or place properties. The previous example of 'Susan is not a Beatle' could definitely be detected at build time, but since many of the possible values can only be resolved as mission responses are collected in the field, the advanced logic still needs to deal with invalid values.

General rule: Allow valid values to be set, anything invalid resets to NULL

The general rule of thumb is: If the {expression} yields a value that is not allowed, the set value or set and clear action will set the target value to NULL. This NULL value is equivalent to the task having no response at all, so it is a condition that is already being handled.

Task-specific constraints

Each task type has its own set of configurable constraints, which are enforced so that task response values set by logic will not create non-sensical mission response values.

MultipleChoice constraints

The {expression} value is matched against the configured list of answers. Matching is case-insensitive.

When the {expression} matches one of the configured answers, the task response value will be the matching answer.

When the {expression} does not match any of the configured answers, the task response value will be NULL.

If T1 is MultipleChoice of "Red", "Green", or "Blue", then:

The `SET VALUE T1 TO 'red'` action will set T1 to 'Red' (note the case-insensitive match)
The `SET VALUE T1 TO 'yellow'` action will set T1 to NULL because yellow is not one of the 3 answers.

MultipleSelect constraints

MultipleSelect constraints support the same constraints as MultipleChoice, with the addition of being able to select more than one of the configured answers.

The {expression} value is matched against the configured list of answers. Matching is case-insensitive.

When the {expression} matches exactly one of the configured answers, the task response value will be the matching answer.

When the {expression} does not match any of the configured answers, the task response value will be NULL.

When the {expression} is a JSON array of quoted strings.

If T2 is MultipleSelect of "John", "Paul", "George", or "Ringo", then: -

The SET VALUE T2 TO 'ringo' action will set T2 to only 'Ringo' (note the case-insensitive match)
The SET VALUE T2 TO 'Susan' action will set T2 to NULL because Susan is not one of the Beatles.
The SET VALUE T2 TO ["John","Susan","Paul"] action will set T2 to both John and Paul, and will ignore Susan since she is not one of the Beatles.

YesNo constraints

YesNo task responses use NULL for no response, 0 for a No response, and 1 for a Yes response.

If the {expression} value is NULL, the YesNo task response will be NULL.

If the {expression} value is a text expression, the YesNo task response value will be 0.

If the {expression} value is numeric, and the value is exactly 0, the YesNo task response value will be 0. All other numeric values will set the YesNo task response value to 1.

Date constraints

A Date task can be set to the value of another Date task, or can be set to date string that follows the 'YYYY-MM-DD' format (only the ISO 8601 date format is supported).

Any other invalid date string value will reset the task response to NULL.

See the [date() function] section below for supported date manipulation expressions.

Count constraints

When a Count task is configured with a minimum or maximum value, any {expression} value outside the range will reset the task response to NULL.

{expression} value will be rounded to the appropriate precision if the Count task is configured with a decimal place limit.

Scale constraints

An {expression} value outside the configured left (minimum) or right (maximum) value will reset the task response to NULL.

{expression} values are truncated into integer values. A text expression will have the value 0.

If T2 is a Scale task then SET VALUE T2 TO 9.9 will set the value of the T2 to 9, not 10.

Price and Temperature constraints

Neither Price nor Temperature tasks have any constraints applied to set value or set and clear actions.

Variable constraints

Neither Text nor Numeric variables have any constraints applied to set value or set and clear actions.

SearchableList, Picture, Signature, Display Text, Display Table constraints

These five task types are not allowed as the {target} of a set value or set and clear action.

Date manipulation expressions

The built-in date() function can be used to manipulate dates in a flexible manner.

The basic syntax is: date({timeValue}, {modifier}, {modifier}, ...)

{timeValue} is either a Date task reference, a 'YYYY-MM-DD' date string, or the special 'now' string. Zero or more {modifier} strings can be supplied, and will be applied in left-to-right order.

{NNN} days adds the number of days to the previous value
{NNN} months adds the number of months to the previous value
{NNN} years adds the number of years to the previous value -
start of month moves to the first day of the previous value's month
start of year moves to the first day of the previous value's year
weekday {N} advances the date forward until the weekday is N. Sunday is 0, Monday is 1, ..., Saturday is 6. If the date is already on the desired weekday, the date is unchanged.
localtime adjusts to the local timezone

Examples:

date('now') - Gets today's date in UTC
date('now', 'localtime') - Gets today's date in the mobile device's local timezone
date(T4, 'start of month', 'weekday 3', '+14 days') - If T4 is a Date task, the result is the 3rd Wednesday of the month selected by T4

Have more questions? Submit a request