Перейти к основному содержимому

Выгрузка и загрузка анкеты, описание структуры файла с анкетой

Любую созданную в системе анкету можно как выгрузить в виде текстового файла, так и загрузить обратно. Эту функцию удобно использовать, например, для передачи запрограммированной анкеты другому клиенту сервиса, просто отправив ему выгруженный файл по электронной почте. Также, возможно формирование файла с анкетой сторонним ПО, для последующей загрузки в SURVEYSTUDIO.

Чтобы выгрузить анкету, необходимо нажать соответствующую кнопку, находящуюся под списком вопросов:

Чтобы наоборот, создать новую анкету из файла, необходимо перейти в список анкет и нажать кнопку:

При этом будет создана новая анкета.

Формат выгружаемого файла

Анкета выгружается в текстовый файл в формате JSON (см. описание тут или тут). Используемая кодировка: UTF8. В файле записывается один объект Questionnaire, содержащий все необходимые свойства анкеты. Каждое свойство объекта состоит из имени (ключ) и значения. При сохранении анкеты из SURVEYSTUDIO имена свойств объектов всегда будут заключены в кавычки, однако если файл будет формироваться сторонним ПО - допускается имена свойств указывать без кавычек. Также, при сохранении из SURVEYSTUDIO, будут заданы значения всех необязательных свойств, которые можно опустить при формировании файла.

Пример содержимого файла:

{
"Magic": "SS2EQN",
"Version": "2.0",
"Name": "Новая анкета",
"Flags": "None",
"Questions": [
{
"OrderIdx": 1,
"Number": 1,
"Text": "Текст вопроса 1",
"ImagePlacement": "Default",
"QuestionType": "SingleChoice",
"Flags": "None",
"AnswerList": "Q1 список"
}
],
"AnswerLists": [
{
"Name": "Q1 список",
"AnswerItems": [
{
"OrderIdx": 1,
"Code": 1,
"Text": "Ответ 1",
"ImagePlacement": "Default",
"Flags": "None"
},
{
"OrderIdx": 2,
"Code": 2,
"Text": "Ответ 2",
"ImagePlacement": "Default",
"Flags": "None"
},
{
"OrderIdx": 3,
"Code": 3,
"Text": "Ответ 3",
"ImagePlacement": "Default",
"Flags": "None"
}
]
}
]
}

Первые два свойства указывают на версию формата и должны иметь фиксированные значения:

{
"Magic": "SS2EQN",
"Version": "2.0"
}

Полный список свойств объекта Questionnaire и описание их значений

  • Magic
    Маркер формата файла. Имеет фиксированное значение "SS2EQN".
  • Version
    Версия формата файла. Текущее значение "2.0".
  • Name
    Строка, содержащая имя анкеты. При загрузке, если анкета с таким же именем уже существует - имя будет дополнено числом, чтобы соблюсти требование уникальности.
  • Code
    Целое число, содержащее код анкеты. Может отсутствовать.
  • Flags
    Набор флагов анкеты. Указывается в виде строки, в которой перечислены через запятую имена необходимых флагов:
    • DisableCleanupOnPostProcessing - запретить проверку с очисткой лишних ответов перед сохранением интервью,
    • MultipleChoiceInCategoricalMode - выгружать вопросы с множественным выбором в категориальном режиме,
    • MultipleChoiceInAlternativeFlagsMode - выгружать вопросы с множественным выбором в альтернативном режиме,
    • Archive - помещена в архив,
    • HideGoBackButton - скрывает в анкете кнопки "Назад" и "Начало",
    • HideInterruptButton - скрывает в анкете кнопку "Завершить",
    • HideAnswerCodes - скрывает в анкете все коды ответов, строк и колонок,
    • HideQuestionNumbers - скрывает номера вопросов анкеты, а также их количество,
    • HideSurveyStudioBranding - скрывает на всех экранах опроса нижний блок, содержащий имя клиента и логотип SURVEYSTUDIO,
    • AutoSubmitSingleChoice - включает автоматический переход к следующему вопросу при выборе ответа в вопросе с единственным выбором,
    • AllowContractorsSeeLogic - показывает всю логику при просмотре анкеты у подрядчика.

