Surveys

This module lets non-technical admins build guided, multi-page surveys with configurable questions, controls, conditional visibility, frequency limits, and reporting metadata — all without writing code.

Quick start: build your first survey

1. In the admin, go to Configuration → Features and enable:
   • CloudSolutions.Surveys
   • Optional: CloudSolutions.Surveys.TypingTest
   • Optional: CloudSolutions.Surveys.DesktopSimulator
2. Go to Content → New → Survey.
3. Enter the survey title and optional description.
4. Add one or more Pages.
5. Inside each page, add one or more Questions.
6. Inside each question, add one or more Controls (input types such as List, Text, Numeric, Typing Test, Desktop Simulator).
7. Configure control metadata (required, hints, limits, formatting, report colors, and optional Survey Control Group assignment).
8. Add visibility rules if needed (show/hide logic).
9. Configure frequency limits and anonymous settings on the survey.
10. Publish and run a test interview.

---

Build a survey with an AI prompt

If your site has the AI features enabled, you can describe a survey in plain language and have an AI assistant build the whole structure for you — pages, questions, controls, visibility rules, and control groups. The Surveys module ships content schemas that teach the assistant the exact shape of every survey part, so an AI-generated survey has the same structure as one built by hand.

Prerequisites

• Enable the CrestApps AI features and set up an assistant that can author content (see AI Chat).
• Enable CrestApps.OrchardCore.Recipes. The survey schemas register automatically once this feature is on — there is nothing extra to configure.

How to prompt

Open your content-authoring AI assistant and describe the survey. Keep the prompt short and concrete — name the topic, the data you want to collect, the control types to use, and any show/hide logic. Give each control a clear, distinct title (visibility rules reference controls by name, so unique titles keep the logic unambiguous).

Example: a VPN readiness survey

The single prompt below builds a complete survey — pages, controls, and conditional logic all at once — that gathers what you need to know to decide how a VPN would work for the interviewee:

Create a survey titled VPN Readiness Assessment that gathers what we need to know to set up a VPN for the interviewee. Use clear, distinct titles for every control so the visibility rules resolve correctly.

• Page 1 – Work location: a predefined-list control "Where do you work?" with options Remote, Hybrid, On-site.
• Page 2 – Home network: show this page only when "Where do you work?" is Remote or Hybrid. Add a numeric control "Home internet download speed (Mbps)"; a predefined-list control "Router type" (ISP-provided, Own router, Mesh system, Not sure) shown only when "Home internet download speed (Mbps)" is greater than 0; and a text control "Which mesh system do you use?" shown only when "Router type" is "Mesh system".
• Page 3 – Devices & experience: a predefined-list control "Which devices will connect?" (Windows, macOS, iOS, Android, Linux); a numeric control "Devices connected at the same time"; a predefined-list control "Have you used a VPN before?" (Yes, No); and a text control "Which VPN did you use?" shown only when "Have you used a VPN before?" is Yes.
• Page 4 – Access needs: a text control "Internal apps or sites you must reach through the VPN", shown only when "Where do you work?" is Remote or Hybrid.

This one prompt shows off the full toolkit: multiple control types (list, numeric, text), and all three levels of visibility — page-level (Page 2), control-level cascades (Router type → mesh system), a follow-up reveal (VPN experience → which VPN), and an OR condition (Remote or Hybrid).

How it maps to the visibility model:

• Each show/hide clause becomes a Show rule on the target control or page, gated by an answer to a source control referenced by title.
• An OR condition (Remote or Hybrid) becomes two rule groups, because logic is AND within a group, OR across groups — the AI produces that structure for you.
• Rules are evaluated at runtime against the current answers, so a hidden control's value is ignored until its condition is met.

See Survey visibility (conditional logic) for the full rule model, operators, and how to fine-tune what the AI generates.

After generation

1. Publish and run a test interview to confirm the flow and any visibility rules behave as expected.

The AI is a starting point — always review the result before publishing, especially visibility rules and any scoring or report metadata.

---

Survey structure explained

Term	What it means	Example
Survey	The full questionnaire	"Customer Onboarding Survey"
Page	A step/screen in the survey flow	"Profile Information"
Question	A question block on a page	"How satisfied are you?"
Control	The actual answer input inside a question	Dropdown, text box, number, typing test

Think of it as: Survey → Pages → Questions → Controls.

Pages

Each Page is a separate screen that the respondent navigates through. Pages have:

• Title — displayed as the page heading.
• Description — optional rich-text context shown above the questions.
• Can Go Back — a toggle (via Survey Page Info) that controls whether the respondent can navigate backward from that page. Disable this on pages you do not want revisited.
• Visibility — conditional rules that show or hide the entire page based on prior answers (see Visibility / Conditional Logic below).

