# Coming from Qualtrics: Importing a .qsf Survey into Potato

Source: https://www.potatoannotator.com/docs/guides/coming-from-qualtrics

**`potato import` reads a Qualtrics survey file (`.qsf`) and turns it into Potato survey pages, with its display logic, branches, randomizers and End of Survey elements translated into page and question rules. From Potato 2.12.0, a study that uses Qualtrics for consent, demographics and a screener and another tool for the labeling can run in one place, with the survey, the annotation, Prolific or SONA, and one export.**

A `.qsf` file holds a survey's questions, blocks, survey flow and logic, not its responses. Potato is an annotation and survey server configured in YAML, so each Qualtrics block becomes a survey page in `phases.order`, and the annotation task sits between the pages that come before it and the pages that come after.

## Export the survey from Qualtrics

**Survey → Tools → Import/Export → Export Survey** downloads the `.qsf`.

## Import it into Potato

```bash
potato import -i screener.qsf -o my-study/
python potato/flask_server.py start my-study/config.yaml -p 8000
```

Each block becomes a page (a page break inside a block starts a new one), each question becomes a Potato question, and the display logic, branches and end-of-survey elements become page and question rules. The new study runs the survey and then a placeholder annotation task, which you replace with the real one. To add the survey to a project you already have:

```bash
potato import -i screener.qsf --into my-study/config.yaml --prefix scr_
```

`IMPORT_REPORT.md` lists everything that did not carry over. [Survey Import](/docs/tools/survey-import) covers the flags and the other six formats.

## Qualtrics features and their Potato equivalents

| Qualtrics | Potato |
|---|---|
| Block | A survey page in `phases.order` |
| Page break | A new page |
| Multiple choice (single, multiple, dropdown) | `radio`, `multiselect`, `select` |
| Matrix table (Likert) | `multirate` |
| Text entry, form | `text`, one `text` per form field |
| Text entry with number validation | `number` with min and max |
| Slider | `slider`, one per statement |
| Rank order, constant sum | `ranking`, `constant_sum` |
| Descriptive text | `pure_display` |
| Force response | `label_requirement: {required: true}` |
| Display logic | `display_logic` with nested `all`, `any` and `not` |
| Branch in the survey flow | `show_when` on the pages under it |
| Randomizer showing all blocks | `phases.counterbalance` |
| Randomizer assigning one embedded-data value | `conditions`, a between-subjects factor |
| End of Survey in a branch, skip to end of survey | `exit_when`, which screens the participant out |
| Choice randomization | `randomize_order` |
| Embedded data from a URL, such as the Prolific ID | Potato's login and [crowdsourcing](/docs/guides/crowdsourcing-prolific-mturk) settings capture it |

A randomizer that assigns embedded data maps onto Potato's `conditions` block, which assigns each participant to a cell when they arrive and keeps the cells balanced as people arrive and drop out. Logic that tested the embedded-data field tests `condition.<field>` after the import. [Experiment Flow](/docs/experiments/experiment-flow) covers assignment, page rules and counterbalancing.

## What the import leaves out

Loop & Merge (the block is imported once), piped text, logic on single matrix cells, "is displayed" conditions, choice-level display logic, quotas, web service and authenticator elements, scoring, custom validation, soft "request response", question JavaScript, and question types with no Potato equivalent (heat map, hot spot, file upload, signature, side-by-side, timing) are not imported. Each one is listed in the report.

Qualtrics' Timing question records page timing, not reaction time. For speeded responses, Potato has [timed trials](/docs/experiments/timed-trials) on annotation items and [jsPsych pages](/docs/experiments/runtime-phases#jspsych-pages).

## Further Reading

- [Survey Import](/docs/tools/survey-import) - Every survey format `potato import` reads
- [Experiment Flow](/docs/experiments/experiment-flow) - Conditions, `show_when`, `exit_when` and counterbalancing
- [Multi-Phase Workflows](/docs/features/surveyflow) - Survey pages around an annotation task
- [Behavioral Experiment Tools Compared](/docs/guides/behavioral-experiment-tools-compared) - Qualtrics beside jsPsych, PsychoPy, Gorilla, lab.js and Potato
- [Sensitive Questions](/docs/annotation-types/sensitive-questions) - List experiments and randomized response

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/master/docs/guides/coming-from-qualtrics.md).