SURVEYOR

INDEX

Installation
Security Issues
Creating Surveys
Activating a Survey
Tokens
DataEntry
Exporting Results
 

1. This script requires the following
• Apache 1.3 or higher (probably will also work in IIS, but this is not tested)
• PHP 4 or higher
• Apache configuration settings to allow security overrides in directories
• MySQL database and permissions to create a database
2. Unpack the files into a directory in your web servers documents folder (such as /htdocs/surveyor)
3. All files except for index.php should be in a subdirectory of this folder called "admin"
4. Ensure that you have read/write permissions in those folders
5. Edit the config.php file:
• set the $databaselocation to the server with your MySQL database on it (usually localhost)
• set the $database port to the MySQL database port (usually 3306)
• set the $databasename to your preferred option (usually surveyor)
• set the $databaseuser to your MySQL username
• set the $databasepass to your MySQL password
   
• set the $homeurl to the web location of your admin script (ie: http://your.domain.name/surveyor/admin)
• set the $publicurl to the web location of your index.php script (ie: http://yourdomain.name/surveyor)
• set the $sitename to your preferred site name (ie: My Really Amazing Survey Site)
• set the $homedir to the actual directory location of the admin scripts on your computer/server. You can use the PHP environment variable $DOCUMENT_ROOT here and add just the directories under your webserver root to make it easier.
• leave the $scriptname as it is unless you change the admin.php script to something else.
• set the $accesscontrol to 1 for security or 0 for no security. Clearly 1 should be your choice unless you have good reasons otherwise. Note that if you are using a non Apache web server, you may as set this to 0, because the security feature is Apache based
• set the $defaultuser to your preferred default username (when the security is initialised) - Note that I recommend that you leave these as they are and then change them later using 'edit users' in the script - for security reasons.
• set the $defaultpass to your preferred default password (when the security is initialised) - Note that I recommend that you leave these as they are and then change them later using 'edit users' in the script - for security reasons.
• set the $siteadminemail to the email address of your preferred site administrator
• set the $siteadminname to the name and/or title of the site administrator
• set the $surveyfaxnumber to the fax number you would like hardcopy faxes returned to
• set the $dropdowns to either "L" for dropdown lists or "R" if you would like radio buttons to display instead of dropdown lists
• set the $maxemails to the maximum number of emails that your server can send within its default timeout setting. Default of 100 relies on a fairly quick and local SMTP server. If your email server is quite slow, this may need to be as low as 10!
• set the $winmysqldir to the location of the mysql binary files (if you are using a windows server)
• DON'T CHANGE THE $os SETTING!
• set the $winapachedir to the location of the apache binary files (if you are using a windows server). If you put the windows htpasswd.exe file in your admin folder, comment out this line.
6. Start your web browser and navigate to wherever your script is (ie: http://your.domain.name/surveyor/admin/admin.php) and the script should take over from there.

This script relies on Apache's web server security system. There is no additional security beyond that. This security is often adequate, however if security is a serious issue for you then you should read up about Apache's security from their website. The author of this software takes no responsibility and makes no claims in relation the appropriateness, or secureness of this software. In short, you should consider this script to be insecure unless you can take steps otherwise.
 

1. Planning a survey
   
   The key to creating an entering a survey using Surveyor is planning. Work out all the questions you will be asking, how they will be answered, and the order in which you want the questions to be asked. Give each question a consecutive number, which you can then use as your question code. Plan the manner in which survey participants will be able to answer questions.
   
    
2. Basic Survey Structure
   
   A survey created in Surveyor consists of the following:
   
   (A) A survey title
   (B) Groups within the survey (there must be at least one group)
   (C) Questions within each group.
   (D) Possibly pre-defined answers.
   
   When you first create a survey, you will be asked for a Survey Title, and a description of the survey.
   
   Before you can add any questions to your survey you must create a group. If you will only have one group in your survey, then how you name this group is irrelevant (except of course for show). If, however, you are going to have multiple groups, you should note that the survey questions will be displayed by group, and the groups will be displayed in alphabetical order. So, if you really need the groups to be displayed in a particular order, consider naming them with an alphabetic start such as "A) Questions about you" and "B) Questions about health". Doing it this way will ensure that your groups are displayed in order. If, for example, you entered the group names as "Questions about you" and "Questions about health", the "Questions about health" group will display first, because alphabetically it comes first. Surveyor is designed to do this deliberately, because it allows you to add extra groups in later, and arrange their positioning by adjusting the title. For example, you could squeeze an extra group between the two by naming it "A1) Questions about your history".
   
   You can create as many groups as you like.

   Groups can also include a "description". This field allows you to publish an explanatory note for any set of questions. If you add a description, then when the public are using the public survey system, they will be presented with that explanation before commencing any of the questions in that group. If you do not include any text here, then public participants will simply move on to the first question in the group with no stop.
   
   Once you have created your groups, you can start adding questions.
   
   When adding a question, you will be asked for a "Question Code", the "Question", "Help" and a "Question Type". All new questions are assigned to the Group you were viewing when you clicked "Add Question", however you can change the group the question belongs too at a later point.
   
   

   • Question Code: Your ID, or number or code for the question. This field is important, because the entry in this will determine the positioning of the question in your survey. Again, numbering this "Q1", and following questions "Q2" and "Q3" will ensure that they appear in the correct order. Using this system allows you to add in extra questions as an afterthought by giving them a code such as "Q1a". Try to be consistent with your coding in this field. Planning makes this process a lot easier.
      
   • Question: This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain the question, leave that for the next field.
      
   • Help: This is an optional field. It is useful if a question needs some explanation, or you want to explain how it should be answered. When you put text in this field, a "Question Mark" icon appears on the survey entry screens, and clicking on this allows the survey participant (or data entry person) to read the help.
      
   • Question Type: This determines the type of response the survey allows. It includes pre-determined options as follows:
      
     • 5 point choice - provides a pre-configured 1 - 5 choice list for questions requiring a 1-5 rating answer.
     • Date - takes date figures. Note that the date must be entered in "YYYY-MM-DD" format.
     • Gender - Provides a pre-configured Male/Female choice
     • List - Allows you to enter a series of pre-determined answers from which the survey participant can choose only one.
     • List with Comment - Presents a series of pre-determined answers from which the survey participant can choose only one, but also provides a comment box for survey participant to explain their choice, or comment on their choice.
     • Multiple Options - Allows you to enter a series of pre-determined answers from which the survey participant can choose more than one
     • Multiple Options with Comments - Allows you to enter a series of pre-determined answers from which the survey participant can choose more than one, and make a comment on each one
     • Short Free Text - a short text field - can take 100 characters.
     • Long Free Text (default) - a long text field - unlimited in size and useful for free text answers.
     • Yes/No - Provides a pre-configured Yes/No choice
     • Array (5 point choice) - allows you to enter a series of pre-determined answers from which the survey participant can rate from 1 to 5
     • Array (10 point choice) - allows you to enter a series of pre-determined answers from which the survey participant can rate from 1 to 10
     • Array (Yes/No/Uncertain) - allows you to enter a series of pre-determined answers from which the survey participant can choose Yes, No or Uncertain as responses
        
    You can create as many questions as you like.
   
   When you have created a question that uses pre-determined answers (ie: dropdown list) you can then add answers to that question.
   
   When adding an answer you will be asked for an "Answer Code", an "Answer" and whether that answer is the "Default".
   
   
   • Answer Code: This is the data that will usually be exported to your spreadsheet when compiling results. You may choose whatever code you want (1 character maximum). Naturally you are limited to around 36 answers per question due to this 1 character limit unless you choose to use non-standard characters.
   • Answer: The answer that will be displayed. Importantly, the order of the answers is determined alphabetically by this field, not by the "Answer Code" field, as previous sections would suggest. One way to control the order in which questions appear is to write them like this "A) 15 years", "B) 20 years" and so forth.
   • Default: One answer from all can be chosen as the default answer (ie: this one will be chosen and entered into your survey results unless it is changed). Change the Default field to "Y" if you want this answer to be the default answer. If you don't choose any default answer the survey result will record nothing if one of the answers is not specifically chosen.
   
   
    

You can test a survey at any point while you are creating it, by choosing the "Test Dataentry" or "Test Survey" buttons in the 'Survey' section of the web page. This allows you to check how the survey looks and feels, before you actually initialise it. When testing a survey your responses will not be saved.

Once you are happy with the structure of your survey you can activate it. Activating a survey does a number of things.

1. It creates a seperate MySQL table to hold all survey responses, and gives each possible answer to the survey a field in that table.
2. It allows people to enter data into that table, and gives you access to other features for the survey, including browse and token facilities.
3. It gives you access to the "tokens" feature. Once a survey is activated, the "tokens" button will be available (see section on Tokens).

Before you activate a survey you should note the following points:

• When the survey is initialised you can change the text for questions, answers, the survey etc, but not the type of question or the type of answer.
• You cannot add new questions or delete questions. Nor can you add answers to any of the array or multiple choice questions.

On many occassions you will want to invite a group of people to participate in your survey, and keep track of who has voted, and ensure that each person can only participate once. Tokens can be setup once a survey has been activated. The tokens feature allows you to do the following:

• Import a list of names and email addresses for participants (from a CSV file) or add/remove individuals
• Generate a unique token number for each participant
• Send an email invitation to each person in your list
• Track who from your list has responded
• Restrict access against people who have not got a token, and those with a token who have already voted.
• Edit/change any details in your list

Once you enable tokens for a survey, then the only people who can access the survey are those who have been issued a token number. Access to the public script will rely on the participant being able to provide their unique token id.

Tokens do not enable you to draw any link between the survey reponses provided and the identity of the person who completed it. When a survey is submitted by a participant, their data goes into the specific survey table without any token id, and their token is updated in the token table simply with a "Y" to indicate that they have completed the survey.