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.

Script versions in QubeSurvey — demonstration

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.