Flow Control

[mojtaba]

In Avicenna, a survey consists of one or more sections that are presented to participants in a predefined sequence. By default, sections are displayed consecutively until the final section is completed, at which point the survey session ends.
Avicenna provides multiple ways to modify the flow of surveys based on participants’ responses, including:

• Showing or skipping a section or question, which can be done via:
  • Criteria
  • Enable Questions option
  • Section and question properties
• Looping through a section
• Section and question randomization

Criteria is the most versatile approach, which lets you display or skip questions or sections based on participants’ responses to earlier questions, either within the current survey or in previous surveys in the study. Although powerful, this method can be complicated and challenging to manage.
Avicenna also provides simpler options for basic showing and skipping patterns, allowing you to show or skip specific questions or alter the survey flow. If you find these options easier than using criteria, you are encouraged to use them instead.

Below, we explain each of these approaches in more detail.

Using Criteria to Control Survey Flow

Criteria enables you to set conditions that decide whether a survey section or question should be displayed or skipped. When a section or question with criteria is reached, Avicenna evaluates the condition using the participant’s responses collected up to that point. Then, the condition is assessed as either True or False.

• If the condition evaluates to True, the section or question is displayed.
• If the condition evaluates to False, the section or question is skipped, and Avicenna continues to the next section or question in the survey.

[!note]
If the section or the question with the criteria is the last, and the criteria evaluates to False, Avicenna will finish the survey.

This section demonstrates how to use criteria to control the visibility of sections and questions in a survey.

[!example] Example 1: Showing a Section Using Criteria
Survey Structure:

Section ID: 1
   (QID-1 - Multiple Answer): Have you been told by a doctor that you have any of the following?
       A ID: 1: Depression
       A ID: 2: Generalized anxiety disorder
       A ID: 3: Social phobia
       A ID: 4: Agoraphobia
       A ID: 5: Post-traumatic stress disorder
       A ID: 6: Panic disorder
       A ID: 7: Obsessive-compulsive disorder

Section ID: 2 (Questions related to the "Obsessive-compulsive disorder")

   (QID-2 - Information): The following statements refer to experiences that many people have in their everyday lives. Please CIRCLE the number that best describes HOW MUCH that experience has DISTRESSED or BOTHERED YOU DURING THE PAST MONTH:

   (QID-3 - Single Answer): Unpleasant thoughts come into my mind against my will, and I cannot get rid of them.
       A ID: 1: Not at all
       A ID: 2: A little
       A ID: 3: Moderately
       A ID: 4: A lot

   (QID-4 - Single Answer): I think contact with bodily secretions (sweat, saliva, blood, urine, etc.) may contaminate my clothes or somehow harm me.
       A ID: 1: Not at all
       A ID: 2: A little
       A ID: 3: Moderately
       A ID: 4: A lot

Goal:
Show Section 2 only to participants who select Answer ID 7 (Obsessive-compulsive disorder) in Question 1.

Configuration:

1. Select Section 2 in the Survey Editor.
2. Open Section Properties from the right-side panel.
3. In the Criteria field, enter:
   Q17139_1 == 7

Where:

• 17139 is the Survey ID

• 1 refers to Question 1

• 7 refers to Answer ID 7

  

Result:
Section 2 is shown only to participants who select Answer ID 7 in Question 1. All other participants skip this section.

[!example] Example 2: Showing a Question Using Criteria
Survey Structure:

(QID-1 - Single Answer): Have you ever used a set of questionnaires to check your child's motor skills?
   A ID: 1: Yes
   A ID: 2: No

(QID-2 - Multiple Answer): Which of the following questionnaires have you used to check your child's motor skills??
   A ID: 1: The Early Motor Questionnaire (EMQ)
   A ID: 2: ASQ - Ages and Stages
   A ID: 3: The Child Evaluation Checklist

Goal:
Show Question 2 only to participants who select Yes in Question 1.

