ORSEE3

We provide a script that allows you to import participant profiles from a data file. The script is located in the install folder and called data_import_txt.php.

To prepare your ORSEE installation for the data import, do the following:

• Set your authentication method in Options/General Settings to either “URL token” or “Migration”. Passwords are not imported. If set to “URL token”, the system will just work with the encrypted participant IDs as tokens. If set to “Migration”, participants will be asked to choose a password upon their first encounter with the system (which is initially authenticated with the token).
• Configure your participant data form. Make sure that your data file will contain all the data marked as compulsory in the data form.
• Create all needed external experiment types (options/Experiment types), note down the ID numbers of these types.
• In particular, also add all items for profile fields of type “select_lang”/“radioline_lang”.
• Prepare a data file, where the columns contain the values for participant profile fields. For select_lang/radioline_lang items, the data needs to contain the ID of the respective value (e.g. the column for fields of studies should not contain values like “Economics”, but the internal ORSEE Id number for “Economics”, as listed in the repesctive table in Options/Items for profile fields of type “select_lang”/“radioline_lang”/Main field of studies.) For select/radioline fields (e.g. the original “gender”), the data needs to contain the option values (see Options/Participant profile fields/Edit …).
• The data file should *not* contain a header. You will need the respective column numbers below, column numbering starts with 0.
• Save the file as “tab-separated txt file”.
• Put the participant data file into the install/ folder, next to this script.
• Fill in the configuration section at the top of the script data_import_txt.php.

The script will use the database configuration in config/settings.php to import the data.

Unfortunately, the script can only import participant data, but not participation data. Importing past experiments and their participation details is much more complex. If you are upgrading from an older ORSEE version, please use the data_import.php script.

The import script will not affect any existing participant data. If you want to start fresh, you will have to empty the exiting or_participants table (in SQL “DELETE FROM or_participants;”). If there is no language field defined in the data file and the configuration below (en, de, etc.), the import script will assume the “public standard language” from the ORSEE configuration for all imported participant profiles.

The script will attempt to convert any text to UTF8.

At the top of the import script data_import_txt.php, you will have to set some import parameters, in particular:

• $debug: If set to true (rather than false), the script will run a dry test, not actually importing any data. Set to “false” to do the actual import.
• $txt_file_name: the file name of your data file
• $participant_status_id: Set this to the participant status ID that should be set for the imported participant profiles. The default status ID in ORSEE is 1 for “active”, which might be a natural choice. However, you may also want to create a new participant status for the imported profiles, e.g. “imported”.
• $subpool_id: The ID of the sub-subjectpool to which the imported participants are to be assigned.
• $experiment_types: a comma-separated list of the IDs of the experiment types to which the participants should be subscribed.
• $pform_mapping: An array of keys (data column names) and values (column index in data file, starting at 0) which indicate which column in the data file should be assigned to which participant form data field. An example is provided in the script.
• $check_compulsory: If set to true, the script will check whether a data field in the import data set is empty when an ORSEE participant form field is defined as compulsory, and abort the import if such an error is found.
• $check_regexp: If set to ''true', the script will check a data field against a regular expression if such regexp is defined for an ORSEE participant form field, and abort the import if such an error is found.