------------------------------------------------------------------------------------------------ ENSEMBLE RELEASE NOTES ------------------------------------------------------------------------------------------------ This file contains release notes for the Ensemble web-based survey and data management system, developed in the Janata Lab at the Center for Mind and Brain, at the University of California, Davis campus. -------------------------------- Ensemble Licensing -------------------------------- "Ensemble" is the proprietary property of The Regents of the University of California ("The Regents.") Copyright (c) 2005-10 The Regents of the University of California, Davis campus. All Rights Reserved. Redistribution and use in source and binary forms, with or without modification, are permitted by nonprofit, research institutions for research use only, provided the conditions in the included license agreement are met. Refer to the file "ensemble_license.txt" for the license agreement, located in the top level directory of this distribution. http://atonal.ucdavis.edu ---------------------------------------------------------------------------------------------- Release v1.6.3 - February 14, 2012 ---------------------------------------------------------------------------------------------- This upgrade includes new handling of audio stimuli. It also provides an initial mechanism to both check for browser support for stimulus types, and recommend action to the user to upgrade their browser or install plugins to provide support for otherwise unsupported stimuli. * We have moved to rely primarily on HTML5 support for presentation of audio files. We include modernizr.js (www.modernizr.com) to check browsers for support of HTML5 audio. In the case that a given browser does not support HTML5 audio tags for a given stimulus type, we rely on one of two fallbacks. If the browser is IE 6-9, we ask the user to install Google Chrome Frames (code.google.com/chrome/chromeframe), which imparts all of Google Chrome's latest functionality to IE. In any other case, we attempt to use jPlayer (jplayer.org), written using jQuery. This is a javascript polyfill that can utilize an Adobe Flash fallback to play .mp3 files. Currently, all of the latest browsers (except for IE) natively support .wav playback. This move substantially reduces our reliance on Flash and the previous Java applet we used to present stimuli, and streamlines our stimulus presentation mechanism. All of this has been done under the hood, so no changes should be necessary to utilize this new mechanism, other than updating your ensemble installation via svn. * We have included a few new stimulus form handlers, named: form_stimulus_matlab*_skip_s.php. These form handlers all provide a "skip" button along with audio stimulus presentation. This button allows the user to end the stimulus at any time, and records the listening time in the database using a question_id specified in the "includes/variables.php" file called "$response_time_id". To use these scripts, you must first define a question in the QEI that will indicate response times or listening times. You must then record the id for this question in "includes/variables.php:$response_time_id". You may then successfully utilize the "form_stimulus_matlab*_skip_s.php" form handlers. * To utilize the browser checking utilities, simply include "form_browsercheck.php" as the first form in your experiment. The form handler currently checks for mp3 and wav support, and if mp3 support is not found, it checks for swf support. Future releases will add the flexibility to specify which file formats to check for in a given experiment. We are using Modernizr.js (www.modernizr.com) to check for browser support for each audio type, and we are using swfobject.js (code.google.com/p/swfobject) to check for swf support. ---------------------------------------------------------------------------------------------- Release v1.6.2 - September 23, 2011 ---------------------------------------------------------------------------------------------- This is a minor upgrade. No additional scripts need to be run or configured, after performing an "svn update" in your distribution directory. * The experiment editor interface was updated, such that the forms listed in the "Add a Form" drop-down menu and each menu in the form list are ordered alphabetically, rather than in order of form id. The experiment names in the experiment selector are also now ordered alphabetically, rather than in order of experiment id. ---------------------------------------------------------------------------------------------- Release v1.6.1 - August 2, 2010 ---------------------------------------------------------------------------------------------- After performing an "svn update", Ensemble will not work properly until the upgrade script "upgrade_v1.6.1_2010Aug2.php" in /install/upgrade_scripts is performed. See the file /install/upgrade_scripts/README for details on how to run upgrade scripts. * The Google Calendar API has been integrated to Ensemble for scheduling utilities. The Google Calendar functions are available as a separate svn checkout at: /home/matrpcuser/svn/thirdparty/php/ensemble_addons Documentation for using the Google Calendar API with Ensemble will be made available on the Ensemble Wiki soon. * Two utilities: Scheduler and Participant Manager use the Google Calendar API. Currently, they are fairly customized for a particular project, but may be used as examples of working with the Google Calendar API. They were added to the admin/external directory. * A "params" field was added to the experiment table. This field is used to store parameters that control basic aspects of survey/experiment display. Params may be left blank, in which case the default display is used. Params are changed in the experiment editor. * Two new survey display features were implemented. These are controlled by experiment "params". - A "progress report" that displays the percentage completion of a survey (default is off) - Renumbering of questions consecutively across the entire survey. Note that renumbering does not affect the way in which the questions are stored in the database. This is a display feature. The displayed question numbers are stored in the "misc_info" field of the response table. Default behavior is turned off (numbering by form). * The installer was improved and a bug fixed: - A bug in the installer that did not allow the user to select the 'dl' subidgen method was fixed. - It is now possible to select the filename for subject MySQL connectivity information (the default filename is conn_subject.php) * A sample Apache configuration file (ensemble.conf) was added to the install directory. This file can be copied to your Apache configuration (usually /etc/httpd/conf.d) to restrict access to admin directories from specified subnets or domains. The configuration file will also redirect any http traffic to secure https (SSL) connections. You will likely need to edit this file to suit your environment. * Response Export Utility can now export subject information (name, passphrase, dob) associated with each response. ---------------------------------------------------------------------------------------------- Release v1.6.0 - May 25, 2010 ---------------------------------------------------------------------------------------------- Significant updates were made to the database in order to support new features for this version. It is imperative that the database and Ensemble web directory are backed up before performing an "svn update" and before running the upgrade script. After performing an "svn update", Ensemble will not work properly until the upgrade script "upgrade_v1.6.0_2010May25.php" in /install/upgrade_scripts is performed. See the file /install/upgrade_scripts/README for details on how to run upgrade scripts. The following fields will be added/changed after running the upgrade script: experiment.language is converted from an enum to varchar(30) experiment.play_question_audio (type enum 'T' or 'F') is added experiment.encrypted_response_table (type enum 'T' or 'F') is added experiment_x_form.form_handler is converted from an enum to varchar(50) form.header_audio_path (type varchar 50) is added form.footer_audio_path (type varchar 50) is added question_x_data_format.audio_path (type varchar 50) is added subject.passphrase (type blob) is added subject.security_questions (type text) is added subject.security_responses (type blob) is added subject.county (type blob) is added 'decline' field (type enum 'T' or 'F') is added to all response tables The following variable will be added to variables_config.php after running the upgrade script: $DEFAULT_LANGUAGE (defaults to "english") Please see the Ensemble wiki (http://atonal.ucdavis.edu/ensemble/wiki) for further details on using any of the following new features. MAJOR CHANGES/ENHANCEMENTS * The response_enum and response_text fields in response tables can optionally be encrypted to protect the privacy of responses. Response tables are encrypted by checking the "Encrypt responses" box when the experiment is first created. * The utilities "View Responses in Table" and "Response Export Utility" were updated so that they support encrypted response tables. * New language support can now simply be added by creating a new language file in /include/languages. To add a new language, simply copy english.php, name it .php, and replace the string constants with their translated versions. * mp3 audio files can now be associated with questions, form headers, and form footers. New utilities were created for submitting the audio files for questions, headers, and footers. The same utilities can also be used to edit the question text, header text, or footer text, as long as the question(s) or form(s) are not locked. The question, header, and footer audio only presents during a survey if the "Play Question Audio" box is checked in the Experiment Editor. * "Required" questions no longer force a response. If one omits the answer to a "required" question, the form reloads with an option to decline the "required" question. Missed "required" questions are also highlighted so that they can be found more easily. Declined responses are recorded in the "decline" field in the response table. * New subject ID form handlers were added. form_subject_register_wpasscode_opt - Expects a pre-existing subject record with an associated passcode. A checkbox is provided to skip this subject ID form if the participant forgot their passcode. This handler will revive an old session if one exists for this subject. form_subject_register_name_dob_county - This form handler only presents if a subject_id has not been associated with the current session. This allows for multiple possible methods of generating a subject ID. The handler does not check for a pre-existing subject record. Creates a new subject record for every session. Records the subject's name, dob, and county, state of residence. form_security_questions_ask - If there are no security questions or security responses recorded for this subject ID, it will present the questions that were added to this form as security questions. The questions and responses are then stored in the subject table. form_security_questions_verify - This form handler is presented only if no subject_id has been associated with the current session. It will then present any security questions associated with the name and dob that were entered on a previous form handler (e.g. form_subject_register_wpasscode_opt). If answered correctly, the form will provide the subject's passcode and initialize a new session (or revive an old session). MINOR CHANGES/ENHANCEMENTS * The form handler choices in the Experiment Editor are no longer retrieved from the table structure of the experiment_x_form table. Form handler choices are automatically picked up by filenames starting with "form_" located in the form_processing directory. This facilitates adding new form handlers. However, this also forces the requirement that any form handler be named beginning with "form_". Selected form handlers are still stored in the form_handler field in the experiment_x_form table (now as a varchar type). * The deprecated form handlers "form_subject_id.php" and "form_subject_id_wvalidation.php" are no longer supported. They have been removed from the Ensemble distribution. The update for v1.4 should have replaced their usage with the appropriate substitutions. * The deprecated functions "present_stimulus" and "play_audio_no_control" are no longer supported. An error message will appear if they are called. Use the replacement functions "present_stimuli" and "play_audio_stimuli_flash" instead. You should not be affected by this change unless you have a custom form handler that calls one of these functions. ---------------------------------------------------------------------------------------------- Release v1.5.3 - January 8, 2010 ---------------------------------------------------------------------------------------------- * Replacement of 'ereg' calls with 'preg_match' for PHP 5.3 and PHP 6.0 compliance. 'ereg' and 'ereg_replace' are deprecated as of PHP v5.3.0 and removed from PHP v6.0. * Error reporting enhancements to MatRPC. Error messages now begin with the string "Error:" Different error conditions provide different error codes and pass a descriptive message. Timestamps are provided by the QPI for MatRPC error messages. Error messages passed to the QPI from MatRPC are also replicated in the MatRPC log so that they can be easily cross-referenced between the log and the QPI. * More robust socket connection code in the QPI. Socket connections are attempted in bursts. In the event that the socket connection failed, the 'socket_establish' function will wait for a specified amount of time (should be set to no more than 2 sec. or so). Successive connection bursts will be attempted until the connection timeout has occurred. There are now three PHP configuration constants associated with the socket_establish routine (configured in variables.php): ENS_SOCKET_CONNECT_TIMEOUT ENS_SOCKET_WAIT_BETWEEN_REQUESTS_MS ENS_SOCKET_WAIT_AFTER_FAIL_MS * The socket connection error code was also generalized to support multiple operating systems and has been tested on OS X. * Make sure that variables.php updates via svn and populates the above constants. If not, add the following lines to variables.php: // Number of seconds before quitting socket connection attempts define(ENS_SOCKET_CONNECT_TIMEOUT,7); //number of milliseconds to wait in between socket connection attempts define(ENS_SOCKET_WAIT_BETWEEN_REQUESTS_MS,100); //number of milliseconds to wait after a socket connection failure define(ENS_SOCKET_WAIT_AFTER_FAIL_MS,1000); * If updating from a previous Ensemble release, make sure to recompile matrpc. Stop your current matrpc process and relaunch the new binary. ---------------------------------------------------------------------------------------------- Release v1.5.2 - November 18, 2009 ---------------------------------------------------------------------------------------------- * Make sure to run the upgrade script, upgrade_v1.5.2_2009Nov16.php, in the install/upgrade directory. The changes performed by this script are very minor (if it performs any changes at all). It simply checks whether the $ENSEMBLE_VERSION variable is stored in the correct place, and whether the new version_info.php file has been added. It will make basic edits to variables.php, variables_config.php, and version_info.php if necessary. Back up your Ensemble directory before running the update. * Moved location of $ENSEMBLE_VERSION variable to a new config file, version_info.php. This was done to facilitate updating this variable with svn updates. Since variables_config.php will not update via svn, this prevents the need to update this variable with a php script every time a new release is provided. * Added encryption key configuration to the Ensemble installation script. This was not added in Release v1.5.0 (and should have been). * Made installation instructions more clear in regards to the "private" directory where the subject username/password, and encryption key are stored. * Cleaned up installation script with regard to specification of "private" directory. The script will keep trying to create (or specify an existing) directory until it is successful. * Added shell scripts to facilitate configuration of MatRPC. * Edited the stim upload scripts to prompt for hostname, database, username, and password. The upload scripts were previously relying on an outdated version of conn_researcher.php ----------------------------------------------------------------------------------------------- Release v1.5.1 - October 27, 2009 ----------------------------------------------------------------------------------------------- * Export Attributes utility was added. This utility is available in the Experiment Admin menu. It exports Attribute records, and optionally, trials and stimuli associated with the attributes. The exported records are downloaded as an SQL file that can then be imported to a freshly installed Ensemble database. * A minor bugfix was made to functions.php, GetSQLValueString. "time" type handling was using a conversion function that was not available. The conversion function didn't seem necessary so the call to it was taken out. * Bugfixes for form_subject_register_wvalidation.php were committed between v1.5.0 and this release. ----------------------------------------------------------------------------------------------- Release v1.5.0 - October 2, 2009 ----------------------------------------------------------------------------------------------- * IMPORTANT: subidgen routines were updated in order to submit and retrieve aes encrypted data. If you update the subidgen files from a previous version of Ensemble, you must run the update script (upgrade_v1.5_2009Oct02.php) in the install/upgrade_scripts directory. This script will convert sensitive subject data fields (listed below) to aes encrypted data stored in blob fields. If you have just done an "svn update", form handlers for generating subject IDs (form_subject_register.php and form_subject_register_wvalidation.php) will not work until you run the update script. * You should block any user connections to the ensemble database before running the update script. This will ensure that users do not update the subject table while the table is being altered. This may mean simply blocking your Ensemble web interfaces, if these are the only interfaces used to update the subject table. * It is strongly recommended that you run the previous update script (upgrade_20090909.php) before running the update script for the current version. If you have updated your Ensemble installation to this version (v1.5) and have not applied either update script, it should be fine to run the two update scripts in succession (first run upgrade_20090909.php, then run upgrade_v1.5_2009Oct02.php). To run the upgrade scripts, simply issue the following on the command line: php -f