Survey Builder guide

What the Survey Builder is

The Survey Builder is the single dashboard page where an authorised tenant user builds a whole survey: its sections, its groups, its questions, the settings on each item, the conditions that show or hide items, the survey's access and presentation options, and — where the plan and permissions allow it — publishing.

Its main advantage is that you stay on one page. Structure, configuration, validation, preview, and review are all visible at the same time, so you can add a question, see it fail validation, fix it, preview the respondent's view, and carry on without navigating away and losing your place.

Opening the Builder

Open Survey Builder from the surveys area of the dashboard. The toolbar at the top of the page offers:

• Back to surveys — returns to the survey list.
• New survey — opens the create-survey dialog.
• Open existing — opens a searchable dialog listing surveys you may edit.
• Focus mode — hides surrounding dashboard chrome so the Builder fills the screen. A banner shows while focus mode is on, and the same button leaves it.
• Publish — appears only when you hold the publishing permission, and is enabled only when the survey is actually publishable. When it is disabled, its tooltip explains that publishing is unavailable.

Starting a new survey

The create-survey dialog asks for the survey's basic information — its name and its code. The code identifies the survey in exports and integrations.

The code cannot be changed after the item is created. You may set a custom code in the create dialog; once the survey, section, group, or question exists, its code is fixed. Choose it deliberately.

Builder layout

The Builder is three panels side by side. Each of the two side panels can be resized by dragging its separator (the separators are keyboard focusable), hidden and shown from the layout toolbar, and returned to their default sizes with Reset layout.

Outline panel

The outline lists the survey, its sections, and everything below them as an expandable tree.

• Search filters the tree, so you can reach a question in a long survey without expanding every branch.
• The disclosure caret on each node with children expands and collapses that branch. It is a separate control from the move arrows next to it, so collapsing a branch never reorders anything.
• Up and down arrows move the selected item within its current parent.
• The move action opens the Move dialog, used to move an item to a different parent.
• Add (+) creates a new child under that node. On the survey node it adds a section; on a section or group it opens a dialog offering the child kinds that node accepts.
• Delete opens a confirmation dialog naming the item.
• Required questions carry a Required badge in the tree.

Selecting any node loads it in the workspace and updates the review panel.

Workspace

The workspace shows tabs, and which tabs exist depends on what is selected. Nothing is shown that does not apply to the selected item.

The Assignments tab appears only when assignment management is available to you.

The selected item is identified by a two-row header: its kind badge and name on the first row, its code with a copy button on the second.

Review panel

The review panel is always visible and covers three things:

1. Readiness. A ready or blocked badge, plus the list of issues that block publishing. Each issue points at the item that causes it, and a refresh control re-runs the check.
2. Preview. A preview of the respondent's view, with a toggle between the Preview context and the Public context so you can see how the survey behaves for an internal preview versus a public link.
3. Unsaved state. Two indicators — one for the structure and one for the selected item — each showing whether it is clean or has unsaved changes.

Sections, groups, and questions

A survey holds sections. A section holds questions, and may also hold groups that gather related questions together. Sections and groups both use the Contents tab to manage what sits inside them.

Every item has a name, a code, and its own settings, edited on its Details tab.

Question configuration

A question's Details tab shows only the settings its type actually uses. The Builder groups question types into basic, choice, and lookup families, and the panel changes with the type:

• Text — minimum and maximum length, and a long-text option for multi-line answers.
• Number — minimum and maximum values. Integer and decimal are configured separately: a decimal question additionally sets its decimal places, and an integer question shows integer-specific help instead.
• Date — minimum and maximum dates.
• Choice — the choices themselves, edited inline on the Details tab (see below).
• Lookup — a lookup dataset, an active-values-only option, a maximum number of selections, an optional parent lookup question for cascading lookups, and a filter-only mode.
• File — maximum number of files and maximum file size.
• Unit and reporting amount settings, where the question type supports them.

Each question also has an active/inactive state, a public visibility setting, and an optional hint shown to the respondent.

Where the platform imposes an authoring limit — such as the maximum text length, or the maximum number of files — the panel shows a note stating the effective limit, so you find out while authoring rather than on save.

Choices editor

Choices are edited inline on the question's Details tab. There is no separate Choices tab: for a choice question, the list of choices is part of the same form as the rest of its settings, so adding a choice and setting its text never leaves the page.

Dynamic tables

A dynamic table is its own item kind. It has a Details tab for the table itself and a dedicated Columns tab for its columns, plus Conditions. Dynamic tables have no Preview tab. The compact column editor supports text, integer, decimal, date, yes/no, single choice, multiple choice, and rating columns. It does not provide a complete choice-option or lookup-dataset authoring workflow, so do not advertise lookup/file table columns without first confirming a supported authoring path.