Например, два флага можно задать так:

{
"Flags": "DisableCleanupOnPostProcessing, MultipleChoiceInCategoricalMode"
}
  • ScriptPreProcessing
    Скрипт Подготовка.
  • ScriptPostProcessing
    Скрипт Обработка.
  • ScriptBeforeShow
    Глобальный скрипт Перед показом.
  • ScriptAfterAnswer
    Глобальный скрипт После ответа.
  • ScriptClientSide
    Глобальный скрипт Во время показа, исполняемый в браузере во время показа вопроса.
  • ScriptCSS
    CSS-стили анкеты.
  • Questions
    Массив вопросов анкеты. Каждый элемент массива представляет из себя объект Question.
  • AnswerLists
    Массив списков вариантов ответов, которые используются в анкете. Каждый элемент массива представляет из себя объект AnswerList.
  • Images
    Массив изображений, которые используются в анкете. Каждый элемент массива представляет из себя объект Image.

Объект Question

Для каждого вопроса необходимо задать значения полей OrderIdx, Number, Text, QuestionType. Остальные поля можно не указывать.

  • OrderIdx
    Целое число, указывающее порядок вопроса в анкете. Допускаются отрицательные значения. Если несколько вопросов будут иметь одинаковое значение в этом поле, то порядок их загрузки не определён.
  • Number
    Номер вопроса. Целое число, больше или равное нулю. Отрицательные значения не допускаются. Номер вопроса должен быть уникален для всей анкеты.
  • Text
    Текст вопроса. Может содержать HTML-разметку (действуют ограничения на используемые тэги и атрибуты).
  • Comment
    Текст комментария к вопросу. Также как и сам текст вопроса - может содержать HTML-разметку.
  • Image
    Имя изображения, связанного с вопросом. Изображение с указанным именем должно быть в списке Images.
  • ImagePlacement
    Тип расположения изображения относительно текста вопроса. Допустимые значения:
    • Default - значение по умолчанию. Расположение задаётся настройками сервера.
    • Before - над текстом.
    • After - под текстом.
    • Left - слева от текста.
    • Right - справа от текста.

Например:

{
"ImagePlacement": "After"
}
  • QuestionType
    Тип вопроса. Допустимые значения:

    • Information - информация,
    • Text - текстовый,
    • Numeric - числовой,
    • SingleChoice - единственный выбор,
    • MultipleChoice - множественный выбор,
    • Table_Text - таблица: текст,
    • Table_Numeric - таблица: числа,
    • Table_SingleChoice - таблица: единственный выбор,
    • Table_MultipleChoice - таблица: множественный выбор.
  • Flags
    Набор флагов вопроса. Указывается в виде строки, в которой перечислены через запятую имена необходимых флагов:

    • None - нет флагов,
    • RandomizeAnswers - рандомизация вариантов ответа перед показом,
    • RotateAnswers - ротация вариантов ответа перед показом,
    • AllowFractionalNumbers - разрешить ввод дробных чисел,
    • VerticalTextInColumnHeaders - вертикальный текст в заголовках колонок табличного вопроса,
    • SwapRowsAndColumns - перевернуть таблицу,
    • CustomValidation - не требовать обязательного ответа на вопрос (проверка ответа скриптами),
    • UseDatePicker - для открытого текстового значения использовать выбор даты,
    • UseTimePicker - для открытого текстового значения использовать выбор времени,
    • EnableGPS - включить запись GPS-координат,
    • EnableGeoCoder - включить определения адреса по GPS-координатам,
    • EnableAudioRecording - включить запись звука,
    • DisableAudioRecording - отключить запись звука,
    • ForceSilentAudioRecording - не отображать индикатор записи звука (скрытая запись),
    • EnableSignatureAttachment - включить возможность добавления подписи к ответу на вопрос (планшеты),
    • AllowEmptySignature - не требовать обязательного добавления подписи (планшеты),
    • AutoSubmitSingleChoice - автопереход далее при выборе единственного ответа,
    • HideGoFirstButton - скрыть кнопку "Начало",
    • HideGoBackButton - скрыть кнопку "Назад",
    • HideInterruptButton - скрыть кнопку "Завершить",
    • ShowAutoAnswerProgress - показать таймер автоответа,
    • EnablePhotoAttachments - разрешить добавление фотографий к ответу на вопрос (на планшетах),
    • SkipExport - исключить вопрос при выгрузке,
    • KeepExportOV - оставить выгрузку открытых значений. при исключении выгрузки вопроса,
    • ExportInAlternativeFlagsMode - выгружать в альтернативном режиме (для множественного выбора),
    • ExportInCategoricalMode - выгружать в категориальном режиме.

