SSI Web 8: Microsoft IIS

Installing Perl

SSI Web uses scripts written in the Perl programming language to run web-based surveys. A Perl interpreter must be installed on your web server for SSI Web surveys to work correctly.

Active State provides a free version of their ActivePerl interpreter at http://www.activestate.com/activeperl/downloads.

When installing ActivePerl, we recommend accepting all of the defaults.

Make sure the following options are checked:

Perl should be added to the PATH environment variable, a Perl file extension association should be made, and the IIS script mapping for *.pl should be created.

Although instructions have been provided for ActivePerl, SSI Web can utilize any available Perl interpreter. Please consult your System Administrator to make sure a Perl interpreter is available.

Installing Perl Database Modules

For Perl to communicate with the database the Perl DBI Module must be installed. Then, assuming that you are connecting to a Microsoft SQL database, you will need to make sure the Perl DBD::ODBC Module is installed.

If you installed Active State's Perl build (see above) then you should also have access to Active State's Perl Package Manager. The Perl Package Manager makes it easy to install Perl Modules.

To start the Perl Package Manager go to a command prompt and enter "ppm".

Search for "dbi". "Mark for install" the DBI module and then click the arrow to "Run marked actions". This will install the DBI module. Next repeat this process by searching for and installing "dbd-odbc".

Configuring IIS

IIS 7.0

Using IIS 7.0 (Windows Server 2008)

Before you begin make sure to complete the Installing Perl section above.

Next, create a folder that serves as your study root in the wwwroot folder. The main folder for web pages under IIS is C:\inetpub\wwwroot (although this is the default location, your system administrator may change it).

For example, if the SSI Web study were called "stu1", a folder could be created in the wwwroot folder named "stu1".

Microsoft Iis Stu1

Microsoft's Web Server IIS (Internet Information Services) should have the Role Service "CGI" installed. You can double check that by going to Control Panel, Programs and Features, Turn Windows features on or off. This will open the Server Manager window. Scroll down to Roles Summary and click the Web Server (IIS) link. Ensure that CGI is installed.

Microsoft Iis Cgi

Open the IIS Manager, located in the Administrative Tools folder of the Control Panel. You now need to either setup a new website or add a new virtual directory and point it to your study in C:\inetpub\wwwroot.

A new virtual directory is created by right clicking a website and selecting "Add Virtual Directory".

Microsoft Iis Virtualdirectory

You then need to specify an alias for the virtual directory and where the actual files for that directory are located on the hard drive. The virtual directory points http://www.yoursite.com/stu1 to c:\inetpub\wwwroot\stu1.

Microsoft Iis Virtualdirectorysettings

Next, highlight the virtual directory and double click on Handler Mappings.

Microsoft Iis Handlermappings Iis7

Click the Add Script Map link on the right side column under Actions.

The Add Script Map dialog box will appear.

Enter the following values:

Request path: *.pl
Executable: C:\Perl\bin\perl.exe "%s" %s
If perl is installed in a different location enter that path. Be sure to add the "%s" %s at the end of the path.
Name: Perl

Microsoft Iis Addscriptmap Iis7

After clicking OK you should see the message below (if not click Request Restrictions in the above dialog first and then click OK).

Microsoft Iis Addscriptmessage

Click "Yes" on the above dialog. You want to "Allow" this entry in the ISAPI and CGI Restriction list.

NOTE: Make sure to do the above steps for *.cgi files as well. This is an important security step.

Microsoft Iis Addscriptmap Cgi Iis7

SSI Web needs permission to read, write, and delete within the "admin" and "data" folders. To allow this in IIS right click on your virtual directory (or website) and go to Edit Permissions. Click on the Security tab and click Edit. Highlight "Users (SERVER2008\Users)" and give them the "Modify" permission.

Microsoft Iis Userpermissions Iis7

Configuration of the web server is now complete and ready for testing. Make sure to test taking the survey from the beginning to the end. Also log into the Admin Module and make sure you can download data etc. Be aware with the many different server configurations, these instructions may vary slightly. Consult your System Administrator for assistance.

IIS 6.0

Using IIS 6.0 (Windows Server 2003)

Before you begin make sure to complete the Installing Perl section above.

To begin, create a folder that serves as your study root in the wwwroot folder. The main folder for web pages under IIS is C:\Inetpub\wwwroot (although this is the default location, your system administrator may change it).

For example, if the SSI Web study were called "stu1", a folder could be created in the wwwroot folder named "stu1".

wwwroot folder

Open the IIS (Internet Information Services) Manager, located in the Administrative Tools folder of the Control Panel. A new virtual directory must be created by right-clicking "Default Web Site" and selecting New|Virtual Directory.

Microsoft Iis 6 Virtual directory

Using the Virtual Directory Creation Wizard, select an alias for the folder. The alias is used in the web URL, i.e. http://www.myserver.com/mystudy/stu1login.html.

Microsoft Iis virtual directory wizard alias

Next, enter the path to the folder where the study is located. This is the study root folder that was created in a previous step.

Microsoft Iis Virtual Directory Wizard Path

Make sure only the "Read", "Run scripts", and "Execute" options are checked.

Microsoft Iis Virtual directory wizard permissions