Static content

Static content is an item that displays information rather than collecting an answer. It supports plain text or a managed PDF/image file and has a Details tab only. A managed file is served through the file pipeline; the physical storage path is not exposed. Static content never creates an answer and is not exported as response data.

Notes and guidance

Informational, guidance, and warning notes inside the Builder can be dismissed with their close button for the current browser session. Validation errors cannot be dismissed this way: they remain visible until the underlying problem is corrected. Dismissing one note never hides a different note.

Conditions

Sections, groups, questions, and dynamic tables each have a Conditions tab, used to show or hide that item based on earlier answers. Because the tab sits beside Details, you can add a condition and immediately preview its effect from the same page.

Survey-level settings

With the survey selected:

• Survey details — the survey's own fields.
• Assignments — who is assigned to the survey, where assignment management is available to you.
• Access — how respondents may reach the survey.
• Presentation — how the survey is presented to the respondent.
• Contents — the survey's sections.
• Response editing — where exposed, controls whether otherwise eligible authenticated responses may be edited. It does not make every response editable: ownership, permission, activity, response status, and access mode are also checked, and anonymous public-token routes expose no edit endpoint.

Moving and reordering items

There are two operations, and they are deliberately distinct:

• Reordering within the current parent — the up and down arrows on the outline node.
• Moving to a different parent — the move action, which opens a two-stage searchable Move dialog: choose the destination, then confirm. When a move would affect other items — for example conditions that reference the item — an impact dialog explains the consequences before anything changes.

Items can also be dragged in the outline, including across parents. The outline shows a reordering hint and, where relevant, a warning about what a move implies.

The Builder persists one mixed section-item order across direct questions, groups, Static Content, and Dynamic Tables. The current Razor respondent player does not consume that mixed sequence directly: it renders direct questions, then groups, then Static Content, then Dynamic Tables. Preview/public web order can therefore differ from the outline. Review the actual respondent runtime before relying on an interleaved mixed order.

Preview

Preview is a tab in the workspace and a panel on the right. It renders the respondent's view for the current selection, and the preview context toggle switches between the internal preview and the public view.

Preview never stores a response. You can walk the whole questionnaire as a respondent would, as often as you like, without creating any response data.

Validation and review

Validation is continuous rather than a step at the end. The review panel's readiness list names every issue that blocks publishing and points at the item responsible, and the refresh control re-runs the check after you make changes. When nothing blocks publishing, the panel says so explicitly.

The unsaved-change indicators distinguish structural changes from changes to the selected item, so you always know what is still to be saved. If you try to leave with unsaved work, an unsaved-changes dialog intervenes.

Arabic and English authoring

The Builder interface runs in both English and Arabic, and the whole page mirrors to right-to-left in Arabic. Authored survey, section, group, and question text is not translated automatically and is stored as the text of that survey rather than as parallel English and Arabic fields. Choose the survey's language and enter its content in that language. When respondents need materially different English and Arabic wording, maintain a separate language-specific survey instead of assuming that switching the dashboard language translates the questionnaire.

Responsive behaviour

The three-panel layout is intended for a wide screen. On narrower screens, hide the outline or review panel from the layout toolbar to give the workspace the full width, and use focus mode to remove the surrounding dashboard chrome.

Publishing

When the survey has no blocking readiness issues, and you hold the publishing permission, the Publish button in the toolbar becomes available and reports its result beside itself. Builder creation currently sets IsActive = true, while Publish separately validates readiness and activates the survey; active and published are therefore not equivalent, and IsActive alone is not proof of readiness or intended visibility. If your organisation's plan or subscription does not currently permit the action, the message explains the exact reason.

Planned immutable version history

Immutable survey versions are approved for implementation planning but are not available in the current Builder. When implemented, ordinary Builder saves will remain draft changes. A version will be created only by first Publish, explicit Republish after changes, or restoring an eligible older snapshot as a new sequential revision. Restore will never edit an old version or move the revision number backwards.

The planned MaxSurveyVersionsPerSurvey plan value will control how many versions are visible/restorable, including the current version: 0 disables the history/Restore surface and 1..50 enables that many entries. It will not disable runtime contentHash or full refresh. Until that implementation ships, the existing Version form field is only a free-text label, not an immutable revision, and no Version History/Restore page should be expected.

Related guides

• Creating surveys: the two methods
• Creating your first survey
• Getting started
• Inviting team users
• Mobile researchers