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 System Administrator can select from a number of project configuration options on the administrative pages after the project has been deployed on a web server. Generally, you should set the options for your project before announcing the survey to the respondents, but you can change the settings after the project is running.

The picture below shows a sample Project Default Settings page. You can click on the items on this picture to learn more about each setting.

Project name

The project name is take from the name of your source QPL questionnaire program (i.e., the .pg6 file). The name is also used to name the MySQL data base that supports this project.

Last update

This date shows when any of the default project settings were changed. (Clicking on the Cancel button abandons any changes you may have made on the page and returns to the main administrative page. It also shows the release date of the QPL software that is running on the site.

Author

You may enter the name of the project author here.

If you will be letting respondents create their own accounts (see Login options), you may enter your email address here and a confirmation email message will be automatically sent from your address to a respondent when he successfully creates or updates his account.

If you are sending the questionnaire embedded in an email message, you may also set this field to your email address to let the system automatically send a confirmation email message to the respondent when the respondent submits his data from the email message.

Title and Subtitle

The title and subtitle fields are automatically filled in with the title and subtitle that the questionnaire author used in his source questionnaire program. Any changes made to the titles here will be used to change the titles on the first page of the questionnaire, the closing page (which is displayed after a respondent exits a questionnaire), any Notice pages, and all the administrative pages. It does not, however, change the titles used on the project home page (i.e., the index.htm file).

The Title will also be used as the Subject line of a confirmation email message to a user who has just created his own account.

Login

The system can be set to use one of three log in procedures:

Option Comment
No account required (Anonymous) Anyone will be allowed to respond to the questionnaire. No log in page is displayed to the respondent and no user information is collected (unless you ask specific questions as part of your questionnaire). A respondent must finish the questionnaire in one sitting; he cannot reopen his questionnaire and update the responses later. A new blank questionnaire is always displayed. All questionnaire records entered using this setting will be given the same user name: "anonymous."
User may create an account A log in page will be displayed to the respondent. If the user name that he enters is not already listed in the system, he will be prompted with another page that asks him to enter his full name, email address, day-time telephone number, and the password that he wants to use when accessing this questionnaire. He can use this user name and password to re-open and edit his responses again later. The user name he enters will be used to identify his questionnaire record.

A syntactically correct email address with a valid domain must be entered before an account will be created.

An email message can be sent automatically to the user after he creates an account that contains his account information, including his user name and password. See Confirming New Account Information for more information.
User must have an account A log in page will be displayed to the respondent. He must enter a user name and password that has already been loaded into the system. He will not be given access to a questionnaire unless a correct user name and password are entered. User accounts may be created using SQL scripts or by adding new accounts using the New function on the Edit User List page. His assigned user name will be used to identify his questionnaire record.
User may login directly from URL If this checkbox option is selected, you may include a respondent's account information in the URL so, when the respondent clicks on the link, he will be automatically logged into his copy of the questionnaire. Respondents and administrators may still log in starting at the home page and then the log in page. If this checkbox option is not selected, then logging in via a URL is not allowed. See Logging In Using URL Options for more information.

Data Entry

The system can be set to let the respondent only access one questionnaire or more than one questionnaire.

This setting and the anonymous log in setting above may not be used together since the anonymous setting always causes a new case to be created.

Option Comment
User may edit only one case The respondent may only edit one questionnaire. This questionnaire will be displayed immediately after he logs in.
User may edit multiple cases After the respondent logs in, a new page will be displayed that lists all the questionnaires to which he has access. This includes all the questionnaires that he created and it can include cases created by other respondents if they both have been assigned to the same respondent group.

New Cases

This system setting is only used when you need to let a respondent edit more than one questionnaire.

Option Comment
User may create only one new case If a respondent has not created a questionnaire record yet, then a new one will be created the first time he logs in and that questionnaire will be opened. If the respondent has only one questionnaire record, then that questionnaire will be opened after he logs in (and he will not have an opportunity to create new cases). If the respondent has more than one questionnaire record (because multiple records were pre loaded into the system for this respondent before the project was launched), a list of questionnaire records will be displayed on a new page and the respondent may pick one to edit.
User may create multiple new cases If a respondent has not created a questionnaire record yet, then a new one will be created the first time he logs in and that questionnaire will be opened. If the respondent has one or more questionnaire records, then a list of questionnaire records will be displayed on a new page and the respondent may pick one to edit. This list also will display a "New" option at the top of the list which will let him create a new questionnaire record.

Authentication

If the survey is not anonymous, you may specify how a respondent's identity is checked.

Option Comment
Normal The respondent must enter a user name and password that matches user account information that was previously loaded into this system (or previously created by this user if users are allowed to create their own accounts).
LDAP This option generally used only for surveys of an organization's intranet users where each respondent's user name and password may be checked using the Lightweight Directory Access Protocol (LDAP) protocol. You must update the LDAP settings in the qpl_config.inc file with your organization's LDAP server settings. Also note that PHP support for LDAP is not enabled by default. You will need to use the --with-ldap configuration option when compiling PHP to enable LDAP support.

In GAO, for example, this option may only be used for internal GAO applications. Here, the respondent must (1) enter a user name that matches account information that was previously loaded into this system and (2) a user name and password that matches a GAO network user account. If respondents are allowed to create their own accounts, this option will automatically create an account for a respondent if the user name matches a GAO network account.

A respondent's user name and password are only authenticated on the LDAP server if the password in the respondent's account for this project is blank. If a password is set in the respondent's questionnaire account, then that password will be used to authenticate the respondent instead of the LDAP server.

Case Identification Question

This option is only used when you allow respondents to edit multiple questionnaires, or will be using a Super User account to edit multiple questionnaires.

You can use this option to specify how respondents will pick from the available cases that are presented in the selection list page. If you do not specify a particular question, the cases will be listed according to a built-in case identification number. You may instead specify the name of a question and the current answer for each case will be shown in the selection list. For example, if one question asks for the respondent's name in a question called "NAME," you could enter NAME below and the list will show the case by whatever has been entered in each name question for all the available cases.

Log File

This option controls whether a record is kept of all the major transactions with the questionnaire. If the "On" option is selected, transactions will be recorded in the log table for this project in the MySQL data base. The "Off" option stops recording transactions.

This option must be set to Off in order to use the Purge History Log function on the main administrative page.

Recent log file entries may be viewed using the available View Recent History Log and View Custom Log Report functions on the main administrative page.

Maximum Failed Login Attempts Allowed

By default, respondents and administrators have ten opportunities to log in using the correct password. After this, a respondent will not be allowed to log in until the Total failed login attempts count is reset to zero for their account.

If a respondent logs in correctly before the limit is reached, his failed login count will be reset to zero.

You can change the maximum to 1 to 255 maximum failed attempts, or to 0 which lets the user have unlimited failed attempts.

Expiration Date For User-Created Accounts

The date entered here will be used to set the expiration date on a new user account when (1) a new respondent logs in the first time and (2) the User may create an account log in option has been selected on this page.

Generally, user accounts should be set to expire when your data collection period ends. If a respondent attempts to log in after his account has expired, a Notice page will be displayed that says when his account expired and who to call if he has any questions.

A respondent's account will never expire if his expiration date setting is blank.

Administrators and Data Administrators may change the expiration date for individual accounts after the project is deployed using the Edit User Account pages.

The System Administrator may change the expiration date for all the accounts after the project is deployed using the Reset Expiration Dates function on the main administrative page.

Maximum Time Allowed For Individual Sessions

QPL questionnaires use "sessions" to keep track of who is currently logged in to which questionnaire, and when he logged in. If a respondent moves from one page to another in your questionnaire, the incoming session information is checked to determine if this submission is from a valid user and, if so, what data record should be updated, and then a new session is issued for the next page. When the respondent logs out properly the session information is deleted.

In order to prevent unauthorized access, submissions with invalid session information are rejected.

To improve your questionnaire's security further, you can (and should) limit the time for which a session is valid.

Normally, the session time should be limited to two hours.

Putting a time limit on sessions is especially useful if your project lets respondents share cases. If one respondent fails to close a case properly it can not be used by other respondents because it is listed as "Being edited." An administrator can use the Release being edited cases function to reset these cases to "Available" if the session of the last person to edit the case has expired.

User Name and Password Size

The default minimum size for user names and passwords is 5 characters.

These settings are used to test user name and password entries when (1) a respondent is using the log on page and (2) an administrator is adding or modifying a user account.

If you load user accounts via an SQL script, you should make sure that no user names or passwords are smaller than these settings. (This information should also be in all lower case letters, though an administrator or respondent may enter his log in information in mixed case.)

URL for Starting Page

If you enter the full URL to your project's home (index.htm) page, the system will check that submissions from a respondent were to a page that was sent from your web site (and not from a locally saved copy of a page or other web site). This is an extra security measure that you can implement to make sure that the only way to submit data to your project is by getting a page from your web site with an authenticated session identifier.

If this field is blank, this information is not checked.

Note that this is not a completely reliable security method because some browsers do not return this information. (This is the HTTP_REFERER field in the HTTP header returned by a browser when the respondent submits a form.)

Assistance Note for Notice Pages

This setting is used to put information about who to call or write with questions on (1) the pop-up help box in the questionnaire, (2) any Notice (error message) pages, (3) the closing page, (4) a confirmation email message to a respondent who has just created their on account, and (5) a confirmation email message to a respondent who has just submitted their data from an emailed version of your questionnaire.

You can use HTML codes to format this information, as in the following example.

If you have questions, please contact<br><br>

John Smith<br>
<a href="mailto:smithj@gao.gov">smithj@gao.gov</a><br>
202-512-1111

Where Clause for Questionnaire Summary Statistics Report and the Export Data and Content Analysis Functions

You may enter a MySQL WHERE clause to control what cases are included in the Questionnaire Summary Statistics report and the Export Data and Content Analysis functions. By default, it contains a clause that excludes all cases that were created using a test account. You may modify this clause to further refine the selection using any of the system or questionnaire program variables in the data table.

Where Clause for Custom Log Report

This MySQL clause controls the log entries that are selected for the View Custom Log Report function on the main administrative page. By default, it contains a clause that only selects log entries for test accounts. You may modify this clause to using any of the system variables in the log table. Often, you will want to change it so that it selects all the log entries for a particular user who may have difficulty using the system.

q_uname LIKE 'smithj'

Log Table Fields

Name Type Comment
q_uname VARCHAR(50) Respondent or administrator user name.
q_id INT UNSIGNED If greater than zero, then it holds the id number of the case that was edited in the data table.
q_comment TEXT Short note about the respondent or administrator action, such as "Recall existing questionnaire at section 41."
q_date TIMESTAMP The date and time when an action occurred.

Select Statement For Custom Reports

The custom report fields let you write any SQL SELECT statement and generate a report when an administrator clicks on the View Custom Log Report function on the main administrative page. The SQL keyword "SELECT," is automatically prepended to your statement. You just enter the rest of the query. (This prevents you from accidentally writing a query that could unintentionally alter the database!)

The Short Report displays the results of the query in one table, with the fields you select as columns and the records as rows. This layout is useful if you are only listing a few columns.

Short Report Layout

The Long report displays the results of each record selected in separate tables, with each field name and its contents listed on separate rows. This layout is useful if you are listing many fields, or fields that have long text values.

Long Report Layout