Field management

E-mail notification

The cwemail module sends initial notification and reminders via e-mail. It uses a question as a template which may include recalls of values stored in the survey data base (probably via pre-population). It features tools to select subsets of cases according to any data in the data base as well as subsets defined by ranges of position numbers in the data set. Therefore, it is possible, for example, to send an initial invitation to all participants which includes their custom access code and which is delivered in their preferred language, and to follow-up with those who have initiated but not completed the questionnaire a week later with a motivational message which could be different from another follow-up to those who have not accessed the questionnaire at all.

E-mail notification is based on a special questionnaire variable which contains the title and text of the message to be broadcast. The following rules apply:

  • the type code EMAIL must be listed on the line of the script containing the question name;
  • EMAIL-type questions do not use the language codes; if language-specific messages have to be sent, create as many EMAIL questions as there are languages and select cases to broadcast to according to a language indicator;
  • the body of the question text contains the subject line of the message;
  • the note part of the question text contains the body of the message to be broadcast;
    • paragraphs must be noted by <P> codes while simple line breaks are signified using <BR>;
    • cwEmail reformats the message to create lines of 65 characters or less while respecting paragraphs and line breaks;
    • an HTML version of the message may be inserted between <HTML> and </HTML> tags; the HTML coding must be adequate and complete — CallWeb does not validate it. It is recommended that a plain text version of the message accompanies the HTML version if the latter is used so as to accommodate all e-mail clients.
  • the text of the title and/or of the (plain or HTML) message may contain recalls (piping) of any data in the data base using CallWeb recall syntax; additionnally, system variables such as the _telkey (the key to individual access to pre-existing questionnaires) can be recalled using the following syntax: {$varname}, e.g., {$_telkey}.
  • the text of the message may contain an instruction to attach a file to the message; to do so:
    • add the following anywhere in the body of the message
      [attach = directory/filename] or [annexer = directory/filename]
    • the filename must be prefixed with the name of the directory where the file is located: if file "abc.pdf" is in directory "cwproject", the proper syntax is
      [attach = cwproject/abc.pdf]
    • it is also possible to attach several files by separating their names with commas as in
      [attach = directory/filename1, directory/filename2]
    • when a file is attached to a message, the message must contain an HTML portion in addition to the usual text portion; if one is not supplied, CallWeb creates it from the plain text version.
  • the text of the message may contain an instruction to track the date and time of the opening of the message by the recipient; to do so add a [track = SOME_OPEN_PART] to the message. The date and time of opening will be stored in that open part in the appropriate _telkey.

The following are required for the e-mail notification operation:

  • one open-end question containing the e-mail address of each participant;
  • one open-end question available to store the datestamp of the mailout; the following codes are also used in that field
    • -1 + datetime of the attempt: the message could not be sent within the allotted amount of time;
    • -2 + datetime of the attempt: the domain name of the e-mail address is not reachable;
    • -8 + datetime of the attempt: the e-mail address field is empty;
    • -99: the system is attempting to send to that case or the procedure crashed while sending to this case.
  • an e-mail address used as the sender of the invitation;
  • the write access password to the CallWeb questionnaire since time date and time of e-mail delivery is stored in the data base;
  • a question which acts as the e-mail text template.

One option, offered interactively, allows for the simulation of the mailing: messages are displayed on screen but neither sent out not timestamped in the data file.

Managing bounced e-mail messages

Using the # Send bounces to instruction, bounced messages can be sent to any arbitrary destination, or to the cwbounces.pl script which logs bounced messages and attempts to signal them in the CallWeb data set. To activate this latter function, follow these instructions:

  • the format of the destination of bounced messages must be "bounces.*@domain.xxx"; CallWeb reformats this address to suit its needs;
  • the # Check bounces against instruction is a comma-delimited list of question names which indicates which question field contain the e-mail addresses to check against the bounced addresses;
  • the # Save bounces into must also be set to a comma-delimited list of question names which will receive the date and time of the bounce notifications (textual open-end parts); there must be as many question names in this list as there are in the # Check bounces against list;
  • note that this system works only for project names using only lower-case characters because of limitations to e-mail address syntax. Note also that none of the directory names in the full path reaching the project directory can contain a dash.
  • the cwbounces.pl module must be appropriately installed.

Automatic e-mail delivery