Questions

Each Question sits inside a page and groups one or more controls. Questions have:

• Title — the question text shown to the respondent.
• Description — optional rich-text shown below the title (supports HTML and Liquid shortcodes).
• Visibility — conditional rules at the question level, evaluated independently of page-level visibility.

Controls

Controls are the actual answer inputs inside a question. Each control has:

• Title — optional; useful when a question has multiple controls so each has an explicit label.
• Metadata — configuration specific to the control type (required, hint, limits, format, colors, group).
• Visibility — conditional rules at the control level, evaluated independently of page and question visibility.

---

Control types

Control	What respondents do	Key metadata options
Predefined List	Select one or many preset options	Options list with labels, weights, colors; dropdown or radio display; min/max selections; Liquid value override
Text Value	Type free text	Single-line, multi-line, or email editor; min/max character length
Numeric Value	Enter a number	Min value, max value, decimal format (none, 1–4 decimals, currency)
Typing Test	Complete a timed typing passage	Speed and accuracy capture
Desktop Simulator	Interact with a simulated desktop	Outcome and score capture (requires Desktop Simulator module)

---

Typing Test control

The Typing Test control is a good fit when a survey needs to measure how quickly and accurately a respondent can type a provided passage. This is useful in hiring, onboarding, skills validation, and role-readiness scenarios where typing performance matters.

What it captures

Typing Test reporting is built around three practical values:

• Words per minute
• Accuracy
• Final score

In practice, this lets teams separate raw typing speed from the overall performance result.

How to configure a Typing Test control

1. Open the survey.
2. Add or edit a Question.
3. Add a Control and choose Typing Test.
4. Open the control metadata.
5. Configure the typing-test settings.

The Typing Test editor includes:

Setting	Purpose
Start Typing Test on button click	Lets the respondent begin the exercise explicitly instead of starting immediately.
Add time limit?	Turns on timed completion.
Add time in Seconds	Sets the time limit when timing is enabled.
Expected words per minute	Defines the target speed used when evaluating the result.
SampleText to type	The passage the respondent must type.
Final score Report options	Controls score-based report colors and value overrides for the final score.
WPM Report options	Controls score-based report colors and value overrides for words per minute.

How to use it well

• Use a short, realistic passage for screening-style assessments.
• Use a longer passage when consistency and sustained accuracy matter.
• Set Expected words per minute to match the role, not a generic target.
• Use a time limit when the exercise should feel controlled and comparable across respondents.

Report setup for Typing Test

Typing Test has two separate report-option areas:

• Final score Report options
• WPM Report options

This means you can treat the overall result differently from typing speed.

For example:

• use Final score Report options when teams want one overall pass/fail style result
• use WPM Report options when teams want to highlight typing speed bands separately

Both areas support:

• multiple score ranges with Add Color Score Option
• Background and Foreground color choices
• Override report value using the score variable

Example Typing Test reporting pattern

Area	Example range	Business meaning
Final score	85+	Ready
Final score	60-84	Review
Final score	<60	Needs improvement
WPM	50+	Strong speed
WPM	30-49	Acceptable speed
WPM	<30	Below target

---

Survey visibility (conditional logic)

Survey visibility lets you show or hide pages, questions, or controls based on prior answers — without any code.

Where to configure it

A Visibility section appears on:

• The Survey Page editor
• The Survey Question editor
• Each Control metadata editor (Predefined List, Text Value, Numeric Value, Typing Test, Desktop Simulator)

Visibility rules are evaluated independently at each level. A control can be hidden even if its parent question is visible, and a question can be hidden even if its parent page is visible.

How to configure visibility (step-by-step)

1. Open the page, question, or control you want to make conditional.
2. Find the Visibility section.
3. Choose an Action:
   • Always visible — no conditions applied (default).
   • Conditionally show — only show this item when the rules pass.
   • Conditionally hide — hide this item when the rules pass.
4. Click Add rule group for each OR branch you need.
5. Inside a group, click Add rule for each AND condition.
6. For each rule, set:
   • Source control — the control whose answer you want to check (entered as Source Control Id).
   • Operator — Is, IsNot, Contains, StartsWith, EndsWith, GreaterThan, LessThan, Empty, NotEmpty.
   • Value(s) — the expected answer (skip for Empty / NotEmpty).
7. Save and test with realistic answer paths.

Rule logic: AND inside a group, OR across groups

• Rules inside one group are all evaluated together (AND logic).
• Multiple groups are combined with OR logic — the item shows/hides if any group's rules all pass.

Example — show a question only for Sales OR Engineering:

