Getting started
Use these four steps to write and test a questionnaire, review it with teammates, run fieldwork and download the data. This guide uses QubeScript; the QubeSurvey extension also supports existing Odin questionnaires.
1. Write and test a survey script in VS Code
This step uses Visual Studio Code. You need VS Code 1.102 or later, permission to install an extension, and a folder for your questionnaire. QubeSurvey has no browser builder yet, so a code editor is currently required to write a script.
Install the QubeSurvey extension from the VS Code Marketplace (in VS Code, open Extensions, search for QubeSurvey, and choose Install). The extension guide covers setup, commands and direct VSIX download.
Run QubeSurvey: New Hello World Survey and save it as hello-world.qube,
or create feedback.qube with this source:
@survey feedback @language en @mode cawi
@question comment text
What should we improve?
@question thanks display
Thank you.
@outcome complete
Finished.Use the extension’s qube command line with the AI agent of your choice to
draft or review the questionnaire (run QubeSurvey: Set Up AI Agent first). The agent can read the questions, answer options and
survey logic together in the script. Review its edits, then run
QubeSurvey: Run Interview. Enter an invented answer to What should we improve?
and continue through Thank you to Finished. Local authoring
and testing need no hosted account. See the QubeScript quickstart
and using qube with an AI agent. Using an existing Odin script? See
Using existing Odin scripts for Odin-specific details.
2. Upload for team testing and tickets
In VS Code, run QubeSurvey: Upload Version on the open .qube file. It uploads
the current source as a new version and opens it in QubeSurvey. Alternatively,
upload the .qube file in Versions on QubeSurvey
under Scripts. Uploading requires Account access and permission to edit the Script. Each uploaded version
stays unchanged; upload another version when you revise the questionnaire.
Open Test and run the paths you checked locally. Ask teammates with access to review the version. File a ticket while a problem is visible, describing the expected and actual behavior. It keeps the tested version and recorded interview history when available.
Compare a proposed corrected source and test the affected and nearby routes, including corrections with Back, before using the version. See Testing a script for saved journeys and replay, and Tickets and proposed fixes for review.
3. Run fieldwork
In Versions, choose Collect responses on the reviewed Script version. It
creates a draft Run named after the Script and today’s date, with Open survey
access, the progress bar only and the human check off, and opens it. If a draft Run
for that version already exists, it opens that Run instead of creating another.
(Runs also has a create form where you can set the name, the activity type, the access
(open survey, personal invitations or signed-in assignments) and these options.)
The sample’s complete ending keeps its answers automatically; no outcome setup is needed.
At the top of the Run, Ready to activate? lists everything activation depends on: the version, the script’s endings, outcomes, available credit, quota configuration, opening dates and the Run’s status. Each item says whether it is ready, blocked or worth checking, and links to the place that fixes it. Activate run stays disabled while any item is blocked. Accepted responses cost US$0.10 each for USD Accounts, drawn from the Account’s prepaid credit under Billing. When everything is ready, choose Activate run and confirm.
In the activated Run’s Settings, copy Shared survey link and open it to test with invented answers. An open link does not limit someone to one response or guarantee that answers contain no identifying information. See Managing fieldwork for access methods and current limits.
4. Export and download the data
Submit an invented response through the Run’s link and check its status in Responses. In Exports, choose the Script version and an available CSV, JSONL or SSS format, create the export, then download it when its status is Ready. Find your invented answer in the downloaded file and use the data dictionary to check its question name. Script preview answers are not included. Exports are private to the requester and require current Account and Script access.