Using parameters set in # Auto email instructions, CallWeb can be asked to scan project data on a regular basis (say, every hour) to identify records which meet a certain condition, and to send them an e-mail message. The e-mail message itself follows the rules outlined above regarding formatting and recalling of record values. The generix syntax of this instruction is as follows (note: the equal signs and the commas are delimiters; use them as described in this example):

    # Auto email xxx = (xxx can be any string uniquely identifying this instance of AUTOEMAIL)
    #>     active = (yes or no, whether the instruction is currently active; the default is yes),
    #>     selection = [ (MySQL expression identifying which cases to email to in the data base; must be within square brackets) ],
    #>     email = (name of the EMAIL-type question in the questionnaire which is used to format the mesage),
    #>     from = (e-mail address shown as sending the message),
    #>     sender = (e-mail address effectively sending the message),
    #>     to = (name of the CallWeb open-end part containing the e-mail address to send to),
    #>     cc = (name of a CallWeb open-end part containing an e-mail address to send a carbon-copy to [optional]),
    #>     reportto = (e-mail address to send reports to; supersedes the administrator_email installation instruction),
    #>     bounces = (e-mail address to send bounces to; the type of address discussed above can be used as well to automatically intercept the bounces),
    #>     store = (name of the CallWeb open-end part where the timestamp of the e-mail sent will be stored),
    #>     max = (maximum number of messages to send in one iteration; this can be used to avoid mail server overload, in or out),
    #>     delay = (seconds of delay before sending a second message to the same domain; the default is 120 seconds),
    #>     unsubscribe = (URL to access the questionnaire unsubscribe feature; see the recipe)

Here is a real life example:

    # Auto email 001 =
    #>     active = yes,
    #>     selection = [ ADATE > 20050101 AND NOT AINVITATION > 0 ],
    #>     email = INVITATION,
    #>     from = info@callweb.ca,
    #>     to = AEMAILADDRESS,
    #>     cc = ACCADDRESS,
    #>     bounces = bounces.*@callweb.ca,
    #>     store = AINVITATION,
    #>     max = 1000,
    #>     delay = 120,
    #>     unsubscribe = http://circum.com/callweb/callweb.cgi?en:{$contexte{projet}}:{$_telkey}:UNSUB

One CallWeb project can contain any number of such automatic e-mail instructions (make sure they have different identifying strings) so that various circumstances (defined by the selection condition) can trigger different e-mail messages.

Limited substitution capabilities exist within the "selection" clause — essentially via the contexte list of data fields. For example, to trigger a message on January 1, 2009, the following condition could be used:

    #>     selection = [ {$contexte{date}} > 20090101 ],

Field management

E-mail notification

The cwemail module sends initial notification and reminders via e-mail. It uses a question as a template which may include recalls of values stored in the survey data base (probably via pre-population). It features tools to select subsets of cases according to any data in the data base as well as subsets defined by ranges of position numbers in the data set. Therefore, it is possible, for example, to send an initial invitation to all participants which includes their custom access code and which is delivered in their preferred language, and to follow-up with those who have initiated but not completed the questionnaire a week later with a motivational message which could be different from another follow-up to those who have not accessed the questionnaire at all.

E-mail notification is based on a special questionnaire variable which contains the title and text of the message to be broadcast. The following rules apply:

  • the type code EMAIL must be listed on the line of the script containing the question name;
  • EMAIL-type questions do not use the language codes; if language-specific messages have to be sent, create as many EMAIL questions as there are languages and select cases to broadcast to according to a language indicator;
  • the body of the question text contains the subject line of the message;
  • the note part of the question text contains the body of the message to be broadcast;
    • paragraphs must be noted by <P> codes while simple line breaks are signified using <BR>;
    • cwEmail reformats the message to create lines of 65 characters or less while respecting paragraphs and line breaks;
    • an HTML version of the message may be inserted between <HTML> and </HTML> tags; the HTML coding must be adequate and complete — CallWeb does not validate it. It is recommended that a plain text version of the message accompanies the HTML version if the latter is used so as to accommodate all e-mail clients.
  • the text of the title and/or of the (plain or HTML) message may contain recalls (piping) of any data in the data base using CallWeb recall syntax; additionnally, system variables such as the _telkey (the key to individual access to pre-existing questionnaires) can be recalled using the following syntax: {$varname}, e.g., {$_telkey}.
  • the text of the message may contain an instruction to attach a file to the message; to do so:
    • add the following anywhere in the body of the message
      [attach = directory/filename] or [annexer = directory/filename]
    • the filename must be prefixed with the name of the directory where the file is located: if file "abc.pdf" is in directory "cwproject", the proper syntax is
      [attach = cwproject/abc.pdf]
    • it is also possible to attach several files by separating their names with commas as in
      [attach = directory/filename1, directory/filename2]
    • when a file is attached to a message, the message must contain an HTML portion in addition to the usual text portion; if one is not supplied, CallWeb creates it from the plain text version.
  • the text of the message may contain an instruction to track the date and time of the opening of the message by the recipient; to do so add a [track = SOME_OPEN_PART] to the message. The date and time of opening will be stored in that open part in the appropriate _telkey.

