Sawtooth Software: The Survey Software of Choice

SSI Web 8: Linux/Unix

SSI Web - Manual Linux / Unix Based Server Documentation

SSI Web will need access to a MySQL database. In order for Perl to communicate with the database the Perl DBI and DBD::mysql modules will need to be installed (see www.cpan.org). 

SSI Web survey authors install SSI Web on their local PC. When they are finished creating a survey, they click Field | Web Server Management.... From this dialog they can enter Database and FTP settings. From there SSI Web will upload and setup the study on the web server. 

If the above step does not work follow the steps below to upload a survey manually.

Uploading Files and Folders

SSI Web survey authors install SSI Web on their local PC. When they are finished creating a survey, they click Field | Web Server Management.... From this dialog they can enter Database and FTP settings. From there SSI Web will upload and set up the study on the web server.

It is also possible to manually upload your survey files by going to Field | Prepare for Manual Upload.

Prepare for Manual Upload assembles the files required to run the web survey. It places these files in a "Web Upload" folder inside the study folder (your study folder can be viewed via Windows Explorer by clicking the "yellow folder" icon). These files are later uploaded to the web server by using FTP software.

The files and folders created in the Web Upload folder now must be set up and configured on your web server. The following table describes the contents of the Web Upload folder.

File / Directory Description
   login.html Login page. Entry point for respondents.
   admin.html Admin Module login page. Entry point for study administrators.
admin Folder or directory.
   STUDYNAME_qst.cgi Main web questionnaire file.
   STUDYNAME_path.cgi Contains server path information.
   STUDYNAME_config.cgi  (see security section below) Contains Admin Module passwords.
   * STUDYNAME_CBC[exerciseID]_[designID].cgi Design file for CBC/Web studies.
   ** STUDYNAME_MXD[exerciseID]_[designID].cgi Desgin file for MaxDiff/Web studies.
   db_setup Folder containing database setup files.
   STUDYNAME_questionnaire.cgi Main web questionnaire file used for setup.
   STUDYNAME_pwds.cgi Respondent password file used to set up the database password table.
cgi-bin Folder or directory that contains all of the Perl files.
   ciwweb.pl  
   admin.pl  
   ciwlibXXX.pl  
   authlibXXX.pl  
   pverlibXXX.pl  
   grdlibXXX.pl  
   enterlibXXX.pl  
   acalibXXX.pl  
   cbclibXXX.pl  
   cvalibXXX.pl  
   maxdifflibXXX.pl  
   acbclibXXX.pl  
graphics Folder or directory that contains all the graphics in your study.
   system Folder containing supporting files.
   ssi_javascriptX_X_X.js SSI Web Javascript library
   ssi_styleX_X_X.css Base style sheet
   ssi_admin_styleX_X_X.css Style sheet for Admin Module
   jquery-X.X.X.min.js Javascript library

* Only for CBC/Web studies
** Only for MaxDiff/Web studies

The default configuration has a cgi-bin folder for each study. Some ISPs do not allow this. For configurations other than the default, see theAlternate Configuration section.

