VTSurvey

Documentation

The software is offered under GNU LGPL. It has been tailored for the Virginia Tech community. Therefore you may have to do a number of changes to adapt it to your needs. Because of our limited resources we cannot give any support for the installation of required middleware or the survey software itself. However, you could try the discussion forum or if you find bugs or have recommendations for improvements please use our bug reporting tool or feature tracker.

How to use VTSurvey

Just follow the User's Guide for survey.vt.edu.

Installation Instructions

VTSurvey is a pretty flexible and customizable application. However, we strongly recommend that you closely follow the installation instructions using the defaults shown below. After the application is up and running you can adapt the installation to your needs.

If you update from a previous version please follow the updating instructions, otherwise just read on.

Step 1: Install Java application server

VTSurvey is a 100%-Java compliant application and should work with any Java application server that supports JDK 1.4 (JDK 1.3 does not suffice since it does not support regular expressions). If you don't have one yet, we recommend to install the free Apache Tomcat server. The Tomcat server is a Java application itself. Therefore you may have to install Sun's JDK 1.4 before you can run Tomcat.

In the following we assume that you don't have anything installed yet. Otherwise just jump steps as appropriate.

Microsoft Windows

Download and install Sun's Java 2 Standard Edition, SDK 1.4 (J2SE SDK), Version: "Windows (all languages, including English)" (install in folder e.g. "C:\j2sdk1.4.2_08", use defaults)
set the JAVA_HOME environment variable to the folder that you installed Java in, e.g. "set JAVA_HOME=c:\j2sdk1.4.2_08"; You should make this a permanent setting by adding JAVA_HOME as an environment variable; e.g.: in Windows XP through Control Panel/(Performance and Maintenance/)System/Advanced/
Environment Variables/
System Variables/New" (do not have a trailing backslash or semicolon at the end)
Download and install Tomcat (e.g. jakarta-tomcat-4.1.31.exe); if the previous link does not work check out the offical Tomcat website: (install Tomcat into a folder called "\usr\local\tomcat\")

Unix (Linux, Solaris, etc.)

Download and install Sun's Java 2 Standard Edition, SDK 1.4 (J2SE SDK) for your platform (use defaults)
set the JAVA_HOME variable to the folder that your Java installation is located in
Download and install Tomcat (e.g. jakarta-tomcat-4.1.31.tar.gz); if the previous link does not work check out the offical Tomcat website: (install Tomcat into a directory called "/usr/local/tomcat/")

Step 2: Download and install Survey application

Download the latest release of VTSurvey
Unpack vtsurvey-<version>.zip: Under MS Windows use WinZIP or any other "unzip" software. Under Unix just type "unzip vtsurvey-<version>.zip"
Copy survey.war into the Tomcat "webapps" folder (typically "/usr/local/tomcat/webapps/")
Create a folder called "/usr/local/survey/" and copy the data folder into it (If you use MS Windows please make sure to create this folder on the same drive letter, e.g. C: or D:, that tomcat is running on); Make sure the user running tomcat has full read/write permissions on this folder
Now you should have a folder "data" inside "/usr/local/survey/" ; this folder should contain folders called "emails", "surveys", "messages",and "users", which themselves contain a number of other files. The folder "data" stores all the application data (survey responses etc.) in the form of XML files. Survey does not require a database.

Make sure that you have the following directory/file structure:

/usr/local/survey/data/emails/ (empty folder)
/usr/local/survey/data/surveys/surveyEntryForm.dtd
/usr/local/survey/data/surveys/surveyMetaData.dtd
/usr/local/survey/data/users/user.dtd
/usr/local/survey/data/users/admin/admin.xml
/usr/local/survey/data/messages/dutch.xml
/usr/local/survey/data/messages/french.xml
/usr/local/survey/data/messages/german.xml
/usr/local/survey/data/messages/italian.xml
/usr/local/survey/data/messages/messages.dtd
/usr/local/survey/data/messages/portuguese-pt.xml
/usr/local/survey/data/messages/serbian.xml
/usr/local/survey/data/messages/serbian_cyr.xml
/usr/local/survey/data/messages/spanish.xml
/usr/local/survey/data/messages/swedish.xml
/usr/local/survey/data/messages/usenglish.xml

If you want to keep the data in a different folder you will need to edit the appDataDir parameter in web.xml (see Step 4).

Step 3: Start & Test

Start Tomcat: Under MS Windows run "startup.bat" in the "\usr\local\tomcat\bin\" folder. Under Unix run "/usr/local/tomcat/bin/startup.sh". Tomcat will startup and unpack the contents of survey.war. It will create a folder called "survey" inside of the folder "webapps".
Inside of "survey" there will be a folder called "src" which you can delete if you want to avoid that your users can view the source code of the application
VTSurvey should be up an running by now. By default, Tomcat listens on port 8080. Therefore you will probably have to enter something like http://localhost:8080/survey/ in your web-browser in order to verify that the application is running. If everything is correctly installed you should be able to login as "admin" (default password is: "adminpass"; change the admin password as soon as possible). Using the admin password you can login to ANY user-account. This is handy for the helpdesk staff but also dangerous. Therefore, your admin password should be very strong.
If you logged in successfully you can proceed to tailor VTSurvey to your needs.

Step 4: Tailor Survey to your needs

Shutdown Tomcat: Under MS Windows run "shutdown.bat" in the "\usr\local\tomcat\bin\" folder. Under Unix run "/usr/local/tomcat/bin/shutdown.sh".
The file "/usr/local/tomcat/webapps/survey/WEB-INF/web.xml" contains all the customization information for VTSurvey along with some documentation.
Apapt at least the following parameters to your needs:
- acceptableUsePolicyURL
- adminEmail
- emailFrom
- hostName
- serviceName
- serviceProvider
- smtpHost
Edit header.jsp and footer.jsp according to your needs
Change the graphic images/createdwith.gif according to your needs
(Re-)Start Tomcat: Under MS Windows run "startup.bat" in the "\usr\local\tomcat\bin\" folder. Under Unix run "/usr/local/tomcat/bin/startup.sh". Your changes should take effect.
If you want to use the LDAP integration for authentication and you are running into problems connecting to your LDAP server, you may want to enable debug messages by modifying the file WEB-INF/classes/log4j.properties

(Step 4.5: Internationalization)

If you want to run for example the French version of VTSurvey you can do so by just changing the web.xml parameter "languageFileName" to "french.xml"
If you encounter problems with certain characters you may also want to change the web.xml parameter "xmlEncoding"
(Re-)Start Tomcat
If you would like to use VTSurvey in another language you can also create your own language file, e.g. afrikaans.xml
Send it to us and we will include it in the next release

Step 5: Have fun :)

Replace the survey.war in your tomcat directory with the current version (and remove existing un-packed versions)
Try out VTSurvey at: "http://your_host_name/survey/", e.g. http://localhost:8080/survey/

Updating from previous versions

Replace the following files within your data folder with the new versions:
surveys/surveyEntryForm.dtd
surveys/surveyMetaData.dtd
users/user.dtd
messages/* (all files)

http://vtsurvey.sourceforge.net/
Last modified: April 11, 2005

web hosting kindly provided by