Skip to content
Askalot
EN
Knowledge Base

Importing a Questionnaire

You already have a questionnaire: a paper form, a PDF from a statistics office, a Markdown draft. Import turns it into a draft questionnaire of your Project, written in QML and checked by the Z3 validator, so you can edit, translate and field it like any other. Askalot reads the file, lists every question it finds with the number the source prints, and generates the questionnaire from that list.

What you can import

Section titled “What you can import”
Format Limits
PDF, born-digital or scanned Up to 100 MB and 300 pages
Markdown (UTF-8 text) Up to 2 MB

A password-protected PDF and a dynamic XFA form are refused with a sentence that says what to do (save an unprotected copy; print the blank form to PDF). Split a longer document and import the parts. Other formats, such as XLSForm, LimeSurvey, SurveyJS and REDCap, are planned.

Before you start

Section titled “Before you start”
  • An AI provider of your own. Import runs on two of your model slots under Profile Settings → AI Models: the Reasoning slot must use an Anthropic API key or AWS Bedrock, and the Direct LLM slot reads the pages that need a picture of the page (scans, grids, damaged text). See AI Functions & Model Options.
  • A role that designs questionnaires. You need the Designer or Manager role in the organization, and you must be able to edit the Project.
  • A monthly import limit. On the free service each import you start counts against your monthly import limit, including one that fails later. See Fair-Use Limits.

If anything is missing, the import is refused before your file is stored and before any AI is used, and the message says what to change.

Starting an import

Section titled “Starting an import”

In the editor, right-click the questionnaires folder and choose Import Questionnaire from PDF or Markdown… (it is also in the command palette), then pick the file. Only this command starts an import: a file dropped onto the folder without it is refused, because an import uses your AI provider and counts against your monthly limit.

An AI client connected over MCP can do the same in three calls; see Importing a Printed Questionnaire.

While it runs

Section titled “While it runs”

The import runs in the background. A short form takes a few minutes; a long instrument can take an hour or more. You can keep working or close the editor. The file shows in the questionnaires folder with what the import is doing (“Importing visitor-survey.pdf — reading the pages”, and so on), in every tab and for every client of the Project. When it ends, the new questionnaire opens, or the editor tells you why it stopped.

Your answers and your file

Section titled “Your answers and your file”
  • Filled-in answers are discarded. If the file is a completed form, the values in its form fields, ticked boxes and handwritten answers are removed before anything else reads the text. Only the printed questionnaire is used, and the report says that answers were discarded. A Markdown file is assumed to be blank apart from its ticked boxes.
  • Hidden content is ignored. Text a reader cannot see (white text, text outside the page, comments in Markdown) is dropped.
  • The upload is deleted. Your file is deleted when the import ends, whether it succeeded, failed or was refused. It is not added to the Project’s documents and is not indexed for search.
  • What a PDF import read is kept. The text the import worked from, with the answers already removed, stays with the new questionnaire as its import source (see below). A Markdown file is not kept this way, because a typed answer cannot be told apart from questionnaire text.

What you get

Section titled “What you get”

A draft questionnaire in the Project, in the language of the source, with:

  • Its inventory: the list the questionnaire was generated from. It maps each question number the source prints to the item that asks it, says which parts of the source were left out and why, and holds the import report: the pages read from a picture, whether answers were discarded, objections the review step left open, and the problems the validator still reports. The inventory describes the first version and is not changed by your later edits. An AI client reads it with get_questionnaire_inventory.
  • Its import source (PDF only): the pages exactly as the import read them, in Markdown, so you can check a question against what the import saw. Titles in larger type become headings and answer options become list items; repeating page headers, footers and printed page numbers are removed and counted. Each page is labelled with its page in the file, the number printed on it and whether it was read from the text or from a picture of the page; the inventory’s page numbers are the file’s. Like the inventory it is never changed by later edits, and it moves, is deleted and is restored with the questionnaire. An AI client reads it a few pages at a time with get_questionnaire_import_source.
  • Marked invented checks. Some checks are not stated as hard rules in the source: a soft edit, or an instruction to the interviewer such as “probe if more than 80 hours”. The import still writes them as checks, so the data stays consistent, but marks each with invented: true and the editor highlights it. Confirm or change each one, then remove the mark. Respondents never see it. See QML Syntax.
  • A Z3 verdict. The questionnaire is validated like any other. When problems remain, the editor says how many and lists them in the Problems panel; the questionnaire is still saved as a draft, and publishing waits until they are fixed.

Printed routing (“If No, go to Q12”) becomes conditions on the questions it skips, across sections. A jump that cannot be followed, for example one that points backwards or to a question the file does not hold, is never guessed: it is listed in the inventory as left out, with the reason, for you to settle.

Section titled “Related”