diff --git a/content/applications/marketing/surveys/time_random.rst b/content/applications/marketing/surveys/time_random.rst index bca0ee4ee..226dfb371 100644 --- a/content/applications/marketing/surveys/time_random.rst +++ b/content/applications/marketing/surveys/time_random.rst @@ -1,48 +1,333 @@ -============================== -Timed and randomized questions -============================== +================ +Create questions +================ -When creating a survey in Odoo, there are options to set a time limit on the survey and randomize -the questions. +In Odoo *Surveys*, crafting and tailoring survey questions is crucial for :doc:`creating and +customizing surveys <../surveys/create>`. -Time limit -========== +Fortunately, Odoo provides numerous ways to configure tailored questions for any kind of survey. -During a timed survey, participants must finish the survey within a specified period of time. -A common use case for implementing a time limit is that it greatly reduces the chance of -participants looking up responses via external resources (e.g. web search), and reduces the survey -to a "closed book" testing environment. +To access a list of *all* the questions that have been created in the database, navigate to +:menuselection:`Surveys app --> Questions & Answers --> Questions`. There, users can view and modify +any question from any survey. -Find the :guilabel:`Survey Time Limit` setting in the :guilabel:`Options` tab of the survey form, -under the :guilabel:`Questions` section. +However, there is only one place in the Odoo *Surveys* application where survey questions can be +created. To do that, navigate to a survey form, by going to :menuselection:`Surveys app --> New`, or +by selecting any pre-existing survey from the :guilabel:`Surveys` page (:menuselection:`Surveys app +--> Surveys`). -.. image:: time_random/time-limit.png +Questions tab +============= + +On a survey form, users can view, access, add, and/or delete questions (and sections) in the +:guilabel:`Questions` tab. + +By default, two columns are present in the :guilabel:`Questions` tab: :guilabel:`Title` (i.e. the +question) and :guilabel:`Question Type`. + +If the :guilabel:`Randomized per Section` option is enabled in the :guilabel:`Options` tab of the +survey form, a column titled, :guilabel:`# Questions Randomly Picked` appears in the +:guilabel:`Questions` tab. + +To reveal the :guilabel:`Mandatory Answer` column on the :guilabel:`Questions` tab, which indicates +if questions require a mandatory answer or not, click the :guilabel:`(optional columns)` icon +located to the far-right of the column titles. + +.. image:: time_random/slider-dropdown-mandatory-answer.png :align: center - :alt: Time limit field in the options tab of a survey template form. + :alt: The slider drop-down menu showing the Mandatory Answer option in Odoo Surveys. -When the :guilabel:`Survey Time Limit` option is checked, a timer will be displayed on every page -of the survey, letting participants keep track of the time remaining while the survey is active. +Create sections +--------------- + +A *section* divides the survey into organized parts, in order to visually group similar questions +together. To make a section, click :guilabel:`Add a section` at the bottom of the +:guilabel:`Questions` tab, proceed to type in a desired name for the section, then either press +:kbd:`Enter` or click away. + +The section line appears in dark gray in the :guilabel:`Questions` tab. + +Then, drag-and-drop desired questions beneath a section, or drag-and-drop a section title on top of +(i.e. *before*) the desired question(s) in the survey, in order to populate the section with +specific questions that fit the theme of the section. + +If the :guilabel:`Randomized per Section` option is enabled in the :guilabel:`Options` tab of the +survey form, the number `1` appears, by default, on the section line, beneath the :guilabel:`# +Questions Randomly Picked` column. + +This indicates that `1` question from that section will be picked at random for each participant +taking the survey, bypassing every other, non-chosen question from that section. To change that +number, select that figure, and type in the desired number in its place. Then, either press +:kbd:`Enter`, or click away. + +Create questions +================ + +To create questions for the survey, click :guilabel:`Add a question` in the :guilabel:`Questions` +tab. + +Clicking :guilabel:`Add a question` opens the :guilabel:`Create Sections and Questions` pop-up +window, in which a survey question can be created. + +.. important:: + There **must** be a survey title entered in order for the :guilabel:`Create Sections and + Questions` pop-up window to appear. If no title is entered for the survey, an error pop-up + message appears in the upper-right corner, instructing the user to enter a survey title. + +When all desired configurations are complete click either :guilabel:`Save & Close` to save the +question and return to the survey form, or :guilabel:`Save & New` to save the question and create a +new one right away in a fresh :guilabel:`Create Sections and Questions` pop-up window. + +Click :guilabel:`Discard` to discard the question entirely. + +Create Sections and Questions pop-up window +------------------------------------------- + +.. image:: time_random/create-sections-questions-popup.png + :align: center + :alt: The Create Sections and Questions pop-up form in Odoo Surveys. + +In the :guilabel:`Create Sections and Questions` pop-up window, start by typing the question into +the :guilabel:`Question` field, located at the top of the pop-up window. + +Then, choose the desired :guilabel:`Question Type`. A preview of each :guilabel:`Question Type` is +to the right of the :guilabel:`Question Type` field, when a :guilabel:`Question Type` is selected. + +Choose from the following :guilabel:`Question Types`: + +- :guilabel:`Multiple choice: only one answer`: a multiple choice question, where only one answer is + permitted. +- :guilabel:`Multiple choice: multiple answers allowed`: a multiple choice question, where more than + answer is permitted. +- :guilabel:`Multiple Lines Text Box`: an open-ended question, where participants can type in a + multiple line response. +- :guilabel:`Single Line Text Box`: an open-ended question, where participants can type in a single + line response. +- :guilabel:`Numerical Value`: a number-based question, where participants must enter a number as a + response. +- :guilabel:`Date`: a date-based question, where participants must enter a date (year-month-day) as + a response. +- :guilabel:`Datetime`: a date-based question, where participants must enter a date *and* time + (year-month-day, hour-minute-second) as a response. +- :guilabel:`Matrix`: a multiple-choice, multiple question, in a table/chart layout, where + participants are presented with different questions on each row, and different answer options on + each column. .. note:: - Participants that do not submit their survey by the preconfigured time limit will *not* have - their answers saved. + Different features appear in the :guilabel:`Answers` and :guilabel:`Options` tabs, depending on + the chosen :guilabel:`Question Type`. -Randomized selection -==================== + However, the :guilabel:`Description` tab **always** remains the same, regardless of the question + type chosen. -When a survey is randomized, Odoo shuffles the questions and reveals them in a random order every -time a participant begins the questionnaire. Using randomization as a survey method discourages -participants from looking at each other's responses, and helps control for individual testing. +Once a :guilabel:`Question Type` has been selected, there are three possible tabs where information +can be customized for the question. These include the :guilabel:`Answers` tab (if applicable for the +chosen :guilabel:`Question Type`), the :guilabel:`Description` tab, and the :guilabel:`Options` tab. -To randomize a survey, click the :guilabel:`Options` tab on the survey form. In the -:guilabel:`Questions` section, select :guilabel:`Randomized per section` for the -:guilabel:`Selection` field. After enabling, navigate to the :guilabel:`Questions` tab and look in -the :guilabel:`Random questions count` column. From there, determine how many questions (per -section) Odoo should select and display during the shuffling of questions. +Each tab offers a variety of different features, depending on what :guilabel:`Question Type` was +chosen. -.. image:: time_random/random-questions.png +Answers tab +~~~~~~~~~~~ + +The :guilabel:`Answers` tab **only** appears if the selected :guilabel:`Question Type` provides +answer options to the participant. + +However, if a custom response is required to answer the selected :guilabel:`Question Type`, like a +:guilabel:`Multiple Lines Text Box`, for example. Or, if the answer to the :guilabel:`Question Type` +is a number, date, or datetime, the :guilabel:`Answers` tab disappears completely. + +If the :guilabel:`Single Line Text Box` is selected as the :guilabel:`Question Type`, the +:guilabel:`Answers` tab remains, although it only provides two checkbox options: :guilabel:`Input +must be an email` and :guilabel:`Save as user nickname`. + +.. image:: time_random/single-line-answer-tab.png :align: center - :alt: Randomized question count in the questions tab of a survey. + :alt: The Single Line Text box question type answers tab in Odoo Surveys. -.. seealso:: - :doc:`scoring` +If the :guilabel:`Input must be an email` option is enabled, a new field, :guilabel:`Save as user +email` appears. If that box is ticked, Odoo saves the participant's answer to that specific question +as their email address. + +If the :guilabel:`Save as user nickname` option is enabled, Odoo saves the participant's answer as +its nickname. + +For all other applicable :guilabel:`Question Type` options that provide answer options to the +participant, the :guilabel:`Answers` tab appears the same. + +.. image:: time_random/multiple-choice-answer-options.png + :align: center + :alt: The answer tab with a multiple choice answer option selected in Odoo Surveys. + +From here, users can add answer options by clicking :guilabel:`Add a line`, and typing in the +various answer options for that question. Then, either press :kbd:`Enter` to lock in that answer +option and immediately add another one. Or, click away to simply lock in that answer option. + +The entered answer options appear in the :guilabel:`Choices` column of the :guilabel:`Answers` tab. + +If any *Scoring* option is enabled in the :guilabel:`Options` tab of the survey form, the +:guilabel:`Correct` and :guilabel:`Score` columns appear to the right of the :guilabel:`Choices` +column. + +To mark an answer option as correct, tick the box beneath the :guilabel:`Correct` column for the +respective question. If :guilabel:`Multiple choice: multiple answers allowed` is set as the +:guilabel:`Question Type`, multiple answers in the :guilabel:`Choices` column can be marked as +:guilabel:`Correct`. + +In the :guilabel:`Score` column, designate how many points (if any) should be rewarded to the +participant for entering that specific answer. It is possible to enter a negative amount as the +:guilabel:`Score` to take points away for an incorrect response. + +The option to upload a corresponding image to accompany the answer options is available on the +question line, beneath the :guilabel:`Image` column, by clicking :guilabel:`Upload your file`, and +uploading the desired image. + +To delete any answer option, click the :guilabel:`🗑️ (trash can)` icon to the far-right of the +question line. + +An exception to that is if the :guilabel:`Matrix` option is selected as the :guilabel:`Question +Type`. If that's chosen, the :guilabel:`Answers` tab remains, but below the typical +:guilabel:`Choices` section, there is a :guilabel:`Rows` section. That's because the +:guilabel:`Matrix` option provides an answer table for participants to fill out. + +.. image:: time_random/matrix-answer-tab.png + :align: center + :alt: The answer tab with a matrix question type selected in Odoo Surveys. + +Description tab +~~~~~~~~~~~~~~~ + +In the :guilabel:`Description` tab of the :guilabel:`Create Sections and Questions` pop-up window is +used to provide any kind of guidelines, instructions, or any other type of supplemental material +deemed necessary to help participants answer/understand the question. + +Entering a description is **not** required. + +Options tab +~~~~~~~~~~~ + +In the :guilabel:`Options` tab of the :guilabel:`Create Sections and Questions` pop-up window, there +are four available sections: :guilabel:`Answers`, :guilabel:`Constraints`, :guilabel:`Conditional +Display`, and :guilabel:`Live Sessions`. + +Answers section +*************** + +.. note:: + Fields in the :guilabel:`Answers` section in the :guilabel:`Options` tab of the :guilabel:`Create + Sections and Questions` pop-up window vary, depending on the selected :guilabel:`Question Type` + and overall :guilabel:`Options` configured on the survey form. + +Multiple Choice question types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the selected :guilabel:`Question Type` is either :guilabel:`Multiple choice: only one answer` or +:guilabel:`Multiple choice: multiple answers allowed`, there is a :guilabel:`Show Comments Field` +present in the :guilabel:`Answers` section. + +When enabled, two additional fields appear: :guilabel:`Comment Message` and :guilabel:`Comment is an +answer`. + +.. image:: time_random/multiple-choice-options-tab.png + :align: center + :alt: The answers section of the options tab when a multiple choice question type is selected. + +In the :guilabel:`Comment Message` field, type in a guiding message to help participants know what +is expected of them (e.g. `If other, please specify`). + +If the :guilabel:`Comment is an answer` option is enabled, Odoo takes the participant's commented +response as an answer, and not just commentary on the question. This is best utilized in surveys +where there is no scoring option enabled. + +Multiple Lines Text Box question type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the selected :guilabel:`Question Type` is :guilabel:`Multiple Lines Text Box`, a +:guilabel:`Placeholder` field appears in the :guilabel:`Answers` section of the :guilabel:`Options` +tab. + +.. image:: time_random/multiple-lines-placeholder.png + :align: center + :alt: The placeholder field when a multiple lines text box option is chosen in Odoo Surveys. + +In the :guilabel:`Placeholder` field, enter a guiding direction to help participants know what they +should write in the :guilabel:`Multiple Lines Text Box` presented to them. + +Single Line Text Box, Numerical Value, Date, Datetime question types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the selected :guilabel:`Question Type` is :guilabel:`Single Line Text Box`, :guilabel:`Numerical +Value`, :guilabel:`Date`, or :guilabel:`Datetime`, two options appear in the :guilabel:`Answers` +section of the :guilabel:`Options` tab: :guilabel:`Validate Entry` and :guilabel:`Placeholder`. + +If the :guilabel:`Validate Entry` option is enabled, two additional fields appear beneath: +:guilabel:`Min/Max Limits` and :guilabel:`Validation Error`. + +.. image:: time_random/single-line-validate-entry.png + :align: center + :alt: The answers section of the option tab when a single line text box question type is chosen. + +In the :guilabel:`Min/Max Limits` field, designate the minimum and maximum allowed quantities for +that specific question. + +In the :guilabel:`Validation Error` field, enter a custom message that Odoo displays when an answer +is not valid. + +In the :guilabel:`Placeholder` field, enter a guiding direction to help participants know what they +should write in the :guilabel:`Multiple Lines Text Box` presented to them. + +Constraints section +******************* + +The :guilabel:`Constraints` section in the :guilabel:`Options` tab is the same, regardless of the +selected :guilabel:`Question Type`. + +.. image:: time_random/constraints-section.png + :align: center + :alt: The Constraints section in the options tab in Odoo Surveys. + +In the :guilabel:`Constraints` section, there is one option available: :guilabel:`Mandatory Answer`. + +When :guilabel:`Mandatory Answer` is enabled, that means that specific question requires an answer +from the participant before they can move on. Also, when :guilabel:`Mandatory Answer` is enabled, +that reveals an additional field: :guilabel:`Error Message`. + +In the :guilabel:`Error Message` field, enter a custom error message prompting the participant to +provide an answer for this question. + +Conditional Display section +*************************** + +:guilabel:`Conditional Display` means the question is **only** displayed if a specified conditional +answer(s) (i.e. :guilabel:`Triggering Answers`) has been selected in a previous question(s). + +.. note:: + The :guilabel:`Conditional Display` section of the :guilabel:`Options` tab is **not** available + when questions are randomly picked. + +There is only one field in the :guilabel:`Conditional Display` section: :guilabel:`Triggering +Answers`. + +.. image:: time_random/conditional-display-section.png + :align: center + :alt: The Conditional Display section of the options tab in the Odoo Surveys application. + +In the :guilabel:`Triggering Answers` field, select specific responses from previous questions that +would trigger this question. More than one answer can be selected. Leave the field empty if the +question should always be displayed. + +Live Sessions section +********************* + +The option in the :guilabel:`Live Sessions` section of the :guilabel:`Options` tab are **only** +supported by *Live Session* surveys. + +There is only one option available in the :guilabel:`Live Sessions` section: :guilabel:`Question +Time Limit`. + +.. image:: time_random/live-sessions-section.png + :align: center + :alt: The Live Sessions section of the Option tab in the Odoo Surveys application. + +When the :guilabel:`Question Time Limit` option is enabled, designate how much time (in +:guilabel:`seconds`) participants have to answer the question during a *Live Session* survey. diff --git a/content/applications/marketing/surveys/time_random/conditional-display-section.png b/content/applications/marketing/surveys/time_random/conditional-display-section.png new file mode 100644 index 000000000..04402a6da Binary files /dev/null and b/content/applications/marketing/surveys/time_random/conditional-display-section.png differ diff --git a/content/applications/marketing/surveys/time_random/constraints-section.png b/content/applications/marketing/surveys/time_random/constraints-section.png new file mode 100644 index 000000000..1386f3900 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/constraints-section.png differ diff --git a/content/applications/marketing/surveys/time_random/create-sections-questions-popup.png b/content/applications/marketing/surveys/time_random/create-sections-questions-popup.png new file mode 100644 index 000000000..135d57c98 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/create-sections-questions-popup.png differ diff --git a/content/applications/marketing/surveys/time_random/live-sessions-section.png b/content/applications/marketing/surveys/time_random/live-sessions-section.png new file mode 100644 index 000000000..5afc9cfe3 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/live-sessions-section.png differ diff --git a/content/applications/marketing/surveys/time_random/matrix-answer-tab.png b/content/applications/marketing/surveys/time_random/matrix-answer-tab.png new file mode 100644 index 000000000..f6f855306 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/matrix-answer-tab.png differ diff --git a/content/applications/marketing/surveys/time_random/multiple-choice-answer-options.png b/content/applications/marketing/surveys/time_random/multiple-choice-answer-options.png new file mode 100644 index 000000000..f4b9361f4 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/multiple-choice-answer-options.png differ diff --git a/content/applications/marketing/surveys/time_random/multiple-choice-options-tab.png b/content/applications/marketing/surveys/time_random/multiple-choice-options-tab.png new file mode 100644 index 000000000..9b1a53c44 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/multiple-choice-options-tab.png differ diff --git a/content/applications/marketing/surveys/time_random/multiple-lines-placeholder.png b/content/applications/marketing/surveys/time_random/multiple-lines-placeholder.png new file mode 100644 index 000000000..2e7a7614f Binary files /dev/null and b/content/applications/marketing/surveys/time_random/multiple-lines-placeholder.png differ diff --git a/content/applications/marketing/surveys/time_random/random-questions.png b/content/applications/marketing/surveys/time_random/random-questions.png deleted file mode 100644 index ee9b6fe02..000000000 Binary files a/content/applications/marketing/surveys/time_random/random-questions.png and /dev/null differ diff --git a/content/applications/marketing/surveys/time_random/single-line-answer-tab.png b/content/applications/marketing/surveys/time_random/single-line-answer-tab.png new file mode 100644 index 000000000..4416c3f61 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/single-line-answer-tab.png differ diff --git a/content/applications/marketing/surveys/time_random/single-line-validate-entry.png b/content/applications/marketing/surveys/time_random/single-line-validate-entry.png new file mode 100644 index 000000000..4cec978af Binary files /dev/null and b/content/applications/marketing/surveys/time_random/single-line-validate-entry.png differ diff --git a/content/applications/marketing/surveys/time_random/slider-dropdown-mandatory-answer.png b/content/applications/marketing/surveys/time_random/slider-dropdown-mandatory-answer.png new file mode 100644 index 000000000..c19cbb2e8 Binary files /dev/null and b/content/applications/marketing/surveys/time_random/slider-dropdown-mandatory-answer.png differ diff --git a/content/applications/marketing/surveys/time_random/time-limit.png b/content/applications/marketing/surveys/time_random/time-limit.png deleted file mode 100644 index becef005e..000000000 Binary files a/content/applications/marketing/surveys/time_random/time-limit.png and /dev/null differ