Dashboard setup: sources and pinned design
Before you build widgets, the setup wizard links one or more surveys as sources and creates variables (named question bindings). Two separate ideas matter:
- Pinned design version - which published survey document defines question text and options for this source.
- Response version scope - which published survey versions contribute responses to widgets.
This page explains how pins are preserved, when to update the design, and how removed questions are handled.
Where to configure
Dashboard edit → setup wizard: step 2 (add source), step 3 (questions), step 4 (variables + scope).
Pinned design version
When you first add a source, the platform pins the current published survey version as survey_design_version_id.
| Action | Pin behavior |
|---|---|
| Re-save setup (normal) | Pin unchanged |
| Add a new source | Pins to current published version |
| Click Update design to v on step 4 | Sends sync_definition_to_latest: true → pin moves to latest published |
The step 4 source card shows Design: Version {N} (pinned). If a newer publish exists, you see a notice and the update button.
Why keep the pin? Surveys evolve. Pinning lets dashboards keep stable question definitions and option labels until you explicitly sync to a newer publish.
Response version scope
Per source, choose which responses widgets count:
| Scope | Responses from | Option labels from |
|---|---|---|
| Pinned | Pinned version only | Pinned design |
| Latest | Latest published | Latest published |
| All | Every published version | Latest published |
Response scope is independent of the design pin. For example, All can include answers from older versions while labels still follow the latest published options.
Removed or republished questions
Validation depends on response scope:
| Scope | Variable binding |
|---|---|
| Pinned | Must exist in the pinned design document |
| Latest | Must exist in the latest published document |
| All | Must exist in any published version |
On setup step 4, each variable shows binding health:
- Missing - question is invalid for this scope. Change the question or delete the variable; you cannot continue until fixed.
- Removed from latest (
allscope only) - question still exists in an older version but not in the latest publish. Save is allowed; chart labels use latest options (see Functions and Break By).
Removing a question on step 3 also removes its linked variable in the draft before save.
Related
- Functions and Break By - widget metrics after setup is complete.