Например, два флага можно задать так:

{
"Flags": "RandomizeAnswers, CustomValidation"
}
  • Condition
    Условие показа вопроса.
  • AnswerList
    Имя списка вариантов ответов для вопроса. Список с таким именем должен быть в массиве AnswerLists.
  • RowList
    Имя списка вариантов ответов для строк табличного вопроса. Список с таким именем должен быть в массиве AnswerLists.
  • MinAnswerCount
    Минимальное необходимое количество ответов для вопроса с множественным выбором (или для каждой строки табличного вопроса с множественным выбором).
  • MaxAnswerCount
    Максимальное допустимое количество ответов для вопроса с множественным выбором (или для каждой строки табличного вопроса с множественным выбором).
  • ColumnCount
    Количество колонок, которое будет использовано при отображении вопроса с единственным или множественным выбором. Для открытого текстового вопроса задаёт количество строк в поле ввода текста.
  • TextLineCount
    Количество строк для вопросов с типом ответа Текстовый.
  • AllowedAttachmentsType
    Тип вложения, которое можно прикрепить к вопросу.
  • MinAttachmentsCount
    Минимальное количество файлов, которые нужно прикрепить к вопросу.
  • MaxAttachmentsCount
    Максимальное количество файлов, которые нужно прикрепить к вопросу.
  • AutoAnswerSec
    Время в секундах, через которое нужно автоматически нажать кнопку Далее.
  • AutoAnswerCode
    Код ответа, который нужно выбрать автоматически в вопросе с выбором, если включён автоответ.
  • OutputColumnTemplate
    Шаблон для формирования имён переменных в массиве для вопроса.
  • OutputColumnTemplateOVT
    Шаблон для формирования имён переменных в массиве открытых текстовых полей вопроса.
  • OutputColumnTemplateOVN
    Шаблон для формирования имён переменных в массиве открытых числовых полей вопроса.
  • CategoricalIndexes
    Список индексов (переопределение используемых по умолчанию) для вариантов ответа вопроса при выгрузке в категориальном режиме. Указываются через запятую.
  • ScriptBeforeShow
    Скрипт перед показом вопроса.
  • ScriptAfterAnswer
    Скрипт после ответа на вопрос.
  • ScriptClientSide
    Скрипт, исполняемый в браузере во время показа вопроса.
  • BeforeShowActions
    Действия перед показом вопроса. Задаются в виде массива объектов QuestionAction.
  • AfterAnswerActions
    Действия после ответа на вопрос. Задаются в виде массива объектов QuestionAction.