Group	Rule
Group 1	Role Is Sales
Group 2	Role Is Engineering

Result: visible when either Sales or Engineering is selected.

How runtime visibility works

When a respondent progresses through the survey:

• The visibility engine evaluates all rules against the answers given so far.
• Hidden pages are skipped in navigation — the Back button also skips hidden pages.
• When an item becomes hidden, its values are cleared so hidden answers do not affect later rules or reports.
• Hidden required fields do not block form submission.

Demo scenario to practice with

New Hire Readiness Check

• Ask for role (Sales, Support, Engineering).
• Ask if they are remote (Yes / No).
• Show Home Office Setup questions only when Remote is Yes.
• Show Territory Readiness only when Role is Sales.
• Show Advanced Product Quiz only when Role is Support or Engineering.

---

Interview frequency limits

The Survey Restriction settings let you cap how many times a single user can complete a survey per day or per week, and control what times of day interviews are permitted.

Daily limit

Enable Daily Limit and set Max Daily Allowed to restrict how many completed interviews a user may submit within a single calendar day. If the limit is reached, the user sees a message and cannot start a new interview until the next day.

Weekly limit

Enable Weekly Limit and set Max Weekly Allowed to restrict how many completed interviews a user may submit within the current week. The week start day is determined by the site's configured day-of-week setting.

Daily time restrictions

Enable Daily Restriction to control when interviews may be taken on each day of the week. For each day you can set:

Option	Behaviour
Allow All	No time restriction on this day
Prevent All	Interviews are blocked for the entire day
Limit Time	Set a From and To window — interviews are only allowed within that window

These restrictions apply per respondent. If a user attempts to start an interview outside the allowed window they see a clear error message.

---

Anonymous surveys

By default, interviews are tied to the logged-in user. Enabling Allow Anonymous on the survey removes the user association so responses are stored without identifying who submitted them.

When to use it:

• Public-facing surveys where no login is required.
• Internal surveys where you want honest feedback without attributing answers to individuals.

How to enable it:

1. Open the survey in the admin editor.
2. Find the Anonymous Survey section.
3. Check Allow Anonymous.
4. Save and publish.

Note: Anonymous interviews still record the completion timestamp but do not record a user ID. Reports will show the entry without a name in the "Completed By" column.

---

Survey Control Groups

Survey Control Groups let you organize controls into named buckets and automatically add summary columns (total, average, or a custom Liquid formula) to reports.

What a Survey Control Group does

• Groups related controls together under a shared heading in the report.
• Adds optional summary columns after the group's individual control columns:
  • Total — sums all numeric values in the group for that row.
  • Average — averages all numeric values in the group for that row.
  • Liquid — runs a custom Liquid formula against the row's inputs and outputs the result.
• Lets you customize column titles for total, average, and Liquid columns.
• Supports a Sort Order field to control where the group appears relative to other groups in the report.

Setting up a Survey Control Group

1. Go to Content → New → Survey Control Group (or find it in the content list).
2. Give it a descriptive title (for example, "Communication Skills").
3. Configure the group options:
   • Check Show Total and/or fill in Total Column Title if you want a sum column.
   • Check Show Average and/or fill in Average Column Title if you want an average column.
   • Check Show Liquid, enter a Liquid Column Title, and write a Liquid expression if you want a custom computed column.
4. Publish the group.
5. Open each control that should belong to this group.
6. In the control's metadata, find Survey Control Group Selector and choose your group.
7. Save and publish the control.

Liquid expressions in a control group

The Liquid expression in a group has access to an Inputs array — each element is a content item representing a control's captured answer. This lets you write cross-control formulas.

Example — combine two numeric controls:

{{ Inputs | where: "ContentItemId", "abc123" | first | property: "NumericValueSurveyControlPart.Value" | plus: Inputs | where: "ContentItemId", "def456" | first | property: "NumericValueSurveyControlPart.Value" }}

Keep Liquid expressions short and test them with real sample data before publishing.

---

Control colors and Liquid overrides

Per-option colors (Predefined List)

Every option in a Predefined List control can have its own background color and font color. When a respondent selects that option, the matching color is applied to the corresponding report cell — both in the on-screen report view and in the Excel export.

Where to set colors:

