CHAPTER 2

Installing The Internet Survey Administrator

Note: Users upgrading to version 4 of the Internet Survey Machine need to use the new cgi programs included in the version 4 kit. The updated cgi programs are: sscar, ssvws and ssweb. If running UNIX you must compile and link them on your system. If using a Microsoft based webserver, use the pre-compiled and linked versions (sscar.exe, ssvws.exe and ssweb.exe).

Installing the Internet Survey Administrator consists of the following tasks.

Web Server Installation Component

Editing site specific links into the StartCreator.html web page
Copying the StartCreator.html web page to your web server
Copying the cgi programs ssweb, ssvws and sscar to the web server
Creating a sub directory in your cgi-bin directory named surveysaid
Setting file protection privileges on the surveysaid sub directory
Copying the SurveyCreator.jar (binary) file to the web server
Using the SurveyCreator to create/modify Administrator's profile
Using the SurveyCreator to create/modify a user's logon profile
Setting the default survey appearance and override options

Installation for Analysis Component

Run the ISM-Client.exe program on each PC that is to have analysis capability for the surveys created with the Advanced Internet Survey Administrator.
The ISM Client (Survey Analyzer) can be download from this link: Download ISM-Client

Detailed Instruction for Web Server Installation

Step 1 -- Editing site specific links into the StartCreator.html web page

Note: There is also a StartCreatorPlugin.html web page that has be included which is the startup page for the Survey Creator if you are planing to use Microsoft's Internet Explorer or Netscape 3.x or 4.x browser. Be sure to do a global replace of parameters. There are multiple instances of parameter settings for IE and Netscape.

The 1st step is to decide what directories you want to use for the Survey Creator applet, Survey Creator HTML startup page and the optional Survey Creator Startup image and audio. Here is a worksheet:

Survey Said file name            Web Server Directory name for file
============================     =====================================

StartCreator.html                _____________________________________

SurveyCreator.jar                _____________________________________

                                 The next four file are optional, but
                                 we recommend an opening screen image
                                 which is defined below as startimage

WelcomeSurveyCreator.jpg         _____________________________________

WelcomeSurveyCreator.au          _____________________________________

thankyou.gif                     _____________________________________

closeaudio.au                    _____________________________________

In the following applet parameters example, change /www.myserver.com/ and /java/ and /cgi-bin/ to the appropriate values for your environment that you listed on the above worksheet. Note the image and audio tags are optional. These applet tags are found in the StartCreator.html file.

     <applet code="SurveyCreator.SurveyCreatorMain.class"
             archive="http://www.MyWebServer.com/java/SurveyCreator.jar"
             width="470" height="80">
      <param name=showdebug value="false">
      <param name=lookandfeel value="metal">
      <param name=windowtitle value="Survey Creator by Advanced Survey Software">
      <param name=buttontext value="Start the Survey Creator">
      <param name=startimage value="http://www.MyWebServer.com/java/WelcomeSurveyCreator.jpg">
      <param name=startaudio value="http://www.MyWebServer.com/java/WelcomeSurveyCreator.au">
      <param name=closeimage value="http://www.MyWebServer.com/java/thankyou.gif"> (N/A after Version 2)
      <param name=closeaudio value="http://www.MyWebServer.com/java/closeaudio.au"> (N/A after Version 2)
      <param name=surveytalk value="http://www.MyWebServer.com/cgi-bin/sscar?">
     </applet>

Note: the last param line for web servers running MS-Windows, the sscar cgi needs an exe file extension and should be set to:

      <param name=surveytalk value="http://www.MyWebServer.com/cgi-bin/sscar.exe?">

Once the StartCreator.html file has been edited for your specific directory structure and optional multimedia files, move it to any public accessible area on your website. For optional param definitions, it is recommended that you set a value to "", rather than completely remove it. For example if you do not want to have an startup audio message, set that line to:

      <param name=startaudio value="">

Step 2 -- Copying the StartCreator.html web page to your web server

Use what ever method you are comfortable with to copy the StartCreator.html page to your web server. This file is simply another web page for your web server to publish. If you use FTP to copy the page, it should be transferred in ASCII mode.

Step 3 -- Copying the cgi programs ssweb, ssvws and sscar to the web server

For web servers running the UNIX (ie, AIX, Solaris, Linux) operating system, copy the ssweb.c ssvws.c and sscar.c files to the cgi-bin directory that you will be using to host the cgi programs. Once these file have been transferred in ASCII mode they must be compiled and linked. This can typically be accomplished with the cc command or gcc command. If you do not specify an output file, rename the file a.out after each compile to the appropriate cgi file name. For example:

>gcc ssweb.c
>mv a.out ssweb

or you can use the mak file supplied for example:

>make ssweb

If you receive an error during compilation that io.h could not be found, simply comment this line out by putting 2 forward slashes in from of the line like this:

// #include <io.h>

For web servers running one of the MS-Windows operating environments, copy the ssweb.exe, ssvws.exe and sscar.exe files to the cgi-bin directory. If using the Microsoft IIS webserver, we recommend using the default scripts directory that is part of IIS's basic directory structure, or a similar directory that is a peer level directory to scripts and preferably NOT a cgi-bin directory that is a sub directory of wwwroot (the html root level directory).

Step 4 -- Creating a sub directory in your cgi-bin directory named surveysaid

Create a sub directory in the cgi-bin directory that contains the ssweb, ssvws and sscar cgi programs. This sub directory must be named surveysaid (all lowercase for case sensitive operating systems like UNIX).

