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 Edit Message page lets you write a message template and specify the sender and receivers of the message. Click the "Test" button at the bottom of the page to test your settings and, if no errors are found, go on to submit your message job to the mail queue.

An example message template is shown below. Click on the headings on the left for more information about that item.

Creator

The administrative user account name of the person creating this message is automatically entered here.

Subject

Enter the subject line for your message. (Limit 80 characters.)

From

Enter the email address of the person who is sending the message. (Limit 120 characters.) Only one address may be entered. This address will appear in the respondent's mail box and on the message.

You may use a "friendly" name in your email address by putting the friendly name first inside double quotes and the email address second inside angle brackets.

Example of a Friendly Address Format

"John Smith, MyCorp Inc." <smithj@mycorp.org>

Example of a Simple Address Format

smithj@mycorp.org

Reply To

Enter the email address of the person who should receive any replies to a message sent to a respondent. (Limit 120 characters.) Only one address may be entered, and it should be entered using the simple format.

This may or may not be the same address as used in the From: line. (At GAO, we generally send messages "From:" someone important and direct the responses to someone who is actually working on the project.)

Return Path

Enter the email address of the person who should receive notices about undeliverable messages. (Limit 120 characters.) Only one address may be entered, and it should be entered using the simple format.

This address may or may not be the same address as used in the From or Reply-to: lines.

The query below that is used to generate the list of email addresses only checks the addresses for syntax errors. Addresses that are syntactically correct will be used to send messages but, if an address is invalid, the message will be returned to this address with notes about why it was undeliverable. Addresses that are not syntactically correct will not be used to create an email message.

Text Message

Enter the text of your message here. (Limit 64K.) No special formatting may be used and the lines in the message will be wrapped just as shown in the text box.

Embedding Data

You may customize the text message with data from the respondent's user account or questionnaire. Put the field name in the message where you want the data to appear, preceding it with a curly brace and dollar sign, "{$," and following it with a curly brace "}." No spaces should be used.

Dear {$q_name},

In this example, {$q_uname} will be replaced with the respondent's name when his email message is created, such as "Dear John Smith" ("q_uname" is the name of the Full Name field in the user account database table. See a list of user table fields below.)

Field names are case-sensitive. All of the built-in database field names should be written using lower-case letters. All of the names you used in your questionnaire program must be entered here using upper-case letters. You should match the case of new fields you create in your query when using column aliases to combine or recode existing fields.

You may embed any number of fields into your message template, but you must also specify what fields your using when building your database query for this template. (See Query below.)

HTML Message

Enter an HTML-formatted message here. (Limit 64K.)

Entering an HTML-formatted message is optional. If none is entered, only the text message above will be used. If an HTML message has been entered, both the text message and HTML message will be used in the message template. The HTML version of your message will be displayed to the respondent unless his or her email reader is unable to display HTML-formatted messages (either because it is an old email reader or because this feature was turned off).

The contents of the text and HTML-formatted messages may be the same or different. If you are sending the questionnaire itself as the HTML-formatted message, they will necessarily be different. (See Sending Your Questionnaire as an HTML Message for more information.)

Embedding Data

You may embed data from a respondent's user account or questionnaire as described above. (See Text Message.)

Using Links

There are two main areas of concern when using links in your HTML message.

1. Have the linked files been put on the web server?

Linked files, such as graphics and style sheets, are not sent with the message. They are opened from across the Internet after the email file has been delivered to the respondent and while it is being rendered in the email reader's browser window.

You must upload any files used by your message to your web site before sending it.

2. Are the addresses of the linked files correct?

Since your message will be opened from your respondent's mailbox, not your web server, using relative addresses for linked files will not work.

You must either use the full URL for each linked file or use the BASE tag in the HEAD section of your HTML document to change the default URL address from the respondent's PC to your web server.

Using the BASE tag is the easier since it lets you build your HTML page locally on your PC, using relative links to your files which are usually located in the same directory as your QPL project files. The BASE tag will be automatically set to your project's web site location if you follow the guidelines below. Or you can explicitly set the BASE tag to another web server location. In this case, it will not be changed when you send your message job to the mail queue.

<BASE> Tag

Use the BASE tag exactly as shown below in the HEAD section of your HTML file, including the comments.

<!-- <BASE href=''> -->

Since it is commented, it will not affect your development of your message while working locally on your PC. And you can use relative links to any graphic images or style sheets that you have stored in the same directory.

When you later paste your HTML file into the HTML Message text box here and click on the "Test" button to build your message job, the BASE tag will be changed to (1) remove the comment markers and (2) insert the URL for your web site. If you have copied all of your linked files to your questionnaire web site, then they will be correctly addressed when a respondent opens your message in his browser.

A sample HTML email template, qpl_sample_letter.htm, is put into your QPL project directory every time you start a new project, and demonstrates how the BASE tag should be used.

Query

Build an SQL query that will (1) get the data for the fields that your are embedding into your message and (2) select the respondents that will get messages.

By default, the query is set to send email messages to all user accounts, including administrators and test accounts, that have valid email addresses. It also always gets the user name and email fields (q_uname and q_email) from the user account.

Selecting Data Fields

You must modify the upper text box to add other data fields if you used them in your message. Each field name must be separated by a comma. You may use column aliases to combine or recode existing data fields so they are more readable in your email message. For example, multiple choice questions are coded as integers in the data base, so these should be recoded with labels if you need to use an answer in an email message.