The contents of the Web Upload folder are usually uploaded to the web server via FTP (File Transfer Protocol). FTP is a method which transfers (uploads) files from your local PC to the web server on the Internet. To FTP your files, you need an FTP program. We recommend FileZilla (http://filezilla-project.org/download.php)

When uploading files to the web server it is essential that you upload in binary mode. Binary mode ensures that the file is not changed in any way during the upload process. The size (number of bytes) of all files should be the same on the web server as they are on your local PC.

Set Up Database

After the files have been uploaded it is critical that you now log into the Admin Module through admin.html. SSI Web will create the necessary database tables the first time you log into the Admin Module. Your survey should now be working. Go to login.html on your web site and test your survey making sure the study behaves as expected and that it is saving data. Remember to return to the Admin Module through admin.html to see your results and download your data. If you need to make changes re-upload the study files (usually just the contents of the db_setup folder) and make sure to log into the Admin Module and click Apply Changes so that your changes will be applied to the database.

Setting Permissions

Certain permissions need to be set for SSI Web to work properly on your web server. Perl needs to be installed on the server and the Perl scripts (ciwweb.pl and admin.pl) need permission to execute. 

Unix file permissions can be set through an FTP program such as FileZilla (see above). In FileZilla right-click the file or folder and then select "File permissions". In the table below, all the files and folders necessary for SSI Web to run are explained. The Unix permissions that need to be set are also shown. "STUDYNAME" is used to represent the name of your study.

File / Directory Description Unix Permissions* 
   login.html Login page. Entry point for respondents. 644    r w _ |r _ _ | r _ _
   admin.html Admin Module login page. Entry point for study administrators. 644    r w _ |r _ _ | r _ _
admin Folder or directory. 703    r w x | _ _ _ | _ w x
   STUDYNAME_qst.cgi Main web questionnaire file. 644    r w _ |r _ _ | r _ _
   STUDYNAME_path.cgi Contains server path information. 644    r w _ |r _ _ | r _ _
   STUDYNAME_config.cgi
    (see security section below)
Contains Admin Module passwords. 644    r w _ |r _ _ | r _ _
   ** STUDYNAME_CBC[exerciseID]_[designID].cgi Design file for CBC/Web studies. 644    r w _ |r _ _ | r _ _
   *** STUDYNAME_MXD[exerciseID]_[designID].cgi Design file for MaxDiff/Web studies. 644    r w _ |r _ _ | r _ _
   db_setup Folder containing database setup files. 707    r w x | _ _ _ | r w x
   STUDYNAME_questionnaire.cgi Main web questionnaire file used for setup. 644    r w _ |r _ _ | r _ _
   STUDYNAME_layout.cgi Contains all data fields. Used to set up data base data tables. 644    r w _ |r _ _ | r _ _
   STUDYNAME_pwds.cgi Respondent password file used to set up the database password table. 644    r w _ |r _ _ | r _ _
cgi-bin Folder or directory that contains all of the Perl files. 701    x x x | _ _ _ | _ _ x
   ciwweb.pl   755    r w x | r _ x | r _ x
   admin.pl   755    r w x | r _ x | r _ x
   ciwlibXXX.pl   644    r w _ |r _ _ | r _ _
   authlibXXX.pl   644    r w _ |r _ _ | r _ _
   pverlibXXX.pl   644    r w _ |r _ _ | r _ _
   grdlibXXX.pl   644    r w _ |r _ _ | r _ _
   enterlibXXX.pl   644    r w _ |r _ _ | r _ _
   acalibXXX.pl   644    r w _ |r _ _ | r _ _
   cbclibXXX.pl   644    r w _ |r _ _ | r _ _
   cvalibXXX.pl   644    r w _ |r _ _ | r _ _
   maxdifflibXXX.pl   644    r w _ |r _ _ | r _ _
   acbclibXXX.pl   644    r w _ |r _ _ | r _ _
graphics Folder or directory that contains all the graphics in your study. 707    r w x | _ _ _ | r w x
   system Folder containing supporting files. 707    r w x | _ _ _ | r w x
   ssi_javascriptX_X_X.js SSI Web Javascript library 644    r w _ |r _ _ | r _ _
   ssi_styleX_X_X.css Base style sheet 644    r w _ |r _ _ | r _ _
   ssi_admin_styleX_X_X.css Style sheet for Admin Module 644    r w _ |r _ _ | r _ _
   jquery-X.X.X.min.js Javascript library 644    r w _ |r _ _ | r _ _

* Unix Permission Notation - The notation consists of three sets of the letters r, w, and x. The letter "r" stands for "read", "w" for "Write" and "x" for "Execute." The first set of letters is for the Unix group "Owner", the second for "Group", and the third for "Other." So the full permissions of r w x | r w x | r w x or 777 give "read", "write", and "execute" permissions to "Owner", "Group", and "Other." 

** Only for CBC/Web studies 

*** Only for MaxDiff/Web studies

Set Up Database

After the files have been uploaded it is critical that you now log into the Admin Module through admin.html. SSI Web will create the necessary database tables the first time you log into the Admin Module. Your survey should now be working. Go to login.html on your web site and test your survey making sure the study behaves as expected and that it is saving data. Remember to return to the Admin Module through admin.html to see your results and download your data. If you need to make changes re-upload the study files (usually just the contents of the db_setup folder). Then make sure to log into the Admin Module and click "Apply Changes" so that your changes will be applied to the database.

If you are getting errors see the Common Mistakes section below.

Security

You are responsible for securing your web server.

Here are a few items to consider: 

  • Make sure that *.cgi files (including password and setup files) are not visible to the world. The server needs to be configured so that it will not permit a browser to display the contents of *.cgi files. One way to do this is to configure your server such that *.cgi files are treated as cgi-scripts (see Add Script Map section above). Make sure that you cannot use a browser to open the file containing your Admin Module passwords (STUDYNAME_config.cgi). For example, you should not be able to view the contents of the STUDYNAME_config.cgi file if you paste an address similar to the one below (using the URL specific to your study) into your browser's address bar:
    http://www.yoursite.com/yourstudy/admin/STUDYNAME_config.cgi
  • Seeing an error message on the screen is the correct result if attempting to access the *.cgi file via a web browser. You should not see the contents of that file. The server needs to be configured so that server directory listings are not visible to the world. Make sure that if you paste the URL to your "admin" folder into your browser's address bar, you are not able to see any file names. For example (using the URL specific to your study):
    http://www.yoursite.com/yourstudy/admin/

Alternate Configuration: Common CGI-BIN for All Studies

The default configuration of SSI Web has a separate cgi-bin directory inside each study root directory. Some web server configurations and ISPs do not allow this. They have a specific location where all CGI scripts must reside in order to execute. The following steps outline how to make SSI Web work with this alternate configuration:

  1. Upload all of the SSI Web Perl files (*.pl) to the location where they have permission to execute (the "common cgi-bin").

  2. In the authoring interface of SSI Web, go to Field | Remote Survey Management | Server Directory Paths. Modify the default paths to account for the new location of the Perl scripts. The following list describes the Server Directory Paths that need to be modified:

    • Administrative Directory: Path from the Perl scripts to the admin directory.
    • CGI Scripts Directory: Path from login.html to the Perl scripts.
    • Relative Path from CGI Scripts to Graphics: Path from the Perl scripts to the graphics directory.

    These changes are stored in the STUDYNAME_path.cgi, login.html, and admin.html files. The notation "../" means go up one directory.

    For example, given the directory structure:
    \cgi-bin
    	ciwweb.pl
    	admin.pl
    	STUDYNAME_path.cgi (might need to be placed here)
    	(etc.)
    \htdocs
    	\study1
    		\admin
    		\graphics
    		login.html
    		admin.html
    
    The alternate paths are:

    • Administrative Directory:   ../htdocs/study1/admin/
    • CGI Scripts Directory:   ../../cgi-bin/
    • Relative Path from CGI Scripts to Graphics:   ../htdocs/study1/graphics/

  3. Remove STUDYNAME_path.cgi from the admin directory. Upload the STUDYNAME_path.cgi, with the modified path information, to the "common cgi-bin" directory next to the Perl scripts.

Common Mistakes

Make Sure Perl is Working

The best way to verify that Perl is working properly on your server is to use a test script named "test1.pl". You can get "test1.pl" by downloading the file.

 Download PerlTestScripts.zip

Simply unzip the contents of the file and upload "test1.pl" to the cgi-bin folder on your web server. Give "test1.pl" proper execute permissions (755) and test it by browsing to it on your web site (i.e. http://www.yoursite.com/study1/cgi-bin/test1.pl. The test is successful if you see "Debug Test #1 Successful" on your screen. If you get an error message, or if the code of the script is displayed on the screen, the test failed. Please contact your system administrator for help in running this simple Perl script.

The Perl files (*.pl) need to be uploaded to your web server in "Binary Mode". The two main Perl files are ciwweb.pl and admin.pl. Both of these files need "execute" permissions. Our Perl scripts need to know where the Perl.exe is installed on the web server. Sometimes this is called the "Path to the Perl Interpreter". This path could vary across web servers. You will need to find out from your hosting provider what their Perl path is.

The SSI Web license agreement specifies that our users are not allowed to modify our Perl scripts. However, you are allowed to modify the Path to the Perl.exe. This path can be found at the top of the Perl files ciwweb.pl and admin.pl.

Sawtooth Software

6:30 AM to 5:30 PM Mountain Time
(GMT-6; GMT-7 Autumn/Winter)
Monday through Friday

Phone: +1 801 477 4700
Fax: +1 801 434 5493
Email: support@sawtoothsoftware.com

We are open!

SKIM Software

9:00 AM to 5:30 PM Central European
(GMT+2; GMT+1 Autumn/Winter)
Monday through Friday

Phone: +31 10 282 3500
Fax: +31 10 282 3560
Email: software@skimgroup.com
Online: www.skimgroup.com

Lighthouse Studio

Lighthouse Studio is our flagship software for producing and analyzing online and offline surveys. It contains modules for general interviewing, choice-based conjoint, adaptive choice-based conjoint, adaptive choice analysis, choice-value analysis, and maxdiff exercises.

Try Lighthouse Studio

  Buy Lighthouse Studio