Step 5 -- Setting file protection privileges on the surveysaid sub directory

The surveysaid directory needs to have the following privileges set:
For UNIX operating systems

user = rwx (read, write, execute)
group = none
other = none

the command to set these file privileges is: chmod 700 surveysaid

Step 6 -- Copying the SurveyCreator.jar (binary) file to the web server

Copy the SurveyCreator.jar to the directory specified in the <applet code=... tag specified in Step 1. If you use ftp to put the file in the appropriate directory, be sure to set mode to Binary transfer.

Step 7 -- Using the SurveyCreator to create/modify Administrator's profile

The administrator's profile enables a unique user that has the ability to create other users. This profile does not initially exist. The first time you run the Survey Creator you should create the administrators profile. The administrators profile login name is always surveysaid Note: lowercase required on case sensitive operating systems like UNIX.

To run the Survey Creator you will need a Java 2 capable browser (i.e Netscape 6), or the Java 2 plugin for IE 4.x )or later and Netscape 3.x or 4.x browsers. Using a browser, simply type in the URL to the StartCreator.html page on your webserver. For example, type in:

http://www.MyWebServer.com/java/StartCreator.html

where:
www.MyWebServer.com is the webserver with the StartCreator.html page on it.
/java/ is the directory on the webserver containing the StartCreator.html page

If the Survey Creator does not start up almost immediately (on a high speed network) or within a couple of minutes on a dialup connection, check the Java Console for error messages.

When the applet is loaded and running:

Click the Start the Survey Creator button to display the Main Window.
Once the Survey Creator window appears, click the Start button in the
lower left hand corner of the program window which will display the dialog
box User Authentication (used for logging onto system).
When it appears, type in surveysaid in the Enter User Name field.
The first time the Administrator's profile is created, a message box appears
with the message:

Administrator profile does not exist
Would you like to create it now?
Answer Yes to the above question.
Answering Yes will display the Administrators Profile form. Select a
User Description, optional Info 1 and Info 2 fields, and select a password.
When finished click on OK which will display the save user profile window.
Click on OK to save the profile back to the webserver. This should cause the message:

The new administrator profile has been created.
It can now be accessed to logon to Survey Said.

To change the Administrator's profile, logon using surveysaid as the User Name and enter the administrator's password. Once logged on, click on the Administrator button in the lower left corner of the program window. You will be prompted again for the administrator's password to gain access to change the administrators profile.

If you ever forget the Administrator's password, you can simply delete the surveysaid.uaf file in the surveysaid directory and follow the steps above. Be sure the administrator's profile (surveysaid.uaf) always exists for security purposes. If it is deleted, anyone could try logging on as surveysaid and gain access to your Survey Said system by creating the administrator's profile.

Important: If you create the administrator's profile, and then try to logon as the administrator (surveysaid), but get the message:

Administrator profile does not exist
Would you like to create it now?

instead of the Enter password dialog box then there was an error creating the user's profile! This is most likely a directory protection error being imposed by the operating system (or possibly in the webserver cgi directory permissions).

Step 8 -- Using the SurveyCreator to create/modify a user's logon profile

To change a user's profile:

First logon as the Survey Said Administrator using the surveysaid profile.
After logging on as the administrator, click on Manage Users .
Enter the name of the new user profile or the name of the profile to modify.
In "The Profile Name" field, or click on Update to get a listing of existing users.
If a new user's name is entered, a message box will appear that says:

This user profile does not exist.
Would you like to create it now?

Answer Yes to create a new profile.
If Yes is selected or an existing User Profile is opened, the User Profile window will appear. The User Description, User's Directory and User's Password are required fields. Info Line 1 and Info Line 2 are optional. Note: multiple users can have the same directory. This allows for creating groups of users that have access to the same surveys.
Also set the User Privileges for Creating Surveys, Analyzing Surveys, and Answering Surveys. The Answering Surveys privilege is not currently implemented.
When finished, click on OK and the Save User Profile dialog box will be displayed. Click on OK.
You should receive a message that says the user's directory was created. If not read the following:

Important: If you do not receive the message User's Directory Created there was an
error creating the user's profile! This is most likely a directory protection error being
imposed by the operating system (or possibly, webserver cgi directory permissions).
Finally, verify the user's directory has sufficient privilege to save survey files. The user's directory needs to have Read, Write, Execute (rwx) privilege. For UNIX systems, this means you may need to set the user's directory permissions with the command chmod 700 "usersDIRECTORY" while being in the surveysaid directory as the current directory, or you may need to change the directories' owner to the process that "runs" the cgi scripts (i.e. the sscar, ssvws, and ssweb programs).

Step 9 -- Setting the default survey appearance and override options

This is a new feature in Version 4 of the Internet Survey Machine. The SurveySaid login account (Administrator) can set defaults for the overall look and feel for both HTML and JAVA based surveys for all users. These settings can be made mandatory or overridable. Any settings that are made mandatory can not be changed by a user. Any settings that are checked "Overrideble" can be changed by the user. To set the default survey settings and specify whether they are overrideable or not, log into the SurveySaid account and click on the "Global Survey Settings" button. Any of the Overrideable buttons that are unchecked will result in the options be disabled on the users screen, thus making them non-overideable. This will force them to use the settings that are defined by the SurveySaid administrator account.

Setting Default Survey Colors

Setting Default JAVA Parameters