Объект QuestionAction

  • OrderIdx
    Целое число, указывающее порядок действий в списке. Допускаются отрицательные значения. Если несколько действий будут иметь одинаковое значение в этом поле, то порядок их загрузки не определён.

  • Condition
    Условие, при выполнении которого действие будет запущено. Если условие не задано - действие запускается всегда.

  • ActionType
    Тип действия. Указывает что необходимо сделать и задаётся одним из возможных значений:

    • JumpToQuestion
    • JumpToEnd
    • Skip
    • Answered
    • AnsweredOrSkip
    • SkipIfNoVisible
    • HideAll
    • HideCodes
    • HideCheckedInQuestion
    • HideFromTo
    • ShowAll
    • ShowCodes
    • ShowCheckedInQuestion
    • ShowOnlyCodes
    • ShowFromTo
    • SetVariableValueFromOpenValue
    • SetVariableValue
    • SetVariableValueFromContactData
    • CopyAnswersFromQuestion
    • LoadAnswersFromContactData
    • ResetAnswers
    • ReturnError
  • ActionVarLong1, ActionVarLong2
    Числовые переменные, задающие необходимые параметры для действий.

  • ActionVarTxt1, ActionVarTxt2
    Текстовые переменные, задающие необходимые параметры для действий.

Объект AnswerList

  • Name
    Имя списка вариантов ответов. Должно быть уникальным для анкеты.
  • ColumnCount
    Если задано, то указывает количество колонок, используемое при отображении вопросов с единственным или множественным выбором.
  • AnswerItems
    Элементы списка вариантов ответа. Задаются в виде массива объектов AnswerItem.

Объект AnswerItem

  • OrderIdx
    Целое число, указывающее порядок вариантов ответа в списке. Допускаются отрицательные значения. Если несколько вариантов ответа будут иметь одинаковое значение в этом поле, то порядок их загрузки не определён.
  • Code
    Код варианта ответа. Внутри одного списка коды вариантов ответа не должны повторяться.
  • Text
    Текст варианта ответа. Допускается использовать html-разметку. Текст может отсутствовать.
  • Image
    Имя изображения, связанного с вариантом ответа. Изображение с указанным именем должно быть в списке Images.
  • ImagePlacement
    Тип расположения изображения относительно текста варианта ответа. Допустимые значения см. ImagePlacement у объекта Question.
  • Flags
    Набор флагов для варианта ответа. Указывается в виде строки, в которой перечислены через запятую имена необходимых флагов:
    • None - нет флагов,
    • OpenValueNum - с открытым значением (число),
    • OpenValueTxt - с открытым значением (текст),
    • Blocking - блокирующий / исключающий,
    • AlwaysVisible - всегда отображается,
    • DisableReordering - не подлежит рандомизации / ротации,
    • DisableRepeat - запрещено использовать в циклах,
    • SkipExport - исключить поле при выгрузке,
    • SkipExportOV - отключить выгрузку открытого значения,
    • HideInRespondentMode - скрывает ответ, строку или колонку таблицы в режиме просмотра респондентом вопроса на планшете.
    • AllowFractionalNumbers - разрешить ввод дробных чисел,
    • AllowEmptyOpenValue - разрешить пустые открытые значения,
    • HideCode - не отображать код варианта ответа,
    • HideText - не отображать текст варианта ответа,
    • FirstColumnBottom - расположить в первой колонке внизу,
    • UseDatePicker - использовать выбор даты,
    • UseTimePicker - использовать выбор времени,
    • CustomRowValidation - не требовать ответ в строке таблицы,
    • HideInRespondentMode - скрыть в режиме респондента.
  • ExportCodeOverride
    Строка, заменяющая код варианта ответа при выгрузке массива.
  • OutputColumnTemplate
    Шаблон для формирования имён переменных в массиве для варианта ответа.
  • OutputColumnTemplateOVT
    Шаблон для формирования имён переменных в массиве открытого текстового поля варианта ответа.
  • OutputColumnTemplateOVN
    Шаблон для формирования имён переменных в массиве открытого числового поля варианта ответа.

Объект Image

Если анкета содержит изображения, то она должна выгружаться в zip-файл, в котором будет как json-файл с самой анкетой, так и все файлы с изображениями.

  • Name
    Имя изображения. Должно быть уникально для анкеты. Используется для ссылки на изображение из вопроса или варианта ответа.
  • FileName
    Имя файла с изображением.