1. Open the Predefined List control in the admin editor.
2. In the Options section, find the option you want to color.
3. Set Background Color (hex color, e.g. #FF0000) and/or Font Color.
4. Save.

How colors flow into reports:

• The report reads the selected option's color and applies it directly to the Excel cell.
• Background color sets the cell fill.
• Font color sets the cell text color.
• If a respondent's selection has no color configured, the cell uses the default report styling.

Use colors consistently across options so reports are easy to scan. For example, use green for "Excellent", amber for "Acceptable", and red for "Poor".

Option weights (Predefined List)

Each option can also have a Weight — a numeric value used in sum and average calculations for control groups. Weights let you score a qualitative list (e.g., "Poor" = 1, "Acceptable" = 3, "Excellent" = 5) so control group totals and averages are meaningful.

Liquid value override (Predefined List)

The Override report value option on a Predefined List control lets you replace the raw selected value with a computed Liquid expression in the report. This is useful when you want the report to show a score or formula result instead of the option label.

How to enable it:

1. Open the Predefined List control metadata.
2. Check Override report value.
3. Enter a Liquid template in the text area.

Available Liquid variables:

Variable	Description
total	Sum of the weights of all selected options
average	Average of the weights of all selected options

Example:

{% if total >= 4 %}Excellent{% elsif total >= 2 %}Good{% else %}Needs Improvement{% endif %}

When an override template is active, the override result appears in the report cell and in the control group's sum/average columns instead of the raw option label.

Validation: If the Liquid template is invalid, the admin editor shows an error and prevents saving. Always test templates with representative data.

---

Score-based report options for Typing Test and Desktop Simulator

Some survey controls support a score-range editor instead of simple per-option colors. This is the editor used for:

• Typing Test -> Final score Report options
• Typing Test -> WPM Report options
• Desktop Simulator -> Report options

This setup is useful when the report color should depend on a numeric result rather than on a selected list value.

How to apply score-based report colors

1. Open the Typing Test or Desktop Simulator control inside your survey.
2. Find the relevant Report options toggle.
3. Turn it on.
4. Click Add Color Score Option.
5. Choose how the rule should compare the score:
   • Equal To
   • Greater Than
   • Less Than
   • Between
6. Enter the score threshold value, or the min and max values for a range.
7. Choose the Background color and Foreground color.
8. Add more score options until all needed ranges are covered.
9. Save the control and run a sample interview.

How to think about the ranges

Each row in the score editor defines a rule for how a result should appear in the report.

Example — Desktop Simulator score colors

Rule	Meaning	Suggested color
Less Than 60	Needs improvement	Red background
Between 60 and 84	Acceptable	Amber background
Greater Than 84	Strong result	Green background

Example — Typing Test WPM colors

Rule	Meaning	Suggested color
Less Than 30	Below target speed	Red background
Between 30 and 49	On the way	Amber background
Greater Than 49	Strong speed	Green background

Override the report value when needed

Both controls also support Override report value so the report can show a friendly label instead of only the raw score.

For these score-based overrides, the Liquid template can use:

Variable	Description
score	The numeric score being reported

Example — convert a raw score into a label

{% if score >= 85 %}Excellent{% elsif score >= 60 %}Meets Target{% else %}Needs Improvement{% endif %}

Typing Test note

Typing Test uses this setup in two places:

• Final score Report options for the final calculated score
• WPM Report options for words-per-minute reporting

That means you can color and label the final score separately from typing speed.

Desktop Simulator note

Desktop Simulator uses one Report options section for score-based color rules, plus the same Override report value option when you want the report to show a business-friendly outcome such as Pass, Review Needed, or Excellent.

---

Numeric Value formatting

Numeric controls support several display formats that apply when the value is shown in a report:

Format option	Example output
No decimals	42
1 decimal	42.0
2 decimals	42.00
3 decimals	42.000
4 decimals	42.0000
Currency	$42.00

The format is set in the control's metadata editor. Choosing "Currency" automatically sets a two-decimal scale.

---

Best-practice checklist

• Start with a simple draft — few pages, few questions — and expand from there.
• Use clear question titles and hints so respondents know exactly what to enter.
• Add required validation only where truly necessary; too many required fields increase abandonment.
• Configure frequency limits early so test interviews do not use up daily or weekly quotas.
• Set option weights before assigning colors — both belong to the same option configuration.
• Add visibility rules gradually and test every path before publishing.
• Keep Liquid expressions and value overrides minimal; complex expressions are harder to debug.
• Re-test after changing page order, deleting questions, or renaming controls referenced by visibility rules.

---

Optional related features

• Surveys Teams (CloudSolutions.Surveys.Teams) — team-aware interview and report behavior.
• Surveys Charts (CloudSolutions.Surveys.Charts) — chart-based reporting surfaces.
• Survey Typing Test (CloudSolutions.Surveys.TypingTest) — typing speed and accuracy controls.
• Surveys Desktop Simulator — simulator-based control input and scoring.

---

Related documentation

• Survey Reporting
• Surveys Desktop Simulator
• Orchard Core documentation