caseData()

array caseData()
array caseData(array Filter, [boolean EmptyValues])
array caseData(string Filter, [boolean EmptyValues])

The function caseData() returns all answer codes and text inputs from the current interview or a part of it.

• Filter
  Specify here rubrics and/or questions for which the data is to be determined. The syntax of this parameter is described in the instructions for getVariables().
• EmptyValues
  By default, no data will be included from questions that have not (yet) been asked in the interview, and no data will be included from open text entries where respondents have not entered anything. Specify true as the second parameter to include such (non-)data as well.
  Note: Codes for missing answers (e.g. -9 for “asked but not answered”) will be included in any case.

The function returns an associative array with the variable names as keys and the data as values.

[
  'AB01_01' => 1,
  'AB01_02' => 2,
  'AB01_03' => 5,
  'AB01_04' => 2,
  'AB01_05' => -9
]

The function returns answer codes for closed questions. This corresponds to the output format 'code' in the function value().

If a survey is conducted regularly with the same persons, some answers from the previous questionnaire should be automatically transferred to the new questionnaire.

One challenge is to identify the person so that a mapping between survey waves is possible. If the invitation to the survey is done by serial mail, the person identifier SERIAL is available for this purpose, which can be determined by means of caseSerial().

The data from the previous interview can be stored in the Database for Contents. As a key for the entry the person identifier is suitable. To maintain the link between variable labels and data, the data is encoded as a JSON string using json_encode().

So, for example, if the demographic data is to be carried over into the next questionnaire, the data must be stored in the content database in the first interview. In the following example, the relevant questions can be found in the “SD” and “PA” sections. The following PHP code must be placed on a page where all relevant questions have already been asked. So if the demographics are queried on pages 12 to 15, the PHP code must be placed on page 16 at the earliest.

// A unique key
// Generate from the person ID
$serial = caseSerial();
 
// Save only if a personal ID is present
if ($serial) {
    // A prefix (e.g. 'data-') is helpful if you
    // want to use the database for other purposes
    $key = 'data-'.$serial;
 
    // Retrieve the actual data of the interview
    $data = caseData(['SD','PA']);
 
    // Code this data and write it to the
    // content database
    $package = json_encode($data);
    dbSet($key, $package);
}

In the following questionnaire you can now read out the data – and if data is available for the person, write it directly into the variable using put(). For example, use caseData() to make sure that there are no answers yet. The following PHP code would be placed in the second questionnaire on the first page.

$currentData = caseData(['SD','PA']);
$serial = caseSerial();
 
// Write data only if in the interview
// data is not yet available and if a
// person ID is available
if ($serial && empty($currentData)) {
    $key = 'data-'.$serial;
    $entry = dbGet($key);
 
    // Proceed only if data is available
    if ($entry) {
        $data = json_decode($entry[0]);
 
        // Proceed only if data is valid
        if ($data) {
            // Set all variables separately
            foreach ($data as $varName => $value) {
                // The third parameter (true) allows,
                // to set non-internal variables
                put($varName, $value, true);
            }
        }
    }
}

Note: This PHP code writes the existing data directly into the data set. Thus, the data is available even if the respondent does not fill out the corresponding pages (anymore) or corrects them. Alternatively, the function preset() can be used instead of put(). However, this must be called on each page, on which relevant questions stand. For this it would be useful to store a function under PHP-Functions in the questionnaire, and call it on all affected pages.

Note: The storage space in the database for content is limited to 64kb per entry. Keep this in mind if you have significantly more than 1000 variables or very long text responses or raw data in the dataset.

Sometimes the data should be transmitted directly to another server via API for further processing. For this the functions sendJSON(), sendPOST() and sendXML() can be used. The function sendJSON() works directly together with caseData().

To send the entire interview data to the URL https://api.example.com/analyze.php, you would insert an additional page before the “last page” in the questionnaire and the following PHP code on top of it.

$data = caseData();
sendJSON('https://api.example.com/analyze.php', $data);