The following are required for the e-mail notification operation:

  • one open-end question containing the e-mail address of each participant;
  • one open-end question available to store the datestamp of the mailout; the following codes are also used in that field
    • -1 + datetime of the attempt: the message could not be sent within the allotted amount of time;
    • -2 + datetime of the attempt: the domain name of the e-mail address is not reachable;
    • -8 + datetime of the attempt: the e-mail address field is empty;
    • -99: the system is attempting to send to that case or the procedure crashed while sending to this case.
  • an e-mail address used as the sender of the invitation;
  • the write access password to the CallWeb questionnaire since time date and time of e-mail delivery is stored in the data base;
  • a question which acts as the e-mail text template.

One option, offered interactively, allows for the simulation of the mailing: messages are displayed on screen but neither sent out not timestamped in the data file.

Managing bounced e-mail messages

Using the # Send bounces to instruction, bounced messages can be sent to any arbitrary destination, or to the cwbounces.pl script which logs bounced messages and attempts to signal them in the CallWeb data set. To activate this latter function, follow these instructions:

  • the format of the destination of bounced messages must be "bounces.*@domain.xxx"; CallWeb reformats this address to suit its needs;
  • the # Check bounces against instruction is a comma-delimited list of question names which indicates which question field contain the e-mail addresses to check against the bounced addresses;
  • the # Save bounces into must also be set to a comma-delimited list of question names which will receive the date and time of the bounce notifications (textual open-end parts); there must be as many question names in this list as there are in the # Check bounces against list;
  • note that this system works only for project names using only lower-case characters because of limitations to e-mail address syntax. Note also that none of the directory names in the full path reaching the project directory can contain a dash.
  • the cwbounces.pl module must be appropriately installed.

Automatic e-mail delivery

Using parameters set in # Auto email instructions, CallWeb can be asked to scan project data on a regular basis (say, every hour) to identify records which meet a certain condition, and to send them an e-mail message. The e-mail message itself follows the rules outlined above regarding formatting and recalling of record values. The generix syntax of this instruction is as follows (note: the equal signs and the commas are delimiters; use them as described in this example):

    # Auto email xxx = (xxx can be any string uniquely identifying this instance of AUTOEMAIL)
    #>     active = (yes or no, whether the instruction is currently active; the default is yes),
    #>     selection = [ (MySQL expression identifying which cases to email to in the data base; must be within square brackets) ],
    #>     email = (name of the EMAIL-type question in the questionnaire which is used to format the mesage),
    #>     from = (e-mail address shown as sending the message),
    #>     sender = (e-mail address effectively sending the message),
    #>     to = (name of the CallWeb open-end part containing the e-mail address to send to),
    #>     cc = (name of a CallWeb open-end part containing an e-mail address to send a carbon-copy to [optional]),
    #>     reportto = (e-mail address to send reports to; supersedes the administrator_email installation instruction),
    #>     bounces = (e-mail address to send bounces to; the type of address discussed above can be used as well to automatically intercept the bounces),
    #>     store = (name of the CallWeb open-end part where the timestamp of the e-mail sent will be stored),
    #>     max = (maximum number of messages to send in one iteration; this can be used to avoid mail server overload, in or out),
    #>     delay = (seconds of delay before sending a second message to the same domain; the default is 120 seconds),
    #>     unsubscribe = (URL to access the questionnaire unsubscribe feature; see the recipe)

Here is a real life example:

    # Auto email 001 =
    #>     active = yes,
    #>     selection = [ ADATE > 20050101 AND NOT AINVITATION > 0 ],
    #>     email = INVITATION,
    #>     from = info@callweb.ca,
    #>     to = AEMAILADDRESS,
    #>     cc = ACCADDRESS,
    #>     bounces = bounces.*@callweb.ca,
    #>     store = AINVITATION,
    #>     max = 1000,
    #>     delay = 120,
    #>     unsubscribe = http://circum.com/callweb/callweb.cgi?en:{$contexte{projet}}:{$_telkey}:UNSUB

One CallWeb project can contain any number of such automatic e-mail instructions (make sure they have different identifying strings) so that various circumstances (defined by the selection condition) can trigger different e-mail messages.

Limited substitution capabilities exist within the "selection" clause — essentially via the contexte list of data fields. For example, to trigger a message on January 1, 2009, the following condition could be used:

    #>     selection = [ {$contexte{date}} > 20090101 ],