> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing Rules

> Write survey routing rules in the simple and advanced editors: triggers, conditions and operators, call facts, every action from jumps and show/hide to option and battery-item masking, Set variable and early endings, plus priority and the validation messages.

## What is a routing rule?

A routing rule says: **when** something is true, **then** do something. For example:

* When `Q2` *Is* `no` → **Jump to question** `Q5`.
* When `Q1` *Is one of* `under_18` → **Screen out** with outcome `under_18`.
* When `Q4` *Is answered* → **Set variable** `first_pref` to *The answer to this question*.

Rules are written on the [Logic tab](/surveys/logic). Open the rule editor by clicking **Add rule**, **Rule from here** on a selected question, dragging from a question's blue dot on the canvas, or clicking an existing rule. On the [Questions tab](/surveys/questions-tab), each question's **Routing** card lists its rules with **Edit in Logic**.

There are two editors: a **simple editor** for one condition and one action, and an **advanced rule builder** for everything else. **Advanced rule →** switches from the simple editor to the builder.

Conditions always compare against an option's **key**, never the words the respondent said — so `Q2` *Is* `no` matches whatever wording the respondent used, as long as it was recorded as the `no` option.

***

## The simple editor

Heading: **New routing rule**.

### When

Pick a **Question**, an operator and a value.

| Operator                              | Meaning                                           |
| ------------------------------------- | ------------------------------------------------- |
| **Is** / **Is not**                   | The answer is, or is not, one option.             |
| **Is one of** / **Is not one of**     | The answer is, or is not, any of several options. |
| **Is answered** / **Is not answered** | The question has, or has not, been answered.      |

For Single choice and Rating questions, pick the value from the question's options, shown as *key · label*. For other types, type it: *Value to compare against*, or *Values to match, comma separated*.

### Then

| Action                  | What it does                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Jump to question**    | Skip ahead to a later question.                                                                                        |
| **Show question**       | Ask a question that would otherwise be hidden.                                                                         |
| **Hide question**       | Skip a question.                                                                                                       |
| **Set variable**        | Store *The answer to this question* or *A fixed piece of text* in a survey variable.                                   |
| **Complete survey**     | End the interview as complete, with an **Outcome code**.                                                               |
| **Screen out**          | End the interview because the respondent is outside the target group, with an **Outcome code** and **Outcome reason**. |
| **Terminate interview** | End the interview for any other reason, with an **Outcome code** and **Outcome reason**.                               |

The **Outcome code** field (placeholder *Outcome code, e.g. screened\_out*) suggests the codes listed in [Closing](/surveys/closing-and-outcomes). Every code you use must be listed there.

Click **Add rule** (or **Save rule** when editing). The confirmations are *Routing rule added*, *Routing rule saved* and *Routing rule deleted*.

### Messages you may see

* *"Add an answerable question on the Questions tab before creating a routing rule."*
* *"There is no later question to jump to. Choose an outcome instead, or pick an earlier source question."*
* *"There is no other question to show or hide."*
* *"This survey has no variables yet. Add one under Variables, then point a rule at it."*
* *"This rule came in with the import. Saving replaces its condition and actions with what you set here; the preserved source expression is dropped."*

***

## The advanced rule builder

Heading: **New routing rule**, or **Edit (key)** for an existing rule.

### Trigger

When the rule is checked:

| Trigger                         | When it runs                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **At the start of the call**    | Before the first question. It can only read call facts, because nothing has been asked yet — use it to gate the very first question. |
| **Before a question is asked**  | Once the **Anchor question** has finished — on voice calls, the same point as **After a question**.                                  |
| **After a question**            | After the **Anchor question** has finished.                                                                                          |
| **When an answer is submitted** | As soon as the **Anchor question**'s answer is recorded.                                                                             |

### When

Choose **Match all (AND)** or **Match any (OR)**, then **+ Add condition**. With no conditions, *"No conditions — the rule fires every time its trigger is reached."*

Each condition has a subject, an operator and a value, plus a **NOT** switch that inverts it.

**Subject** — any answerable question, or a fact about the call:

| Call fact                  | True when                                     |
| -------------------------- | --------------------------------------------- |
| **The number is a mobile** | The contact's number is an Australian mobile. |
| **The call is inbound**    | The respondent called in.                     |
| **The call is a test**     | The call is a test call.                      |

A call fact is compared with **is true** or **is false**.

**Operator** — for questions:

| Operator                                                               | Use with                                                                    |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **is**, **is not**                                                     | One value or option.                                                        |
| **is one of**, **is none of**                                          | Several options, picked as chips, or several values — *One value per line*. |
| **is greater than**, **is at least**, **is less than**, **is at most** | Number answers.                                                             |
| **is answered**, **is not answered**                                   | Any question.                                                               |
| **is selected**                                                        | An option.                                                                  |

### Then

Click **+ Add action**. A rule needs at least one (*"A rule needs at least one action."*), and can have several — for example, set a variable and jump.

| Action                   | What it does                                                                                                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Jump to question**     | Skip ahead to a later question. Jumps only go forwards: *"Jump rules must target a later question."*                  |
| **Show question**        | Ask a question that would otherwise be hidden.                                                                        |
| **Hide question**        | Skip a question.                                                                                                      |
| **Include option**       | Offer only certain options on a later Single choice or Rating question.                                               |
| **Exclude option**       | Remove an option from a later Single choice or Rating question.                                                       |
| **Exclude battery item** | Remove an item from a later [battery](/surveys/question-types/battery). The item is recorded as `NA` and never asked. |
| **Set variable**         | Store the answer, or a fixed piece of text, in a [survey variable](/surveys/survey-variables).                        |
| **Complete survey**      | End the interview with an outcome code.                                                                               |
| **Screen out**           | End the interview with an outcome code and a *Reason, in plain words*.                                                |
| **Terminate interview**  | End the interview with an outcome code and a *Reason, in plain words*.                                                |

Imported surveys can also contain **Redirect** actions, which cannot be authored.

### Masking options and items

**Include option**, **Exclude option** and **Exclude battery item** target either a named option or item, or **The answer to the question this rule reads**. The second form is how you drop whatever the respondent already chose. For example, to ask for a second preference without offering the first:

* Trigger **When an answer is submitted**, anchor `Q7` (first preference).
* Action **Exclude option** on `Q8` (second preference), target *The answer to the question this rule reads*.

The mask is applied when the later question starts.

### Priority

**Priority** is a number from 0 to 10,000. Rules on the same trigger run in priority order, lowest first; rules with the same priority run in the order they were written. When two rules set the same variable, the one that runs later wins — and a rule whose condition is false clears the variable rather than leaving it alone (see [Survey variables and piping](/surveys/survey-variables#setting-a-variable)).

***

## How rules behave on a call

* **Show and hide.** A hidden question is skipped unless a show rule fires for it.
* **Order.** Without a rule, questions are asked in outline order: section by section, question by question.
* **Endings.** When **Complete survey**, **Screen out** or **Terminate interview** fires, the respondent hears the closing text for that outcome code, then the farewell. A screen-out on an option chosen from a mishearing is confirmed with the respondent before it takes effect.
* **Skipped questions.** A question skipped by a rule is not recorded as answered. If a later prompt pipes its answer, Readiness warns that it can speak as empty (see [Survey variables and piping](/surveys/survey-variables)).
* **Display questions** take no answer, so no rule can fire after them.

***

## Validation messages

The builder and the save check for these:

* *"An AND group needs at least one condition."* (or *"An OR group …"*)
* *"A NOT group wraps exactly one condition."*
* *"“(fact)” is true or false, so it can only be compared with is / is not."*
* *"A comparison needs the question it reads."*
* *"Choose at least one value to match."*
* *"A comparison value is required."*
* *"An outcome code is required."*
* *"A human-readable reason is required."*
* *"Choose the question or section this action targets."*
* *"Choose the question and the option to mask."*
* *"Choose the battery and the item to mask."*
* *"Choose the variable to set."*
* *"Choose what the rule writes into the variable."*
* *"Write the text the rule stores in the variable."*
* *"The condition reads (key), which is not in this version."*

[Readiness](/surveys/readiness) also blocks a rule that reads a question or option the survey does not have, or ends with an outcome not listed in Closing.

***

## Deleting things rules depend on

A question, option or variable that a rule uses cannot be deleted until the rule is changed. The messages name the rule, for example:

* *"This question is used by the rule “(key)” (trigger). Delete or edit that rule first."*
* *"(options) is still read by (rules). Change or delete that rule before removing the option."*
* *"(rules) still sets this variable. Change or delete that rule first."*

Renaming a question key updates the rules that reference it; the inspector warns *"(n) rule(s) reference this key ((keys)). Renaming updates them too."*