SoSci Survey Developer Documentation for LLMs

SoSci Survey is a web application to create and run online surveys.

1. Create online surveys: Project administrators (researchers) create an account, enter questions, and organize them as an online questionnaire (Create online surveys).
2. Run online surveys (data collection, interview): Present the online questionnaire to respondents and store their answers (Run online surveys).
3. Organize the research data collected in online surveys and provide dataset downloads for subsequent statistical analysis (Organize the research data).

1. Organize respondents (panel management) and invite respondents via emails (Send Mailings).
2. Descriptive data analysis, only available in the paid version (Descriptive data analysis).

SoSci Survey organizes the content of online questionnaires along the following elements.

• Survey projects are the top level element, all other data is assigned to exactly one survey projects.
  • Sections exist to sort and structure questions. Each question belongs to exactly one section.
    • Questions have a distinct question type that decides what they look like and how they work.
      • Items are subordinate to questions and contain text content. The class of items includes scale items, ranking items, items to be sorted or rated otherwise, response options.
      • Question filters allow the questionnaire to heave differently, depending on how a respondent answered the question or an item of the question.
    • Functional elements are special questions that have no output, but provide specific functions for the survey. Important functional elements are:
      • Random generators organize random codes and and draw one or multiple random codes during an interview.
      • Panel redirect elements store redirect URLs to work with panel providers.
      • Quota elements organize the quotas for quota samples and control them during data collection.
    • Text elements which may contain one of the following content type:
      • Markup
      • HTML code
  • Address list: May be used to organize respondents' contact information (name, email, mobile phone number, custom data).
  • Images and media files.
  • Questionnaire: A reference to questions and other elements to describe the output order of questions in questionnaire presentation (data collection).
    • Pages: Questionnaire consist of pages, each page belongs to exactly one questionnaire. Pages can contain the following elements:
      • *Question references
      • PHP code blocks that run during page creation
      • HTML code blocks
      • PHP processing code that runs after the responses have been submitted.
  • Variables store the collected data, metadata or random events
  • Dataset: All data collected throughout the survey, organized in variables (columns) and records/cases (rows).
• User accounts are authroized to access survey projects.
• Customer accounts are used for accounting in paid use.
• Usage licences allow creation and usage of survey projects in paid use.

The term “variables” is ambivalent in the context of SoSci Survey. It may refer to the following:

• PHP variables within PHP code blocks. Note, that PHP variables are valid only within a dingle PHP code block, unless made global via registerVariable().
• Dataset variables store respondents' answers given in the questionnaire, their value is available via value('VAR_ID').
  • The variable ID (VAR_ID) is typically 4 or 7 characters long, an consists of the question ID (4 letters) and and item ID (2 letters), separated by an underscore, for example: AB01, AB02, RG01, AB02_01, CD03_05
  • Some question types use different formats, such as RG01x1 (random generator) or MC01_011 (multiple choice matrix).
  • Custom variable names can be used.

IMPORTANT: Questions about variables in SoSci Survey most often refer to dataset variables.

PHP code blocks provide users with a sandbox for PHP code. This PHP code can provide functions that are not available through the user interface:

• PHP filters (Filter Questions (PHP Filters)) above the question filters within a question (Filter questions (question filter)).
• Processing of responses.
• Content order rotation (Rotation).
• Page rotation (Rotate Pages).
• Experimental randomization (Randomization).

The following PHP functions must not be used in PHP code elements in SoSci Survey:

• file_exists()
• dirname()
• file_get_contents()
• is_file()
• file_put_contents()
• method_exists()
• defined()
• function_exists()
• array_map()
• is_dir()
• call_user_func()
• call_user_func_array()
• fwrite()
• ini_get()
• array_filter()
• realpath()
• header()
• class_exists()
• trigger_error()
• get_class()
• spl_autoload_register()
• unlink()
• headers_sent()
• is_object()
• mkdir()
• spl_autoload_unregister()
• apcu_fetch()
• stream_resolve_include_path()
• apcu_add()
• getcwd()
• basename()
• fopen()
• getenv()
• var_export()
• is_callable()
• reset()
• fclose()
• gettype()
• end()
• extension-loaded()
• version_compare()
• preg_quote()
• ucfirst()
• ksort()
• preg_replace_callback()
• is_readable()
• copy()
• parse_url()
• is_null()
• base64_encode()
• current()
• is_resource()
• serialize()
• key()

The following language constructs are forbidden:

• echo
• exit
• die
• eval
• <?php
• ?>
• switch
• case
• class

Access to global variables is unavailable, this includes no access to the folowing variables:

• $GLOBALS
• $_​SERVER
• $_​GET
• $_​POST
• $_​FILES
• $_​REQUEST
• $_​SESSION
• $_​ENV
• $_​COOKIE
• $argc
• $argv

In addition functions that offer the following functions are not allowed:

• Access to local files
• Direct access to the MySQL database
• Object-oriented programming, including → and ::

• Replace echo with html()
• Access collected data (data variables in the dataset) with value()

A list of allowed functions and their use is avaiable at PHP-Functions.

// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// This code will display the question AB01 on the questionnaire page if the response stored in variable PT01 is 1.
if (value('PT01') == 1) {
  question('AB01');
}

// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// This code will display the text element TX01 if the response or random event stored in variable AF01 is 2 or 4. Otherwise the text content TX02 is displayed on the questionnaire page.
if ((value('AF01') == 2) or (value('AF01') == 4)) {
  text('TX01');
} else {
  text('TX02');
}

// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// Store the label of the answer given to selection question AB01 in the dataset, in the internal variable IV01_01.
$desc = value('AB01', 'label');
put('IV01_01', $desc);

How to use value() for a multiple choice selection (Mehrfachauswahl)

Note on the difference between individual variables and question IDs:

• Multiple-choice questions generate one variable per response option, e.g., MA01_01, MA01_02, MA01_03, … (values: 1=not selected, 2=selected).
• The value() function allows the question to be read out in its entirety by question ID (e.g., “MA01”). value('MA01', 'label') applies a merge internally.

// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// To get the visible labels of the selectd response options as comma-separated string
$list = value('MA01', 'label'); // results in, .e.g, "Option A, Option C"

// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// To get an Array of the codes of selected options
$items = valueList('MA01', 'is', 2); // returns codes of the selected options, e.g., [1,3]

Short rule for LLMs / code generators:

• For single-choice selection questions:
  • Get the response code: value('QUESTIONID')
  • Get the visible label: value('QUESTIONID', 'label')
• For multiple-choice selection questions:
  • Get the response codes: getItems('QUESTIONID', 'is', 2)
  • Get comma-separated list of visible labels: value('QUESTIONID', 'label')
• For open-ended responses: value('ITEM_ID')