Configuration:

1. Select Question 2 in the Survey Editor.
2. Open Question Properties from the right-side panel.
3. In the Criteria field, enter:
   Q17855_1 == 1

Where:

• 17855 is the Survey ID

• The first 1 refers to Question 1

• The second 1 refers to Answer ID 1

  

Result:
Question 2 is shown only to participants who select Yes in Question 1. Participants who select No will skip Question 2.

Using the Enable Questions Option to Control Survey Flow

Avicenna allows you to show or hide questions within a section based on a participant’s response to another question. Each potential answer for a single answer or multiple answer question includes an Enable Questions property, which accepts a list of question IDs. When a participant selects that answer, the specified questions are enabled.

[!note]
All questions that are shown or skipped using the Enable Questions option must be in the same section as the single or multiple answer question that contains the triggering answer.

[!example] Example: Showing a Question Using the Enable Questions Option
Survey Structure:

(QID-1 - Single Answer): Did you experience coughing or wheezing last week?
   A ID: 1: Yes
   A ID: 2: No

(QID-2 - Single Answer): Do you believe that it is likely that these symptoms were related to poor air quality?
   A ID: 1: Yes
   A ID: 2: No

Goal:
Show Question 2 only to participants who select Answer ID 1 (Yes) in Question 1.

Configuration:

1. Select Question 2 in the Survey Editor.

2. Open Question Properties from the right-side panel.

3. Scroll down and turn Enabled → Off.

   This ensures Question 2 is skipped by default.

   

4. Go back to Question 1.

5. Open Question Properties → Answer.

6. Go to the Answer ID 1 section.

7. In Enable Questions, select Question 2.

   

Result:
Question 2 is shown only to participants who answer Yes to Question 1. All other participants skip Question 2 automatically.

Using the Section and Question Properties to Control Survey Flow

Each section specifies what section should be shown next or whether the survey should be marked as completed after the section is done. By default, each section points to the next section in order, or finishes the survey if it is the last section. You can change this flow using the Next Section ID property of each section’s settings.

[!example] Example: Skipping a Section Using the Next Section ID Property
Survey Structure:

Section ID: 1

   (QID-1 - Single Answer): Do you receive treatment for heart disease (For example, angina, heart failure, or heart attack)?
       A ID: 1: Yes
       A ID: 2: No

   (QID-2 - Single Answer): Does your heart disease limit your activities?
       A ID: 1: Yes
       A ID: 2: No

Section ID: 2

   (QID-3 - Single Answer): Do you receive treatment for high blood pressure?
       A ID: 1: Yes
       A ID: 2: No

Section ID: 3

   (QID-4 - Single Answer): Do you have regular physical activity?
       A ID: 1: Yes
       A ID: 2: No

Default Behavior:
Participants see Section 1 → Section 2 → Section 3 in order.

Goal:
After Section 1, go directly to Section 3 and skip Section 2.

Configuration (Using Section Properties):

1. Select Section 1 in the Survey Editor (the selected section is highlighted with a blue border).

2. Open Properties from the right-side panel.

3. In Next Section ID, select 3.

   

Result:
After completing Section 1, Avicenna takes participants directly to Section 3, and Section 2 is skipped.

Overriding the Flow Using Question Properties
You can also change the next section based on how a participant answers a question.

Goal:
Show Section 2 only if the participant reports NOT having heart disease in Question 1.

Configuration (Using Question Properties):

1. Select Question 1 in Section 1.

2. Open Properties → Answer.

3. Go to the Answer ID 1 section.

4. Set Next Section ID = 3.

   

Result:

• If the participant selects Yes in Question 1 → Avicenna skips Section 2, and goes to Section 3.
• If the participant selects No → the normal flow continues, and Section 2 is shown.

[!note]
Even when the next section is changed at the answer level, all remaining questions in the current section are still shown. In this example, participants will always see Question 2 in Section 1, regardless of their answer to Question 1.