After finishing the Virtual Directory Creation Wizard, the alias used appears in the list of items under Default Web Site. Right-click the alias and select Properties.

Microsoft Iis Virtual directory prop menu

To verify that SSI Web scripts will run correctly, check that "Execute permissions" says "Scripts and Executables", and click Configuration.

Microsoft Iis Virtual directory properties

Scroll down through the extensions, and verify that your Perl interpreter is registered to handle .pl extensions. If it is not present, check with your System Administrator about adding the extension.

Microsoft Iis Virtual directory prop config

Permissions must be set on the files so that they can be viewed on the Internet. To do this, right-click the virtual directory, and select "Permissions".

Microsoft Iis Permissions menu

Find the entry for "Internet Guest Account", and if not already checked, put a check for the "Modify" flag. All the flags below it should also become checked. Click OK to close the permissions window.

Microsoft Iis Modify Flag

To complete the configuration, click Web Service Extensions from the tree view. If not already allowed, right-click "All Unknown CGI Extensions" and select Allow. This should also be done for other items referring to CGI, such as "Perl CGI Extension" (this may vary with your Perl interpreter).

Microsoft Iis Web extensions

Configuration of the web server is now complete and ready for testing. Be aware with the many different Perl interpreters and server configurations, these instructions may vary slightly. Consult your System Administrator for assistance.

IIS 5.0

Using IIS 5.0 (Windows 2000 Server)

Before you begin make sure to complete the Installing Perl section above.

To begin, create a folder to serve as your study root in the wwwroot folder. The main folder for web pages under IIS is C:\Inetpub\wwwroot (although this is the default location, your system administrator may change it).

For example if the SSI Web study were called "stu1", a folder could be created in the wwwroot folder named "stu1".

wwwroot folder

Open the IIS (Internet Information Services) Manager, located under Start|Programs|Windows NT 4.0 Option Pack|Microsoft Internet Information Server. A new virtual directory must be created by right-clicking "Default Web Site" and selecting New|Virtual Directory.

Microsoft Iis 5 Virtual directory

Using the Virtual Directory Creation Wizard, select an alias for the folder. The alias used in the web URL, i.e. http://www.myserver.com/mystudy/stu1login.html.

Microsoft IIS Virtual directory wizard alias

Next, enter the path to the folder where the study is located. This is the study root folder that was created in a previous step.

Microsoft IIS Virtual directory wizard path

Make sure only the "Read", "Run scripts", and "Execute" options are checked.

microsoft iis virtual directory wizard permissions

After finishing the Virtual Directory Creaton Wizard, the alias used appears in the list of items under Default Web Site. Right-click the alias and select Properties.

Microsoft IIS virtual directory prop menu

To verify that SSI Web scripts will run correctly, check that "Execute permissions" says "Scripts and Executables", and click Configuration.

Microsoft Iis virtual directory properties

Microsoft Iis virtual directory prop config

Permissions must be set on the files so that they can be viewed on the Internet. To do this, right-click the "stu1" folder in Windows Explorer (not IIS), and select "Properties".

Microsoft Iis 5 permissions menu

On the Security tab, find the entry for "Everyone", and if not already checked, put a check for the "Modify" flag. All the flags below it should also become checked. Click OK to close the properties window.

Microsoft Iis 5 Permissions

IIS 4.0

Using IIS 4.0 (Windows NT 4.0 Server)

Before you begin make sure to complete the Installing Perl section above.

For example if the SSI Web study were called "stu1", a folder could be created in the wwwroot folder named "stu1".

Microsoft Iis wwwroot folder

Open the IIS (Internet Information Services) Manager, located in the Administrative Tools folder of the Control Panel. A new virtual directory must be created by right-clicking on "Default Web Site" and selecting New|Virtual Directory.

Microsoft Iis 4 Virtual directory

Using the Virtual Directory Creation Wizard, select an alias for the folder. The alias is used in the web URL, i.e. http://www.myserver.com/mystudy/stu1login.html.

Microsoft Iis 4 Virtual directory wizard alias

Next, enter the path to the folder where the study is located. This is the study root folder that was created in a previous step.

Microsoft Iis 4 Virtual directory wizard path

Make sure only the "Allow Read Access", "Allow Script Access", and "Allow Execute Access" options are checked.

Microsoft Iis 4 virtual directory wizard permissions

After finishing the Virtual Directory Creaton Wizard, the alias used appears in the list of items under Default Web Site. Right-click the alias and select Properties.

virtual directory prop menu

To verify that SSI Web scripts will run correctly, check that "Permissions" is set to "Execute (including script)", and click Configuration.

Microsoft Iis 4 Virtual directory properties

virtual directory prop config

Permissions must be set on the files so that they can be viewed on the Internet. To do this, right-click the "stu1" folder in Windows Explorer (not IIS), and select "Properties".

microsoft iis permissions menu

On the Security tab, click the Permissions button.

Microsoft Iis 4 Permissions tab

Find the entry for "Everyone", and if not already, set the permission to "Full Control". Click OK to close the permissions window.

Microsoft Iis 4 Permissions

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 the Alternate 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.

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:

Upload all of the SSI Web Perl files (*.pl) to the location where they have permission to execute (the "common cgi-bin").
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/
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.