user.q_name, ELT(Q37, 'Yes', 'No') AS FINISH, DATE_formAT(NOW(), '%M %e, %Y') AS DATESENT

In this example, three fields are selected from the data base:

  1. The respondent's name is selected from the user table using the standard field, q_name. You would embed this field into your message template as {$q_name}.
  2. The respondent's answer to question Q37 is recoded using labels instead of numbers. The recoded answer is named FINISH. You would embed this field into your message template as {$FINISH}.
  3. The MySQL NOW() function is used to get the current date, formatted using the DATE_formAT function, and then the result is named DATESENT. You would embed this into your message template as {$DATESENT}.

Selecting Data Tables

The radio buttons in the middle are used to specify whether you will be using only user account data for your mailing or both user account and questionnaire data. By default, only user account data will be used (which is stored in a table called "user"). Generally, you would select this first option when you want to send a message to everyone who has a user account.

If you want to target email messages according to certain answers respondents gave in the questionnaire, select the second option. This option matches user accounts with questionnaire data (which are stored in a table called "data,"). It will only select respondents who have (1) a matching questionnaire record that (2) meets your other search criteria.

The third radio button is used when you want to send email messages to people who have never logged in (and you have not preloaded respondent records into the data table). This option identifies the user accounts of respondents who have no data records.

Setting Retrieval Criteria

The lower text box is used to select the respondents who will get messages. If you only want to send messages to non-respondents, according to a particular answer in the questionnaire, you would first check the second radio button to include the data table in your query and then add the condition that identifies non-respondents, such as "Q37=2," where Q37 is a multiple choice question that asks if the respondent is finished and the second response item is "No."

The following tables list built-in user and data table variables you may use in your queries. In addition, you may use your question names in your queries. In this case, you should view the job.sql script that was generated when you built the PHP version of your project. This will show how each of your questions was defined in the data table.

user Table Fields

Field Comment
q_unameUser name.
q_pswdPassword.
q_nameFull name.
q_emailEmail address.
q_phoneTelephone number.
q_otherComments.
q_groupGroup code (default is "NONE").
q_user_statusUser account status (0=account closed, 1=normal user, 2=super user, 3=admin, 4=data admin, 5=sys admin).
q_num_bad_loginsNumber of failed log in attempts.
q_expireDate this account expires (never expires if NULL)
q_midId number of the last email message sent to this user.
q_submitted_whenDate and time the last email message was sent.
q_submitted_countTotal number of email messages sent to this user.

Standard data Table Fields
(Additional fields may be added from your questionnaire.)

Field Comment
q_idId number of the questionnaire data record.
q_unameUser name of user who created the record.
q_groupGroup code of user who created the record.
q_last_edit_byUser name of the user who last edited the record.
q_atqLast question touched.
q_atsecLast questionnaire page touched.
q_availableFlag indicating whether record is currently being edited (0) or available for editing (1).
q_remote_addrIP address of last user (usually blank).
q_http_user_agentDescription of user's browser and operating system.
q_fromEmail address of user (usually blank).
q_javascriptUser's version of JavaScript.
q_updatedDate and time the record was last updated.

Delay

Specify how long your message job should wait in the mail queue before messages are created and sent. The default delay is one hour, but you may change it to have no delay or extend the delay up to two weeks.

Messages jobs in the mail queue may be recalled if mailing has not begun. (See Save/Recall below.)

The message job will be started (i.e., the query is run and then used with the message template to build and send individual messages) when the delay has passed and the mail queue is checked for eligable jobs, usually every hour or half hour. How often the mail queue is checked for eligable jobs is set by your web server administrator when he or she set up the server for QPL projects. (See QPL formation information.

The mail queue also only sends up to 500 messages at one time. If your job (or others that are also in the queue) generates more than 500 messages, the remaining messages will be sent the next time the mail queue is checked for eligable jobs.

Attachment

Enter the name of your attachment file here. Only one file may be attached to a message job and the file must be uploaded to your project web site before the message job may be sent to the mail queue. Also, if you are using a Linux server, you must use the same letter-case as was used when copying the file to the server.

If you need to send a large file, such as an Acrobat PDF file, it is often better to put a link to the file in your message or project home page (i.e., index.htm) instead of sending it as an attachment. This way, respondents with slow dial-up connections can choose when to get the attachment.

Comments

Enter any notes about this message here. These comments are not used to build your message job. They are usually used to document anything unusual about the job or to explain how the query works.

Save/Recall

Click the "Save" button to save any changes and return to the Select Message page.

If you have submitted this message job to the mail queue, this button will be relabeled "Recall." If the mail queue has not started processing the message job, you can cancel the job by clicking the "Recall" button.

Recalled messages may be edited, tested, and resubmitted to the mail queue.

You may not save changes to message jobs that have been submitted to the mail queue. You may, however, use the "Copy" button to make a copy of this message and then modify and send that new message.

Test/View Log

Click the "Test" button to run various tests on your message job. The results of the tests will be displayed on the Test Message page.

If you have submitted this message job to the mail queue, the button will be relabeled "View Log." If the mail queue has started processing this job, you may click on the "View Log" button to view a list of all message recipients and when each message was sent.

Copy

Click the "Copy" button to make a copy of this message job. All of the settings will be copied to new message job, and sequence number will be appended to the end of the Subject line. You may then modify, test, and submit the new message to the mail queue.

Cancel

Click the "Cancel" button to abandon any changes you may have made and bo back to the Select Message page.

Print

Click the "Print" button to print this page.