2009-08-03
QPL Reference Manual

Warning! This page is in the process of being rewritten for QPL Version 6. It may still have references to QPL Version 5.

The following table summarizes many key issues that you need to consider before putting your questionnaire project on a web server.

Issue Question Comments
URL What is the name of your web site? Usually, the name will be directory off of your main web site address, such as "websurveys.gao.gov/nasasurvey." Generally, you should avoid using spaces and underscore (_) characters in your address. Linux does not support directory names with spaces and underscores are hard to see if you put the URL in an hypertext link which underlines the whole address. (Note: Each QPL project should be loaded into a separate directory on your web server.)
Security How will respondents access your questionnaire? The QPL administration screen gives you several options:

(1) Anonymous. No user name or password is required, but respondent can not re-open their responses later.

(2) Semi-anonymous. Respondent can create their own user name and password and can use this information to re-open their responses.

(3) Not anonymous. Respondents must use predefined user names and passwords.
Authentication How will user names and passwords be tested? The QPL administration screen gives you two options:

(1) Normal. When any type of user logs in, their user name and password will be checked against the entries in the project user table. These accounts are created either interactively using the administrative project pages or by writing an SQL script that loads the accounts.

(2) LDAP. You can let users log in using the account name and password they use to log into their organization's network if the organization maintains a public Lightweight Directory Access Protocol (LDAP) directory. Typically, you will only use this option when performing an intranet survey within an organization which has set up LDAP access to its network directory services (NDS).
Access Can the respondent access only one or multiple questionnaire forms? The QPL administration screen lets you specify whether respondents may only access one form or may select among two or more forms to which they have access rights. Respondents always have rights to forms that they have created. You may also let respondents share forms by also giving them group rights. Then all the respondents in the same group can access forms that were created by any member of the group.

If you allow respondents to access multiple forms, you also need to tell the respondent how to pick from the case from which they have access. By default, the QPL case selection page lists cases according to the internal data base record number. You can changes this to something more meaningful setting the administrative project option "Case identification question" to a question in your questionnaire that uniquely identifies each case. Then case selection page will list the current contents of this question in the list of cases.
Help Who should respondents call if they have questions? The QPL system provides several places to put help desk names, phone numbers, and email addresses:

(1) Home page. The project home page, "index.htm," is created when you build the web version of your project. You should edit this page to add welcoming information and information about who to call if problems occur. (This page is called "hello.htm" when you build the local test version of your project. If you edit this page, you should copy the narrative you added to the index.htm file when your ready to deploy your project. You cannot rename the hello.htm page as index.htm. How the home page launches the questionnaire is different for your local test environment and your web server.)

(2) Notice pages. You should insert your help desk information as an HTML snippet in the QPL administration project settings page. This snippet will be automatically inserted (a) in the page that is displayed when the respondent properly exits your questionnaire (b) any "Notice" pages that may be displayed if a system error occurs, and (c) the pop-up help page that is displayed if the respondent clicks on the question mark button on the navigation bar.
Accounts Who should get what sort of access to your questionnaire? The QPL system lets you create two types of user accounts:

Respondents

These are the people who will can view and edit one or more questionnaires. There are two types of respondent accounts:

(1) Normal users. These typically are your respondents. These users can view and edit one or more questionnaire forms according to how you have set the project access rights and any group rights you have given to their accounts.

(2) Super users. These are typically project supervisors. These user can view and edit all the forms. A super user can access any questionnaire regardless of the access setting and group rights.

Administrators

These users perform various tasks to support the operation of the questionnaire project. These users do not see the questionnaire. Instead, these users see pages that summarize the activity on the project and allow changes to be made to the project and user account settings. Three types of administrative accounts are available:

(1) Administrator. This is the person who is managing the respondent help desk (i.e., the person respondents call if they have problems.) This administrator can create and edit normal and super user accounts, close accounts, change account expiration dates, reset the failed login count for accounts, release "being edited" cases,and view summary project statistics.

(2) Data Administrator. This is the person who is responsible for analyzing the responses. This administrator can perform all of the above tasks, plus create Administrator accounts and export the data from web site. (Note: This is usually the QPL questionnaire author since this person has the software needed to decrypt the exported data files. See Data Analysis for more information.)

(3) System Administrator. This is the person who builds the web site. This administrator can perform all of the above tasks, plus create Data Administrator accounts, run various system maintenance functions, and set all of the project options. One System Administrator account, called "admin," is always created for each project. System Administrator accounts may only be created by writing an SQL script.
Expiration When will user accounts expire? You should specify the date when each user account will expire. After this day, a respondent who tries to access your project will be shown a Notice page that tells them that their account has expired. It will also display your help desk information if you entered it on the administrative project settings page. You can change an individual respondent's expiration date using the administrative user accounts page. You can change some or all of the respondents expiration dates by writing an SQL script.

If you are allow respondent's to create their own accounts, you can use the administrative project options "Expiration date..." to set the expiration date for these accounts. (Note: This date only affects new accounts, not user accounts that were already existing.)
Log-in Failures How many log-in failures should the system allow? By default, QPL will allow each respondent ten log-in failures (i.e., entering the wrong password) before it automatically closes the account. You can change this number on the administrative project settings page. You may reset a user's log in failure count to zero, if necessary, using the administrative user account page.
Session time When should a respondent's connection to a questionnaire be terminated due to inactivity? QPL maintains an internal session id (instead of a "cookie")that is used to validate users as they move from page to page in your questionnaire. The session id is automatically deleted when the respondent exits properly.

By default, this is set to never expire. You should, however, set this a relatively short time, such as two hours. In this case, if a user has not moved to a new page or properly exited from the questionnaire after two hours, the connection will be cancelled and the respondent will need to log in again. This is an important security measure that is intended to prevent unauthorized access to your project.

The session time setting is also important when your respondents are sharing cases. If one respondent has a case open, no other respondents may open that same case until the first respondent exits properly. This prevents two users from editing the same case at the same time. If the first user fails to exit properly, other users cannot access the case until (1) the first user re-opens the case and exits it properly, or (2) the session for that case has expired and the project administrator as run the "Release being edited cases" function on the administration screen.
User names and passwords How long should user names and passwords be? By default, QPL requires user names and passwords to be at least 5-characters long. You can change the settings from 3 to 50 characters on the administrative project settings page. Respondents may enter their user names and passwords using upper or lower case letters.
Notification How will respondents know when the questionnaire is available and what user names and passwords to use? While respondent notification is not strictly part of the QPL system, a sample Perl script and template email letter are provided here that you can use to create individualized email letters to each respondent. This Perl script reads a list of email addresses, user names, and passwords and sends a customized email message to each respondent. The message should also contain the URL link to your questionnaire web site.

This Perl script is designed to be run from a web server using the Unix send_mail utility program.

See the QPL Email page for more information.