Importing Surveys

What an import does

An import turns a survey definition file into a new survey in Voxworks. The file you upload is kept as an immutable snapshot, and its content becomes a read-only imported version — the snapshot stays the authority on what the survey says. Imports accept Voxworks JSON survey definitions. Support for Qualtrics, Forsta Surveys and Voxco export files is planned. Importing needs the surveys.create permission.

Import from platform

On the surveys list, open New survey and choose Import from platform. The wizard reads: “The import runs server-side — you can leave this page and track it in Jobs.” It has three steps.

1. Choose a source

Pick a platform card. Each is badged File upload only: surveys are imported from a definition file. In the next step, upload a Voxworks JSON definition.

2. Provide the definition

“The file is stored as an immutable snapshot and normalised into a read-only imported version. Re-importing the same survey later creates a new version rather than editing this one.” Choose the Definition file and click Start import. Only .json files are accepted.

3. Import

The import runs through four stages:

Stage	Shows
Save source snapshot	The file name and its fingerprint.
Normalize questionnaire	(n) sections · (n) questions · (n) options
Validate support	(n) supported · (n) transformed · (n) read-only · (n) unsupported, plus any blockers.
Finalize version	Imported version created — read-only

If the identical file was imported before, it is recognised as Already imported and the existing survey is reused. Finish with Open the imported survey, View jobs or Import another.

Upload new version

To update an imported survey, open it and click Upload new version in the workspace header (it needs surveys.edit). The dialog has three steps — Choose file, Review source, Import:

The drop zone reads Choose a survey definition — “Voxworks canonical JSON v1, up to 5 MB. PDF and Word documents are intentionally rejected because they are not structured survey definitions.”
Download canonical JSON example saves voxworks-survey-example.json, a small working definition to start from.
Review source shows the Provider, Parser format, Acquisition, Content type and SHA-256 fingerprint, with the note “The original file is retained as an immutable source snapshot. Imported content stays read-only; create a Voxworks copy when you need to edit it.”
Click Import new version. The upload becomes the survey’s next version, also read-only. The confirmation is Imported version with (n) questions; an identical file gives This exact upload already exists — opening it now.

The JSON format

A Voxworks survey definition is a JSON object:

{
  "schemaVersion": 1,
  "provider": "voxworks",
  "sourceFormat": "voxworks_canonical_json_v1",
  "name": "Customer follow-up",
  "description": "A minimal structured survey definition.",
  "defaultLanguage": "en-AU",
  "targetChannel": "voice",
  "blocks": [
    {
      "key": "experience",
      "title": "Experience",
      "questions": [
        {
          "key": "satisfaction",
          "type": "single_choice",
          "prompt": "Were you satisfied with your experience?",
          "required": true,
          "options": [
            { "key": "yes", "text": "Yes" },
            { "key": "no", "text": "No" }
          ]
        },
        {
          "key": "comments",
          "type": "long_text",
          "prompt": "What could we do better?",
          "required": false
        }
      ]
    }
  ]
}

Field	Required	What it holds
`name`	Yes	The survey’s name.
`schemaVersion`	No	`1` or `2`.
`provider`, `sourceFormat`	No	Where the definition came from.
`description`	No	The survey’s description.
`defaultLanguage`	No	The language code.
`targetChannel`	No	`voice`.
`blocks`	One of `blocks` or `questions`	Sections, each with a `key`, `title` and `questions`.
`questions`	One of `blocks` or `questions`	Questions without sections.
`rules`	No	Routing rules — up to 5,000.
`variables`	No	Survey variables — up to 500.
`outcomes`	No	Outcome codes — up to 500.
`voice`	No	Fixed-section settings: agent, FAQs, behaviours, gatekeeper and closing.

Question types

Each question’s type can be a Voxworks type or a common alias:

`type` in the file	Imported as
`display`, `info`, `instruction`	Display
`single_choice`, `radio`, `single`, `single_select`, `select_one`	Single choice
`rating`, `scale`	Rating
`number`, `numeric`, `integer`	Number
`long_text`, `textarea`	Long text
`first_name`, `firstname`, `given_name`	First name
`phone`, `phone_number`	Phone number

Other types — multiple choice, short text, email, date, matrix, rank order, constant sum, file upload and so on — are kept so you can read them, but voice cannot run them. The question inspector shows them with “Not supported for voice. The question can be read and deleted; its type cannot be changed here.” Matrix, rank order and similar grid types are also flagged in Readiness as preserved for inspection only. In a Voxworks copy, delete these questions or rebuild them as a voice type.

Limits and errors

Limit	Value
File size	5 MB
Sections	500
Questions	10,000
Options	50,000

Message	Cause
”The uploaded file is empty.”	The file has no content.
”The uploaded file exceeds the 5 MB limit.”	The file is too large.
”Only structured JSON survey definitions are supported.”	The file is not a `.json` file.
”The uploaded file is not valid JSON.”	The JSON cannot be read.
”The survey definition is invalid: (first issue)“	A field is missing or wrong — for example “The file must contain at least one block or question."
"The survey exceeds the supported question or option limit.”	Too many questions or options.
”The definition must include a survey name.”	`name` is missing (Upload new version dialog).
”Choose a structured JSON survey definition.”	The file is not a `.json` file (Upload new version dialog).
”The file exceeds the 5 MB limit.”	The file is too large (Upload new version dialog).

Working with an imported survey

An imported survey is read-only for good. Its workspace shows a 🔒 Imported badge and the banner “Imported versions are read-only.” — “The uploaded snapshot remains authoritative. Create a Voxworks copy to change questions or logic.” A provenance strip shows the source’s id, snapshot (date) and a Source details link to the Settings tab. To edit it:

Click Create Voxworks copy in the header.
The copy is a new, fully editable survey made from the import’s latest version — see Versions and drafts.
Add what an import does not carry, such as a Voice in the Agent section, then validate, test and publish it.

Import jobs are listed on the Jobs page. A failed import never leaves a half-built version behind.

Getting Started

Building a survey

Question types

Agent & Gatekeeper

Logic & Routing

Publishing & Running

Results

Importing Surveys

What an import does

Import from platform

1. Choose a source

2. Provide the definition

3. Import

Upload new version

The JSON format

Question types

Limits and errors

Working with an imported survey

​What an import does

​Import from platform

​1. Choose a source

​2. Provide the definition

​3. Import

​Upload new version

​The JSON format

​Question types

​Limits and errors

​Working with an imported survey

What an import does

Import from platform

1. Choose a source

2. Provide the definition

3. Import

Upload new version

The JSON format

Question types

Limits and errors

Working with an imported survey