[!caution]
Any answer option in a single or multiple answer question can specify the next section that should be shown after the current section. However, in a multiple answer question, if different answers specify different next section IDs, the last answer selected by the participant will override the previous values.
This results in nondeterministic behavior and is not recommended. If answers in a multiple answer question are expected to change the index of the next section, you need to make sure that they all point to the same section.

Looping Through a Section

You can configure a section as a Loop Section, which allows Avicenna to repeat that section multiple times based on a participant’s response to a Source Question. Specifically, Avicenna will iterate through the loop section X times, where X is determined by the response to the source question.

[!example]
Survey Structure:

Section ID: 1

   (QID-1 - Single Answer): Have you eaten any processed food since last week?
       A ID: 1: Yes
     A ID: 2: No

   (QID-2 - Number): How many processed foods have you consumed?

Section ID: 2

   (QID-3 - Text): What is the name of the food?
   (QID-4 - Image): Take a picture of the food.

Goal:
Ask participants to report details of each processed food they have consumed.

Configuration:

1. Select section 2.

2. In the Properties panel, enable Loop Through this Section.

3. Set Question ID 2 as the Source Question ID.

   

Result:
Avicenna will repeat the questions in section 2 as many times as the number of processed foods reported by the participant for the past week.

Supported Source Question Types

The source question can be one of the following:

• A Number question:
  The loop section will be looped X times, where X is the response to the Number question.
• A Multiple Answer question:
  The loop section will be looped once for each chosen option.

[!info]
If the reply to the number source question is 0, or no option is chosen in a multiple answer source question, the loop section will be skipped.

Questions inside a loop section also support specific placeholder: {{loop_value}}. This placeholder allows you to refer to the option being asked inside the loop section.

• For number source questions, {{loop_value}} will be replaced by an ordinal iteration number, i.e., 1st, 2nd, 3rd, 4th, and so on.
• For multiple answer source questions, {{loop_value}} will be replaced by the content of the selected answer.

[!example]
Let’s continue our example above. To use the Loop Value placeholder:

1. Select the question you want to edit.
2. Click on Edit to open the content box.
3. While writing the question text, click Add Placeholder and choose Loop Value.

Your questions should look like this:

Section ID: 2
   Q ID: 3: Text: What is the name of the {{loop_value}} food?
   Q ID: 4: Image: Take a picture of the {{loop_value}} food.

Result:
Assume the participant reports 2 processed foods in Question 2.
Avicenna will loop Section 2 twice, and the questions will look like this:

Section ID: 1

   Q ID: 2: Number: How many processed foods have you consumed?
      Answer: 2

Section ID: 2 - Iteration 1:

   Q ID: 3: Text: What is the name of the 1st food?
   Q ID: 4: Image: Take a picture of the 1st food.

Section ID: 2 - Iteration 2:

   Q ID: 3: Text: What is the name of the 2nd food?
   Q ID: 4: Image: Take a picture of the 2nd food.

Question Randomization

We have previously discussed Section Randomization. In addition to that, you can randomize the selection of questions within each section using Question Randomization. To randomly select a subset of questions within your section, you need to use the Included Question ID(s) and Selection Count options.

[!example]Example: Randomly Showing One Question from a Group
Assume your survey section contains seven questions with IDs from 1 to 7:
Goal:
Questions 1, 2, 3, and 4 should always be shown. From questions 5, 6, and 7, only one question should be randomly included in the section.

Configuration:

1. Open Section Properties
2. Go to Question Randomization.
3. Select questions 5, 6, and 7 under Included Question ID(s).
4. Set the Selection Count to 1.

Result:
The section will always include questions 1–4, plus one randomly selected question from questions 5, 6, and 7.

Random Question Order

You can also enable the Random Question Order option to randomize the order in which these questions are displayed.

[!note]
These randomizations are applied only once per survey session.