Writing Advanced Logic Rules
CONTENTS
What are advanced logic rules?
How to use the advanced logic text editor
Deleting tasks referenced in rules
Examples of advanced logic rules
What are advanced logic rules?
Advanced logic rules allow mission builders to customize Missions, making their structure more flexible and dynamic. Companies with advanced logic have access to a Logic tab in the mission builder. This tab contains a text editor where advanced logic rules are written.
Logic tab and text editor
Advanced logic rules perform a wide array of actions that make Missions more dynamic.
The supported rules fall into three categories: dynamic tasks, set value, and calculations.
| Rule Type | Behavior |
| Dynamic Tasks | Show or hide tasks, sections, or answer options based on specified conditions |
| Set Value | Automatically insert a specified task response value if certain conditions are met |
| Calculations | Combine numeric or text values to solve for a variable or to set an aggregated task response value |
How to use the advanced logic text editor
If your company has advanced logic enabled, a Logic tab will appear in the mission builder. To begin writing advanced logic rules, simply click on the word Logic to the right of the Build tab.
Supported abbreviations
Before writing a rule, familiarize yourself with the expected abbreviations for tasks, sections, and answer options. In the advanced logic editor, sections are referenced with the letter S, tasks with the letter T, and answer options with the letter A.
| Object | Abbreviation | Order | Example | Meaning |
| Section | S | Alphabetical (A-Z) | SA | The first section of a mission |
| Task | T | Numeric (1-100) | T1 | The first task within a section |
| Multiple Choice or Multiple Select answer option | A | Numeric (1-100) | A1 | The first answer option on a specified task |
Reference the structure panel to determine the expected naming convention for a section, task, or answer option:
- In the pictured Mission, the first section named Displays is considered SA. Sections are listed in alphabetical order and defined by the letter S.
- The first task within a section is considered T1. Tasks are listed in numeric order and defined by the letter T.
- The multiple-choice answer options listed for the task ‘What is on the display?” are considered A1, A2, and A3. Answer options are listed in numeric order and defined by the letter A.
If an advanced logic rule references a task, section, or answer option it must include this syntax to be considered valid. Note: Task identifiers can also be used to reference tasks in a rule. Read more about task identifiers here.
If a task exists within a section, include the section abbreviation followed by a period, and then include the task number. For example, SA.T1 references the first task (T1) in the first section (SA) of a Mission.
If a rule includes a specific task’s answer options, use the task abbreviation followed by a period and then include the answer option number. For example, T1.A1 would be the first answer option available on the Mission’s first task (T1). If this task exists within a section, include the section shorthand first: SA.T1.A1.
How to write a rule
To write a rule, begin typing on the advanced logic text editor. Rules will turn red if they are incomplete or contain errors.
For an advanced logic rule to be considered complete, it must include three components: conditions, actions, and events. Operators are also used to specify a condition’s expected behavior.
Conditions
A logic statement’s condition defines a scenario that will trigger a rule. A condition is provided with an IF, IF NOT, or IF ALWAYS statement at the beginning of a rule.
- IF indicates that if the specified condition is met, the rule will be triggered.
- IF NOT indicates that if the specified condition is not met, the rule will be triggered.
- IF ALWAYS indicates that the rule should always be triggered.
Actions
An action is a behavior that should occur if the stated condition is met. Actions can apply to a single task, range of tasks, single section, range of sections, answer options on multiple choice/multiple select tasks, or a range of answer options on multiple choice/multiple select tasks. Supported actions include:
- SHOW: Show tasks, sections, or multiple choice/multiple select answer options.
- HIDE: Hide tasks, sections, or multiple choice/multiple select answer options.
- SET VALUE: Define a task response value based on specific conditions being met.
- SET AND CLEAR: Define a specific task response value and if a condition is not met, clear out the given response.
Events
Events specify when the rule should be triggered. There are three supported event types:
- 'ON RESPONSE' specifies that the rule should be executed as task responses are being submitted on the mobile device. These rules update the Mission in real-time prior to a full mission response submission.
- 'ON MISSION' or 'ON START' specify that the rule will be enforced when the mission response is started. This means that the mission structure will not update in real-time based on specific task response submissions, rather, the rules will be evaluated and the mission structure will be determined as soon as the user begins a Mission.
- 'ON MISSION AND RESPONSE' specifies that the rule will be enforced as the mission begins and reevaluated as responses are submitted.
Operators
Operators signal how a section, task, or response should be evaluated and can combine multiple conditions within a single rule. Operators are essential in an advanced logic rule because they evaluate, compare, and calculate task response values.
Most operators fall into one of three categories: logical, comparison, and arithmetic.
Logical operators test for the truth of a condition. This condition must be met for an advanced logic rule to be enforced.
| Operator | Meaning | Example |
| AND | Multiple conditions must be met for the rule to be enforced | IF SA.T1.A1 AND SA.T2.A1 |
| BETWEEN | The operand must have a value within a specified range for the rule to be enforced | IF SA.T1 BETWEEN ‘1’ and ‘10’ |
| EXISTS | A specified criterion must be found for the rule will be enforced | IF SA.T1 EXISTS |
| IN | The operand must equal at least one value in a specified list for the rule to be enforced | IF SA.T1 IN ('Chips','Popcorn') |
| NOT | Reverses the value of any other operator (NOT EXISTS, NOT BETWEEN, NOT IN) | IF SA.T1 NOT BETWEEN ‘1’ and ‘10’ |
| LIKE | The operand must match a pattern specified within wildcard operators for the rule to be enforced. This match is case-insensitive. | IF SA.T1 LIKE 'CHIP%' |
| GLOB | The case-sensitive version of LIKE | IF SA.T1 GLOB 'CHIPS' |
| OR | At least one specified condition must be met for the rule to be enforced | If SA.T1.A1 OR SA.T2.A1 |
| IS NULL | A specified value must return NULL for the rule to be enforced | IF SA.T1 IS NULL |
Comparison operators compare multiple task response values to determine if a condition has been met and whether or not an advanced logic rule should be enforced.
| Operator | Meaning | Example |
| == | Equals | IF SA.T1 == SA.T2 |
| = | Equals | IF SA.T1 = SA.T2 |
| != | Not Equal To | IF SA.T1 != SA.T2 |
| <> | Not Equal To | IF SA.T1 <> SA.T2 |
| > | Greater Than | IF SA.T1 > SA.T2 |
| < | Less Than | IF SA.T1 < SA.T2 |
| >= | Greater Than or Equal To | IF SA.T1 >= SA.T2 |
| <= | Less Than or Equal To | IF SA.T1 <= SA.T2 |
| !< | Not Less Than | IF SA.T1 !< SA.T2 |
| !> | Not Greater Than | IF SA.T1 !> SA.T2 |
Arithmetic operators run mathematical expressions on task response values and are commonly used in action statements.
| Operator | Meaning | Example |
| + | Addition | SET VALUE SA.T3 TO SA.T1 + SA.T2 |
| - | Subtraction | SET VALUE SA.T3 TO SA.T1 - SA.T2 |
| * | Multiplication | SET VALUE SA.T3 TO SA.T1 * SA.T2 |
| / | Division | SET VALUE SA.T3 TO SA.T1 / SA.T2 |
| % | Modulus returns the integer remainder of a division | SET VALUE SA.T3 TO SA.T1 % SA.T2 |
For a full list of supported operators click here.
Comments
The advanced logic text editor supports the use of comments. Comments can explain a rule—providing context to others that have access to mission logic—or they can be used to prevent the execution of a rule.
To write a comment, begin a line with /* and end the comment with */. Comments will appear in gray text and can span multiple lines.
Any rule that appears gray has been commented out and will not run.
Error handling
If a rule is written with an error, the invalid components will be highlighted in red and a text popup will denote any errors. The total count of errors will be presented at the top of the Logic tab and at the top of the text editor.
An erroneous rule that does not use supported syntax abbreviations
Errors must be resolved before the Mission can be published.
Deleting tasks referenced in rules
The build tab denotes which tasks are referenced in logical expressions. Tasks that are used in rules can be deleted, but a popup will appear to confirm the decision.
Once the task is deleted, an error will appear on the logic tab indicating that a rule contains a deleted task.
This rule will need to be updated to remove errors or deleted to start the Mission.
Examples of advanced logic rules
Here are some basic examples of what mission builders can do with advanced logic by task type and rule type.
Examples by task type:
| Task Type | Use Cases & Example Rule |
| Multiple Choice Multiple Select |
|
| Yes/No |
|
|
|
| Short Answer |
|
|
|
| Date |
|
Examples by rule type
-
Dynamic Tasks: Hide Sections C and D when Task 1 (T1) in Section A (SA) is answered ‘Chips’
-
Set Value: Always set the task response value for Task 3 (T3) in Section B (SB) with the sum of responses given for SB Task 1 (SB.T1) and SB Task 2 (SB.T2)
-
Calculations: Always set the value for the numeric variable ‘total_chip_count’ to the sum of responses given for Section B Task 1 (SB.T1) and Section B Task 2 (SB.T2)
