homefeaturesexamplesDOCUMENTATIONblogpricingcontact us
technical documentationCATI documentationcookbookrobot

Table of contents

COMPLETE TECHNICAL DOCUMENTATION ON A SINGLE PAGE
QUICK START
INTRODUCTION
DESIGN
Question name line **
Question text
Question note
Answer categories
Simple skips
Display condition
Open end part
Response recall
Computed questions
Commenting a script
STRUCTURE
Pages
Tables
Permutations of questions
Hierarchical projects
Interruption
APPEARANCE
Page structure and templates
Text formatting
Colours and layout
In-questionnaire formatting
Examples of final products
MANAGEMENT
Permission management
Integrated module
Initiation of a project
File management
Quota management
E-mail notification
Questionnaire completion
Modifications to a project
Case management
Real-time results
Extraction of data
Data base destruction
Performing back-ups
APPENDIX A Pound Instructions
APPENDIX B Installation instructions
APPENDIX C URL options
APPENDIX D Recent changes and additions
APPENDIX E Formatted tabular output syntax
APPENDIX F Security features
APPENDIX G Context data
APPENDIX H TEST pound instruction
APPENDIX I System messages
APPENDIX J System variables
APPENDIX K Weight variables (deprecated)**
APPENDIX L Basic HTML codes
APPENDIX M Project initiation checklist
APPENDIX N File types
Summary card of CallWeb syntax
* Updated in July 2019
** Updated in August 2019

   

Quick start

This page provides brief instructions on how to set up your first CallWeb project. It is assumed that you have access to a Web server equipped with CallWeb and to an FTP program to transfer files to the server.

  1. Using your Web browser, call the CallWeb integrated module; the address was provided to you by your administrator.
  2. From there, use the cwedit module to create a one-question questionnaire.
  3. Save this questionnaire script under the file name "test" — the questionnaire file will be named test.scw (the .scw extension indicates a CallWeb script).
  4. Still from cwedit, click on the Compilation icon. This will open a new window which will report the status of the compilation, and any compilation errors.
  5. Close the cwedit window.
  6. Click on your browser Reload button to refresh the integrated module page with the information on the project your have just compiled.
  7. Select the "test" project from the drop-down list next to "Start a new questionnaire; ../callweb.cgi" and click on the icon on that line.
  8. Your question appears on this new, one-question project!

   

General introduction

CallWeb is a computer system which facilitates the creation of intelligent forms and questionnaires and the management of the collection of data using these forms and questionnaires.

This document reviews the operations of CallWeb in the following sequence:

  • first, basic questionnaire design syntax is explained
  • then, ways to define a structure for the questionnaire are reviewed
  • third, tools available to control the questionnaire appearance are presented
  • finally, a project life-cycle is explained

Much of the CallWeb action is centered around scripts which are text files comprising the definitions of each question in the questionnaire — and then some. There are two ways to create and modify scripts:

  • using a text editor like Notepad or TextPad, the questionnaire designer has direct control over every aspect of the questionnaire and can perform changes extremely fast;
  • using the cwedit CallWeb module, the designer can also control every parameter of a questionnaire in a more user-friendly (but definitely slower) environment. cwedit has three limitations: it does not support the SUFFIX CORNER parameter, the response category ALIAS parameter and the concurrent use of same-named container questions.

The choice of the questionnaire creation and modification is yours; however, this documentation is focussed on the text editor approach (rather than the cwedit module) because it is faster and because it requires more handholding in the beginning.

   

Questionnaire design

Introduction

A CallWeb questionnaire is contained in a strict ANSI file (only ANSI characters, no word processing commands) where each question is presented in the sequence in which it will be used in the questionnaire. The questionnaire file uses the following naming convention: the extension must be .scw (stands for "script for CallWeb") and the file name (without extension) becomes the project name as far as CallWeb goes. Caution: the case of the letters counts in the name of the file and in the project name.

The structure of a question definition is as follows:

    QUESTION_NAME_GOES_HERE
    % Question text follows this % sign
       QUESTION TEXT
    % Note text follows this % sign
       NOTE TEXT
    % Answer categories follow this % sign
       ANSWER CATEGORIES
    % Simple skips follow this % sign
       SIMPLE SKIPS
    % Display condition follows this % sign
       DISPLAY CONDITION
    % Open end part definition follows this % sign
       OPEN END PART
    ! End of question definition

So a real-life example of a question definition would be as follows.

    ##
    ## Question Q1
    ##
    Q1
    % Question text
       Are you generally considered a male or a female?
    % Note
    % Answer categories
       Male
       Female
       *9*I don't really know
    % Simple skips
       9 = BYEBYE
    % display condition
       Q0.EQ.1
    % Open end part
       9 = C80 2 40
    ! End of question definition

Each segment of the questionnaire definition will now be reviewed.

   

Questionnaire design

Question name line

The question name line uses the following syntax (all information must be supplied on a single line):

    QUESTION_NAME MIN=n MAX=n NCOLS=n SUBSET=question CODESIN=question CATEGORIES=question CORNER=(text) ONE OR MORE KEYWORDS MUST=(condition)

The question name:

  • may contain up to 64 characters;
  • must start with a letter other than A;
  • may contain letters, numbers and the underscore character.

The MIN= parameter is the minimum number of responses expected. Set at zero, it allows nonresponse to a question. The default is 1.

The MAX= parameter is the maximum number of responses expected. Set at a value greater than 1, it forces the use of check boxes rather than radio buttons. The default is 1.

Setting both MIN and MAX at zero creates a question without answer categories. CallWeb displays the question text and note, if applicable.

The NCOLS= parameter determines over how many columns the response categories will span. The overall system default is a single column list. This system default can be overridden by a questionnaire-wide default using the # N COLONNES PAR DEFAUT instruction. Finally, the question-level NCOLS parameter can override all of the defaults on a question by question basis.

The SUBSET=question parameter names the open-end part to use to reduce the list of answer categories using a substring in the code labels (see a full description).

The CODESIN=question parameter names the open-end part to use to reduce the list of answer categories using any criteria from a related data base (see a full description).

The CATEGORIES=question parameter names the open-end part to use as input to create the list of answer categories (see a full description).

The MUST=(condition) parameter specifies a logical condition under which an answer MUST be supplied to the question.

The CORNER=(text) parameter changes the text displayed in the left corner of a table header, for this question only. It can contain one segment for each questionnaire language, specified using square brackets and two-letter language codes (e.g., [EN]).

  • See the section on Display conditions for the syntax of logical conditions.
  • The logical condition must be within parentheses (for xBase-style conditions) or braces (for Perl-style conditions).
  • This is in addition to the MIN and MAX parameters such that a question can have a minimum of zero answers (be allowed to not be answered except under circumstances defined in the MUST condition).
  • The MUST condition is applied only if the question is displayed according to its display condition.
  • The MUST condition should be specified last on the Question Name line.
  • Example of use: one can build a two-variable-side-by-side matrix of, say, importance ratings, where the last entry is an "other" with an open-end box and a rating scale. These two questions have a minimum of zero answers since some people may have no "other" answer but if a scale rating is supplied, a description must be offered in the open-end box. In this case, MUST=(Q2.GT.1) applied to Q1 would insist upon the supply of an answer to Q1 if Q2 was answered to.

The KEYWORDS can be any of the following values (logically, some can be used concurrently, others not):

AFFECTING RESPONSE CATEGORIES
ROTATIONresponse categories without a [B]locked behaviour code are presented in random order (formerly but still working: codes with values of less than 900). It can also be used with the ROTATION=Qx syntax; the permutation of the current question is then copied from the permutation of Qx (also called "parallel permutation" or "controlled permutation").
INVERSIONresponse categories without a [B]locked behaviour code are randomly inverted (formerly but still working: codes with values of less than 900). It can also be used with the INVERSION=Qx syntax; the inversion of the current question is then copied from the inversion of Qx (also called "parallel inversion" or "controlled inversion").
ALPHAresponse codes without a [B]locked behaviour code are alphabetically ordered according to the response label in the language displayed (formerly but still working: codes with values of less than 900)
DROPDOWNresponse categories are presented in a dropdown list instead of as a set of radio buttons or checkboxes
CHECKALLthis keyword automatically sets the maximum number of allowable answers to the number of non exclusive answer categories.
SCALEthis parameter tells CallWeb to display the response categories as a horizontal scale. Used alone, the scale cell widths are left to the browser to determine; used as "SCALE=nn", the scale cell widths are no less than "nn" pixels. Add a C before "nn" and the scale is centred on the page. This feature does not work in conjunction with the succinct cloning syntax.
FORCEHEADER(or FORCEENTETE) when questions are displayed in table format, this question type forces the addition of the table banner (the text of response categories) before the current question.
ONCEACROSSonly one respondent can select any given category of response (with a code less than 9000); already-selected categories are not shown in the list of possible answers.
NOTESTcancels compilation tests on response categories (useful to speed up the compilation when a question includes thousands of answer categories, it has been tested in the past and no change was made to it).
SEMANTICsplits the note field into two pieces at the last slash character and places the second piece in response categories to provide the effect of a semantic differential scale. Note: do not use note copying or response category copying in SEMANTIC questions.
NOPRINTCATdeactivates the printing of response categories in print mode (useful for very long lists of categories).
DONOTPRINTdeactivates the printing of the question in print mode.
SUGGdisplays the warning message for an insufficient number of responses only once (then allows continuing with fewer responses than required by the MIN parameter). Note: works only once a record is saved in the data base.
PERFORMING CALCULATIONS
BLANK(never displayed) the first code is attributed to the variable if the display condition is true (see also calculations)
CALCUL(never displayed) the question performs a calculation and returns the result in another (or the same) variable
RANDOM(never displayed) a random integer is attributed to the variable (see also calculations)
WEIGHTa weight is stored in the open-end part of this variable and is used in reporting frequencies in cwfreq and cwquestionnaire
AFFECTING THE DISPLAY OF BUTTONS
CULDESACthe questionnaire stops at that question without leaving to an external URL. The question is displayed, without a "next" button or image. If the question is part of a multi-question page, it must come last since the last question of the page determines the display of the button set.
BACKWALLat that question, the questionnaire does not display a button to go back to the previous question and does not allow to backtrack. If the question is part of a multi-question page, it must come last since the last question of the page determines the display of the button set.
UNLOCKif it is the last question of a page or if the question is on a page of its own, a "Save and close" button is added which validates the input, saves the data, releases the lock on the case and closes the window.
NOSTOPif it is the last question of a page or if the question is on a page of its own, the "Stop" button is not displayed.
NOTHERMOMETERsuspends the display of the progress bar on the current page (if located on the first question of a page for a progress bar located at the top of the page or the last one for a bar at the bottom of the page).

NOLANGUAGE
suspends the display of the language button(s) on the current page (if located on the first question of a page for a progress bar located at the top of the page or the last one for a bar at the bottom of the page).
SUBMITuses the "# Submit Text" and "# Submit Image" pound instructions for the Next Page button.
NOPRETESTdeactivates the "# Pretest" pound instructions for the question.
TYPES OF QUESTIONS
RELATIONestablishes a relational link between the current project and another project acting as a child. This question displays buttons to add children, delete them and modify them. See the section on hierarchical projects for more details.
ERASERELdefines a question that is used to probe for confirmation of deletion in hierarchical projects. See the section on hierarchical projects for more details. Such a question is automatically made BACKWALL; it is not shown in the normal flow of the questionnaire.
NEVERUPDATE(never displayed) CallWeb never updates the data base for that variable (may be useful when CallWeb is one component of a larger data base context)
STOCK(never displayed) a passive question, it does nothing but can be used to stock information via a CALCUL question; it is also used to insert "Other, specify" boxes in tables
ONLYONCEonce such a question has been answered, CallWeb refuses to change the answer provided. This stubborn behaviour is also valid for the open-end part.
AUTONEXTused as AUTONEXT=n, it moves on to the next questionnaire screen automatically after n seconds and attributes the first defined response category to the answer. Display conditions are respected. This instruction requires JavaScript on the client station.
MEMOdisplays a table of questions and answers for the list of questions comprised in the question text (in the form: Q1-Q5, Q7, Q8-Q10,...); only regular questions containing answers are displayed. Display conditions are respected.
MEMEXCLexcludes a question from being displayed by a MEMO question.
EMAIL(never displayed) the question is used by cwEmail to send invitation/notification messages to participants
VERBATIMdisplays all character open-ends in a questionnaire in a single window and allows for cleaning their content. Only open ends already containing something are displayed. A VERBATIM question is forced, during compilation, to a minimum and a maximum of zero answers. Also, such a question cannot be part of a TABLE/MATRICE pound instruction, but it can be part of a GROUP/ECRAN definition and it can bear a display condition
VBTMEXCLexcludes a question from being displayed by a VERBATIM question.
QUOTA(never displayed) the question contains instructions regarding completion quotas
INFOCATI(displayed only from the interviewer interface) used by the CallWeb's CATI environment; identifies questions whose data are displayed to the interviewer along with the next telephone number to dial. An INFOCATI field with a T type open-end part displays a dial button if the project uses a dialler.
CONTACT(displayed only from the interviewer interface) used by the CallWeb's CATI environment; identifies a single question that contains the contact script for a telephone survey. Such a question may use recalled values
DESTOP(never displayed) used in the block of questions reached by a STOP button, it branches the flow back to the question from which the STOP button was invoked.
PAGEBREAKspecifies that a page break should be inserted after this question if the questionnaire is printed. It can be used in addition to _print mode. A page break is NOT inserted within a matrix.
GOTOURL(never displayed) specifies that the flow will go to a URL found in the URL option. Details are found in a related recipe.

NOPARAGRAPH
avoids placing the text of the question within an HTML paragraph bearing the QUESTION CSS style.

   

Questionnaire design

Question text

The question text may flow over several lines. CallWeb concatenates all lines prior to processing the text. Remember that the final appearance for the survey participant, including line wrapping, is controlled by the browser.

Example of a question text segment:

    % Question text
       [EN]Are you generally considered a male or a female?
       [FR]Êtes-vous généralement vu(e) comme un homme ou une femme?

The question text may contain HTML codes. Such codes are interpreted directly by the browser.

Recall of previous answers can be done in the question text. See the Response recall section for the syntax of the recalls.

If more than one language is defined in the questionnaire, language segments of the question must be preceded by the international ISO language code within brackets (e.g., [EN]). A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.

The text of the question can be borrowed from another question by putting the equal sign (=) left of the name of the question from which to copy.

   

Questionnaire design

Question note

Notes are displayed after the question text, using a different look; they also specify the text of the line in matrix presentations (see Tables section).

Example of a note segment:

    % Question note
       [EN]Please be as specific as possible.
       [FR]Veuillez être aussi précis que possible.

The note text may contain HTML codes. Such codes are interpreted directly by the browser.

Recall of previous answers can be done in the note text. See the Response recall section for the syntax of the recall.

If more than one language is defined in the questionnaire, language segments of the note must be preceded by the international ISO language code within brackets (e.g., [EN]). A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.

The text of the note can be borrowed from another question by putting the equal sign "=" left of the name of the question from which to copy.

Question cloning

When a series of questions that are exactly the same except for the Note field (and possibly the display condition) must be created (e.g., to create a battery of questions presented in a table format), it is possible to use a succinct cloning syntax. This is more easily explained with an example:

    Q1
    % question
       Have you ever:
    % note
       [SUFFIX:_A]ridden a bicycle
       [SUFFIX:_B]driven a car
       [SUFFIX:_C]piloted a plane
    % categories
       Yes
       No
    % skips
    % condition
    % open part
    !

This code creates three questions (Q1_A, Q1_B and Q1_C) which share all characteristics except for the content of the Note. These questions may or may not be then placed into pages and/or tables. If different languages are used, each suffixed entry must contain the proper language segments.

The container question (Q1 in the example above) does not exist as far as CallWeb is concerned; only the suffixed questions do. Therefore, while it is possible to copy from and to the suffixed questions (Q1_A and following in the example), it is not possible to copy from and to the container question (Q1 above). This means that, following the same example, this code is legitimate:

    Q1
    ...
       [SUFFIX:_A]=Q0_A
       [SUFFIX:_B]driven a car
       [SUFFIX:_C]piloted a plane
    ...
    Q2A
    ...
    % note
       =Q1_A
    ...

and this code as well:

    Q1
    ...
       [SUFFIX:_A]ridden a bicycle
       [SUFFIX:_B]driven a car
       [SUFFIX:_C]piloted a plane
    ...
    Q2
    ...
    % note
       [SUFFIX:_A]=Q1_A
       [SUFFIX:_B]=Q1_B
       [SUFFIX:_C]=Q1_C
    ...

but that this one is not:

    Q1
    ...
       [SUFFIX:_A]ridden a bicycle
       [SUFFIX:_B]driven a car
       [SUFFIX:_C]piloted a plane
    ...
    Q2
    % question
       =Q1
       ## Hint: that's because Q1 is a container question, hence it does not exist
    ...
    % note
       =Q1
    ...

We highly discourage building a script containing a regular question (e.g., Q1) AND a container question (e.g., Q1 + various suffixes), or two container questions, with the same name. The compiler is able to deal with such situations but the cwedit module cannot.

Display conditions can also be applied to particular suffixes. Such a display condition is inserted between brackets immediately after the SUFFIX bracket set and immediately before the text of the note. SUFFIX display conditions supersede any display condition that could be attached to the container question. Thus, in the following example:

    Q2
    % question
       Have you ever:
    % note
       [SUFFIX:_A][Q1.EQ.1]ridden a bicycle
       [SUFFIX:_B]driven a car
       [SUFFIX:_C]piloted a plane
    % categories
       Yes
       No
    % skips
    % condition
       Q1.EQ.2-4
    % open part
    !

the display condition on the first statement is [Q1.EQ.1] while the other statements have a display condition of [Q1.EQ.2-4].

The same logic applies to CORNER=(text) parameters which can be added on the SUFFIX line as follows:

    Q2
    % question
       Have you ever:
    % note
       [SUFFIX:_A][CORNER=([EN]Put this text in the corner of the table)]ridden a bicycle
       [SUFFIX:_B]driven a car
       [SUFFIX:_C]piloted a plane
    % categories
       Yes
       No
    % skips
    % condition
       Q1.EQ.2-4
    % open part
    !

The CORNER=(text) parameter changes the text displayed in the left corner of a table header, for this question only. It can contain one segment for each questionnaire language, specified using square brackets and two-letter language codes.

SUFFIX questions are not limited to building tables but they are a very quick way to create a series of questions that share a response set and that can be displayed in table format. It is sometimes useful to insert a title row in such a table, as shown in the image to the right where the PRODUCT and FINANCIAL lines act as titles (no data is collected about them). One simple way to create such titles is to add the letter "T" to the keyword "SUFFIX" (making it "SUFFIXT"). A SUFFIX-title question is imposed a minimum of zero answers (so that it can be left unanswered) and all of its response codes are given a behaviour code of "N" (in addition to any other behaviour code the answer categories may have) so that no response object (a radio button or a check box) is shown in the cells of the title line.

   

Questionnaire design

Answer categories

Each answer category must be laid out on a single line. Remember that the final appearance for the survey participant, including line wrapping, is controlled by the browser. The syntax of the answer category line may be either of the following three:

    Simply a label
    *number*Label
    *number*behaviour_code*Label

A simple label is automatically assigned a numeric code one unit larger than the previous code, starting from 1. If a number is provided between asterisks, that number becomes the category code. Answer categories need not be ordered according to this number and numbers need not form a sequence.

Answer categories are always given numeric codes. By default, CallWeb reserves four digits to store all answers to regular questions (exclusive of open end parts, see Open end part section) but more can be used. If more are used, the "# Extraction width" pound instruction will be requested by the compiler.

One or more behaviour codes may be added between asterisks following the number code (a number code is required in order to use a behaviour code). Behaviour codes are selected from the following list:

Aalways displayed code; this code is always displayed in cwfreq,cgi even if the module is instructed to leave out categories with counts of zero.
Bblocked code; this code remains in its location in the context of permutations, inversions or alpha orders. A [B]locked code is an anchor. Codes before and after it are subject to permutation, inversion or alpha order; assuming that there are codes from 1 to 10 in a ROTATION question and that codes 1, 5 and 10 are [B]locked, then codes 2 to 4 and 6 to 9 are randomly ordered (within these two sequences) and codes 1, 5 and 10 are static in the first, fifth and tenth location.
Cno comma; commas will be stripped from the numeric open-end part associated with the question.
Ddefault category; this answer category is selected by default when the question is displayed.

E
evidence: this answer category is displayed as a title above the radio buttons/checkboxes as well as the regular label area; this answer is not selectable.
Fforced category; this answer category will be displayed no matter what the situation is (e.g., category display conditions, SUBSET questions).
Gproper case; the alphanumeric open-end part associated with the question will capitalize the initial letter as well as every letter following a delimiter (space, comma, dash, etc.).
Iinvisible; the response category is not displayed as part of the questionnaire.

K
kill the carriage return before the alphanumeric open-end box.
Lprefix; the response category label is prefixed with the text (and possibly HTML code) in "# LIRE" and it is formatted using the .NEPASLIRE style.
Min a matrix context only, the response category label is displayed within the matrix cell corresponding to this category; recalled values are recognized. Using M in conjunction with N allows the display of a category label alone in a cell; this category label could be made up of only a recalled response. By default, the banner cell above the first row of an M response category is empty; alternatively, CallWeb can fill the banner cell with the text found after a [COL] code in the response category label of the first matrix question (e.g.,
*1*M*[EN]???[COL]DK/NR[FR]???[COL]NSP/PDR
displays "???" within the table cells and the text "DK/NR" or "NSP/PDR" in the banner cell). This system works with drop-down lists if the [COL] text is in the first response category.
Nnon selectable category; this answer category is not available for selection but its label is displayed; this is useful to insert sub-titles in long category lists.
Ooptional open-end part; if this answer category possesses an open-end part, it could be selected without completing the open-end component.
Pprefix; the response category label is prefixed with the text (and possibly HTML code) in "# NE PAS LIRE" and it is formatted using the .NEPASLIRE style.
Sspecial code; in regular list format, the SPECIAL style is applied to the response label; in table format, in addition to this formatting, the column coloured with the "# M_SpecialColour" colour as if it were cited in the SPECIAL parameter of the TABLE statement.
Ttest the open-end; attached to a code which is related to a numeric open-end, T redisplays the page if the value entered is less than the planned minimum or more than the planned maximum; the value supplied on that second page is accepted no matter what.
Uuppercase; the alphanumeric open-end part associated with the question will turn all text to uppercase characters.
Vmissing value code; used by cqfreq in univariate distributions to indicate missing value codes.
Xexclusive category; this answer category must be selected alone if at all; this behaviour code makes sense only in the context of multiple response questions.
<places an open-end box on the left side of a table cell (default position); used on the first response code of a question, it does the same for a drop-down list. Outside of a table, it places a one-line box on the left side of the response label.
=centers an open-end box in a table cell; used on the first response code of a question, it does the same for a drop-down list.
>places an open-end box on the right side of a table cell; used on the first response code of a question, it does the same for a drop-down list. Outside of a table, it places a one-line box on the right side of the response label.
)places the text defined using the "M" behaviour code (above) right of the radio button or checkbox (the default is left). See also "# M text position".
(places the text defined using the "M" behaviour code (above) left of the radio button or checkbox (this is the the default position). See also "# M text position".
~deactivates the display of the calendar for a D open-end.

Language segments in answer categories are treated in the same manner as within the question text. A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.

Example of an answer category:

    *9*X*[EN]Don't know[FR]Ne sait pas

An unlimited number of categories may be defined for each question. Questionnaire compilation is obviously longer as the number of categories increases.

Copying of answer categories

It is possible to borrow integrally the answer categories from another question by inserting a single line in the answer category section. This line contains the symbol "=" and the name of the question from which to borrow such as in the following:

    =Q1

Borrowing questions and questions borrowed from need not be in any particular order in the questionnaire.

Response aliases

Response aliases are elements of text which are different from the main label of an answer and which can be recalled instead of the main label. The syntax of aliases is as follows:

    label[ALIAS PW:text][ALIAS NAME:text]

Language codes and behaviour codes can be used along with aliases as in the following example:

    *5*D*[EN]label[ALIAS FIRST:text][ALIAS SECOND:text][FR]étiquette[ALIAS FIRST:texte][ALIAS SECOND:texte]

In a given set of answer codes, some codes may bear aliases while others don't. A give code can possess an indefinite number of aliases. Aliases must be placed after the label of the response. Aliases are used in recalls using the syntax &QUESTION#alias_label (e.g., &Q1#PW).

Special cases: permutations and inversions

CallWeb features special tools to implement answer category permutation and inversion.

If the keyword "ROTATION" is present on the question name instruction, the answer categories are displayed in random order, suject to the categories with a B behaviour code.

If the keyword "INVERSION" is present on the question name instruction, the answer categories are displayed in the original order or the reversed order, randomly, suject to the categories with a B behaviour code.

Example:

    Q1 ROTATION
    % Question text
    [EN]Are you generally considered a male or a female?
    [FR]Êtes-vous généralement vu(e) comme un homme ou une femme?

Special case: display conditions on response categories

By default, all response categories are displayed. However, their display can be made conditional to previous answers by inserting an additional line containing a display condition within square brackets. Such a condition line affects the category that is defined on the line following immediately.

Example:

    A label
    [Q1.EQ.1]
    *2*Label
    *3*Label

In this example, the second category is displayed and available only if the value of Q1 is 1. Answer category display conditions are enforced even when questions are presented as tables.

   

Questionnaire design

Simple skips

The definition of a simple skip is... simple: list the answer category code(s) left of an equal sign (=), separated by commas, and the question to skip to to the right of the equal sign. There can be any number of such definitions in a question; each must be on its own line.

Example of a simple skip:

    % Simple skips
    8,9 = BYEBYE

Note that, by default, when questions are skipped, all of the data that they contained are erased. This behaviour can be changed for the whole questionnaire by setting the # Cleaning skips parameter to "no" or for a specific skip by prefixing the destination question with a "~" sign as in

    % Simple skips
    8,9 = ~BYEBYE

Hyperlink skips with JUMP

It is possible to create a hyperlink to a particular question in the current questionnaire. The syntax is as follows:

    ... {JUMP:QUESTION}text{/JUMP} ...

This syntax creates a link on "text" (which can part of any of the question elements) that jumps immediately to question "QUESTION" without processing any input from the current page. This type of hyperlink skip does not clean intervening questions.

It is also possible to JUMP to another project using the following syntax: {JUMP:QUESTION,project}.

Finally, it is also possible to JUMP to a specific case of another project using the following syntax: {JUMP:QUESTION,project,telkey}.

These various flavours of {JUMP:} can all produce encrypted links if they are called as {JUMPC:}. (See the cover function.)

   

Questionnaire design

Display condition

A display condition is a logical expression which determines whether a question is displayed. It is a way to implement skip logic which is much more robust than simple skips or calculated skips because it is directly associated with the destination question.

The logical expression must use the xBase logical expression format (for experts: the expression can also follow Perl syntax and use any variable in the Perl environment if the condition is presented between "{" and "}" signs). It may use any of the variables defined in the questionnaire, including prepopulated data. Basics of the xBase logical expression format are as follows:

  • comparison operators are: .EQ., .NE., .GT., .GE., .LT., .LE.
  • logical operators are: .AND., .OR., .NOT.
  • simple mathematical operations such as: +, -, /, *, **
  • parentheses are permissible and affect the order of interpretation.
  • questionnaire languages can be identified using the following syntax: LANGUAGE(la) or LANGUE(la) where "la" is a single two-letter ISO language code or a series of them separated by commas and/or spaces.
  • empty variables can be identified using the following syntax: ISEMPTY(Q1) or ESTVIDE(Q1) (Q1 is replaced with the appropriate field name, which could be an open-end part name).
  • non-empty variables can be identified using the following syntax: NOTEMPTY(Q1) or NONVIDE(Q1) (Q1 is replaced with the appropriate field name, which could be an open-end part name).
  • QUESTION(Q1) is true if Q1 is the current question when the test is performed. QUESTION(Q1...) is true if the name of the current question when the test is performed starts with Q1.
  • NRESPONSES(Q1) returns the number of responses given to Q1.
  • MOBILE() returns 1 or true if the questionnaire is displayed on a mobile device (0 otherwise).
  • when using .EQ. and .NE. (on regular single-answer and regular multiple-answer questions as well as integer open parts), the right side of the comparison may take three forms:
    • Q1.EQ.1 and Q1.NE.1 compare the answer to Q1 to a single integer
    • Q1.EQ.1,3,5 and Q1.NE.1,3,5 compare the answer to Q1 to a each integer and returns true if one of them matches (for .EQ.) or none of them matches (for .NE.)
    • Q1.EQ.1-5 and Q1.NE.1-5 compare the answer to Q1 to a each integer between the two bounds and returns true if one of them matches (for .EQ.) or none of them matches (for .NE.)
    • Q1.EQ.1-5,7 and Q1.NE.1-5,7 compare the answer to Q1 to a each integer between the two bounds as well as other individual values (any number of ranges or individual values can be supplied between commas) and returns true if one of them matches (for .EQ.) or none of them matches (for .NE.)

CallWeb takes care of applying the xBase logic on multiple-answer questions.

Remember that all answer categories are numeric. This simplifies the construction of logical expressions.

Example of a display condition segment:

    % Display condition
    (Q1.GT.2.AND.Q2.EQ.1)

When CallWeb encounters a display condition which evaluates to "false", it erases any data that the associated question may contain in its numeric and open-end portions — however, it does not erase the destination of a CALCUL variable. This is a logical behaviour since that question should not have been displayed to start with — although it may have been legitimately displayed before the user backtracked and changed previous answers. To create a non-displayed variable where data must be stored (such as prepopulated fields), consider using the open-end portion of a BLANK question or the NEVERUPDATE or STOCK question types, or the display condition must be prefixed with a tilde (~) to indicate a non-cleaning display condition (much like the tilde prefix makes a simple skip non-cleaning)..

It is possible to borrow the display condition from another question by inserting a single line in the display condition section. This line contains the symbol "=" and the name of the question from which to borrow such as in the following:

    =Q1

Borrowing questions and questions borrowed from need not be in any particular order in the questionnaire.

   

Questionnaire design

Open-end part

An alphanumeric, numeric and other types of open-end component may be attached to any answer category. It is stored in a separate "question" which bears the same name as the originating variable to which the letter "A" is preappended. The definition of open-end parts follows this syntax: list the associated answer category code(s), separated by commas, left of an equal sign and add the open-end instructions right of the equal sign.

Example of an open-end segment:

    % Open-end part definition
    9 = C80

The syntax of the open-end instruction line is as follows (according to the type of data expected).

SyntaxUseExplanation
Cwidthalphanumeric open-endwhere WIDTH is the number of characters of the character field
Nwidth.decimals min maxnumeric open-endWIDTH is the number of characters of the numeric field;
DECIMALS is the number of decimals;
MIN is the minimum acceptable answer value; it may be a constant, the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces;
MAX is the maximum acceptable answer value; it may be a constant, the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces
Mwidth password data entrywhere WIDTH is the maximum number of characters of the character field
Ewidthe-mailto open a 40-character text box validated as an e-mail address associated with response code 4, use: 4 = E40
UwidthURLto open a 40-character text box validated as a URL associated with response code 4, use: 4 = U40. The string "http://" is added if absent and the following validation is performed: the string must contain at least one dot but no at-sign
PwidthCanadian postalan example would be similar to the e-mail example above except for the key-letter P
Swidthfirst three digits of a Canadian postal codesame as above except for the key-letter S
TwidthTelephone numberrequires 10-digit telephone numbers (non-numeric characters are deleted and the number is reformatted as (xxx)xxx-xxxx)
D min maxdatedate fields are always displayed as 8-character text fields; the system expects the date formatted as YYYYMMDD and accepts dashes, spaces and slashes between the three segments; if the respondent browser accepts JavaScript code, clicking in the date box pops a calendar from which the respondent can pick a date.
MIN is the minimum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces;
MAX is the maximum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1) or a Perl expression within braces
H min maxhourhour fields are always displayed as 4-character text fields; the system expects the time formatted as HHMM and accepts a dash, a space, a colon and the letter h between the segments;
MIN is the minimum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1);
MAX is the maximum acceptable answer value; it may be the name of a variable in the questionnaire (e.g., Q1 or AQ1)
IwidthIP addressto open a 15-character text box validated as an IP address associated with response code 4, use: 4 = I15
Rwidth lines columns regular-expressionregular expressionto open a 7-character text box validated as a course ID which looks like XXX:XXX associated with response code 4, use:
4 = R15 1 15 [a-zA-Z0-9]{3}:[a-zA-Z0-9]{3}
In the case of this open-end code, lines and columns MUST be specified. References to regular expressions: 1, 2
Lwidth [condition]droplist open-endwhere WIDTH is the number of characters of the character field; this displays a C-type open-end preceded by a droplist of entries already found in the data for this question. A condition expressed in MySQL syntax and using any data in the dataset can be added between brackets to limit the values shown in the dropdown list (for example [Q1=1] or [AQ1="ABC"]). In use, a selection made in the droplist always supersedes text typed in the open-end box
Fwidth
open-end to upload a file to the serverwhere WIDTH is the number of characters of the field. The # GENERAL UPLOAD PARMS pound instruction defines the location of the upload as well as the constraints imposed to the size and types of files that are allowed. Files are stored in a MySQL table and, optionally, in the upload directory, and they are named according to the project name, the _telkey, the name of the open-end question and the file extension of the file originally uploaded. There cannot be more than one question with an F open-end per page of the questionnaire.

Controlling the size of the data entry box

Most open-end parts default to displaying a 4-line, 40-column box. The size of the box can be determined on a case-by-case basis using the following syntax:

    open-end_parameter n_rows n_columns

as in

    C30 1 20

which opens a 1-row, 20-column box to contain an alpha-numeric answer of a maximum of 30 characters.

Note: multi-line boxes do not implement the limit as to the acceptable number of characters; in this case, the limit is used only upon extracting a fixed-column file. Single-line boxes do constrain the input to the number of characters specified along with the open-end type.

Numeric open-end parts always open a single-line data entry box; the width of this box is a function of the number of characters allowed by the open-end part definition.

Formatting numeric values

By default, numeric values supplied in open-end parts are not formatted; in fact, extraneous characters like dollar signs and percent signs are stripped from the value stored in the data base and French decimal commas are changed to English decimal points.

Using the following syntax, it is possible to display a formatted version of an open-end part in data entry boxes and in response recalls:

    1 = N5 FORMAT=formatxx

where

  • "FORMAT=" is a keyword that must be supplied as such;
  • "format" is one of the following values:
    • NUM: for a simple numeric value using xx decimals
    • DOLLAR or DOLLARS: for a currency value expressed in dollars
    • POUND or POUNDS: for a currency value expressed in Sterling pounds
    • EURO or EUROS: for a currency value expressed in euro
    • PERCENT or POURCENT or %: for a percentage value
    • TELEPHONE: for a telephone number stored as a 10-digit number
    • ZERO: returns z zero-padded version of an integer value
  • "xx" is the number of decimals to display (except for TELEPHONE where no xx is expected and ZERO where xx is the total number of positions in the final zero-padded integer value).

Therefore, 1 = N6.2 0 100 FORMAT=DOLLAR2 would display the open-end part as a dollar value with 2 decimals.

Note that the field width (6 in the example above) determines the width of the data entry box for a numeric value; this width must be sufficient to allow for the display of the formatted value.

Also note that the "format" keyword can be replaced by a substituted value in Perl (between braces) format; this allows for conditional formatting (e.g., displaying currency amounts as a function of a previous question).

   

Questionnaire design

Response recall

CallWeb allows for the recall of three types of information in the question text, question note and answer categories:

SyntaxActionNotes
&questionRecall of the label of the answer selected by the respondentRecalling a RELATION question this way will insert a complete table of the children in the recall location.
&@questionRecall of the answer code selected by the respondent (the numeric code associated with a regular question)Recalling a RELATION question this way will insert the number of children in the recall location.
&&AquestionRecall of the open-end answer provided by the respondent (alphanumeric or numeric open end parts) 
&question#nRecall of the ALIAS "n" of the response code. See the page on answer categories for the concept of alias.If no alias exists for a given answer category, the main label is displayed. This syntax is useful to adapt the recall of an answer to the context of the question (to add an article or to capitalize, for example.)

Recalls can be performed on data stored in any type of question, be that a regular "asked" question or a BLANK question, a CALCUL question, etc.

Example of recall of the answer category selection in question Q1:

    % Question text
    [EN]Earlier, you mentioned that you are generally considered a &Q1? Was it always the case?
    [FR]Vous avez mentionné plus tôt que vous êtes généralement vu(e) comme un(e) &Q1? Est-ce que cela a toujours été le cas?

Recall pound instruction

Special recall values can be created using the "# Recall" or "# Rappel" instruction. The syntax of the instruction is as follows:

    # Recall some_label = [EN]recalled_text[FR]texte_rappelé

These values are recalled using the following syntax: &#some_label. For example, all "New" icons used in this documentation appear using

    &#NEW which is defined in the following pound instruction: # Recall NEW = <img src="cwdoc/new.gif" style="vertical-align:middle">.

To avoid clashes with HTML symbols, some_label must be in capital letters when recalled and it must start with a letter. It can contain letters, numbers and the underscore character.

# RECALL (or # RAPPEL) can use display conditions so that different substitutions are done under different circumstances. Display conditions come right before the recalled value itself as in:

    # Recall WORD = [AQ1.LE.1][EN]word[FR]mot[AQ1.GT.1][EN]words[FR]mots

In this example, &#WORD recalls "word" (singular) if AQ1 is less than or equal to 1 and "words" (plural) if AQ1 is greater than 1.

The display condition is expressed in xBase syntax unless it is within braces and it is expressed in Perl syntax. If the display condition contains a closed bracket symbol (as in a Perl regular expression including classes of characters), use double open and closed bracket symbols to delimit it (as in [[{condition}]]). The recalled text of the first matching display condition is used. The condition [ELSE] is always true; it is useful to conclude a series of conditions.

If the recall is followed by a tilde (e.g. &#WORD~), this character serves as a delimiter and is NOT transmitted to the questionnaire page thereby allowing the absence of spacing between the ercall and the text that follows it..

Advanced features

Recalled values are inserted within HTML <SPAN> markers to give them the SUBSTITUT style. This can interfere with the proper display of some recalled values — particularly if the recalled values are placed within hyperlink marks. To avoid the addition of the SUBSTITUT style, insert a tilde character (~) between the recall symbols and the variable name as in the following:

    % Question text
    [EN]Earlier, you mentioned that you are generally considered a &~Q1? Was it always the case?
    [FR]Vous avez mentionné plus tôt que vous êtes généralement vu(e) comme un(e) &~Q1? Est-ce que cela a toujours été le cas?

It is possible to recall any variable available in the Perl environment as part of the CallWeb script (see the context data, in particular). The recall syntax is then {$variable}. For example, the following page header would cite the current case access code:

    # HEADER EN = Your case access code is {$_telkey}

Recalled values may contain recalls. For example, the following instruction is valid and will recall the _telkey value using &#TELKEY:

    # Recall TELKEY = {$_telkey}

There is yet another type of recall (although it is more than a simple recall). Any Perl expression (not only variable names) can be displayed where substitutions are allowed using the following syntax:

    <EXECUTE>Perl expression</EXECUTE>

Using this syntax, one can display the result of complex calculations without having to store them in a CallWeb question field.

Also, it is possible to calculate the result of a recall into a question or as part of an EXECUTE tag. See the "substitue" function on the computed questions page.

Finally, here is a specialized type of substitution: <crypt>text</crypt>. The text between these tags is encrypted using the cover function. There is a special application of this type of substitution. Options inserted in CallWeb questionnaire URLs can be obfuscated using syntax like the following:

    http://somedomain.com/cwx.cgi?_crypt=<crypt>_proj=THISPROJECT&_telkey=SOMETELKEY</crypt>

which produces

    http://somedomain.com/cwx.cgi?_crypt=0648090e3706020808253b346d0370622a45362a172e1a13380e0e123916016c1f322319

Used in an e-mail invitation, for example, CallWeb encodes the value between <crypt></crypt> tags and associates it to the _crypt URL option. This option is decompressed by CallWeb to recover the initial options and values that the encrypted text contains. It is possible to encrypt only a portion of the URL options if there are advantages to doing so.

   

Questionnaire design

Computed questions

BLANK questions

If the keyword "BLANK" is present on the question name instruction, then

  • the question does not display on screen;
  • the value of the first answer category is assigned to the question; and,
  • eventually, the flow follows the simple skip associated with the first answer category.

A BLANK question can be associated with a display condition to attribute a value to the question conditional on previous answers or to perform complex skips.

Complex skips

A simple skip associated with the first answer category of BLANK questions is honoured. Therefore, BLANK questions can be used to implement complex skips via the display condition, i.e., the complex skip logic is placed in the display condition and the destination of the skip is associated with the first category of the question.

Complex skips can also be implemented via CALCUL questions (see the next paragraph). In this case, a calculation is made, returning a value into the same question (for example; this is not a necessity, as long as there is a value in the CALCUL question to use for skips), and response categories are associated with simple skips. For example, using the contexte system variable, the following code checks whether the current time is before or after noon and redirects the questionnaire flow accordingly:

    REDIRECT CALCUL
    % Text
    REDIRECT = ( $contexte{heure} < 120000 ) ? 1 : 2
    % Categories
    *1*AM
    *2*PM
    % Simple skips
    1 = ~Q_AM
    2 = ~Q_PM
    % Display condition
    % Open parts
    ! ===================================================<

CALCUL questions

If the keyword "CALCUL" is present on the question name instruction, CallWeb expects the question text to use the following syntax:

    output_variable = perl_expression

This returns the result of the evaluation of "perl_expression" in "output_variable". The "perl_expression" must follow Perl syntax and question names must be prefixed with "$". Please refer to the questionnaire driving Circum Network Inc.'s EchantiCalc script for several examples of use of this feature.

Some special functions can be used in a CALCUL question to perform survey-specific actions. Among them are:

add_call_cetappelused to add a fake entry to the case call history to account for a completion over the open Web. See the CallWeb cookbook for a complete description of its use.
add_to_dateused to add or subtract time from a date-time value. See the CallWeb cookbook for a complete description of its use.
calc_graphused as calc_graph(field => Q1), it produces a chart of the Q1 data and inserts it where the function is called. See the related recipe.
combine_into_multipleused as Q5 = combine_into_multiple($Q1, $Q2, ...), this function combines the answers to different (single or multiple) close-ended questions into a multiple selection value. The value returned does not contain duplicate codes.

cover (or obscurcir)
used as ASTRING = cover("string"), it returns an encoded version of the string that can be decoded with the uncover function. This function uses a simple encoding algorithm that returns printable ASCII characters.
emailused as AWHEN_EMAIL_SENT=email("blabla\@domain.com",$AEMAIL_ADDRESS,"EMAIL_ENGLISH"), this function sends an e-mail to AEMAIL_ADDRESS based on the text in EMAIL_ENGLISH and puts the date and time of the action in AWHEN_EMAIL_SENT. Additional arguments are, in order: the width in characters of the text-only portion of the message (65 by default), the e-mail address where a cc is sent, and the e-mail address where a bcc is sent.
except_codesused as Q1B = except_codes($Q1,1,2,3), this function returns a multiresponse answer from which the listed codes (here, 1,2, and 3) are excluded.
ferme_le_navigateurused as ""=ferme_le_navigateur(), this function sends the JavaScript code required to close the browser window.
indexpositionused as Q2=indexposition(number,number,number,...), it returns the position of the largest Nth number where N is the first number supplied. The largest number is in position 1. Thus, indexposition(2,1,3,5,5,7,9) returns 5 because 7 is the second largest value and it is in fifth position.
last_accessused as Q2=last_access("argument"), it returns information on the last access to the case. Arguments: "date" returns the 8-digit date (YYYYMMDD); "time" returns the 6-digit time (HHMMSS); "datetime" return the 14-digit date time value (YYYYMMDDHHMMSS).
maxused as Qx=max(number,number,number,...), it returns the largest number.
minused as Qx=min(number,number,number,...), it returns the smallest number.
n_callsused as AQ=n_calls(), it returns the number of calls in the case call history; used as AQ=n_calls("Code1","Code2"), it returns the number of calls with dispositions Code1 or Code2 in the case call history; used as AQ=n_calls("Code*","Nocode"), it returns the number of calls with dispositions starting with Code or dispositions Nocode in the case call history. There can be multiple arguments of this type.
n_recordsused as Q2=n_records("CONDITION","PROJECT"), it returns the number of cases in the project data base which correspond to the condition (expressed in MySQL syntax, without the WHERE keyword). If the project name is absent, the current project is used.
n_selectionsused as Q2=n_selections($Q1,1,2,3,4), it returns the number of responses in Q1 among the list of valid responses given thereafter.
n_suchused as NSELECT1=n_such(1,4,9,"Q1-Q10"), it returns the number of responses equal to 1, 4 or 9 among the responses to questions Q1 to Q10.
positionsused as POS = positions(number,number,number,...), it returns the positions of the first number in the list made up of the numbers following the first number; the positions are delimited by the multiple-answer delimiter. Thus, positions(5,1,3,5,5,7,9) returns 3µ4.
pull_valueused as AQX = pull_value(KEYWORD,QUESTION,PROJECT,WHERE,LIMIT), it extracts the values found in the QUESTION question of PROJECT project in cases of that project which fit the WHERE clause (phrased as a MySQL WHERE statement). The function returns a delimited list of values delimited by mu characters. KEYWORD can be "ALL" or "UNIQUE" to return all values, even duplicates or unique values. The values are returned in no particular order. Example: AQX = pull_value("ALL","myquestion","myproject","RESERVED <> 1") places a list of values from "myquestion" in "myproject" where RESERVED is different from 1 in AQX in the current project.
push_valueused as AQX = push_value(VALUE,QUESTION,PROJECT,WHERE,LIMIT), it places VALUE in the QUESTION field of project PROJECT in the one case of that project which corresponds to the WHERE condition (expressed in MySQL syntax). The function returns the _telkey of the case that was affected (into AQX in the example). If something goes wrong, the function returns an empty string rather than a valid _telkey value. If more than one case in the PROJECT correspond to the WHERE condition, the function also returns an empty string... unless LIMIT is the number 1 in which case the function randomly selects one of the _telkeys that correspond to the WHERE condition. Example: AQX = push_value("1","RESERVED","myproject","RESERVED <> 1",1). This will place a 1 in the RESERVED question of myproject in one case selected randomly among the cases where RESERVED does not already equal 1 and return the affected _telkey into AQX.
put_values_in_caseused as AQX = put_values_in_case(key=>value, key=>value, ...), it places values in fields of a given record in a given project. The complete syntax and utilization are described in the CallWeb cookbook.
random_integerused as AQX = random_integer(n), it returns a random number between 1 and "n". "n" can be a fixed value like 10 or a value stored in a CallWeb field such as $AQ1.
random_integer2used as QX = random_integer2(n,"QX"), it returns a random number between 1 and "n" into QX. "n" can be a fixed value like 10 or a value stored in a CallWeb field such as $AQ1. The selection of the random integer is made among possible integers that have been least often selected in QX as of when the function is called. For example, looking for a random integer between 1 and 3, if 1 has already been chosed twice and 2 and 3 have never been chosen, either 2 or 3 will be returned, randomly. This ensures a flat distribution of all integers between 1 and n over time. To implement a distribution other than flat, it is possible to request a random integer between 1 and 100 and to perform different actions according to shares of the 100 integers (e.g., skip the next question if the random number is less than 51).
random_subsetused as COMBO = random_subset($MULTIQ,n), it returns a random selection of "n" answers among the answers stored in the multiple-response question "MULTIQ". The complete syntax and utilization are described in the CallWeb cookbook.
recodeused as Q4RECODE = recode("Q4","Q4RECODE","1,2,3=1","4-6=2","ELSE=3"), it returns the recoded value of Q4 (a close-ended question) into Q4RECODE using the rules which follow the second argument of the function. (Still using the same example) If Q4RECODE has a maximum number of answers greater than 1 (multi-response question), recode returns as many recoded categories as apply; otherwise, Q4RECODE contains the first recoded category intercepted by the rules. For example, if Q4 contains answers 1, 2 and 5, the recode returns 1 and 2 into Q4RECODE if Q4RECODE is a multiple-answer question and only 1 if it is a single-answer question. Rules following an "ELSE" rule are never tested.
record_wavused as AFILENAME = record_wav("start") or PROCESSES = record_wav("stop"), this function starts or stops a recording of the feed received by the computer microphone. This is used in face-to-face interviewing. More details in the cookbook.
residualused as Q3C=residual($Q2,$Q3A,$Q3B,...), it returns the responses in Q2 stripped of the responses in Q3A and Q3B (there can be any number of additional arguments); this was developed to identify the third selection in Q2 (a question allowing three selections) once the top selection in Q3A and the secondary selection in Q3B were excluded.
select_random_combinationused as COMBO = select_random_combination(among,number,exclusive,other_combination,other_combination,...), it returns a combination of "number" integers between 1 and "among". The complete syntax and utilization are described in the CallWeb cookbook.
shuffle_code_labelsused as AQy = shuffle_code_labels("Qx","[EN], [FR], ","[EN] and[FR] et"), it returns a list of the text of all answer categories in Qx, in random order, separated by the second argument; the third argument supplies the link between the second last and the last categories (typically "and", but it could be "or" or a comma, for example). Substitutions and display conditions are respected.
straightlinedused as BINARY=straightlined("Q1-Q10","QFLAG"), it returns a 1 if all answers from Q1 to Q10 are the same (straightlining). QFLAG is an optional question name; if it is present two things happen: first, a 1 is stored in that field if the test fails; second, the test is not conducted if there is already a 1 in that field. See the CallWeb cookbook for more details.
substituesubstitue("&Q1") or substitue("&@Q1") or substitue("&&AQ1") is the string of text produced by the recall functions;
test_email_addressused as AQX = test_email_address(e-mail address), it verifies whether the e-mail address is correct. See the related recipe. Make sure to set the test_email_address_hostname installation option to a subdomain that resolves to the IP address of the server performing the test.
time_betweenused as AQX = time_between($ATIME1,$ATIME2,"some_unit"), it returns the amount of time between the two arguments expressed as some_unit (choices are SECONDS, MINUTES, HOURS and DAYS). The time values are expressed as YYYYMMDD at a minimum; hours (HH), minutes (MM) and seconds (SS) can be added as well — time values are actually padded to the right to 14 characters with as many zeros as necessary.

uncover (or decouvrir)
used as ASTRING = uncover("string"), it returns a decoded version of the string that was encoded with the cover function.

COMPUTE BUTTON feature

It is sometimes useful to perform a mathematical operation right on a page, such as summing a series of numerical answers and displaying the total. This can be accomplished by adding a button on the page; that button performs the operations programmed in a CALCUL question and then redisplays the same page where a recall of values can be performed.

Syntax of the COMPUTE BUTTON:

<COMPUTE BUTTON>CALCUL_QUESTION, text</COMPUTE BUTTON>
or
<BOUTON CALCULE>CALCUL_QUESTION, text</BOUTON CALCULE>

CALCUL_QUESTION is the name of the CALCUL question triggered by the button. The text which follows the CALCUL_QUESTION and a comma is displayed as part of the button. If this text happens to be the name of a (image) file, that image is used to display the button. In this case, a third portion, still delimited by a comma, can contain the ALT text of the image. A fourth portion, still delimited by a comma, can contain the keyword NOTEST to ensure that the button calculation is activated even if the data on the page do not conform to the normal validation tests.

For example, the following code:

    Q3 MIN=0 MAX=1
    % question
    [EN]How many people from each of the following age groups live in your household, including you who have already indicated being over 17?
    [FR]Combien de personnes de chacun des groupes d'âges suivants votre ménage compte-t-il en vous incluant et compte tenu que vous avez déjà indiqué être âgé de plus de 17 ans?
    % note
    [SUFFIX:A][EN]Less than 10 years old[FR]Moins de 10 ans
    [SUFFIX:B][EN]From 11 to 17 years old[FR]De 11 à 17 ans
    [SUFFIX:C][EN]18 and more[FR]18 ans ou plus
    % categories
    *1*=*[EN]Number of people[FR]Nombre de personnes
    % skips
    % condition
    % open-end
    1 = N2.0 0 10
    ! ==================================================
    Q3D MIN=0 MAX=1
    % question
    =Q3A
    % note
    [EN]<COMPUTE BUTTON>CALCQ3,Sum up</COMPUTE BUTTON>[FR]<BOUTON CALCULE>CALCQ3,cw/additionner.gif</BOUTON CALCULE>
    % categories
    *1*NM*[EN]&&ACALCQ3[FR]&&ACALCQ3
    % skips
    % condition
    % open-end
    ! ==================================================
    CALCQ3 CALCUL
    % question
    ACALCQ3 = $AQ3A + $AQ3B + $AQ3C
    % note
    % categories

    % skips
    % condition
    % open-end
    1 = N3.0 0 999
    ! ==================================================

displays this table:

 Number of people
Less than 10 years old
From 11 to 17 years old
18 and more
(recalled &&ACALCQ3 value here)

Note: other Web survey packages perform such operations using JavaScript; in keeping with the CallWeb philosophy, no JavaScript is used in programming this feature. Also, the operations triggered by the COMPUTE BUTTON are totally up to the questionnaire designer (e.g., totalling, sum of products, extraction of data, string manipulation) since they are encapsulated in a CALCUL question which may perform any operation and modify any number of fields.

The display condition of the CALCUL question triggered by the button is enforced.

RANDOM questions

RANDT is now deprecated. Please use the random_integer function described above.

If the keyword "RANDOM" is present on the question name instruction, CallWeb expects the rest of the question to use one of the following syntaxes:

    RANDT(number,output_variable)
    RANDT(input_variable,output_variable)

The RANDT function returns, in "output_variable", a random integer between 1 and either NUMBER or the value of the variable named "input_variable".

   

Questionnaire design

Commenting a script

It is often useful to add comments in CallWeb scripts to provide explanations of what the designer is trying to accomplish. The feat may not be so obvious to another questionnaire designer who may be called upon to modify one's script.

There are two classes of comments in a CallWeb script:

  • comments that are deleted during compilation; these are all the script lines that start with at least two pound signs (that can be preceded by one or more blank spaces or tabs);
  • comments that are saved during compilation and that are printed on questionnaire printouts produced by the cwquestionnaire module; these comments are located at the end of a script line, passed a space and two pound signs, They are associated with the segment of the question where they are located and they are printed accordingly by cwquestionnaire.cgi.

Here are the legitimate locations of printing comments:

    Q3A ## Question name comment
    % question ## Question segment comment
      [EN]How many people from each of the following age groups live in your household, including you who have already indicated being over 17?
      [FR]Combien de personnes de chacun des groupes d'âges suivants votre ménage compte-t-il en vous incluant et compte tenu que vous avez déjà indiqué être âgé de plus de 17 ans?
    % note ## Note segment comment
      [EN]Less than 10 years old[FR]Moins de 10 ans
    % categories ## Category segment comment
      *1*=*[EN]Number of people[FR]Nombre de personnes ## Specific category comment
    % skips
      1 = Q99 ## Specific skip comment
    % condition
      Q1.EQ.1 ## Display condition segment comment
    % open-end
      1 = N2.0 0 10 ## Specific open-part comment
    ! ==================================================

Note that printing comments are not compabible with cwedit.cgi and with the copy syntax which uses the equal sign (=).

   

Questionnaire structure

Introduction

The basic CallWeb questionnaire contains a series of instructions defining questions and variables. Another set of commands is available to affect questionnaire structure. All of these instructions are located within the questionnaire file and identified with a pound sign ("#") as the first character of the line. Each of these instructions must fit on a single line in the questionnaire file.

   

Questionnaire structure

Pages

By default, CallWeb displays one question per browser screen. The # GROUP instruction changes this default behaviour. It uses the following syntax:

    # Group NAME = VAR1 - VAR2

where

  • NAME is the name of the page; any unique alphanumeric string is acceptable;
  • VAR1 is the first variable to include on the browser page;
  • VAR2 is the last variable to include on the browser page; obviously VAR2 must come after VAR1 in the questionnaire order.

Limitations: note that skips cannot take place within a page and that simple skips are honoured only on the last question displayed on the page. Also, BLANK questions and CALCUL questions do not perform their feat within pages; these types of questions should be located between defined pages if necessary — in fact, their inclusion in a page is flagged as an error by the compiler.

   

Questionnaire structure

Tables

By default, CallWeb displays each question sequentially. The # TABLE instruction changes this default behaviour. When a series of variables belong to a matrix:

  • the question text of the first variable is displayed;
  • the note field of each question labels each row, and;
  • the answer categories of the first question determine the columns labels and their order.

The syntax of the "# TABLE" instruction is:

    # TABLE NAME = VAR1 - VAR2 HEADER=n PIXELS=n COLVARS=n POSITION=x FORCE_CODES TRANSPOSE SPECIAL=(n,...) CORNER=(...) VALIDATION

where

  • NAME is the name of the matrix; any unique alphanumeric string is acceptable;
  • VAR1 is the first variable to include in the table;
  • VAR2 is the last variable to include in the table; obviously VAR2 must come after VAR1 in the questionnaire order; (the next arguments are all optional and their study should be reserved to more advanced users)
  • HEADER=n is the frequency at which the column headings are repeated within the table, expressed in number of questions (-1 means no repetition); it can also be called using ENTETE=n
  • PIXELS=n is the number of pixels the browser should attempt to give to each response column (-1 lets the browser figure out the layout);
  • COLVARS=n is the number of variables to stack in the columns;
    • the default is -1 which means that the columns of a table are defined by the first variable in the table set (it can also be called using the VARSCOL=n name)
    • a value of 1 has a similar meaning except it directs the system to place the text of the first question within the matrix, above and across the answer categories
    • a value greater than 1 means that the matrix displays that number of variables across the columns of the matrix — obviously, the number of variables in the matrix must be a multiple of the number of columns used across the columns; the system displays the first COLVARS columns across the first row of the matrix, then the second set of COLVARS columns across the second row, and so on; in the questionnaire .scw file, the variables must be ordered according to the sequence of use in the matrix, i.e., from left to right and from top to bottom (i.e., if the matrix comprises 8 questions (Q1-Q8) and is defined as using two variables across the columns, Q1 and Q2 are displayed in that order on the first row, then Q3 and Q4 on the second row, etc.)
  • POSITION=x determines the position of the table on the page: "LEFT" or "GAUCHE" puts the table on the left margin; "RIGHT" or "DROITE" does the same on the right margin; "CENTER" or "CENTRE" centres the table horizontally on the page. The default value is LEFT.
  • FORCE_CODES is a keyword which forces the variables in the matrix to use their own response codes (whereas, without it, every variable in the matrix uses the codes of the first-row variable for their column order); this cannot be used along with permutated response codes; for example, this can be used to display a drop-down list of provinces and territories in a table that otherwise contains single boxes of text;
  • TRANSPOSE reverses the presentation of rows and columns. By default, CallWeb displays the response categories as columns and the questions as rows such that one (or more) selection is expected on each row; with TRANSPOSE, the questions are arrayed as columns and the response codes make up the rows such that one (or more) response is expected for each column. For example, parent educational achievement could be requested with each of the mother and the father occupying one column of the matrix;
  • SPECIAL is an instruction which identifies the response codes that are to be coloured differently from the normal table colour; the normal colour is driven by the # M_COULEURCELLULES instruction while the SPECIAL codes are painted with the # M_COULEURSPECIALE instruction; the column header cell, which is normally coloured by the # M_COULEURTITRESCOLONNES instruction, also bears the special colour for the selected codes. All vertical variables of the table share these special codes such that, if code 9 is to be special-coloured, all codes 9, in all vertical variables, are coloured as such; also refer to the "S" answer category behaviour code;
  • CORNER is text within parentheses that appears in the upper left hand side corner of the matrix; language codes in the form of [xx] may be embedded within this text; if the text includes parentheses, insert them as &# codes where an open parenthesis is the code &#40; and a closed parenthesis is the code &#41;
  • VALIDATION is a special validation instruction for the matrix as a whole; validation instructions include:
    • EXCLUSIF(min,max,A)
      this validation instruction demands that the respondent provides only one answer per column of the table; the system accepts a minimum of MIN answers between the values of 1 and MAX; if the "A" argument is provided, the test is performed on the open end parts of the questions in the matrix; otherwise it is performed on the normal questions.
    • ORDRE(min,max,A)
      this validation instruction places demands on the respondent similar to EXCLUSIF except the answers are interpreted as an order of preference; therefore, the set of answers must include, at a minimum, all values between 1 and the MIN argument out of a maximum of MAX answers.

Important note: by definition, tables are displayed within pages; therefore, the questions making up the matrix must also be part of a (and the same) page defined with a # GROUP instruction.

The following statements show an example which incorporates all of the circumstances described in this section:

    # Group Alpha = Q1-Q10
    # Table Beta = Q2-Q8
    # Permutation Gamma = Q3-Q7

   

Questionnaire structure

Permutation of questions

By default, CallWeb displays the questions in the order in which they are defined in the questionnaire. This default order can be affected by simple skips and complex skips. It can also be randomised via the permutation of questions.

CallWeb uses the # PERMUTATION instruction to define sets of consecutive questions which are to be displayed in random order. The syntax follows:

    # Permutation NAME = VAR1 - VAR2 STEP=step LIMIT=limit LIKE=permutation

where

  • NAME is the name of the permutation; any unique alphanumeric string is acceptable;
  • VAR1 is the first variable to include on the permutation set;
  • VAR2 is the last variable to include on the permutation set; obviously VAR2 must come after VAR1 in the questionnaire order;
  • STEP is the number of variables in each block to be permutated (default = 1; can also be named PAS).
  • LIMIT is the number of blocks of variables (blocks are defined by the STEP parameter) to display (default = all; can also be named LIMITE).
  • LIKE (COMME in French) is the name of another permutation that will drive the order of the current permutation (default, none).

In the following example,

    # Permutation 1 = Q5-Q10 STEP=2

Q6 always comes right after Q5, as will Q8 after Q7 and Q10 after Q9. However, the three pairs are offered in random order to respondents as in:

    Q7-Q8, Q5-Q6, Q9-Q10
    or
    Q9-Q10, Q7-Q8, Q5-Q6

In the following example,

    # Permutation 1 = Q5-Q10 STEP=1 LIMIT=2

Only two randomly selected questions in the series from Q5 to Q10 are displayed, in random order.

In the following example,

    # Permutation 1 = Q5-Q14 STEP=2 LIMIT=2

Only two randomly selected blocks of two questions in the series from Q5 to Q14 are displayed. They could be Q7-Q8 and Q11-Q12, for example.

Display conditions affect which variables are displayed throughout the questionnaire, including in permutations.

Parallel permutations

Sometimes, the order of a second set of questions must be the same as the random order of a first set of permutated questions. This is achieved by adding the LIKE= parameter to the second permutation definition followed by the name of the first permutation. For example:

    # Permutation P1 = Q5-Q14 STEP=2 LIMIT=2
    # Permutation P2 = Q15-Q24 LIKE=P1

Permutation P2 will always be presented in the same order as permutation P1. Note that the LIKE parameters do not supercede the STEP and LIMIT parameters. The number of items in the two permutations must be the same. Different display conditions may apply and modulate the number of items displayed in a given questionnaire but the order of those displayed will be the same.

Permutation within permutation: embedding permutations at any depth

All of the features described above can be implemented in permutations that are performed within permutated blocks. For example, in the following definitions:

    # Permutation E001 = Q1-Q15 STEP=5
    # Permutation I002 = Q1-Q5
    # Permutation I003 = Q11-Q12
  • one exterior permutation E001 entails three blocks of 5 questions which will appear in random order (e.g., sometimes Q1-Q5, then Q11-Q15, then Q6-Q10)
  • one interior permutation I002 presents Q1 to Q5 in random order;
  • another interior permutation I003 makes Q11 and Q12 appear in random order (e.g., an interior permutation does not need to use an entire block of the exterior permutation).

The questions of a permutation cannot overlap between blocks of the exterior permutation. Also, a permutation cannot include questions that are part of an exterior permutation and other questions that are not.

Note: permutation imbedding works only if the names of the permutations are chosen such that, in each case, the exterior permutation comes before the interior permutation, in alphabetical order of permutation names.

Such imbedding of permutations can be done at any depth level (e.g., permutations within permutations within permutations within ...).

   

Questionnaire structure

Hierarchical projects

Typically, all data for a project are maintained within a single CallWeb data base. There are times, however, when a more complex structure is more appropriate. Let's take the example of a study on family employment. Part of the questionnaire may deal with the household; another part may request information from each household member. Of course, it is possible to set up a large enough number of blocks of questions to accommodate the largest possible household, but this may not be the most efficient way to collect the information. That's where hierarchical projects come into play.

In hierarchical projects, a master CallWeb project acts as the parent data base (in our example, it would deal with the household). One or more "children" CallWeb projects link into the master project to allow as many children "relations" as is required. In our example, each household member would be a child of the master household project. Each such child relation requires a separate CallWeb project; there can be any number of such relationships within a project and children projects may have children projects of their own. For example, one household could have several household members and each household member could have several jobs.

Syntax

Hierarchical projects are defined using RELATION-type questions.

  • In a RELATION question, the minimum and maximum number of answers refer to the number of child records. Setting the minimum and maximum to 1 and 3 will ensure that the respondent enters at least 1 child and no more than 3. The default values are 0 and 9999 respectively.
  • The number of child records is stored in the RELATION question upon moving to the next page.
  • A RELATION question has no text of its own; therefore, it would normally be inserted in a multi-variable screen which would provide context and explanations. Note that a RELATION question cannot co-exist on the same page with other questions collecting answers; the reason for this is that the add and modify relation buttons open a new questionnaire without first saving the information in the current page of the parent questionnaire.
  • The question text segment of the question is used to pass along the RELATIONship parameters using the following syntax (where commas and slashes count!):
parameter value exemple explanation
child_project=children,name of the CallWeb project
parent_telkey_varname_in_child_project=parent_telkey,name of the child project variable that will contain the parent _telkey code
display_from_child_project=Q1/Q2/AQ3,the slash-separated list of child values displayed in table format within the parent project. Each question name listed can be preceded by a display condition within square brackets. If the display condition requires a comma, insert it as &#comma; (with the trailing semi-colon); if it needs a slash, inset it as &#slash; (with the trailing semi-colon).
copy_into_children=Q11/Q12/AQ13,the slash-separated list of values to be copied from the parent to the children (they must exist in both projects and be attributable in the child project [see # ATTRIBUTABLE QUESTIONS])
child_subset_in_sql=Q1=1,(optional) the expression must be a valid WHERE MySQL expression (without the keyword "WHERE"); if present, this parameter determines the list of child records displayed by the RELATION question; it supersedes the selection of child records containing the "parent_telkey_varname_in_child_project" value. The expression cannot contain a comma since commas act as separators.
erase_question=QCONFIRM,(optional) this is the name of a question in the parent questionnaire that is used to request confirmation of the deletion of a child record. In the absence of this parameter, deletions are done without confirmation. The "erase_question" must possess the ERASEREL question type. It is not shown in the normal flow of the questionnaire and it is automatically made BACKWALL.
erase_code=1,(optional) this is the numeric code of the "erase_question" question that indicates that the request for deletion was confirmed; it is mandatory if "erase_question" is defined. For example, if the question is "Do you really want to delete this record?" and if "Yes" bears code 1, then "erase_code=1" would be used in the RELATION question.
erase_calcul=QCALCUL,(optional) this is the name of a CALCUL question that is executed after deleting a child record when "erase_question" equals "erase_code".
read_also=Q99,(optional) a slash-separated list of child values read from the child record and that are necessary for some substitutions.
order_by=Q99,(optional) a slash-separated list of child values used to sort the child table.
crypt
=yes,(optional) yes or no, whether or not the links to the children are crypted.

Useful pointers

  • Use an open-end part (e.g., APARENTCODE) to store the many characters of parent_telkey_varname_in_child_project.
  • Variables copied from the parent to the child (parent_telkey_varname_in_child_project and copy_into_children) should probably bear a STOCK type so that they are not displayed.
  • In the child project, variables copied from the parent must be listed in a # Attributable questions instruction so that the child project accepts the values.
  • There are default text values for the buttons to add, modify or delete a child as well as to refresh the page displayed. These text values can be customized for a project using a series of pound instructions prefixed with # Text relation.
  • For technical reasons, the "refresh" button of RELATION questions is NOT compatible with the DEMO mode. The same can be accomplished in DEMO mode by backtracking to the question prior to the RELATION question and going forward again.
  • Recalling a RELATION question as &@QUESTION inserts the number of children in the recall location. Recalling as &QUESTION inserts a complete table of the children.
  • The child project must include a "# URL" instruction pointing back to the parent questionnaire. The URL link should use a syntax like this one:
    # URL = callweb.cgi?_proj=PARENT_NAME&_lang=EN&_telkey={$APARENT_TELKEY}&_debute=RELATION_QUESTION
    where PARENT_NAME is the name of the parent project, APARENT_TELKEY is the name of the child variable containing the parent telkey (parent_telkey_varname_in_child_project, above) and RELATION_QUESTION is the name of the RELATION question in the parent project.

Respondent user interface

When reaching the RELATION question, the respondent is shown an "Add" button and a "Refresh" button. Upon clicking the Add button, the system continues with a new child questionnaire; once that child questionnaire is completed, the system redisplays the parent questionnaire with a table describing the existing child or children. In this table, a link allows the respondent to correct one of the children or to delete it. The table also displays information from each children using the question text and the text of the answer categories from the child project. Alternative text for questions text and answer categories can be defined in the appropriate segments of the child questionnaire by putting this alternative text between <parent></parent> tags. For example,

*1*This is the text for category 1 <parent>Category 1</parent>

would display "This is the text for category 1" within the child questionnaire but "Category 1" in the summary table in the parent questionnaire.

Extracting data from child records

Child data are stored in a separate CallWeb project. Nonetheless, it is possible to extract information from the child data during the completion of the questionnaire and use it in the parent project.

The &apropos_relations function can be used in CALCUL questions to perform extractions. The general syntax of this function is as follows:

    DESTINATION = &apropos_relations("RELATION_QUESTION","DATA_TYPE","OPTIONAL_PARAMETER")

The following table details the existing data types that can be produced and their associated parameters.

Data typeParametersExample
N(none)&apropos_relations("REL","N")
TOTAL or SUMchild variable to sum up&apropos_relations("REL","TOTAL","AQ1")
MINchild variable from which to get the minimum&apropos_relations("REL","MIN","AQ1")
MAXchild variable from which to get the maximum&apropos_relations("REL","MAX","AQ1")
AVGchild variable from which to get the average&apropos_relations("REL","AVG","AQ1")
STDchild variable from which to get the standard deviation&apropos_relations("REL","STD","AQ1")

   

Questionnaire structure

Interruption

A button to offer respondents the ability to interrupt the questionnaire may be added on every page of the questionnaire by activating the # Bouton stop instruction. By default, # BOUTON STOP is deactivated as in:

    # Bouton stop = non

To display the Interruption button, set the instruction to "oui" and add the question where the respondent will be directed upon interruption after a comma, as in:

    # Bouton stop = oui, Q99

This instruction will force the display of an Interruption button on each page of the questionnaire. If the respondent clicks that button, they will be directed to question Q99 but, upon coming back into the questionnaire later, they will resume from the page attained before requesting the interruption.

The STOP button can also be displayed conditionally based on a display condition placed in lieu of the Yes first argument, in square brackets. For example:

    # Bouton stop = [QTYPE.EQ.1], Q99

will display the STOP button only if QTYPE equals 1.

What happens on the page where the interruption is directed is up to the CallWeb script designer. It could be a page without buttons (BACKWALL, CULDESAC and NOSTOP) displaying some message or the URL needed to return into the questionnaire. It could be calculated questions that send an e-mail to the respondent with instructions. It could be anything CallWeb can do with its set of features and questions.

The text of the Interruption button is controlled by the # TEXTE STOP instruction. Each language of the questionnaire may have its own such instruction as in:

    # Texte stop = [EN]Stop[FR]Arrêt

The interruption button can also be an image. See the # IMAGE STOP instruction.

Although a STOP block of questions is often used to allow stopping of a questionnaire at one point and resuming from where the interruption block was invoked, it can also be used to branch to a special set of questions from anywhere in the questionnaire and then to go back to the normal flow of questions afterwards. To perform this feat, add a # Stop button instruction, branch to an isolated part of the questionnaire and end this block of questions with a question qith a DESTOP type. The DESTOP question branches back to the question from which the STOP button was invoked.

   

Questionnaire appearance

Introduction

The appearance of the questionnaire is controlled by three sources of information: a cascading style sheet, various pound sign instructions and some in-questionnaire parameters.

   

Questionnaire appearance

Page structure and templates

In its simplest form, the CallWeb page (see the example on this page) is a vertical construction that includes the following pieces:

  • a header, controlled by the # Header instruction
  • an optional horizontal series of buttons, controlled by the # Button order top instruction
  • the body of the page, that contains the questions
  • an horizontal series of buttons, controlled by the # Button order bottom instruction
  • a footer, controlled by the # Footer instruction

This linear structure and the related pound instructions allow for the creation of a wide variety of questionnaire looks and for the creation of custom pages. While remaining simple, this structure is constraining: it can only be vertically oriented and the integration of visual elements from other sites like corporate Web sites is arduous and limited. The # Template instruction shatters these constraints imposed by the vertical construction of the questionnaire.

Template-controlled page structure

The # Template instruction offers a second page composition method. It identifies an HTML file from which the questionnaire page is built. For example, the HTML file could be a copy of a typical Web page from an organisation or templates of the Government of Canada Common Look and Feel Standards for the Internet standard. In that HTML page, the CallWeb designer places markers that CallWeb substitutes for portions of questionnaire pages. The existing markers are as follows:

MarkerCorresponding contentNotes
&*HEADERPage header controlled by the # Header instructionThis maker does not need to be at the top of the page.
&*BUTTONSTOPHorizontal series of buttons controlled by the # Button order top instructionThis maker does not need to be at the top of the page.
&*BODYQuestions displayedThis maker does not need to be in the middle of the page.
&*BUTTONSBOTTOMHorizontal series of buttons controlled by several pound instructionsThis maker does not need to be at the bottom of the page.
&*FOOTERPage footer controlled by the # Footer instructionThis maker does not need to be at the bottom of the page.
&*BUTTONSH:... (note the colon)Horizontal series of buttons selected from the list of letters that follows the colon. Eligible letters are: [B]ack, [N]ext, [U]nlock, [L]anguage, [T]hermometer, [S]top. For example, &*BUTTONSH:BN displays a Previous page button and a Next page putton, in that orderThis marker, like the others, can be anywhere on the page.
&*BUTTONSV:... (note the colon)Vertical series of buttons selected from the list of letters that follows the colon. Eligible letters are: [B]ack, [N]ext, [U]nlock, [L]anguage, [T]hermometer, [S]top. For example, &*BUTTONSV:BN displays a Previous page button and a Next page putton, in that orderThis marker, like the others, can be anywhere on the page.

These markers can be placed anywhere in the HTML template page. This could allow, for example, to have a Previous page button on the left side of the page and a Next page button on the right side. None of the markers is mandatory and all can be repeated (e.g., there can be several &*BUTTONSH:...)

Technical note: the template page must be built taking into account that the questionnaire is produced from the root directory of the CallWeb instance. Therefore, links to objects (e.g., images, styles, hyperlinks) must be relative to the root directory (which is most flexible) or must be absolute (which is simplest).

   

Questionnaire appearance

Text formatting

CallWeb expects to find a cascading style sheet (CSS) called "style.css" in the directory of the questionnaire file; otherwise, it looks for it in the resources directory (usually gr/) and finally in the current directory (the CallWeb root installation directory in the case of the callweb module or the source utility directory for utilities). The # Stylesheet instruction can also be used to name a stylesheet file for a particular project.

To obtain the official CallWeb look, place this stylesheet in the gr/ directory and the folloing instructions in the etc/usager.conf file:

    _M_COULEURTITRESCOLONNES = #4578A6
    _M_COULEURCELLULES2 = #D5EBFF
    _M_COULEURCELLULES = #E8F4FF
    _M_COULEURBORDURES = #A8B4BF

The explanation of the syntax of CSS is beyond this manual; several good references exist, as well as several Web sites. (http://www.w3.org/TR/REC-CSS1 is a key reference.) The CSS must define some specific styles and it may contain additional ones.

CallWeb styles (note that capitalization of the style name counts in certain browsers and that CallWeb uses all-uppercase style names):

  • .QUESTION
    used to format the question text;
  • .REPONSE
    used to format the text of answer categories in normal format;
  • .AUTOSUBMIT
    used to format the text of answer categories subjected to # Auto submit; the following style is particularly useful:
    .AUTOSUBMIT { padding-right: 20px; background: transparent url(../gr/autosubmit.gif) no-repeat center right; }
  • .NOTE
    used to format the text of notes;
  • .COLONNE
    used to format the text of answer categories in matrix format;
  • .LIGNE
    used to format the text of item in matrix format;
  • .SUBSTITUT
    used to format the text which is recalled from previous data, in question text, note and answer categories;
  • .THERMOMETRE
    used to format the text of the thermometer text;
  • .MATRICE, .MATRICE2, .MATRICE3
    attributed to all question tables (displaying questions as rows and answer categories as columns); useful to locate the tables horizontally;
  • .CATEGORYTABLE
    attributed to HTML tables which structure the answer categories;
  • .BOUTONS
    attributed to the button table; useful to locate the buttons horizontally;
  • .ERREUR
    used to format error messages;
  • .H5
    used to format a few headings;
  • .EQUIVALENTH5
    used to format utility headers;
  • .EQUIVALENTH6
    used to display question names under some circumstances;
  • .NEPASLIRE
    used to format response categories using the P behaviour code;
  • .LIRE
    used to format response categories using the L behaviour code;
  • .SPECIAL
    used to format response categories using the S behaviour code.
  • .BUTTON
    used to format buttons such as the Next Page or Previous Page buttons.
  • .DROPDOWN
    used to format dropdown lists.
  • .NUMBOX
    used to format numeric open-end boxes.
  • .TEXTBOX
    used to format single-line and multi-line text boxes (open-end parts).
  • .CATI_APP_BUTTON_O
    used to format CATI appointment buttons with a mandatory comment.
  • .CATI_APP_BUTTON_F
    used to format CATI appointment buttons with an optional comment.
  • .CATI_APP_BUTTON_A
    used to format CATI appointment buttons without comment.
  • .CATI_OTH_BUTTON_O
    used to format CATI result buttons other than appointments with a mandatory comment.
  • .CATI_OTH_BUTTON_F
    used to format CATI result buttons other than appointments with an optional comment.
  • .CATI_OTH_BUTTON_A
    used to format CATI result buttons other than appointments without comment.
  • .CATI_QUE_BUTTON
    used to format the CATI button that opens the questionnaire.
  • .CATI_TEL_BUTTON
    used to format the CATI buttons that change the telephone number.
  • .CATI_ACT_BUTTON
    used to format the CATI buttons associated with actions (new number, search, finish).
  • .PERMBUTTON
    used format submit buttons in administrative forms.

Styles which should be defined:

  • BODY
    sets the background, the default font and the page margins for the entire questionnaire. (With regard to text formatting, we prefer to set all of the basic HTML tags so that all browsers behave correctly. The main ones, for CallWeb use, are P, TABLE, TR and TD.)

Other styles:

  • Any other style may be defined and used in question text, note and answer category text via the SPAN HTML syntax: <SPAN CLASS=style>texte</SPAN>

Text formatting

   

Questionnaire appearance

Colours and layout

A number of pound instructions control the formatting of several aspects of the questionnaire appearance. Another page of this documentation identifies which aspects of the page are controlled by CSS styles.

Colours and layout

All tabular outputs (tables and MEMO questions within questionnaires but also parameter tables in utilities, record dumps in cwNav, two-way crosstabs in cwFreq, etc.) are produced by the same protocol. This protocol uses the pound instructions stored within the questionnaire to format tabular outputs. If the questionnaire script does not contain specific instructions for a particular aspect of the tabular output, CallWeb uses the specific installation defaults stored in the instance configuration directory. If instructions are not found there, defaults apply.

Advanced colours and layout

It is possible to control the formatting of question tables in a finer way by using a CSS style sheet. To access this advanced mode, first activate it with the following pound instruction:

# Styles for tables = yes

With this mode activated, the format of table cells is controlled by a collection of style sheets rather than by the pound instructions listed above. The following image documents which style controls which cell. The lines of style definition under the image indicate the statements used in the style.css file (note that all style names are in uppercase letters).

Advanced colours and layout

 .ORDINARY_CELL_A, .ORDINARY_CELL_A0, .ORDINARY_CELL_A1 { background: #E4EDF9; }
.ORDINARY_CELL_A2 { background: #F9FAFF; }
.ORDINARY_CELL_B, .ORDINARY_CELL_B0, .ORDINARY_CELL_B1 { background: #FFFFFF; }
.ORDINARY_CELL_B2 { background: #CCCCCC; }
.SPECIAL_COLUMN0 { background: #FFFFFF; }
.SPECIAL_COLUMN1 { background: #FFFF66; }
.SPECIAL_COLUMN2 { background: #CCFF00; }
.SPECIAL_LINE_A0 { background: #FFFFFF; }
.SPECIAL_LINE_B0 { background: #CCCCCC; }
.SPECIAL_CELL1 { background: #FFFFCC; }
.SPECIAL_CELL2 { background: #CCFF99; }

Here is how this works:

  • first, note that the table is broken down into three vertical sections (because there are two questions side by side; it would be two if there was only one question and four if there were three questions, etc,):
    • the first vertical section is the column of row labels; note that all styles in that column end with a "0";
    • the second vertical section corresponds to the first question; all of its styles end with "1";
    • the third vertical section is where the second question is located; all of its styles end with "2";
    • if there were more vertical questions, the numbering of the styles would ensue.
  • second, note that, in the body of the table, the colours of lines alternate for odd-numbered and even-numbered lines; styles corresponding to odd-numbered lines have an "A" as the second last character while the syles for even-numbered lines have a "B" in the same position;
  • there are 4 style name prefixes:
    • SPECIAL_COLUMN (which becomes SPECIAL_COLUMN0, SPECIAL_COLUMN1 and SPECIAL_COLUMN2 for the various vertical sections) controls the column headers;
    • SPECIAL_LINE_ (which becomes SPECIAL_LINE_A0 for the odd-numbered lines in section 0, etc.) controls the line headers;
    • SPECIAL_CELL (which becomes SPECIAL_CELL0 and SPECIAL_CELL1 for the various vertical sections) controls the cells belonging to columns defined as "special" using a answer category behaviour code or the table definition pound instruction;
    • ORDINARY_CELL_ (which becomes ORDINARY_CELL_A1, ORDINARY_CELL_B1, ORDINARY_CELL_A2 and ORDINARY_CELL_B2 for the odd- and even- numbered lines in sections 1 and 2, etc.) controls the cells in the body of the table.
  • if this advanced mode is used in a project, it also affects the presentation of tables in utility programs. Therefore, it is a good idea to define the following styles (which are not used in question tables but are in other contexts): ORDINARY_CELL_A, .ORDINARY_CELL_A0, .ORDINARY_CELL_B, .ORDINARY_CELL_B0.

   

Questionnaire appearance

Particular cases: in-questionnaire formatting

Open-end box size

It was earlier stated that the syntax to define an alphanumeric open-end part was

    Cwidth

In fact, two other arguments may be used, as follows:

    Cwidth LINES COLUMNS
  • LINES is the number of lines of the textbox;
  • COLUMNS is the number of columns of the textbox.

HTML coding

In the question text, the question note and in the text of answer categories, as well as other questionnaire pound instructions such as # ENTETE and # PIED, it is possible to include standard HTML code. This way, HTML tables can be drawn to line up parts of text, hyperlinks can be inserted, images can be displayed, etc.

   

Questionnaire appearance

Final products

Here are examples of appearences that CallWeb pages may take. Of course, this is by no means an exhaustive set.

   

Field management

Introduction

The management of a CallWeb field project encompasses a series of operations which are depicted in the next exhibit, along with the tool which is reserved for each step. It is assumed that text editing (we really like TextPad) and FTP transfers are mastered by the project manager (even though the cwdocs module can now be used to transfert files).

The rest of this section describes the five stages of a field project: the initiation of the project, modifications during data collection, case management of data, real-time table production and data extraction.

Project management

   

Field management

Permission management

cwpermAll administrative accesses to CallWeb are controlled by a set of permissions that are based on modules and projects. Access to questionnaires by respondents and access to CATI interviewer modules are NOT subject to this permission scheme.

If no permissions are defined (such as upon initial use of the system), the site manager must access the cwperm.cgi module in the utility directory and define a super-user (see definition below). This super-user can then define additional users according to site needs.

Key concepts

There are two kinds of users: super-users and regular users. Super-users have access to anything and are the only ones who can use cwperm.cgi to create users and set permissions. Regular users can only perform the tasks that they are allowed according to the permissions set for them by the super-user.

There are six types of permissions, as follows:

  • All modules, all projects: a regular user can be given access to all modules and all projects. This is equivalent to the super-user permissions with the exception that that regular user cannot access cwperm.cgi to create users and set permissions;
  • All modules, one project (or more): a user can be given access to all modules for a specific project (or more than one);
  • All projects, one module (or more): a user can be given access to all projects from a particular module (or more than one);
  • One (or more) projects, one (or more) module: a user can be given piecemeal access to combinations of particular projects and particular modules; this is the finest level of permission control. It can be used, for example, to grant a client access to frequency tables in their project;
  • Generic # Accessible by module permissions: a user can be given access to a selection of modules for projects where they are named in the # Accessible by pound instruction; these permissions have no effect outside such projects.
  • Permissions that are dynamically borrowed from other users: a user can be associated to other users from which it borrows their permissions in real time. These users can themselves borrow permissions from other users (in a cascade).

Users are temporarily locked out of the system if they accumulate three incorrect accesses within a two minute period.

Permission management functions

Once a super-user accesses cwperm.cgi (either directly or via the integrated module), they get a menu similar to the one depicted here. The following functions are available to them:

  • Display the list of users
    This simply lists all user names, for reference.
  • Create a user
    A new user is given a name and a type (super-user or regular user). The user type cannot be changed later on.
  • Change a user's password
    Any user can be given a new password, which needs to be confirmed.
  • Add/modify a user's permissions
    After selecting a user whose permissions are to be modified, a (rather daunting) interface is displayed that allows the super-user to identify which permissions that user shall possess. Each available module is displayed in columns, in addition to a column for all modules. Each project is presented in rows, in addition to a row for all projects and a row for projects identifying the user in # Accessible by. Permissions can be redundant (e.g., a permission for all projects on cwfreq.cgi and a permission on one particular project on the same module). The most liberal interpretation of permissions is made later on.
    A box labelled "Permission level" accepts positive integers; it is not yet in use.
  • Copy permissions from one user to one or more
    Permissions can be copied from one user to one or more other users. A useful strategy using this feature would be to create a fake user that bears the permissions for a group of users and then to copy permissions from this fake user to all users in the group. Permission copying can be dynamic (and change in real time with changes to the permissions of the source users), additive (the permissions of the source user are added to the existing permissions of the destination user without touching existing permissions of the destination user) or can entirely replace the existing permissions of the destination user.
  • Delete a user
    Users can be deleted entirely form the permission system, one at a time.
  • Log out
    This option interrupts the activity of the super-user in cwperm.cgi.

User management strategies

More to come.

   

Field management

Integrated module

Integrated moduleA module called cw, located in the utilities directory, provides a front-end for every CallWeb module available in the said directory (as well as the callweb.cgi module located one level up in the directory structure.

It is highly advisable to use this module to access all of the other CallWeb programs as the required and optional parameters are displayed on screen (no typing, no risk of forgetting arguments).

Utilities located in the main utilities directory (defined in the installation file) have access to all CallWeb projects. To create an instance of a utility program that has access to a limited number of projects, follow the procedure explained in the CallWeb cookbook.

   

Field management

Initiation of a project

Required pound statements

In addition to the definition of questions, a CallWeb questionnaire script must include the following three pound statements:

  • # Available languages = LA,LA,LA,...
    This statement lists the languages that are defined in the questionnaire, using 2-letter ISO codes (EN for English, FR for French, ES for Spanish); CallWeb reports every instance of missing text segments based on this list.
  • # Default language = LA
    This statement identifies the language which is displayed by default if no language is stated upon calling a CallWeb tool; it uses a 2-letter ISO code.
  • # Survey type = (one of the following codes)
    This statement determines the type of data collection.
    • Open = fully open, no provision of an access code (was 1)
    • Closed = controlled access; the data base must be prepopulated (was 2)
    • Open Combination = fully open; a user id and a password are selected by the participant (was 3)
    • Open Offered = fully open, provision of an access code for resuming (was 5)
    • Password = controlled access; the data base must be prepopulated; the _password field contains the changeable password (was 7). A cookbook recipe describes this system in detail.

Physical installation of the questionnaire script file

The physical installation of a CallWeb project requires that the questionnaire script file:

  • bears a .scw extension (lower case); CallWeb considers all .scw files as questionnaires;
  • be located on a Web server in a directory whose name starts with "cw" and be located one level under the directory where the callweb program is located (the directory must be owned by the user under which the Apache server runs or offer read-write-execute permissions to the world — check with your system administrator);
  • be accompanied by a file named "style.css", in the same directory as the questionnaire script file; this cascading style sheet file controls certain aspects of the formatting of the questionnaire; all projects in a directory share the style.css file; projects located in different directories prefixed with "cw" can use different style.css files.

Each CallWeb project creates the following files:

  • project.qcw
    a compiled version of the questionnaire for fast access.
  • especially named MySQL database
    the data base of answers provided; it may contain a series of empty records if it was prepopulated with data by the project manager prior to initiating the field work.

Questionnaire compilation

Once a questionnaire is sufficiently complete (still subject to tests and modifications) and uploaded to the Web server, the cw script is used to activate various functions.

Compilation requires the script name. Six options are available:

  • Structural change
    This box must be selected if the project data structure changes with the new script; data structure changes are:
    • the addition/deletion of a question
    • the addition/deletion of an open-end part
    • the transformation of a single-answer question into a multiple-answer question or vice versa
    • moving questions in the questionnaire
  • Details
    This checkbox activates the display of detailed compilation messages.
  • Test
    The "test" checkbox may be selected to request a test compilation without changes to the existing compiled questionnaire or to the existing response data base.
  • Beautify scw
    With this box checked, the system produces a new version of the .scw file with "percent" lines labelled and indentation inserted to facilitate reading.
  • History
    Displays the compilation history for the project.
  • Copy
    Initiates the copy of the .qcw file to another server.

The compilation produces a wealth of information which should be studied carefully. Compilation errors are highlighted using the .ERREUR style found in the style.css file and located at the top of the compilation report.

If compilation errors are found, no change is made to the compiled questionnaire or to the response data base.

Compilation may also produce "warnings". Warning messages are elements of information of particular interest that are not errors per se but that could potentially be considered problematic. They include:

Questionnaire comparison

cwCompare can be used to help identify the structural differences between two versions of the same questionnaire. Both versions must be compiled and reside on the same server. cwCompare does not compare the text of the questionnaire — only the structural components (skips, question types, etc.).

Data prepopulation

Once the questionnaire has compiled without error, data may be forced into the data base. This is called prepopulating the data base. This must be used to create access codes in fully controlled data collections. Prepopulation can also be used to insert information about people who will complete the questionnaire, in a controlled-access context; these data can then be used in the course of the data collection.

Prepopulation can be done on an empty CallWeb data base or cases may be added to an existing data base.

Prepopulation data are supplied in a file with the following characteristics:

  • the file name must bear an extension starting with a "t", such as "prepop.tab";
  • ANSI file;
  • one record per case;
  • fields are tab-delimited;
  • the first line of the file lists the variables in the prepopulation file according to the question name in the questionnaire script; names are tab-delimited; fields using names that are not used in the questionnaire script are ignored;
  • the case identification code (called _telkey in CallWeb) must be present in the prepopulation file; it may contain letters, numbers and the underscore character — any other character is stripped out from the imported value as well as from the value supplied to start the questionnaire (such that, say, a telephone number with parentheses and dashes could be supplied as an identification code and it would survive the deletion of inadmissible characters);
  • it is possible to add comments to the prepop file by starting them with a comment string (##).

This file must be uploaded to the Web server and located in the same directory as the questionnaire script file for the project.

To assure the preservation of prepopulated data in all circumstances (include case reinitialization), use the NEVERUPDATE keyword on the question name line of the questions in which data are imported.

In the cw integrated interface, cwprepop can be called by selecting the project name and the name of the tab-delimited data file from drop-down lists.

The cwprepop module can also be used to add data into existing cases (or replace existing data) if the "replace variables" button is selected instead of the "add cases" button in the cw interface. In this context, a value of "--" does not replace the pre-existing value.

Generation of random test data

Once the questionnaire has compiled without error, test data can be randomly generated to verify that the logical conditions of the script work as expected. The script cwgen performs this function. It can be used in two manners:

  • if the project data base is empty (no data was pre-populated or created via questionnaires), cwgen (called from the integrated module cw) accepts, as argument, the number of questionnaires to create;
  • if the project data base is not empty, cwgen requests confirmation of the operation using the destruction keyword and proceeds to re-generate all questionnaires in the data base while respecting pre-populated data.

Each question in the questionnaire is scanned for each case and a random answer is selected for close-ended questions and for open-end parts. Skips, calculations, no-answer questions, etc. are honoured; matrix texts and Test pound instructions are not — and a list of these oversights is produced upon completing the random generation of data.

CallWeb aborts the random generation process if it reaches what appears to be an infinite loop.

   

Field management

File management

The CallWeb cwdocs module allows you to manage your project files on the server without the need for a separate FTP or SFTP program. Like all other CallWeb modules, cwdocs is entirely Web-based and requires no local installation.

With this module, users can create, delete, copy, rename and move directories. They can also upload, download, delete, copy, rename and move files. (To come: deleting to a trashcan.)

This module was written with security in mind. Users are jailed within the CallWeb instance; if cwdocs is called from a directory other than the master utility directory, users are jailed in that directory. They see only files that are reasonably managed in a Web application. They cannot change file or directory permissions.

cwdocs can only modify or delete directories and files that are accessible to the user under which the Web server runs. Therefore, it is possible that users of cwdocs will not be able, for example, to delete files or directories that were created by other Linux users. That's the cost of security.

When a user creates a directory off the root of the CallWeb instance, access to that directory is added to that user's permissions. However, that access permission is not deleted if the directory is erased. It would be deleted if a super-user re-saved the user's permissions in the permission module.

Access to cwdocs will be from a new icon placed in the upper right-hand side corner of the integrated module interface.

   

Field management

Quota management

CallWeb supports completion quotas based on single-character stratification (e.g., gender) and multiple-character stratification (e.g., gender within age groups) as well as compound stratification (e.g., a set of quotas on gender and a set on age groups). Membership to a stratum can be based on pre-populated data as well as on data collected in the questionnaire itself and on a combination of such. Quota targets can be modified at any time during the data collection period. Once a quota is filled, respondents from that stratum are redirected within the questionnaire, for total control over the handling of the situation.

Strata and quotas are defined in a special type of question: the QUOTA type. A question is a QUOTA question if the keyword "QUOTA" is present on the question name instruction. The syntax of the question text is as follows (in this syntax, quotas, commas and equal signs are significant):

    Q1 QUOTA
    % Question text
    complete = name of the variable indicating a complete case,
    skip = name of the variable where to skip when a quota is filled,
    value = quota, value = quota, ...

The ingredients of the definition of quotas are as follows:

  • complete = name of the variable indicating a complete case,
    The question named as "complete" is used to determine whether a case has been completed for the purposes of quota calculation; any value greater than zero in the Complete question indicates a complete questionnaire. As long as the value of the Complete question is unassigned or equal or less than zero, the case is not used in totalling the number of questionnaires completed within the quota. This variable may be a question located late in the questionnaire or a value calculated specifically for this purpose. If it uses the open-end part of a numeric question, remember to refer to the "A" variable name.
  • skip = name of the variable where to skip when a quota is filled,
    Once a quota is complete, the flow of the interview is altered: the questionnaire continues with the question listed as the "skip" question. The "skip" question can be located anywhere in the questionnaire. Typically, it would be a CULDESAC question ending the questionnaire, but it could also be a BLANK or CALCUL question which could act as a flag to control the questionnaire flow, or any other valid CallWeb questionnaire structure.
  • stratum value = quota target, ...
    The "stratum value" part is the number of the stratum (and the value of the QUOTA variable); the "quota target" is the number of questionnaires expected in that stratum. Moreover, in the CATI version of CallWeb, a fixed variable called PRESTRATE may possess a numeric value corresponding to the maximum number of dossiers available to interviews at once. This second value is supplied in the same fashion as the quota target (i.e., stratum number = maximum number).

Stratum membership is determined by the value stored in the QUOTA variable. For example, if the QUOTA variable contains a 4 for a particular case, that case belong to quota number 4. Response categories may be defined (and labelled) for QUOTA questions but this is not mandatory. If they are defined, the labels are used by the report modules.

A particular quota is deemed complete when the number of cases with a value greater than zero in the "complete" variable is equal to or greater than the target stated in the QUOTA question for that stratum.

QUOTA questions are subject to display conditions: the quota criteria are activated only if the display condition is true.

Several QUOTA questions may be used in a questionnaire; they are used if and when the flow of the questionnaire reaches them. Therefore, a first set of quotas could be imposed on a first characteristic, early in the questionnaire or based on prepopulated data, and a second set of quotas could take effect later, maybe based on data collected as part of the interview or calculated data.

The following constraints apply to QUOTA questions:

  • if the QUOTA variable is unassigned or has a value that is not listed in the list of quotas, quotas are not enforced and the questionnaire continues;
  • a QUOTA question should always be located before the complete case variable within the questionnaire; if it isn't, partial questionnaires could erroneously be considered complete (unless the QUOTA question comes late in the questionnaire, in which case its usefulness is doubtful);
  • since QUOTA questions involve a skip, they cannot be placed within a multi-question page; they must be inserted between defined pages;
  • membership to a stratum and the number of completed questionnaires in a quota are verified only upon reaching and activating the QUOTA question;
  • the QUOTA question is never displayed on screen; it is an administrative question; its value must be determined by pre-populated data or via a calculation;
  • there can be an unlimited number of strata in a questionnaire.

   

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 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

Questionnaire completion

Once the questionnaire is compiled — and data are prepopulated, if necessary — potential participants may be invited to complete the questionnaire. There is a variety of technical ways to open access to a questionnaire. Some are reviewed.

The most transparent way to access a CallWeb questionnaire is with the following Web instruction which applies to a fully open questionnaire or one where participants are provided with access codes on the fly:

    http://here.com/callweb.cgi?_proj=project&_lang=LA

where

  • "project" is the name of the questionnaire script;
  • "LA" is the language in which to access CallWeb; if not provided, the questionnaire default language is used.

If an access code (see the # Survey type pound instruction) must be supplied to open a questionnaire, the same instruction may be used (and the system will prompt for the access code) or the instruction may be completed as follows:

    http://here.com/callweb.cgi?_proj=project&_telkey=code

where

  • "project" is the name of the questionnaire script;
  • "code" is the access code;
  • the _lang=LA parameter can be added to the call; it determines the language of the questionnaire; if it is not provided, the questionnaire default language is used.

If the questionnaire must be initiated at a location other than the first question (for a blank questionnaire) or the last question displayed (for a return questionnaire), the URL may contain a specific entry point as follows:

    http://here.com/callweb.cgi?_proj=project&_telkey=code&_debute=QUESTION

where

  • "project" is the name of the questionnaire script;
  • "code" is the access code;
  • "QUESTION" is the name of the question which will act as entry point into the script. The _AUDEBUT_ code can be used to force the questionnaire to begin at the first question, notwithstanding where the questionnaire was last left.

An appendix to this documentation lists all available URL options available when calling a questionnaire.

The instruction to access CallWeb may be hidden on a static page using a form or a hyperlink or using Web redirection tools like go.97.ca or custom built Web scripts.

Extremely short URL syntax

CallWeb also supports an extremely short URL syntax which ensures that links are not cut off in invitation e-mail messages. The syntax is as follows:

    callweb.cgi?language:project:telkey:initial_question

as in

    callweb.cgi?EN:demo:11111:Q21

or

    callweb.cgi?EN:demo

if no access code is required or supplied within the link and the questionnaire starts at the beginning or at the last question displayed.

In fact, even the language parameter is optional; if it is not supplied, the default language defined in the questionnaire script is used. Note that CallWeb uses as the language parameter the first value that is made of two (and only two) letters (such that, if the project name, the _telkey or the _debute question are two-letter codes, the language parameter must be specified and must come before the other two-letter code). The other parameters must be in the order defined above.

Given the proper set up of the Web server, it is also possible to dispense with the explicit call to the callweb module (in Apache terms, by making callweb.cgi one of the DirectoryIndex entries). the link could then be shortened to something like:

    http://ici.com?demo

   

Field management

Modifications during the course of a project

Any modification may be made to the questionnaire during the course of a project and without interrupting the collection of data. Of course, adding a question won't suddenly make data appear in completed questionnaires, but the system can regenerate itself to take modifications into consideration from there on and keep as much of the previously collected data as possible.

A simple compilation is sufficient to affect changes to a questionnaire:

  • if the change does not add questions, delete questions, rename questions or move questions;
  • if the change does not modify whether or not questions have open-end parts;
  • if the change does not change a multiple-response question into a single-response question or vice versa.

The compilation procedure reports whether a structural data change is required. If so, it will be performed only if the "structural change" checkbox of the integrated module has been selected; otherwise, the compilation will terminate with an error and no change will be made either to the compiled questionnaire or to the data base.

   

Field management

Case management

Sometimes, data must be accessed on a case-by-case basis to look up responses, to correct them or to code open-ends. CallWeb offers cwNav to do just that. A call to cwNav (which stands for Navigate) is done via the integrated interface by providing the project name in the "Display data" section of the cw module.

The cwNav tool displays a menu to select cases and to select a subset of questions to display. Provided the right access codes are provided, the interface offers two ways to delete cases, three to view a case individually and three to open a case for editing.

Mass editing

Of particular significance is the mass editing mode that is activated by making the proper selection in the options menu. In mass editing mode, all displayed fields of all displayed cases are editable directly in a grid-like format. This could be particularly useful to display open-ended responses and a series of open-ended coding variables to perform a content analysis of the textual responses.

In mass edit mode, if _res (the most recent call result) is selected for editing, a new line appears in the menu. It offers the possibility of changing all existing _res values among selected cases to a new value. A dropdown list of possible _res codes is offered. If one of these codes is selected, all cases with _res values within the scope of the case selection are changed to that chosen value.

If a multiple-response question is edited in boxed mass edit mode, different values can be separated by commas or spaces. CallWeb edits the data upon Action! to delimit the values using "μ" characters. This is useful to code open-ended questions.

Reapplying CALCUL questions

cwNav also allows to reapply CALCUL questions (that is, to compute or recompute a calculation) on existing cases. After possibly identifying the cases to use in the operation using the case-selection portion of the menu, select a CALCUL question from the appropriate drop down list in the cwNAV interface (this feature is only available if the write-access password has already been supplied, if one is defined) and click Action!. Then key in the "UPDATE" keyword (upper case) and click Action! again.

Technical note: when reapplying CALCUL questions using cwnav.cgi, system variables (with names starting with an underscore) from the case data (such as _prepops and _h1) must be capitalized in the CALCULations (which is not the case in the CALCULations which take place during the performance of the questionnaire). One way around this issue for CALCUL questions which are intended to be used in cwnav.cgi as well as in the regular CallWeb context is to double up the name of the field and to put an "or" bar between the two as in $_prepops|$_PREPOPS. In Perl parlance, this means "use $_prepops if it exists, otherwise use $_PREPOPS".

Assigning values based on calculated expressions

This module also includes the ability to assign values to a variable based on a MySQL expression. Any field in the data base can be reassigned. Any type of assignment may be performed as long as the syntax of the expression is legitimate from MySQL's point of view and as long as the result of the expression conforms to the selected field data type. The following rules apply:

  • only cases identified by the selection criteria (at the top of the utility menu) are affected by the assignment;
  • the two parameters which specify a range of data base records to deal with ("Start from record no." and "Number of records to use") are NOT used in performing this operation;
  • once a target variable is selected (on the "Update using MySQL" line in the interface) and a MySQL expression is entered, and after activation with the Action button, the system displays the ensuing assignment expression and requests confirmation via a keyword; the keyword is "UPDATE" (upper case).
  • remember that the normal fields in the data base (non open-end parts) are stored as 16-byte character fields; MySQL allows mathematical operations on such fields (which are converted from character to numeric on the fly). Open-end parts (fields prefixed with A) are 64,000-byte character fields.

For example, it is possible to assign to AQ2 a value that is twice that of AQ1 with the following expression: AQ1*2. Also as an example, this operation could be performed only on cases where AQ2 is larger than 10 by making the proper selection in the options menu.

Use of this feature should be left to exceptional circumstances as the control of the assignment rests entirely with the user; none of the normal CallWeb data validation procedures are applied.

   

Field management

Real-time results

The cwFreq tool builds univariate frequency distributions, histograms, two-way tables and descriptive statistics in real time. It performs its duties equally well on numeric and on alphanumeric data. A call to cwFreq (which stands for Frequencies) is done via the integrated interface by providing the project name in the "Build tables" section of the cw module.

The cwFreq tool displays a menu to select cases and to select a subset of questions to display. Provided the right access codes are provided, the interface offers access to cases for editing.

   

Field management

Extraction of data

Data may be extracted at any time from the CallWeb data base and formatted for use with popular data analysis software. CallWeb can create:

  • four data files:
    • a comma-delimited file suitable for use in Excel (.csv extension);
    • a fixed-column file suitable for use in statistical data analysis software like SPSS, SAS, StatXP and R (.dat extension);
    • a tab-delimited file suitable for re-population of a CallWeb data base (.tcw extension);
    • a comma-delimited file of the open-end parts along with the associated question name and _telkey (.opn extension).
  • five program statement files:
    • an SPSS code file for reading the fixed-column data file, including the assignment of variable and value labels (.sps extension);
    • an R code file for reading the fixed-column data file, including the assignment of variable labels and variable formats (.r extension);
    • a SAS code file for reading the fixed-column data file, including the assignment of variable labels and variable formats (.sas extension);
    • an ASCQUE instruction file for the creation of a VoxCo Interviewer questionnaire which can then be converted to a StatXP format for reading the fixed-column data file, including the assignment of long labels and category labels (.asc extension);
    • a Classic 1.1 Triple-S instruction file (.sss extension).
    • an XML Triple-S 2.0 instruction file (.ssx extension).
    • a Stata code file for reading the fixed-column data file, including the assignment of variable labels and variable formats (.stt extension);
  • and a copy of the CallWeb question (.scw file).

The cwExtr (which stands for Extraction) tool is called from the integrated interface. cwExtr compresses the files it extracts into a zip archive. It either sends this zip file by e-mail to the address identified in # Send extractions to or it leaves the extraction on the server. The destination is selected in the cwExtr parameter interface.

In database-to-database mode (requested from the integrated interface, cwExtr can copy data from one CallWeb data base directly into another CallWeb data base. The source and destination data bases can reside in separate servers but they can also be in different instances of CallWeb on a single server or in the same CallWeb instance. In this mode, new data records can be added to the destination data base and existing data records can be updated with the data in the source data base. It is possible to select only a subset of fields to be transferred but system fields (the name of which starts with an underscore) are always transferred. All fields selected for transfer from the source data base must exist in the destination data base but the data base structure may differ between the two CallWeb projects otherwise.

   

Field management

Data base destruction

Once a project is completed and the data have been secured by an extraction, the cwdestruction module is used to get rid of the data base itself. The program requests that the keyword "DESTRUCTION" be typed in to confirm the intentions of the user. The write-access password must also be supplied if it is defined in the cwNav write password pound instruction.

This module is the only one (other than cwcompile, of course) which works even if the questionnaire file is not available. This allows for the destruction of data bases even if the questionnaire file was deleted (or otherwise rendered inaccessible) before the data base.

There is no further confirmation of the destruction command, so be extremely prudent in using this module.

   

Field management

Performing back-ups

CallWeb data reside in MySQL data bases which are not readily available to back-up software. The cwArchive modules perform timed back-ups of data files and place the zipped archives in the project directory.

The cwArchive back-up planning tool is available from the cw integrated module. It lists each CallWeb project based on the existence of MySQL data tables. For each project, hourly and daily back-ups can be planned. The number of hourly and daily back-up files to conserve on disk must also be set. It is also possible to provide an e-mail address where the back-ups will be sent.

By combining these tools, it is therefore possible, for example, to back-up the data file at 11AM, 2PM and 6PM while keeping 6 of these back-up files on disk (thereby providing two days of fail-safe back-ups) and to send a back-up set every night to an off-site e-mail address.

The first line of the back-up planning table defines the default behaviour that is applied to all project that don't possess their own planning strategy — this way, once the default strategy is defined, it is not necessary to worry about defining a back-up strategy for each new project.

cwArchive implements the following efficiency procedures:

  • if the data have not changed between two back-up procedures of the same kind (either hourly or daily), the most recent back-up file is not kept — so that automatic mirroring utilities do not uselessly make copies of the same data over and over. This means that new back-up sets are not created as long as the data remain the same.
  • following the logic of the previous point, only new back-up sets are sent by e-mail.
  • if a daily back-up is planned at the same time as an hourly back-up, only the daily back-up is performed.

The cwArchive.pl module must be referenced in the /etc/cron.hourly directory to that it is started up every hour. The text on the installation of CallWeb offers more information in this regard.

   

Appendix A

Pound instructions

Pound instructions define various elements of the behaviour of CallWeb. They start with a pound sign (#) which may be preceded by spaces or tabs for the sake of clarity. A given pound instruction may be split over several lines by starting the second and following lines with a pound followed by a greater-than sign (#>); this combination may be preceded or followed by spaces or tabs.

Instruction SyntaxExplanationDefault value
MANDATORY
# Available languages
# Langues disponibles (*)
=EN,FRList of languages which will be available in the questionnaire. Languages are defined using two-letter ISO 639-1 language codes.none
# Default language
# Langue par defaut (*)
=ENDefault language used when none or a non existent one is specified. It must be one of the languages identified in # Available languages.none
# Survey type
# Type enquete (*)
=code
  • Open | Ouvert = fully open, no provision of an access code (was 1)
  • Closed | Ferme = controlled access; the data base must be prepopulated (was 2)
  • Open Combination | Ouvert Combinaison = fully open; a user id and a password are selected by the participant (was 3)
  • Open Offered | Ouvert Offert = fully open, provision of an access code for resuming (was 5)
  • Password | Mot de passe = controlled access like Closed plus an encrypted password (was 7). A cookbook recipe describes this system in detail.
none
STRUCTURE
# Group ID
# Ecran ID (*)
=Qm-QnQuestions between Qm and Qn, including Qm and Qn, will be displayed on a single page.none
# Table ID
# Matrice ID (*)
=Q1-Q2 HEADER=n PIXELS=n COLVARS=n POSITION=x FORCE_CODES TRANSPOSE SPECIAL=(n,...) CORNER=(...) VALIDATIONQuestions between Qm and Qn, including Qm and Qn, are displayed in table format. The table header is repeated every HEADER row; the columns are PIXELS wide; there are COLVARS vertical questions. The POSITION can be LEFT|GAUCHE (default), CENTRE or RIGHT|DROITE. Details.none
# Permutation ID=Qm-Qn STEP=n LIMIT=n LIKE=permutationQuestions between Qm and Qn, including Qm and Qn, are presented in random order and only LIMIT blocks are displayed. LIKE is the name of another permutation that drives the order of the current permutation. Details.none
# New question order
# Nouvel ordre de questions (*)
=comma-delimited lists of question names; lists are slash-delimitedreorders questions defined in the questionnaire; there can be any number of reorder lists; they are separated by slashes. Each list is made of an arbitrary number of question names separated by commas, presented in the new order in which they will be processed in the questionnaire. This instruction facilitates the generalised use of the SUFFIX syntax. Example: # New question order = Q3, Q2, Q1 / Q14, Q16, Q15. As with all pound instructions, only one such instruction (the last one in the .scw file) is active in the questionnaire.none
# Deactivate pages
# Desactiver les pages (*)
=yes|no
oui|non
Whether or not CallWeb uses the GROUP (ECRAN) and TABLE (MATRICE) instructions in the questionnaire. May serve to linearize a questionnaire for CATI purposes.no
(DEPRECATED)
# Note segment
# Segment note (*)
=yes|no
oui|non
Whether or not the NOTE text is presented in its own separate field in the .scw file (as opposed to the old syntax with the [NOTE] indicator in the question text)yes
(DEPRECATED)
# Rotations on RO
# Rotations sur RO (*)
=yes|no
oui|non
Whether or not a pair of RO variables will behave as bounds of a permutation of questions. It should be set to "no" but it exists for backwards compatibility considerations.no
# INDEX
=List of questionsComma-delimited list of questions needing to be indexed in the database. Open-ended question (using text fields) must be specified along with the number of characters to index within parentheses (e.g. AQ1(20)).none
ACCESS (general)
# cwNav read password
# Mot de passe cwNav lecture (*)
=passwordPassword to read data in utility programs.none
# cwNav write password
# Mot de passe cwNav ecriture (*)
=passwordPassword to modify and delete data in utility programs.none
# cwextr zip password (*)=passwordPassword used to encrypt extracted data in a zip file (spaces compressed upon use).none
# cwcompile zip password (*)=passwordPassword used to encrypt information stored by cwcompile in a zip file (spaces compressed upon use).none
# cwarchive zip password (*)=passwordPassword used to encrypt back-up data stored by cwarchive.pl in a zip file (spaces compressed upon use).none
# cwemail password
# Mot de passe cwemail (*)
=passwordPassword to send e-mail message through cwemail.none
# Return permitted
# Retour permis (*)
=yes|no
oui|non
Whether the permission is granted to return into a completed interview.no
# Password change in type 7
# Changement de mot de passe en type 7 (*)
=yes|no
oui|non
Whether the user is offered the possibility to change their password in Survey type Password.yes
# Seconds locked
# Secondes de verrou (*)
=# of secondsNumber of seconds during which a questionnaire is reserved to the active user.0
# Language switch
# Changement de langue (*)
=yes|no
oui|non
Whether the user can switch languages once the questionnaire is started.yes
# Telkey pattern=patternPattern followed for the creation of case identifiers (_telkey): combination of [C]onsonant, [V]owel, [L]etter, [N]umeric and [?] for any of these. Each character of the pattern is replaced by one character in the access code. Substitutions are honoured.CVCVCVN
# use_telkey_table=yes|no
oui|non
adjusts the use_telkey_table installation instruction on a project by project basis (necessary for the correct operation of BASEpretest). "Yes" in this instruction will work only if the installation instruction is already set to yes.yes
# Visible from
# Visible depuis (*)
=directory listComma-delimited list of utility directories which can access this project. The master util directory (defined by the "repertoire_utilitaire_maitre" key in the main configuration file) has default access to all projects.none
# Accessible by
# Accessible par (*)
=list of usersComma-delimited list of users who have access to the project based on their "Accessible by" accesses as defined in cwperm.cgi.none
# Noreturn condition
# Condition de non retour (*)
=logical conditionxBase or Perl (in braces) logical condition indicating when a case cannot be re-entered — if the "# Return permitted" instruction has been set to "no". If a respondent has gone past the last question and that "# Return permitted" was set to "no", the questionnaire cannot be re-entered; the same is true of the "# Noreturn condition" is true; this allows to control return access without making respondents leave the questionnaire (presumably to a static Thank you page).none
# Control by cookie
# Controle par cookie (*)
=yes|no(in callweb.cgi only; does not work in cwx.cgi) activates a cookie-based control system which prevents the creation of a second questionnaire by a given computer in a fully open project; it has no effect on other types of questionnaires.no
# Deny access if
# Nier acces si (*)
=logical conditionxBase or Perl (in braces) logical condition indicating when cases cannot be accessed. The condition can use any value in the questionnaire and any contexte data such as the date and time.none
# Freeze data if
# Figer les donnees si (*)
=logical conditionxBase or Perl (in braces) logical condition indicating when cases cannot be modified any further. The condition can use any value in the questionnaire and any contexte data.none
# Allow new in open combination=yes|noIn Open combination mode, accepts or refuses the creation of new cases based on newly supplied _telkeys.yes
# Auto submit=logical conditionxBase or Perl (in braces) logical condition indicating whether CallWeb automatically submits a questionnaire page upon the selection of an answer. This is activated only on pages that contain a single question that allows for a single selection (radio button type); it is not activated on answer categories that contain an open-ended part.none
# Master compilation server
# Serveur maitre de compilation (*)
=server nameName of the server which has permission to compile the script. The server name is defined in the configuration file.none
# Master codes=comma-delimited list of codesEach of these passwords provide access to the project via the callweb.cgi (or cwx.cgi) module. Access is not granted without providing one of these codes.none
ACCESS (CATI and robot)
# Supervisor password
# Mot de passe des superviseurs (*)
=passwordPassword used by supervisors to access call queue management functions.none
# Master CATI server
# Serveur maitre pour le CATI (*)
=server nameName of the server which has permission to manage the CATI component of a project. The server name is defined in the configuration file. This instruction requires that the control_by_other_server_possible installation option be set to yes.none
# Maximum interviewers=numberMaximum number of interviewers allowed in the project at once.999999
# Linear CATI mode=yes|noIn CATI mode, by default, questionnaires are displayed in a second browser window while the interviewer's call management screen remains open. With "# Linear CATI mode" set to "yes" or "oui", the questionnaire opens in the same window as the call management screen and a button is displayed at the top of the questionnaire to return to the call management screen.no
# Cati=yes|no|ivr
oui|non|ivr
Determines whether or not a CallWeb project is to be managed as a CATI project or as an IVR project. CATI projects have specific requirements which are enforced when this option is on. A default value may be defined in the CallWeb instance configuration file using the keyword "cati" (lower case).no
ACTION (general)
# Include=file nameInserts the content of the file at that location in the script, before compilation. If the file name has no path, the file must be located in the same directory as the .scw file; a path relative to the root of the CallWeb instance may be provided, e.g., cw/file.inc. Files that are included may contain Include statements of their own. With Include, one can share portions of questionnaires between scripts.none
# Test ID=[TRIGGER]... [CONDITION]... [MESSAGE]... [TYPE]...Applies error CONDITION test when receiving a value for the TRIGGER question and, if true, returns error MESSAGE where the TYPE specifies. Details.none
# Recall ID
# Rappel ID
=recalled text
or
[condition]recalled text
Creates a value which may be recalled using the &#ID syntax. See the recall page for details. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Default JavaScript to
# JavaScript par defaut*
=yes|no
oui|non
Determines whether or not JavaScript should be considered active if no information was yet received from the client session.yes
# Load JavaScript Library
=yes|no
oui|non
Determines whether or not JavaScript libraries (Mootools and Highcharts) are loaded for questionnaire pages.yes
(DEPRECATED)
# Email
# Courriel (*)
=e-mail addressE-mail address where every completed questionnaire is e-mailed as back-up. Separate multiple addresses with commas.none
# Default cwemail email
# cwemail email par defaut (*)
=e-mail addressdefault e-mail address used as sender in cwemail; can be changed within the cwemail interface.none
# Default cwemail sender
# cwemail envoyeur par defaut (*)
=e-mail addressdefault e-mail address used as actual technical sender in cwemail (as opposed to the e-mail address that appears in the From field of the message); can be changed within the cwemail interface. This information is used by the receiving server to assess the risks of the message being spam. It should be an address that is deliverable to the sending server.none
# cwemail report to (*)=e-mail addresse-mail address to which the turbo-mode report is sent.system administrator
# List Unsubscribe (*)=URL to unsubscribedefault URL to access the questionnaire unsubscribe feature. See the relevant cookbook recipe.none
# Send extractions to
# Envoyer extractions a (*)
=e-mail addressE-mail address where cwextr data extractions can be e-mailed. Separate multiple addresses with commas.none
# cwextr copy directory
# repertoire sauvegarde cwextr (*)
=(local directory)Name of a local directory offered by default as a location where to put extractions in cwextr.none
# Extraction width
# Largeur extraction (*)
=ncolumnsDefault extraction width for closed questions.4
# Minimal extraction width
# Extraction de largeur minimale (*)
=yes|noIf set to yes, data extractions default to the minimal number of columns required to represent the data.no
# Refuse duplicates in cwprepop
# Rejeter les doublons dans cwprepop (*)
=list of questionsComma-delimited list of questions or system variables (like _telephone) that cwprepop will test for duplicate values. Cases with duplicate are not prepopulated and their status is reported.none
# Send bounces to=e-mail addresssingle E-mail address where bounces from e-mail sent by CallWeb will be directed.
If the address is formatted as bounces.*@domain.xxx, CallWeb reformats the address to work with cwBounces.pl which intercepts bounced messages.
none
# Check bounces against=AQnName of the open-end part containing the e-mail address to which invitations/messages were sent. This value is used by cwbounces.pl to identify to which data base record a bounce message is associated. It must be set to use cwbounces.pl and the bounces.*@domain.xxx form of # Send bounces to.none
# Save bounces into=AQnName of the open-end part containing the date and time of the bounce messages received for this data base entry. It must be set to use cwbounces.pl and the bounces.*@domain.xxx form of # Send bounces to.none
# Complete case
# Dossier complet (*)
=SQL logical expressionLogical expression describing completed questionnaires. It must be a valid SQL-syntax expression; no validation is performed on its syntax.none
# Cleaning skips
# Sauts nettoyants (*)
=yes|no
oui|non
Whether or not data cleaning will be performed between the bounds of forward skips.yes
# Save backwards
# Sauve a reculons (*)
=yes|no
oui|non
Whether or not to save responses provided on a page before clicking on the CallWeb back button (not the browser back button). For logical reasons, no data validation is performed.yes
# Url=urlURL where the browser will be sent at the completion of the questionnaire. The value can include recalled values. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. Therefore, different language versions can exit to different URLs as in # URL = [EN]http://yahoo.com[FR]http://yahoo.fr Substitutions are honoured..none
# Attributable questions
# Questions attribuables (*)
=list of questionsDeclares the list of questions (in the form: Q1-Q5, Q7, Q8-Q10,...) which may have their values attributed at the time of the original call of a case. For example, assuming that Q1 is among these questions and that abc is an Open project, calling "callweb.cgi?_proj=abc&Q1=2" would open a new record in the data base and attribute value 2 to question Q1 — this works with all _typeint types of projects.
The rules are: only questions listed in this instruction can be attributed; only cases that have never been accessed can be attributed; only questions that are empty can be attributed (e.g., a prepopulated value cannot be changed via this procedure). Not all attributable questions need be attributed.
Note that question names are always capitalized and that URLs and forms are case-sensitive.
Remember, that in the flow of the questionnaire, all questions, including those listed in this instruction, are subject to be blanked out by BLANK question types, display conditions and skips; appropriate non-cleaning skips may be required to preserve the values attributed via this protocol.
none
# Pretest=text or HTML codecreates hyperlinks to BASEpretest and displays them besides every question that does not possess a NOPRETEST question type. If present and if BASEpretest exists, these links are created and pop a new window with a feedback form. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. See the related recipe.none
# Pretest project
# Projet pretest (*)
=textname of the CallWeb project used for the # Pretest feature.BASEpretest
# Auto email=complex syntax (see the page on e-mail notification)provides the parameters required for automatically sending e-mails under pre-set conditions.none
# Stop  No parameters. Interrupts the compilation of the questionnaire file and disregards the following instructions.n/a
# Execute if
# Executer si
=CALCUL question name or names separated by slashes
or
[condition]CALCUL question name or list of names separated by slashes
Identifies a CALCUL question (or a slash-delimited list of CALCUL question names) that is (possibly, conditionally) executed before displaying the next page. This instruction is evaluated after every page when the processing of the answers sent is found errorless and before calculating the display of the next page. See the recall page for details on the conditional syntax.none
# Always open at
# Toujours ouvrir a
=question nameIdentifies the question that the questionnaire opens on at every start (which ever question the questionnaire was closed on). The keyword _AUDEBUT_ can be used.none
# Only for server ID
# Seulement pour le serveur ID (*)
=another pound instruction"Only for server" is followed by the name of a server (defined in the CallWeb instance configuration file) as in # Only for server ABC = # cati = yes. This instruction is followed by another pound instruction which is activated only for the named server. Note that normal validations performed on the sub-instruction (in the previous example, "cati = yes") are not performed during compilation; it is good practice to test the sub-instruction as a normal instruction before tucking it into a "# Only for server" instructions.none
# Copy questionnaire into
# Copier le questionnaire vers (*)
=user@location/directorySends a copy of the compiled questionnaire to a secondary CallWeb server in the context of a multi-server configuration. The instruction includes the shell user, the domain name or the IP address of the target server and the destination project directory, such as
# Copy questionnaire into = someuser@callweb.ca/var/www/html/somerep/cwproject
This copies the .qcw file as well as an empty .scw file. Public keys must have been exchanged between the servers for this instruction to work. More than one copy can be defined by specifying a comma-delimited location/directory list. It is also possible to copy other files located in the project directory by stating their name or pattern as part of the comma-delimited list, such as
# Copy questionnaire into = someuser@callweb.ca/var/www/html/somerep/cwproject, *.pdf, *.docx
which would copy all pdf and docx files from the compilation server to the distant server.
none
# MySQL engine=engine nameSpecifies which of the MySQL storage engines to use for the project data base.none
# BASEclicks=yes|no
oui|non
Specifies whether the time spent on each page of the questionnaire should be stored in the BASEclicks data base.no
# General Upload Parms=dir = x, file = yes|no, min = m, max = n, extensions = ext1/ext2/...Specifies the parameters used by File Upload open-end questions: dir is the directory where the files are stored within the project directory; file is a yes|no indicating whether the files are stored in the "dir" directory in addition of the MySQL database; min is the minimum number of bytes required for an uploaded file (default = zero); max is the maximum number of bytes allowed for an uploaded file (no default); extensions is a slash-delimited list of file extensions allowed (an asterisk indicates that all extensions are accepted).none
ACTION (CATI and robot)
# Use do not call list=yes|no
oui|non
Whether or not to use the information in project BASEdonotcall when pre-populating a project; also controls the display of the do-not-call checkbox on the interviewer interface.yes
# Do not call email=e-mail addressE-mail address where a notification is sent every time an interviewer adds a telephone number to the do-not-call list. Separate multiple addresses with commas.none
# CATI selection 3=question, yes|no
question, oui|non
States that a certain question in the questionnaire is to act as a third case selection criterion for interviewers in CATI mode. The second parameter, following a comma, indicates whether interviewers are allowed to change the value of this datum from their call management window.question name, none; action switch, YES
# Productivity index=MySQL expressionMySQL expression returning an index of interviewer productivity. Used in cwprod.cgi. See also the productivity_index installation option.ROUND((completes_first + 2*completes_norefusal + 5*completes_withrefusal - 3*refusals_first ) / duration,1)
# Close full quota
# Fermeture automatique des quotas atteints
=yes|no
oui|non
In CATI mode, controls whether the automatic quota closure system is activated.yes
# Basic call management=yes|no
oui|non
In CATI mode, controls whether the call queue management system uses simple dropdown lists to specify delays or more flexible value boxes.no
# Other n in cwsuper
# Autre n dans cwsuper **
=MySQL expressionMySQL expression returning a count from the data base in cwsuper.none
APPEARANCE CONTROL (page)
# Template
# Gabarit
=file_nameName of the HTML file to be used as questionnaire template. The path may be specified, otherwise the file must be located in the project directory. In left undefined, the page is built using the traditional vertical construction. Another documentation page provides details. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. Substitutions are honoured.none
# Stylesheet=file_nameName of a file containing CSS styles specific to the current project. The path may be specified, otherwise the file must be located in the project directory. If not defined, substitution rules apply. Substitutions are honoured.none
# Page_position=left|center|rightPosition of the CallWeb question area within the browser window.left
# Page_width
# Page_largeur (*)
=pixels|%Width of the CallWeb question area within the browser window. It can be specified in pixels (a raw number) or in terms of percentage of the window (number with a percent sign).100%
# Page_wire_pixels
# Page_fil_pixels (*)
=pixelsWidth, in pixels, of the wire separating the CallWeb question area from the rest of the browser window.0
# Page_wire_colour
# Page_fil_couleur (*)
=#FFFFFFColour of the wire separating the CallWeb question area from the rest of the browser window.#FFFFFF
# Page_interior_colour
# Page_interieur_couleur (*)
=#FFFFFFColour of the CallWeb question area. The colour of the outside area is determined by the "body" style in the cascading style sheet file.#FFFFFF
# Background image
# Image de fond (*)
=url.gif|url.jpgImage to display underneath the questionnaire area.none
# Page_interior_margin_pixels
# Page_interieur_marge_pixels (*)
=2Width of the space separating the CallWeb question area from the wire and the rest of the browser window.2
# Default N columns
# N colonnes par defaut (*)
=numberDefault number of columns over which the response categories are laid out. This general value can be overridden on a question by question basis using the ncols argument on the question name line.1
# Header
# Entete (*)
=textText displayed at the top of each page. HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Footer
# Pied (*)
=textText displayed at the bottom of each page. HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Between questions
# Entre questions (*)
=yes|no
oui|non
Whether or not a horizontal line separates each question.no
# HTML Title
# Titre HTML (*)
=textTitle displayed in the browser bar during the execution of the questionnaire. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. Substitutions are honoured.none
# Title
# Titre (*)
=textProject title displayed at the top of the questionnaire listing in cwQuestionnaire. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Display question names
# Affiche noms questions (*)
=yes|no
oui|non
Whether or not question names are displayed on screen (debugging tool).no
# Activate the mobile mode
# Activer le mode mobile (*)
=yes|no
oui|non
Whether or not mobile devices are shown simplified pages.no
# Thousand separator
# Separateur de milliers (*)
=character(s)Specifies the character or characters to use to separate groups of thousands in numeroc values. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example._
APPEARANCE CONTROL (tables)
# M_CellColour
# M_CouleurCellules (*)
=#FFFFFFColour of the interior of odd-numbered-row cells in tables.#FFFFFF
# M_CellColour2
# M_CouleurCellules2 (*)
=#FFFFFFColour of the interior of even-numbered-row cells in tables.#FFFFFF
# M_SpecialColour
# M_CouleurSpeciale (*)
=#ACACACColour of the SPECIAL codes for the table.#CCCCCC
# M_InteriorSpacing
# M_EspacementInterieur (*)
=numberWidth of the interior margins in matrix cells3
# M_Borders
# M_Bordures (*)
=numberWidth of the border in tables1
# M_BorderColour
# M_CouleurBordures (*)
=#CCCCCCColour of the matrix borders.#FFFFFF
# M_ColumnTitleAlignment
# M_AlignementTitresColonnes (*)
=T|B|MLocation of column titles within their cells: T = top, B = bottom, M = MiddleB
# M_ColumnTitleColour
# M_CouleurTitresColonnes (*)
=#FFFFFFColour of the column title cells in tables.#666699
# M_LineTitleColour
# M_CouleurTitresLignes (*)
=#FFFFFFColour of the odd-numbered row title cells in tables.#CCCCCC
# M_LineTitleColour2
# M_CouleurTitresLignes2 (*)
=#FFFFFFColour of the even-numbered row title cells in tables.#FFFFFF
# M_ Cell highlighting
# M_ mise en evidence (*)
=#EEEEEEColour of the cell highlighting.Same as column headings
# Cell highlighting
# Mise en evidence des cellules (*)
=yes|no
oui|non
Activates or deactivates cell highlighting in response categories and in tables.yes
# Styles for tables
# Styles pour matrices (*)
=yes|no
oui|non
Whether or not to activate the use of CSS styles to format the question tables.no
# M text position
# Position texte M (*)
=left | right
gauche | droite
Position, relative to the radio button or the checkbox, of the text produced in a table cell by the M answer behaviour code..right
APPEARANCE CONTROL (buttons and thermometer)
# Display language button
# Affiche bouton langue (*)
=
  • 0 or NO or NON
  • 1 or TOP or HAUT
  • 2 or BOTTOM or BAS
Location of the buttons used to swap from one language to the next: no button, to the top after the title or at the bottom along the navigation buttons.BOTTOM
# Display back button
# Affiche retour arriere (*)
=yes|no
oui|non
Whether or not the "back" button or image is displayed.no
# Page Error Image
# Image erreur page (*)
=file nameIdentifies a graphic file to use to highlight errors in a submitted questionnaire page. If the file name has no path, the file must be located in the same directory as the .scw file; a path relative to the root of the CallWeb instance may be provided, e.g., cw/file.gif. Substitutions are performed at compilation time.gr/erreur_page.gif
# Field Error Image
# Image erreur champ (*)
=file nameIdentifies a graphic file to use to highlight errors at the question level. If the file name has no path, the file must be located in the same directory as the .scw file; a path relative to the root of the CallWeb instance may be provided, e.g., cw/file.gif. Substitutions are performed at compilation time.gr/erreur_champ.gif
# Forward text
# Texte avance (*)
=textText displayed on the "Next" submit button or under the "Next" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Next question
# Submit text
# Texte submit (*)
=textText displayed on the "Next" submit button or under the "Next" submit image for SUBMIT-type questions. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Submit
# Backwards text
# Texte recule (*)
=textText displayed on the "Previous" submit button or under the "Previous" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Previous question
# Unlock text
# Texte unlock (*)
=textText displayed on the "Unlock" submit button or under the "Unlock" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Save and exit
# Stop text
# Texte stop (*)
=textText displayed on the "Stop" submit button or under the "Stop" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Stop
# Button order bottom
# Ordre des boutons bas (*)
=code lettersDetermines the order of presentation (left to right) of the buttons and progress bar/thermometer at the bottom of each question screen. The letters indicate the nature of the buttons and their order: [B]ack button, [N]ext button, [U]nlock button, [L]anguage buttons, [T]hermometer, [S]top button. This is also the default order. Any letter not supplied in the instruction is added by the compiler, in this same order, after declared buttons. Whether some of these buttons appear is controlled by other pound instructions.BNULTS
# Button order top
# Ordre des boutons haut (*)
=code lettersDetermines the order of presentation (left to right) of the buttons and progress bar/thermometer at the top of each question screen. The letters indicate the nature of the buttons and their order: [B]ack button, [N]ext button, [U]nlock button, [L]anguage buttons, [T]hermometer, [S]top button. This is also the default order. Unnamed buttons are not displayed.none
(DEPRECATED)
# Button order
# Ordre des boutons (*)
=code lettersDetermines the order of presentation (left to right) of the buttons and progress bar/thermometer at the bottom of each question screen. The letters indicate the nature of the buttons and their order: [B]ack button, [N]ext button, [U]nlock button, [L]anguage buttons, [T]hermometer, [S]top button. This is also the default order. Any letter not supplied in the instruction is added by the compiler, in this same order, after declared buttons.BNULTS
# Button position
# Position des boutons (*)
=LEFT | CENTER | RIGHTPosition of the directional buttons.LEFT
# Top button position
# Position des boutons haut (*)
=LEFT | CENTER | RIGHTPosition of the top directional buttons (overwrites # Button position).LEFT
# Bottom button position
# Position des boutons bas (*)
=LEFT | CENTER | RIGHTPosition of the bottom directional buttons (overwrites # Button position).LEFT
(DEPRECATED)
# Thermometer
# Thermometre (*)
=0|1|2|51|52 , QUESTION1 , QUESTION2Location of the progress bar: 0, no progress bar; 1, to the right of the page title, expressed as a percentage; 2, to the right of the "Next" button, expressed as a percentage; 51, to the right of the page title, expressed as a number of questions, 52, to the right of the "Next" button, expressed as a number of questions.
QUESTION1 and QUESTION2 are optional; they are separated by commas. They are the names of a first and last questions used in calculating the completion rate; if only QUESTION1 is specified, QUESTION2 is assumed to be the last question of the questionnaire; if neither are specified, QUESTION1 is the first question of the questionnaire.
0
# Display thermometer
# Affiche thermometre (*)
=NONE | TOP | BOTTOM | AUCUN | HAUT | BAS, NUMBER | NOMBRE | PERCENT | POURCENTAGE | MUTE | MUET, QUESTION1, QUESTION2Position de la barre de progression.
  • NONE or AUCUN, no progress bar;
  • TOP or HAUT, after the page header;
  • BOTTOM or BAS, to the right of the "Next" button.
After a comma,
  • PERCENT or POURCENTAGE to express the progress as a percentage;
  • NUMBER or NOMBRE to express it as a number of questions left;
  • MUTE or MUET to put no text right of the progress bar.
QUESTION1 and QUESTION2 are optional; they are separated by commas. They are the names of a first and last questions used in calculating the completion rate; if only QUESTION1 is specified, QUESTION2 is assumed to be the last question of the questionnaire; if neither are specified, QUESTION1 is the first question of the questionnaire. QUESTION1 and QUESTION2 may also be substitutions which compute to a question name when the questionnaire is displayed.
NONE
# Stop button
# Bouton stop (*)
=no|yes|[condition], question|substitution
non|oui|[condition], question|substitution
Whether or not the Interruption button is displayed. If set to "yes" or to a true display condition between square brackets, a second parameter is passed after a comma: the name of the question where the respondent is directed after clicking on the Interruption button, or a substitution that will compute to a name when the questionnaire is displayed.no
# Thermometer text
# Texte thermometre (*)
=textText displayed above the progress thermometer. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Progression in the questionnaire
# Thermometer colour
# Couleur thermometre (*)
=#FFFFFFColour of the thermometer.# M_ColumnTitleColour
# Thermometer width
# Largeur thermometre (*)
=pixelsNumber of pixels used by the width of the thermometer.200
# Thermometer height
# Hauteur thermometre (*)
=pixelsNumber of pixels used by the height of the thermometer.10
# Thermometer border width
# Largeur bordure thermometre (*)
=pixelsNumber of pixels of the thermometer border.1
# Thermometer border colour
# Couleur bordure thermometre (*)
=#FFFFFFColour of the thermometer border.#CCCCCC
# Thermometer gap width
# Largeur espace thermometre (*)
=pixelsNumber of pixels of the gap between the thermometer border and the thermometer itself.1
# Thermometer gap colour
# Couleur espace thermometre (*)
=#FFFFFFColour of the gap between the thermometer border and the thermometer itself.#FFFFFF
# Second line of buttons
# Seconde ligne de boutons (*)
=yes|noControls the display of the text line which follows the buttons and thermometer at the bottom of the page. Can be used to attach "alt" and "title" text to graphical Next, Back and language buttons while avoiding the text equivalent below the buttons.Yes
# Image left
# Image gauche (*)
=image_file_nameName of the image file to be used as a "Previous" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Image right
# Image droite (*)
=image_file_nameName of the image file to be used as a "Next" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Submit image
# Image submit (*)
=image_file_nameName of the image file to be used as a "Next" button if the question has a SUBMIT question type. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Language image
# Image langue (*)
=image_file_nameName of the image file to be used as a language button. The path must be specified. In left undefined, a standard HTML button is displayed. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Image stop=image_file_nameName of the image file to be used as a "Stop" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Image unlock=image_file_nameName of the image file to be used as an "Unlock" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Radio button suffix
Suffixe des boutons radios *
=textSuffix added to the names of the image files used to replace radio buttons and check boxes. Substitutions are honoured.. The image files may reside in the project directory or in the resource directory (gr/). The following image types are sought (in this order): png, gif, jpg. Ideally, images should be between 12 and 15 pixel square. Eight images must be defined in a set: cboxCheckedDisabled, cboxDisabled, cboxChecked, cbox, radioCheckedDisabled, radioDisabled, radioChecked, radio (e.g., cboxCheckedDisabledGREEN.png). The following sets are predefined: BLUE, GREEN, PURPLE, RED, YELLOWnone
# Radio button directory
# Repertoire des boutons radios *
=textDirectory where the radio button and check box images are found (see # Radio button suffix). It must be a subdirectory of the instance root directory. Substitutions are honoured..gr/
APPEARANCE CONTROL (messages)
# Mandatory question
# Question obligatoire (*)
=HTML textInserts the HTML text after the question or note text of a mandatory question (which has a minimum number of answers of at least 1). The text can use HTML coding such as <SPAN CLASS=ERREUR>*</SPAN>. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# General error message
# Message erreur general (*)
=textText displayed at the top of the page if an error was identified in the responses provided. HTML codes are interpreted but the whole text is formatted using the .ERREUR style. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Incomplete or erroneous data were identified on this page. Please see below.
# Demo message
# Message demo (*)
=textText displayed at the top of the page if the system functions in demo mode (no data saving). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.DEMONSTRATION MODE. Responses will not be recorded.
# Frozen data message
# Message donnees figees (*)
=textText displayed at the top of the page once # Freeze data if is true (no modifying saving). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.The data in this case are frozen. No change will be recorded.
# System message [message number]
# Message du systeme [message number] (*)
= Redefines (and customizes) system messages. "[message number]" must be substituted for the actual number of the system message to affect. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Enforce response length
# Contraindre la longueur des reponses (*)
=yes|noLimits a multi-line alpha-numeric response to the number of characters specified in the .scw file (if JavaScript is activated in the respondent's browser). Also determines whether CallWeb produces an error message if a multi-line alpha-numeric response is longer than the open-part length defined in the questionnaire.no
APPEARANCE CONTROL (access code page)
# Access page header=yes|no
oui|non
Whether or not to display the page header (# Entete LA) on the access code request page.yes
# Access page footer=yes|no
oui|non
Whether or not to display the page footer (# Pied LA) on the access code request page.yes
# Access request telkey=textText displayed before the input box on the access code request page (when no access code is offered). HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>Your access code, please</P>
# Access give telkey=textText displayed before the input box on the access code request page (when a new access code has been offered). HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>Your access code is <B>{$_telkey}</B>.<BR>Keep it to be able to access your answers in the future.</P>
# Access send telkey button=textText of the Send button on an access code request page. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Send
# Access send telkey image=image_file_nameName of the image file to be used as the Send button on an access code request page. The path must be specified. In left undefined, a standard HTML button is displayed. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.none
# Access no telkey button=textText of the "I have no access code" button on the access code request page (# Survey type = Open Offered). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.If you don't have an access code, click here
# Access bad telkey=textText displayed when an incorrect access code is supplied (# Survey type = Closed or Open Offered). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>The access code supplied (<EXECUTE>$formdata{_telkey}</EXECUTE>) is not valid.</P>
# Access bad telkey 7=textText displayed when an incorrect access combination is supplied (# Survey type = Password). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>This combination of access code (<EXECUTE>$formdata{_telkey}</EXECUTE>) and password is not valid.</P>
# Access request access code in type 3=textText displayed in # Survey type = Open Combination to request an access code (the syntax rules for the code could be inserted in this statement). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>Your <B>access code</B>, please.<BR>If you don't have an access code yet, please create one.</P>
# Access request password in type 3=textText displayed in # Survey type = Ouvert Combinaison to request a password (the syntax rules for the password could be inserted in this statement). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>Your <B>password</B>, please.<BR>If you don't have a password yet, please create one.</P>
# Access bad combination in type 3=textText displayed upon finding a bad password for an existing access code in # Survey type = Ouvert Combinaison. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER CLASS=ERREUR>This access code already exists or the access code/password combination is invalid.</P>
# Access bad telkey pattern in type 3=textText displayed upon finding an access code which does not conform to # ACCESSTELKEYPATTERN. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER CLASS=ERREUR>The access code does not follow the expected pattern.</P>
# Access bad password pattern in type 3=textText displayed upon finding a password which does not conform to # ACCESSPASSWORDPATTERN. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER CLASS=ERREUR>The password does not follow the expected pattern.</P>
# Access request password in type 7 (*)=textText displayed in # Survey type = Password to request a password. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER>Your <B>password</B>, please.</P>
# Access request new password in type 7 (*)=textText displayed in # Survey type = Password to offer the entry of a new password. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<p align="center">If you want to change your <b>password</b>, enter the existing password above, then type a new password below twice.</p>
# Access bad telkey pattern in type 7 (*)=textText displayed upon finding a password which does not conform to # ACCESSTELKEYPATTERN. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.<P ALIGN=CENTER CLASS=ERREUR>The password does not follow the expected pattern.</P>
# Access telkey pattern=regular expressionRegular expression used to described the pattern of acceptable access codes in # Type enquete = 3. Do not include the starting and ending slashes but escape the expression according to rules. The regular expression is assumed to start with ^ and end with $ — that is, the entire user ID supplied must conform to the pattern..+
# Access password pattern=regular expressionRegular expression used to described the pattern of acceptable passwords in # Type enquete = 3. Do not include the starting and ending slashes but escape the expression according to rules. The regular expression is assumed to start with ^ and end with $ — that is, the entire password supplied must conform to the pattern..+
APPEARANCE CONTROL (relation)
# Text relation add=textIn the context of a RELATION question, text displayed on the button to add a child. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Add
# Text relation refresh=textIn the context of a RELATION question, text displayed on the button to refresh the page. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Refresh
# Text relation delete=textIn the context of a RELATION question, text displayed on the button to delete a child. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Erase (immediate effect)
# Text relation modify=textIn the context of a RELATION question, text displayed on the button to modify a child. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.Modify
APPEARANCE CONTROL (CATI and robot)
# Read
# Lire
=textText inserted before an answer category label with behaviour code L. Can contain HTML code. Substitutions are honoured.<IMG SRC="gr/lire.gif">&nbsp;
# Do not read
# Ne pas lire (*)
=textText inserted before an answer category label with behaviour code P. Can contain HTML code. Substitutions are honoured.<IMG SRC="gr/nepaslire.gif">&nbsp;
# Display min max
# Affiche min max (*)
=yes|no
oui|non
Whether or not the minimum and maximum number of answers are displayed in the note field.no
# Robot caller id=telephone numberTelephone number displayed by the IVR robot.none
# Robot caller id text=texttext displayed by the IVR robot.none
# Caller id=telephone numberTelephone number displayed by the Asterisk server placing calls on behalf of interviewers.none
# Caller id text=texttext displayed by the Asterisk server placing calls on behalf of interviewers.none
OTHER
## textComment; not subject to compilation.none
#> textContinuation line. The text on this line is added to that of the previous linenone

* This value is used internally by CallWeb.

   

Appendix B

Installation instructions

Server software requirements

CallWeb needs the following to be installed on the server:

  • Perl 5 (including the following modules: CGI, CGI::Carp, DB_File, DBI, Fcntl, File::Compare, File::Copy, File::Path, FileHandle, IO::Socket, locale, LWP::Simple, Net::FTP, Net::Telnet, POSIX, Time::HiRes, Time::Local, SOAP::Lite 1.08, Encode)
  • MySQL 4 or better
  • Berkeley DB
  • a Web server (tested with Apache 2 with mod_unique_id enabled)
  • Sendmail
  • (for dialer and robot operations) Asterisk, version 1.2 or better (and the Asterisk::AGI Perl module)

Questionnaire designer client station

The following software has proven very valuable in editing CallWeb .scw files:

  • TextPad is an extraordinary pure-text editor which offers a whealth of functions. In particular, it supports syntax highlighting which makes CallWeb .scw files much more readable. A TextPad syntax highlighting file is available for CallWeb. Alternatively, some like Notepad++ for which CallWeb has a basic syntax highlighting file as well.
  • KeyText is a fabulous keyboard and hot key mapper. For example, one can paste an entire CallWeb question definition by simply pressing a predetermined combination of keys.
  • the free RGBtoHEX provides an easy way to select colours and identify the corresponding hex code.
  • the free Pixie is a colour picker: point to a colour on screen and Pixie tells you the hex, RGB, HTML, CMYK and HSV values of that colour (the hex value can be copied to the paste buffer using a keycoard key combination). ColorZilla, a free Firefox extension implements a similar function, but it is available only within Firefox.
  • there are hundreds of useful Web applications. For example, http://gradcolor.com/ creates a gradient which is very useful to find different intensities of a given coulour (do this by requesting a gradient from that colour to white).

File locations

DirectoryContentNotesPermission
{master}Main access directorymandatory: callweb.cgi, cwroutine.pl
optional: cwx.cgi cwjscripts.js, cwAST.pl
read, execute (world)
{master}/grSystem graphic filesmandatory: collection of .gif files
optional: style.css (when no style.css exists in the project directory)
read, execute (world)
{master}/cw... (i.e., name starting with "cw" or "cw" only)Everything project-relatedmandatory: *.scw, *.qcw
optional: style.css (for all projects located in the same directory; the # Stylesheet instruction can specify a stylesheet for a particular project), navigation images, all files referenced by questionnaires in that directory (linked by cw.../file.xxx in the .scw file), project configuration file (named projectSOMETHING.conf)
 
Notes
(1) all directories named cw* are considered project directories
(2) .scw (raw questionnaire) files must be located in their respective cw directory for compilation purposes; once compiled, they may be deleted or moved
(3) several projects may cohabitate in the same cw* directory; they then share the style.css file
(4) prepopulation files (e.g., pop.tab) must be located in the directory of the project to which they contribute
read, write, execute (world)
{master}/{any name}CallWeb utilitiesoptional according to circumstances: cw.cgi, cwappels.pl, cwarchive.cgi, cwarchive.pl, cwautoemail.pl, cwbounces.pl, cwcheck.cgi, cwcompare.cgi, cwcompile.cgi, cwdestruction.cgi, cwdossier.cgi, cwedit.cgi, cwemail.cgi, cwextr.cgi, cwfreq.cgi, cwgen.cgi, cwnav.cgi, cwpermissions.pl, cwprepop.cgi, cwquestionnaire.cgi, cwstats.cgi, cwstats.pl, cwtelkeys.cgi, cwupdate.cgi, cwupdate.pl
for CATI installations: cwcodescati.cgi, cwgroupes.cgi, cwoutcomes.cgi, cwphone.cgi, cwphone.pl, cwprod.cgi, cwsuper.cgi, cwsuperimp.cgi, cwsuperpro.cgi, cwsuperpro.pl, cwdial.pl
for robot installations: cwrobot.pl (see complete robot installation instructions)
optional: style.css (controls the appearance of utilities, unless a project-related style.css (or other file) exists)
read, execute (world)
{master}/{any name}CallWeb CATI interviewer utilitiesmandatory for CATI installations: int1acces.cgi, int2select.cgi, int3travail.cgiread, execute (world)
{master}/etcSystem configuration filemandatory: the name must start with "usager" and end with ".conf" as in usager__531vh.confowner: apache
read, write (owner)
{master}/calCalendar filesoptional but mandatory to get pop-up calendarsread, execute (world)
/opt/callwebCallWeb daemon programmandatory for the daemon mode: callwebd.plread, execute (root)
/etcCallWeb daemon program configuration filemandatory for the daemon mode: callwebd.confread, write (root)
/var/spool/callwebCallWeb daemon program spool directorymandatory for the daemon mode: directory where the CallWeb daemon reads and writes request and response filesread, write (world)
/etc/rc.d/init.dCallWeb daemon control programmandatory for the daemon mode: callwebdread, write (world)

System configuration file

The system configuration file and the project configuration files may contain several parameters controlling the in-depth behaviour of CallWeb and its default appearance. Some parameters must be supplied in one file or the other. Mandatory parameters are (parameters are case-sensitive):

client=(prefix used in naming MySQL data bases for this installation; do not include periods)
hote=(MySQL host, typically "localhost" but it could be the IP address of a distant MySQL server)
usager=(MySQL user name)
motdepasse=(MySQL user password)
driver=(Perl data base engine driver, typically "mysql")

The following are mandatory in CATI mode:

local_area_codes=(in CATI mode only, comma-delimited list of area codes not requiring a long distance call)
long_distance_exchanges_in_local_area_codes=(in CATI mode only, comma-delimited list of area+exchange codes requiring a long distance call within an otherwise local zone)
server_gmtoffset=offset hours to GMT (negative west of Greenwich)
gmtnnn=GMT offset hours for the area code nnn; negative west of Greenwich; there is one such line for each area code
gmtnnnxxx=GMT offset hours for exchange xxx in area code nnn; negative west of Greenwich; these are exceptions to the area code rules

The following are mandatory to connect an Asterisk server to CallWeb:

asterisk_ip=local network IP address of the Asterisk server
asterisk_ip_ecoute=local network IP address of the Asterisk server for supervising stations (asterisk_ip is used if asterisk_ip_ecoute does not exist)
asterisk_external_ip=external IP address of the Asterisk server (could be the same as asterisk_ip if the CATI server is on the same local network as the Asterisk server)
asterisk_telnetport=Telnet port on the Asterisk server (usually 5038)
asterisk_telnetuser=Telnet user on the Asterisk server (to communicate with Asterisk)
asterisk_telnetpw=Telnet user password on the Asterisk server (to communicate with Asterisk)
asterisk_cati_callerid=telephone number used for call display in CATI context
asterisk_cati_callerid_text=name used for call display in CATI context
asterisk_mysqlcdr=name of the MySQL data base where Asterisk stores the cdr table (usually asteriskcdrdb)
asterisk_mysqluser=mysql user on the Asterisk server (must be accessible from the CallWeb server)
asterisk_mysqlpw=mysql user password on the Asterisk server (must be accessible from the CallWeb server)
asterisk_sqlengine=SQL engine used on the Asterisk server (usually mysql)
longdistance_cost_per_minute=cost per minute of long distance calling
longdistance_minimum_seconds=minimum chargeable length (seconds) of a long distance call
longdistance_increment_seconds=increment (seconds) used to calculate long distance charges

The following are mandatory in robot mode:

pris_locaux=comma-delimited list of PRI lines which can dial local and long distance numbers (e.g., "pris_locaux = 1, 2" defines dialling lines 1 to 23 and 24 to 45)
pris_interurbains=comma-delimited list of PRI lines which can dial only long distance numbers (e.g., "pris_interurbains = 3" defines dialling lines 46 to 71)
asterisk_ivr_callerid=telephone number used for call display in robot context
asterisk_ivr_callerid_text=text used for call display in robot context
asterisk_mysqluser=mysql user on the Asterisk server (must be accessible from the robot server)
asterisk_mysqlpw=mysql user password on the Asterisk server (must be accessible from the robot server)
asterisk_sqlengine=SQL engine used on the Asterisk server (usually mysql)
cati_ip_for_robot=external IP address of the robot server (the Asterisk server needs to verify the number of interviewers logged in)
cati_user_for_robot=MySQL user for CallWeb on the robot server
cati_pw_for_robot=MySQL user password for CallWeb on the robot server
cati_clientdb_for_robot="client" parameter used by the robot on the robot server (see the client parameter above)
external_transfer_string=string used by Asterisk to send robot calls on a SIP trunk
siptrunk_prefix=string used by Asterisk to identify robot calls to be sent to a SIP trunk
number_of_SIP_channels=integer indicating how many SIP trunk channels the robot has access to

The following are mandatory in connecting CallWeb to a predictive dialer:

dialer_dbhote=IP address of the dialer data base host
dialer_dbusager=user name on the dialer data base
dialer_dbmotdepasse=password on the dialer data base
dialer_dbdriver=data base engine used by the dialer data base (e.g., mysql)
dialer_dbname=name of the dialer data base on the data base host
dialer_result_table=name of the table where call results are stored in the dialer data base
dialer_softphone_port=interviewer softphone port (the softphone is used to communicate some information to the dialer
dialer_server=IP address of the dialer host
dialer_server_port=port used by the dialer host
dialer_wait_for_human=number of seconds that CallWeb will wait for the dialer to supply a human call before giving up (default = 60)

In a project-specific configuration file, if the MySQL host is redefined, the following entry is mandatory:

projet=(name of the CallWeb project to which the configuration file belongs)

Any pound instruction can be inserted in the system configuration file. All such pound instructions found in the system configuration file are inserted at the beginning of all questionnaires upon compilation. This means two things:

  • that system-wide defaults can be defined for any of the pound instructions, such as defining a default read access password for all projects with "# cwNav read password = some_password";
  • that such system default values can be overwritten inside any questionnaire by adding the same instruction (with other parameters) in the .scw file.

In addition, optional configuration parameters include (parameters are case-sensitive):

administrator_email=(e-mail address of the CallWeb system administrator)
notify_after=(number of days of data base inactivity that triggers an e-mail reminder; the default is 14)
notify_every=(number of days between notifications of inactive projects as defined by notify_after; the default is 1)
maximum_undo_versions=(number of update versions to keep available for undo; the default is 5)
serveurftp=(name/address of the FTP server offering system updates and upgrades)
proxyftp=(name/address of the proxy server through which FTP has to connect; add ":port" if the proxy does not use the default FTP port)
usagerftp =(user name on serveurftp)
motdepasseftp =(password for usagerftp)
engine=(MyISAM or InnoDB)
use_telkey_table=(yes or no; determines whether a table of reserved _telkeys is used for open projects (preferable); requires mod_unique_id in Apache; default "no")
nom_de_ce_serveur=(name of the server; used in # Only for server and # Master compilation server instructions)
repertoire_utilitaire_maitre=(name of the master utility directory)
repertoire_cati_maitre=(name of the master directory for CATI scripts)
nom_installation=(name of the installation reflected in the utility banner)
langue=(2-letter code for the default language)
update_daemon=(0 or 1 according to whether the daemon files must be updated with cwupdate. Place in only one CallWeb instance on a given server.)
cwextr_types=(default extraction file types presented as a comma-delimited list among the following: csv, dat, tcw, opn, sps, sas, rcode, asc, sss, scw)
cwextr_email=(e-mail address to select as the default extraction destination)
csv_delimiter=(single character used as a delimiter in extracted csv files)

champs_par_csv
=(default number of fields in an extracted csv file)
test_email_address_hostname=(domain name used by the test_email_address function to build the FROM parameter (should be a subdomain like mail.callweb.ca). Uses $ENV{HTTP_HOST} or $ENV{HOSTNAME} otherwise.)
url_principal=(URL used by cwautoemail.pl to call cwemail.cgi; must be a fully qualified URL ending with a slash such as http://domain.com/utilities/)
max_var_label_length=(default maximum length of variable labels extracted to other software code; default = 60)
max_value_label_length=(default maximum length of category labels extracted to other software code; default = 40)
max_spss_alpha_field=(maximum number of characters read off alphanumaric fields in SPSS; default = 254)
default_cwtelkeys_pattern=_telkey pattern proposed by default by cwtelkeys
_M_COULEURCELLULES=(# colour code; base cell colour for tables)
_M_COULEURCELLULES2=(# colour code; second cell colour for tables)
_M_COULEURTITRESCOLONNES=(# colour code; column header cell colour for tables)
_M_COULEURTITRESLIGNES=(# colour code; base line header cell colour for tables)
_M_COULEURTITRESLIGNES2=(# colour code; second line header cell colour for tables)
_M_COULEURBORDURES=(# colour code; border colour for tables)
_M_BORDURES=(number of pixels for table borders)
_M_ESPACEMENTINTERIEUR=(number of pixels for internal spacing of table cells)
_M_ALIGNEMENTTITRESCOLONNES=(T|B; vertical alignment of column header cells)
cati=(oui|non|ivr, whether the installation is CATI- or IVR-type by default)
couleur_commentaire_o=(# colour code; colour of the CATI result codes where interviewer comments are mandatory)
couleur_commentaire_f=(# colour code; colour of the CATI result codes where interviewer comments are optional)
couleur_commentaire_a=(# colour code; colour of the CATI result codes where interviewer comments are disallowed)
between_cati_buttons=(number of pixels to insert between CATI buttons presented to interviewers)
lignes_commentaires=(number of lines of the comment entry box for interviewers)
colonnes_commentaires=(number of columns of the comment entry box for interviewers)
size_of_stratum_selection_box_in_cwsuperpro=(number of lines for the multiple select drop-down list of strata in cwsuperpro; default 5)
default_for_cati_comment_carry_over=(yes|no whether the interviewer comment is carried over from call to call by default
delai_min_entre_appels=minimum number of seconds between two call results by a particular interviewer for a given case
allow_password_change_by_interviewers=yes | no (if yes, interviewers are given a chance to change their password upon login)
allow_sip_change_by_interviewers=yes | no (if yes, interviewers are given a chance to change their SIP extension upon login)
constrain_to_groups=yes | no (if yes, the free case selection option is not displayed to interviewers if groups exists in CATI mode)
allow_viewing_time=yes | no (if no, interviewers are not offered the option to view thier cumulated time in CATI mode)
interviewer_clock=12|24 (displays the apppointment clock as a 12- or 24-hour clock; 24 is the default)
allow_cross_project_search=yes | no (if no, interviewers are not offered the list of projects from which to search for a case in CATI mode)
interviewer_timer=yes | no (whether or not interviewers are shown a timer on the call management screen; the default is yes)
mpBASEtemps=password used in BASEtemps (mpBASEtemps is used in cwsuper to give supervisors access to interviewer time slips.)
productivity_index=MySQL expression returning an index of interviewer productivity. Used in cwprod.cgi. The default is ROUND((completes_first + 2*completes_norefusal + 5*completes_withrefusal - 3*refusals_first ) / duration,1).
repertoire_wav=absolute path to the server directory containing the project directories where .wav files of the interviews are stored
repertoire_html_wav=directory alias defined in the Apache configuration to permit building URLs to the .wav files even if they are outside the Web server directory structure
seconds_before_dialling=seconds (in CATI mode with an Asterisk dialler, length of the pause between the display of the call management screen and the automated dialling of the telephone number)
storeinBASEappels=yes | no (in CATI mode, if no, call results are not stored in real time in BASEappels and interviewers do not get a dynamic count of their results)
week_start=between 0 and 6: determines when the week starts in the calculation of the _week system variable; 0 for Sunday, 1 for Monday, etc.
comparative_results=yes|no (in CATI mode, controls the display of a summary of interviewer productivity to each interviewer)
command_prefix_for_record_wav=(some text) (prefix command used by the Apache user to start and stop recordings in face-to-face settings)
url_to_cwagent=(url) (full URL to the cwagent.cgi script to bridge agents from int2select.cgi to cwagent.cgi; should be in the usagerXXX.conf file of the CallWeb instance agents use to log in) (e.g., http://192.168.0.1/prod/interviewers/cwagent.cgi)
url_from_cwagent=(url) (full URL to the int2select.cgi script to bridge agents from cwagent.cgi back into int2select.cgi; should be in the usagerXXX.conf file of the CallWeb instance where cwagent.cgi runs, i.e. in the robot instance) (e.g., http://192.168.0.2/prod2/interviewers/int2select.cgi)
agent_languages=comma-delimited list of ISO language codes offered to the agents logging into cwagent.cgi
parms_to_copy_dump_file (OBSOLETE)=apache@server (where "server" is a distant MySQL server where the backup dump files will be written. This parameter serves to copy the dump file over to the administrative server and to delete it from the MySQL server. For this to work, ssh keys must have been exchanged for the Apache user [for compilation backups] and the root user [for automated backups])
control_by_other_server_possible=yes | no, set this to yes if it is possible that there will be CATI projects that are controlled by another server based on the # Master compilation server pound instruction
default_cwpermissions_directory_permissions=permission level assigned to project directories by cwpermission; it must be in octal representation; the default is 0777.
default_cwpermissions_file_permissions=permission level assigned to project files by cwpermission; it must be in octal representation; the default is 0666.
cwpermissions_deletes_from_cwdir=(case insensitive regular expression, minutes); the two options are separated by a comma; cwpermissions.pl deletes files that correspond to the regular expression pattern when they are older than the number of minutes stated in the second option; the regular expression is not tested — it is entirely the responsibility of the CallWeb manager.
exclude_from_cwcompile_backup=(case insensitive regular expression); defines a regular expression identifying files to NOT save in cwcompile zip backups.
hide_user_from_cwdocs_link=yes; if defined, this option hides the user code from the cwdocs link in cw.cgi.
check_login=yes | no, set to no, it deactivates the authentification system.
dialer_timeout_milliseconds=number of milliseconds after which the dialer considers a call ring-no-answer.
musiconhold=0|1, whether or not to use music-on-hold when transfering a batch-dialed extra call to an agent.
external_transfer_string=string used by Asterisk to compose SIP channel information for external audio monitoring; this is lifted from the relevant Asterisk context.
systemlog=level of logging to be performed in the instance. Valid values are: 0: Emergency (emerg); 1: Alerts (alert); 2: Critical (crit); 3: Errors (err); 4: Warnings (warn); 5: Notification (notice); 6: Information (info); 7: Debug (debug).
max_log_size=maximum size of the log file before rotation, expressed in megs.
service_command_path=path of the service command used in cwupdate.pl. Normally, this option is not necessary.
login_pw_valid_days=number of days after which a user must change their password to access CallWeb utility modules (none by default).
login_pw_allow_same=(yes|no) whether or not users are allowed to supply the same password when requested to change it.
login_pw_rules=tab-delimited list of regular expressions that must be adhered to in creating a new password.
login_pw_rules_message=text displayed to explain the password composition rules. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.
out_of_service=(yes|no) blocks all access to the instance questionnaire and displays a general out-of-service message.
no_lastlogin_storage=(yes) avoids storing the time of last utility program login in the permission file.

Automated tasks

A number of tasks are performed automatically by various programs once they are scheduled in the cron feature of a Linux server. They are as follows.

ScriptType of installationDescriptionTypical location
cwupdate.plAllScans the CallWeb instance and updates programs to the most recent version.cron.minute
cwpermissions.plAllAdjusts the permissions of CallWeb directories and files which require open access by the Web server, throughout the CallWeb instance.cron.minute
cwsuperpro.plCATIScans projects to perform updates of the CATI files containing the cases available to telephone interviewers.cron.minute
cwphone.cgiCATI with AsteriskFor CATI installations equipped with an Asterisk PBX server, updates the list of last times when there was activity on an IP address. Add the CallWeb "client" name as an argument, e.g., "perl cwphone.cgi PROD".cron.minute
cwdial.plCATI with Asterisk and dialerFor CATI installations equipped with an Asterisk PBX server and the CallWeb dailer, absorbs automated call results into the CallWeb call history. Add the CallWeb "client" name as an argument and an ampersand to release the process, e.g., "perl cwdial.pl PROD &".cron.minute
cwrobot.plIVRFor robot servers: handles placing calls on the Asterisk server as well as collecting call results from the Asterisk server (see complete robot installation instructions). The call must be accompanied by the "client" name from the installation file of the CallWeb instance.cron.minute
cwarchive.plAllPerforms the back-ups throughout the instance of CallWeb as determined in cwarchive.cron.hourly*
cwautoemail.plAllSends the e-mail messages requested in "# Auto email" instructions throughout the instance of CallWeb. Add the CallWeb "client" name as an argument, e.g., "perl cwautoemail.cgi PROD &".cron.hourly*
cwstats.plAllComputes various usage statistics based on CallWeb data bases throughout the instance of CallWeb. The results are displayed by cwstats.cron.hourly
cwupdate.cgiAllE-mails the system administrator in case of available system updates.cron.daily
cwappels.plCATI(CATI only) Re-creates the BASEappels data base which contains one entry for each call made in each project available in the CallWeb instance.cron.daily
* Considering the functionality of the script, this must be its location.
Note that each of these scripts needs to be called individually for each instance of CallWeb installed on the server. To simplify this process, put an executable text file containing a series of "cd" commands (to change to the utilities directory) followed by "perl script" commands in the pertinent cron directory, as in:
cd /var/www/html/scripts
perl cwstats.pl
cd /home/someuser/scripts
perl cwstats.pl

One last script cwbounces.pl is a special case. Its purpose is to intercept bounced messages and to update the CallWeb data base with an indication of this bounce. It is not located in the cron system but rather, it is called by Sendmail upon receiving bounced messages for the "bounces" address. A single instance of this program services an entire server and all instances of CallWeb installed on it. Here are detailed installation instructions:

  • put the cwbounces.pl script in the main utilities directory;
  • make cwbounces.pl executable (0755);
  • create a symbolic link cwbounces.pl in /etc/smrsh, pointing to the cwbounces.pl script in the utilities directory;
  • create a virtual user called "bounces.+*@domain.xxx" (adjust the domain name but leave the left side of this expression intact) and send its mail to the "bounces" alias;
  • create a mail alias "bounces" piped to the cwbounces.pl script (|cwbounces.pl).

Note that, for cwbounces.pl to work with a given instance of CallWeb on a server, the following directories and files must be readable by the user or the group "mail" (under which Sendmail runs):

  • the cwroutines.pl file ;
  • the etc directory;
  • the file usager???.conf file within the etc directory (the exact name of this file varies with each instance of CallWeb).

Daemon mode installation

The CallWeb daemon mode is three times as fast as the base mode. In daemon mode, CallWeb runs constantly in the server background, waiting for questionnaire page request files to be placed by cwx.cgi (which replaces callweb.cgi in daemon mode) in the spool directory. The CallWeb daemon processes these request files and places the HTML code of the next questionnaire page in the spool directory for cwx.cgi to display to the respondent.

To use the CallWeb daemon mode, follow the installation instructions and then call the questionnaires with the cwx.cgi module instead of the callweb.cgi module.

CallWeb daemon mode installation instructions:

  • the daemon mode requires that Apache loads the mod_unique_id module. Make sure that the following line is part of the Apache configuration:
    LoadModule unique_id_module modules/mod_unique_id.so
  • create the directory /var/spool/callweb and allow the Web server user to read from it and to write to it, for example:
    mkdir /var/spool/callweb
    chmod 0777 /var/spool/callweb
  • place cwx.cgi in the CallWeb installation master directory and allow the Web server user to execute it, for example:
    chmod 0755 cwx.cgi
  • create the /opt/callweb directory and place callwebd.pl as well as cwroutines.pl in it, for example:
    mkdir /opt/callweb
    cp callwebd.pl /opt/callweb
    cp cwroutines.pl /opt/callweb
    chmod 0700 /opt/callweb/callwebd.pl
  • create the /var/log/callweb directory and make it writable by the Apache user, for example:
    mkdir /var/log/callweb
    chown apache:apache /var/log/callweb
    chmod 0755 /var/log/callweb
  • place callwebd in /etc/rc.d/init.d and give it execution permission by root, for example:chmod 0700 /etc/rc.d/init.d/callwebd
  • request that the CallWeb daemon be started automatically upon server boot: chkconfig --add callwebd (see update-rc.d for Ubuntu)
  • to allow for daemon system updates, add the following line to the usagerXXX.conf file of one instance on the server (probably the most active production instance): update_daemon = 1. That CallWeb instance will control updates to the daemon system.
  • if the system is connected to a Munin server:
    • activate loglevels 1 (for problems) and 4 (for page creation) in /etc/callweb.conf (see below);
    • place the callwebd_pages script in the /etc/munin/plugins directory
    • make callwebd_pages executable
    • restart Munin with service munin-node restart

The CallWeb daemon is started, stopped and restarted with the command service callwebd start|stop|restart. The daemon status can also be probed with service callwebd status. When the "restart" or the "stop" command is issued, the CallWeb daemon waits until the request queue is empty before proceeding with stopping the daemon.

The CallWeb daemon configuration file is /etc/callweb.conf. The CallWeb daemon must be restarted for changes to the configuration file to take effect. Its content is as follows.

SectionContentNotes
AnywhereLines starting with a pound sign are commented out.
[General]loglevel=n"n" is the sum of the numerical values associated with each element of information that may be logged. For example, a loglevel of 5 activates the logging of information numbered 1 and 4. The elements of information are numbered as follows:
1: system start and stop, problems encountered
2: state of the server, noted every minute
4: name of each file processed and project concerned
8: opening of request files and closing of response files
A loglevel of 0 indicates that no information is to be logged.

Multi-server configuration (CallWeb cluster)

Using the configuration files, it is possible to develop various server implementations of CallWeb. First, CallWeb can run on the same computer as the data base server if the "hote" parameter of the main CallWeb configuration file points locally:

hote = localhost

Another CallWeb server could use the same MySQL server by specifying a distant address for the "hote" in its main configuration file:

hote = 99.99.99.99

If the two CallWeb servers use the same "client" parameters in their main configuration file, both servers will "see" projects from both origins; that would be the typical setup of a multi-site CATI system. If they use different "client" parameters, each CallWeb server will only see its own projects.

Each project used in a multi-server configuration (also called "CallWeb cluster") should possess a # Master compilation server pound instruction to protect the integrity of the questionnaire files. Parallelism of the questionnaire files across servers is ensured by the # Copy questionnaire into instruction which dispatches a copy of the questionnaire (and an empty .scw file) to distant servers (there should be one such instruction for each of the distant servers in the CallWeb cluster which will use the questionnaire). This dispatching of questionnaires requires that a direct SSH connection (with exchange of public keys) exists between the servers; see below for the procedure.

In a multi-server configuration, re-compilation of the .scw script involving changes in data structure should be performed on the computer running the MySQL server. Otherwise, while the compilation will be performed and the data base adjusted if required, no backup of the data will be kept before modifying the data structure.

Note that, for bi-mode projects, the CATI CallWeb server must be the Master for compilation so that the .ccw file is correctly processed.

Exchange of public keys between servers

This procedure must be carried out only once per server connection. In brief, here is the procedure for the exchange of public keys between Linux servers:

  • in this procedure, "computer2" (the server, or the CallWeb computer which will receive the compiled CallWeb questionnaires) is the machine granting access to "computer1" (the client, or the computer which will send the compiled CallWeb questionnaires);
  • on computer1,
    • in a root shell, issue the following commands:
      • passwd apache [when prompted, enter a password for user apache]
      • usermod -s /bin/bash apache
      • chown apache:apache /var/www
    • enter a shell with the apache user ("su apache");
    • as the apache user, issue the following commands in a computer1 terminal window:
      • cd /var/www/
      • [if the .ssh directory does not exist] mkdir .ssh
      • cd .ssh
      • ssh-keygen -t rsa [accept the default options and do not specify a passphrase; this generates two files: id_rsa and id_rsa.pub]
    • in a root shell, issue the following commands:
      • chown root:root /var/www
  • copy id_rsa.pub from computer1 to computer2, in directory /var/www/.ssh (for example, via SFTP);
  • on computer2, in a root shell, issue the following commands:
    • usermod -s /bin/bash apache
    • cd /var/www/.ssh
    • cat id_rsa.pub >> authorized_keys
  • in a shell as the apache user on computer1, initiate an SSH connection and type "yes" when prompted; this needs be done once to accept the exchange of keys.

   

Appendix C

URL options

It is highly advisable to use the cw integrated module to access the various components of CallWeb (for simplicity and safety). Nonetheless, there may be circumstances where direct coding of URLs is necessary. The following tables provide the URL options which can facilitate the creation of specialized menus.

URL options for the callweb module

URL options are used when building the URL to call CallWeb. Such URL could look something like: <http://blabla.ca/callweb.cgi?_proj=test&_demo=1&_lq=1&_print=1&_debute=Q1>. CallWeb also offers a short syntax to call questionnaires.

OptionValueBehaviour
_telkeyaccess codeSupplies the case access code.
_projproject nameSupplies the project name which must be exactly the same as the .qcw file (case sensitive).
_langtwo-letter language codeSupplies the language code of the language to use in interacting with the program. Only language codes defined in the "# Langues disponibles" can be used. Codes follow the ISO language code convention. If this information is not supplied, the system defaults to the language defined in the "# Langue par defaut" instruction.
_demo1Activates the demonstration mode where no data are saved in the data file and a warning message (determined by the "# Message demo" instruction) is displayed at the top of every screen.
_epw
encoded password stringIn survey type Password, passes along the encoded value of the password, as stored in the data base.
_lq1The _lq switch ("lq" stands for "list of questions") displays a drop-down list of all page-starting questions, at the top of each page. By selecting one of these entries, the system automatically skips to that page. Warning: display conditions are not enforced, i.e., the question selected will be displayed whether or not the context calls for it. This switch is useful for questionnaire layout purposes but should not be used in production.
_printintegerThe _print switch displays the entire questionnaire on screen, disregarding any page structure instructions and display conditions. It is useful to easily produce a generic printed version of questionnaire as seen by the respondents. Portions of questionnaires can be printed using the _debute and the _termine options.
The integer can be simply 1 to activate _print mode, but it can also be the sum of the relevant values below to exercise more control over the output:
1 = activate _print mode
2 = do not display navigation buttons
4 = do not display the page footer
8 = do not display the page header
_debuteQ1This switch supplies the question name where the questionnaire will be initiated. The name must be in upper-case characters. Without this option, the questionnaire starts at the first displayable question or, in the case of a questionnaire that has been started already, at the last question seen.
_termine
Q2This switch supplies the question name where _print ceases printing the questionnaire.
_custom1The _custom switch displays the entire questionnaire on screen including responses provided by the respondent but skipping questions without answers. It is useful to easily produce a printed version of questionnaire as seen by a particular respondent, for filing purposes.
_affichenomsquestions1This switch requests the display of the question names within the CallWeb questionnaire.
_access1This switch puts the CallWeb questionnaire in accessibility mode for visually impaired. The pages do not use style sheets, structure tables and layout tables; CallWeb tables are displayed in linear mode.
_training_mode1This switch puts the CallWeb questionnaire in interviewer training mode where skips and display conditions are displayed but not enforced.
_show_skips1This switch displays skips on screen.
_show_dc1This switch displays display conditions on screen.
_show_codes1This switch displays the numeric codes of each answer category.
_show_substitutes1This switch displays the recall codes instead of actually performing the recalls.
_no_permutation1This switch deactivates permutations throughout the questionnaire.

   

Appendix D

Recent changes and additions

DateChange / addition
August 1, 2019Addition of the WEIGHT question type to weight cwfreq and cwquestionnaire results.
July 4, 2019Conversion of plus signs into &plus; in open end parts.
October 18, 2018No more logging of non-existent project pages.
August 25, 2018Additions of MATRICE2 and MATRICE3 classes to embedded tables to give more formatting control.
March 16, 2018Addition of an option to skip the MX test in cwemail.
June 8, 2017Addition of an option to prevent taking a text copy of the data before a compilation with structural change.
February 7, 2017The integrated module only shows prepop files that reside in folders of projects that are accessible to the user.
October 19, 2016Addition of the # Index pound instruction.
September 16, 2016Special characters are converted HTML entities in e-mail messages.
May 3, 2016cwprepop can import zeros in close-end fields.
December 8, 2015Addition of the random_integer2 function.
November 5, 2015Addition of a Message-Id header to e-mail message to reduce the risks of spam identification.
August 12, 2015Addition of the CRYPT option to RELATION questions.
August 5, 2015Addition of the # Load JavaScript Library pound instruction.
July 15, 2015BOX variables acknowledge open-end part FORMAT instruction.
July 10, 2015The email function can send a bcc.
March 4, 2015{JUMP} skips can now be encrypted using {JUMPC}.
March 3, 2015Addition of the # Always open at pound instruction.
March 3, 2015Addition of the NOPARAGRAPH parameter on the question name line.
February 17, 2015Addition of display conditions to the columns of the child table RELATION questions.
February 16, 2015Addition of the K behaviour code to avoid a hard return before an alhpanumeric open-end box.
January 17, 2015Addition of the # Bottom Button Position and # Top Button Position pound instructions.
January 11, 2015Addition of the E behaviour code to define an answer category as a title.
January 10, 2015Addition of the # Page Error Image and # Field Error Image pound instructions.
January 10, 2015Addition of the NOLANGUAGE parameter on the question name line to avoid displaying the language button(s).
January 10, 2015Addition of the max_spss_alpha_field usager.conf instruction to allow for alphanumeric fields larger than 254 in SPSS code.
September 15, 2014cwprepop disregards lines in prepop files that start with a comment (##), allowing for commented data files.
August 20, 2014The # IMAGE LEFT, # IMAGE RIGHT, # SUBMIT IMAGE, # IMAGE STOP pound instructions accept substitutions and, thus, conditional recalls.
July 20, 2014cwfreq now uses calc_graph to chart univariate and bivariate distributions.
July 20, 2014Addition of the calc_graph function.
July 15, 2014Addition of the GOTOURL question type.
July 13, 2014The "# Execute if" pound instruction can invoke more than one CALCUL question.
July 13, 2014Addition of an extraction of the questionnaire in Triple-S XML 2.0 format.
July 13, 2014Addition of the # Pretest Project pound instruction to name the CallWeb project used for pretest.
July 12, 2014Attempting to start a questionnaire from a non-existing question is disallowed.
July 12, 2014Addition of the ORDER_BY option to RELATION questions.
June 27, 2014Addition of the READ_ALSO option to RELATION questions.
April 8, 2014Addition of the ERASE_CALCUL option to RELATION questions.
April 1, 2014The number of lines of multi-line open-end boxes adapt to the amount of text entered.
November 15, 2013Addition of the CATEGORIES question type which draws its answer categories from the contents of an open-ended question.
November 5, 2013Addition of the substitution.
November 5, 2013Addition of the obscurcir/cover and decouvrir/uncover functions.
August 9, 2013cwxlog.cgi reports information from the local instance log.
August 8, 2013Db-to-db extraction can use a data base port other than the MySQL default.
June 16, 2013Addition of the tilde delimiter to &#RECALL substitutions to allow the absence of spacing after the recall.
June 15, 2013The # READ and # DO NOT READ pound instructions can use substitutions.
June 13, 2013cwextr.cgi produces more compact SAS and SPSS code.
May 22, 2013Error conditions in sending e-mail messages now keep a trace of the date and time of the failed attempt.
May 8, 2013Addition of mode specific control over the _print mode.
May 8, 2013Addition of the DONOTPRINT question type which skips the question in _print mode.
May 6, 2013Modification of a variety of style assignments in the administrative modules to provide a more unified look and increased control over the user experience. CallWeb's official style sheet and colour scheme.
April 25, 2013Addition of the PAGEBREAK question type.
April 25, 2013Addition of the _debute and _termine URL options, used in conjunction with _print.
March 29, 2013Addition of the "# Execute if" pound instruction.
March 29, 2013Addition of the ability to give cwdocs.cgi permissions to specific directories
February 19, 2013The "# Enforce response length" pound instruction shows the number of characters allowed in a multi-line text box and the number of characters left.
January 28, 2013Addition of the out_of_service usager.conf instruction to temporarily block all access to the instance questionnaires and display a general out-of-service message.
January 28, 2013Addition of the # Radio button directory pound instruction to relocate the radio button and checkbox images.
January 26, 2013Passwords used to access utility programs can be made to expire after a certain number of days using the login_pw_valid_days, login_pw_allow_same, login_pw_rules, and login_pw_rules_message installation instructions.
January 17, 2013Addition of the # Radio button suffix pound instruction to change the appearance of radio buttons and checkboxes.
January 14, 2013Addition of the # Freeze data if and # Frozen data message pound instructions.
January 2, 2013The Template pound instruction accepts substitutions.
January 2, 2013Addition of the MOBILE() operator in display conditions.
January 2, 2013The Stylesheet pound instruction accepts substitutions.
December 20, 2012The D-type open-end question accepts Perl expressions within braces for the minimum and maximum dates.
December 19, 2012Addition of the Thousand Separator pound instruction.
December 7, 2012Addition of the combine_into_multiple function.
December 3, 2012Addition of JavaScript code to avoid sending the CallWeb questionnaire page with a hit on the return key in a text box.
December 2, 2012New SUGG question type (SUGGest) which warns only once for an insufficient number of responses.
November 28, 2012The <COMPUTE BUTTON> instruction has an additional parameter to avoid normal question validation.
November 28, 2012The compiler can copy .scw files and associated # INCLUDE files from a distant server (while creating the necessary folders and without a starting project).
November 24, 2012Addition of the n_records function.
October 12, 2012Addition of the except_codes function.
October 3, 2012Addition of the encrypted password to contextual information.
October 3, 2012Addition of the _epw parameter to URLs.
October 2, 2012Addition of a JavaScript library and introduction of smart checkboxes.
July 19, 2012Addition of the "Password" option to the Survey Type pound instruction. This type of access control is based on a fixed user ID and a changeable password. A cookbook recipe describes this system in detail.
June 26, 2012Addition of the last_access function for calculated questions.
June 7, 2012Using an L-type open-end question, a selection condition can be specified to limit the values shown in the dropdown list.
May 30, 2012New "compress" mode associated with "print" mode in the integrated module: it omits the radio buttons of the first question in a table to use the space to print row labels thereby producing a tighter printout.
May 17, 2012Addition of the "cwemail password" pound instruction to control the sending of e-mail messages via cwemail.
December 7, 2011The following pound instructions can accept substitutions (including a conditional one): URL, HTML Title, and Telkey pattern.
November 30, 2011If a <BOX> question does not have an open-end part, the close-ended answer categories are presented as a dropdown list.
November 23, 2011The # STOP BUTTON and # DISPLAY THERMOMETER pound instructions can accept a substitution (including a conditional one) in lieu of a question name.
November 21, 2011The # STOP BUTTON pound instruction can be controlled by a display condition.
November 16, 2011Print mode (which shows an entire questionnaire on a single Web page) can insert questionnaire page break markers on-screen as well as real page breaks upon printing.
November 5, 2011The SCALE question type centres the scale on the page if the column width is preceded by a C (e.g., SCALE=C80).
November 5, 2011Addition of the "cwarchive zip password" pound instruction to encrypt back-up data in a zip file.
November 5, 2011Addition of the "cwcompile zip password" pound instruction to encrypt compilation results in the zip file.
November 5, 2011Addition of the "cwemail report to" pound instruction to specify an e-mail address where to send the turbo-mode cwemail.cgi report.
November 5, 2011cwautoemail.pl refrains from processing an autoemail instruction if a previous call to it has not yet completed.
November 1, 2011In cwemail.cgi, addition of a report on messages waiting in the queue and ability to delete a queue of messages.
October 27, 2011Addition of the "cwextr zip password" pound instruction to encrypt extracted data in the zip file.
October 10, 2011Profound revamping of the mechanism used to send e-mail messages using the daemon mode. It improves the performance of the Autoemail pound instruction and the cwemail.cgi module tenfold while using less of the server resources.
August 27, 2011New function n_calls.
August 23, 2011cwedit.cgi supports a comment line located between the question name line and the percent line starting the question text segment.
August 21, 2011cwautoemail.pl requires that the CallWeb "client" name be appended as an argument, e.g., "perl cwautoemail.cgi PROD &". This allows concurrent autoemail tasks in different instances on the same server.
July 7, 2011Addition of various installation instructions which increase the security of the files in project directories: default_cwpermissions_directory_permissions, default_cwpermissions_file_permissions, cwpermissions_deletes_from_cwdir, and exclude_from_cwcompile_backup.
June 21, 2011Addition of the tilde (~) behaviour codes to deactive the display of the pop-up calendar in a D open-end question.
April 4, 2011The archival module can save the automatic back-ups to a directory other than the project directory, including on another server.
March 29, 2011Addition of the DESTOP question type which branches back to the question from which the STOP button was invoked.
February 28, 2011The integrated module can show a simplified interface for a single project.
February 25, 2011Addition of NRESPONSES display condition operator which returns the number of responses given to a question.
February 23, 2011Addition of the "Activate the mobile mode" pound instruction which displays a simpler page to mobile devices.
February 23, 2011Addition of the "M_Cell highlighting" pound instruction to define the coulour used in cell highlighting.
February 22, 2011Addition of the "Cell highlighting" pound instruction to deactivate cell highlighting in questionnaires.
February 14, 2011Addition of the indexposition function.
February 1, 2011The "value" used in subsetting comparisons in utility programs may be "$week" or "$XXweeks". These expressions are then translated into the appropriate date so many weeks ago.
January 30, 2011Addition of the <parent></parent> structure which allows the specification of alternative text for questions and answer categories to be shown in RELATION tables.
January 24, 2011cwupload.cgi is now integrated into cwdocs.cgi. Please delete cwupload.cgi from the utilities directory.
January 18, 2011Reestablishment of project-level read and write passwords, by popular demand, on top of the access control system.
January 9, 2011Addition of the concept of group or dynamic permissions to the access control system.
December 31, 2010Addition of a comprehensive access control system for all utility programs.
December 15, 2010Improvements of response category behaviour codes to control the placement of an open-end box around the response category label.
November 25, 2010Addition of the ability to upload documents to the server via the "F" open-end type.
November 21, 2010The cwedit module supports question-level locking, allowing multiuser editing of questionnaires.
November 21, 2010Bounce message management is now performed, much more efficiently, by the CallWeb deamon.
November 21, 2010cwextr.cgi extracts a standard .tcw file even when multiple dichotomies are requested.
November 21, 2010Bivariate tables can now exclude columns without cases.
November 20, 2010Addition of the NOPRETEST question type to cancel "# PRETEST" for a particular question.
November 19, 2010The progress bar can now be without text on its right, thanks to the MUTE keyword on # Display thermometer.
November 19, 2010CallWeb cleans out extraneous characters (like periods) from project names in URLs to avoid broken links in e-mails.
October 20, 2010"# Attributable questions" is tested for non-existent variable names.
October 9, 2010A "please be patient" message is displayed on questionnaire pages while cwcompile is dropping a field from a project database.
July 17, 2010cwcompile flags the presence of an unconditional skip from a question other than the last one of a multi-question page as an error.
July 16, 2010New calculation function "time_between" returns the amount of time between two dates or times.
July 16, 2010Addition of the "Default cwemail sender" pound instruction to specify the e-mail address that is technically sending the message in cwemail.
July 13, 2010Addition of the use_telkey_table pound instruction to adjust the use_telkey_table installation instruction on a project by project basis (necessary for the correct operation of BASEpretest).
July 12, 2010Addition of the concept of "warnings" as part of cwcompile: warning messages are displayed during compilation but don't prevent it from happening.
July 10, 2010Addition of the concept of "title SUFFIX" that automatically turns a SUFFIX question into a title in a table.
July 8, 2010Addition of the capacity to ask for confirmation of deletion of child records in hierarchical projects.
July 2, 2010&# recalls are shown in an intelligle way in cwquestionnaire and cwfreq as well as in questionnaire mode if the option to show recall codes is selected.
July 1, 2010The email function can send a cc.
June 30, 2010cwemail.cgi can produce a # AUTOEMAIL statement based on the selections made in the interface.
June 17, 2010New calculation function "shuffle_code_labels" returns the text of a series of answer categories, in random order.
June 12, 2010cwextr can save an extraction in any directory on the computer running CallWeb. This is particularly useful to extract data from a laptop CallWeb computer to a USB key. See the # cwextr copy directory pound instruction.
June 11, 2010Addition of the # Minimal extraction width pound instruction.
June 3, 2010New extraction option to prefix the variable labels using the question name.
May 31, 2010cwdossier.cgi displays the question name from within cwnav.cgi.
May 31, 2010cwcompile.cgi allows empty lines between two question definitions in the .scw file.
May 21, 2010Addition of a reserved _telkey table to better control the attribution of _telkeys in open projects. Related to the new "use_telkey_table" installation instruction.
May 19, 2010Addition of the creation of a rough .scw file from a tab-delimited data file.
May 12, 2010Addition of parallel inversions using INVERSION=Qx whereby the inversion of answer categories is made the same as the inversion of answer categories in another question.
May 11, 2010The FORMAT instruction now adds thousands separators when numeric formats are specified.
April 19, 2010Addition of a list-unsubscribe header in messages generated by cwemail.cgi and cwautoemail.pl, and the corresponding "list unsubscribe" pound instruction.
April 18, 2010Addition of a sender header in messages generated by cwemail.cgi and cwautoemail.pl.
April 8, 2010cwextr.cgi can use a delimiter different from a comma in csv files (useful for those who use a non-English version of Excel, for example). The new csv_delimiter installation instruction can make this new delimiter the installation default.
April 8, 2010A comparison of the .scw and .scw.last files is saved in the .zip file created by each questionnaire compilation.
April 6, 2010Addition of the QUESTION() operator in display conditions.
March 15, 2010cwcompile.cgi identifies an error in the absence of a calculation in a CALCUL question.
March 13, 2010The "# Enforce response length" pound instruction constrains the length of a multi-line alpha-numeric answer to the limit defined in the questionnaire (as long as JavaScript is activated in the respondent's browser).
February 11, 2010cwextr.cgi produces a report on the parameters of the extraction and places it in the extraction .zip file as _info_.txt.
February 10, 2010cwstats.cgi historical counters can be reset.
February 8, 2010The "# Control by cookie" pound instruction now reopens the same case on the last-seen page as if the _telkey had been passed in the URL.
January 24, 2010Addition of "custom" mode that displays a customized version of the questionnaire (with answers) for a particular _telkey.
January 23, 2010Addition of hints to explani options in the integrated module.
December 12, 2009Addition of the creation of Stata code in the extractor.
December 11, 2009cwnav.cgi can recalculate several fields at once.
November 22, 2009The text of the various buttons (Next page, Previous page, Submit, Stop, Unlock) can use any of the recall syntaxes. In particular, the text of the buttons can use the conditional "# Recall" instruction and thus completely adapt to the questionnaire circumstances.
November 22, 2009Addition of the SUBMIT question type that uses "# Submit Text" and "# Submit Image" pound instructions for the Next Page button.
November 22, 2009Addition of the NOPRINTCAT question type that deactivates the printing of response categories in print mode (useful for very long lists of categories).
November 22, 2009Addition of descending sorts in cwnav.cgi.
November 22, 2009Addition of the REPORTTO option to # AutoEmail.
November 11, 2009Addition of the # Access send telkey image pound instruction; it defines a image for the Submit button on the password request page.
October 28, 2009Substitutions can be used in system messages.
October 20, 2009Addition of the add_to_date function.
October 20, 2009Addition of the "# Enforce response length" pound instruction to produce an error message if a multi-line alpha-numeric answer is longer than the limit defined in the questionnaire.
October 6, 2009Addition of the # Stylesheet pound instruction to define a project-specific stylesheet.
August 22, 2009Addition of the ZERO FORMAT option for numerioc open-end parts.
August 21, 2009Addition of CSS control over the questionnaire buttons, text and numeric boxes, and dropdown lists.
July 17, 2009Addition of an automatic selection of all cases in utility modules.
July 10, 2009Addition of the ELSE condition to the RECALL pound instruction.
July 10, 2009Addition of the NOTEMPTY operator for logical conditions.
June 24, 2009Addition of the straightlined function which identifies straightlining in Web surveys.
June 23, 2009Addition of the put_values_in_case function which can place values in any field of any case of any project as well as create cases in a project.
June 10, 2009The RECALL pound instruction now includes the ability to recall different strings or values according to display conditions.
May 25, 2009Addition of control over the maximum length of variable and value labels extracted to SPSS code and the like by cwextr.cgi. Defaults can be set in the configuration file.
May 9, 2009Addition of the ")" answer behaviour code which place table cell text (behaviour "M") right of the radio button or checkbox. See also "# M text position".
May 5, 2009Addition of the AUTONEXT question type which moves automatically to the next questionnaire screen after a set number of seconds.
May 1, 2009Addition of an installation option (interviewer_timer) controlling the display of the timer to the interviewer.
April 30, 2009New ability to undo CallWeb system updates.
April 30, 2009New A answer behaviour code which Always displays the category in cwfreq.cgi tables.
April 28, 2009The short URL syntax has been made more flexible.
April 18, 2009Addition of the capacity to start cwautoemail.pl within a particular project from cwemail.
April 18, 2009Addition of the capacity to send carbon-copies via cwemail and the Auto email pound instruction.
April 17, 2009Addition of the capacity to test Auto email pound instruction from cwemail.
April 17, 2009Addition of the ACTIVE option to the Auto email pound instruction to activate and deactivate such instructions.
April 16, 2009cwautoemail issues a message to the system administrator after completing a task.
April 14, 2009Addition of an installation option (notify_every) controlling the frequency of notifications of inactive projects.
April 9, 2009Addition of an exception to the CSS progress bar for Internet Explorer 6 which does not properly render the CSS code. The old table-based progress bar code is used for it.
April 8, 2009Addition of an e-mail reminder about projects that have been inactive for more than 14 days (this delay can be changed in the configuration file).
April 7, 2009Addition of the test_email_address function to verify whether an e-mail address is deliverable.
April 5, 2009The progress bar faithfully reflects the path through the questionnaire when permutations are performed over several pages.
April 4, 2009Addition of the MEMEXCL and VBTMEXCL question types to exclude questions from being displayed in MEMO and VERBATIM questions.
March 27, 2009Whole new set of pound instructions for progress bars: "# Thermometer width", "# Thermometer height", "# Thermometer border width", "# Thermometer border colour", "# Thermometer gap width", "# Thermometer gap colour"
March 24, 2009The callweb.cgi and cwx.cgi modules can optionally show recall codes (instead of performing the recalls) and avoid permutations to produce a stable version of the questionnaire for printing and sharing.
March 22, 2009The callweb.cgi and cwx.cgi modules can optionally show response codes, display conditions and skips. Combined with the print mode, which shows the entire questionnaire on a single Web page, this allows for the production of versions of the questionnaires to share with non-technical personnel.
March 21, 2009The new CallWeb daemon mode is ready for production.
February 17, 2009All elements of the new CallWeb daemon mode are in place — but not yet put into production.
February 14, 2009Addition of a hyperlinked table of contents to cwfreq.cgi output if more than one table is produced.
February 10, 2009Optimisation of cwautoemail.pl to avoid delays associated with empty e-mail address fields.
February 9, 2009Structural changes to the database may be accepted during compilation if they are the only compilation issue.
February 8, 2009Addition of the "training mode" which displays the questionnaire without consideration for skips and display conditions and which does not substitute response recalls. This is meant as a demonstration mode for interviewer training.
February 7, 2009Addition of the "# Template" pound instruction which allows for the construction of questionnaire pages based on existing HTML pages. Now you can mirror the look of existing Web sites and implement standard pages like the Government of Canada Common Look and Feel Standards for the Internet standards.
February 1, 2009Addition of the "# Button order top" and "# Button order bottom" pound instructions which replace the "# Button order" instruction. Backward compatibility is maintained.
February 1, 2009Answer categories controlled by # Auto Submit are formatted using the AUTOSUBMIT style and can, therefore, depict their autosubmit status.
February 1, 2009Major redesign of the questionnaire page production system that will allow a variety of new features.
January 13, 2009A log of structural changes performed on questionnaires is maintained in a file called project.change.log.
December 15, 2008The priority of messages can be specified in cwemail.cgi.
December 8, 2008cwedit.cgi saves .scw files with Windows end-of-line characters.
November 23, 2008Addition of the ability to insert any pound instruction in the system configuration file.
November 6, 2008Addition of the Auto submit pound instruction to speed up CATI work.
September 22, 2008Addition of the extraction of R code to read in the CallWeb file.
September 18, 2008Extractions to .csv files can now include more fields to accommodate enhanced capacities of Excel 2007.
September 4, 2008Univariate and bivariate tables can now exclude rows without cases.
June 26, 2008Addition of the comparative_results installation instruction to display interviewer productivity data to interviewers.
June 20, 2008The necessary _telkey field can be placed anywhere on the prepopulation files.
June 17, 2008The Pretest feature was modified so that a specific pretest comment made on a particular question of a certain case is re-displayed if the pretest link is used again on the same question of the same case.
June 16, 2008Addition of the Allow new in open combination pound instruction that controls whether new cases can be created in "Open combination" mode.
June 9, 2008Major overhaul of the questionnaire production code so that questionnaire pages comply with the XHTML standard. Modification of the utility modules to come.
April 20, 2008New cwdocs file management module with which users can create, delete, copy, rename and move directories, and upload, download, delete, copy, rename and move files on the server — all only with a browser.
April 9, 2008Particular modules (maybe less used modules) of the integrated module can be hiden from the menu structure.
April 4, 2008Addition of the Robot caller id pound instruction that specifies which number the IVR robot displays when calling.
March 16, 2008Addition of the CODESIN code selection instruction and of the pull_value data base management function.
March 3, 2008Addition of LANGUAGE display condition operator to specify language versions of the questionnaire.
February 19, 2008Addition of the _week system variable which indicates when the questionnaire was last accessed expressed as a week date.
February 14, 2008Improvements to the management of e-mail in cwemail.cgi: better identification of unreachable domains, additional error codes in the output field.
February 12, 2008New calculation function "push_value" to place a value in a question in any project based on arbitrary selection conditions.
February 2, 2008Addition of two case selection criteria in all utility programs: "in a list of values" and "outside a list of values"
January 31, 2008cwquestionnaire.cgi can produce multilingual questionnaire printouts.
December 4, 2007Multiple comparisons of ranges and individual values is now possible in display conditions (e.g., Q1.EQ.1-5,7).
November 13, 2007New SEMANTIC question type to facilitate the programming of semantic differential scales.
November 12, 2007An INFOCATI field with a T type open-end part displays a dial button if the project uses a dialler.
November 12, 2007The cwquestionnaire module can display aliases of response categories.
November 9, 2007cwfreq.cgi is now able to display univariate distributions and tables in decreasing frequency order.
October 23, 2007Addition of the ability to comment various parts of the question definition; these comments are reproduced by cwquestionnaire.cgi
October 20, 2007In the cwemail.cgi module, it is possible to test a mailiout to single e-mail address.
October 18, 2007Addition of the capacity to copy a CallWeb script from another server before compilation.
October 14, 2007Open-end questions associated with <BOX> instructions don't need to be defined before their use in the questionnaire anymore.
October 12, 2007Addition of the <COMPUTE BUTTON> instruction which displays a new button on the page and performs arbitrarily simple or complex calculations before returning to the same questionnaire page.
October 6, 2007In the presentation of a table involving _cetecran, cwfreq hyperlinks to a cwquestionnaire display of the question.
September 14, 2007In cwnav.cgi, if a multiple-response question is edited in boxed mass edit mode, different values can be separated by commas or spaces. CallWeb edits the data upon Action! to delimit the values using "μ" characters.
September 3, 2007In table presentations, answer categories that would never be selectable because of display conditions are not shown.
September 2, 2007Addition a mechanism to # Auto email to avoid bombarding a domain with messages and, thereby, reduce the risks of being black-listed or identified as a spammer.
September 2, 2007Addition of links to other utility programs, passing along all common parameters. This allows to carry over a case selection (and other parameters) automatically from one utility program to another.
August 29, 2007Addition of an optional title displayed in utility programs (cwnav.cgi, cwfreq.cgi, cwoutcomes.cgi and cwquestionnaire.cgi). It is formatted with the EQUIVALENTH5 style by default.
August 28, 2007cwcompile.cgi compares the ID of the current user to that of the most recent person who compiled a project and reports discrepancies.
August 18, 2007Addition of the BASEpretest pound instruction which activates the CallWeb pretest mode. See the related recipe.
August 11, 2007Addition of the NOTEST question type which cancels compilation tests on response categories for a certain question; useful to speed up the compilation when a question includes thousands of answer categories, it has been tested in the past and no change was made to it).
August 9, 2007CallWeb now implements parallel permutations where the random order of one set of variables is mirrored in another set.
August 6, 2007cwextr.cgi can now extract directly into another CallWeb data base located on the same server or another server.
July 10, 2007cwarchive.pl keeps the questionnaire script .scw file and the style.css file in the .zip archive along with the .tcw version of the data.
July 5, 2007In addition to optionally showing field display conditions in the header of the tables, cwfreq.cgi can acknowledge the presence of skip patterns — which is helpful in assessing the integrity of the data.
June 26, 2007Addition of the capacity to recalculate CALCUL questions on any number of data records from within cwnav.cgi.
June 20, 2007Addition of the BASEclicks pound instruction which speeds up calls to callweb.cgi.
June 2, 2007CHECKALL can be used in conjunction with the copy of answer categories.
June 2, 2007Assuming no language parameter is passed on to CallWeb, the questionnaire now start in the first language accepted by the respondent's browser if this language exists in the questionnaire. The default language is used otherwise.
May 25, 2007New DEACTIVATE PAGES pound instruction which shortcircuits the GROUP (ECRAN) and TABLE (MATRICE) instructions in the questionnaire. It may serve to linearize a questionnaire for CATI purposes.
May 18, 2007E-mail messages are sent no faster than one per five seconds to any given domain to avoid bombarding.
May 17, 2007Several constraints in the management of multi-server projects are lifted.
May 13, 2007New RECALL pound instruction which provides another method to substitute text and values in questionnaires.
May 12, 2007Recalls can now be made within recalls (of any type within any type and at any depth level).
April 24, 2007cwupdate.pl can now run at the cron.minute pace, allowing for much more dynamic system updates.
April 23, 2007The short CallWeb syntax may now include the name of the initial question in the questionnaire.
April 19, 2007New recode function to recode answers into another coding scheme.
April 19, 2007New I answer behaviour code which makes the code invisible.
April 17, 2007The RTF (Word-printable) version of the questionnaire is now uploaded to the workstation where it can be opened directly into Microsoft Word (or other RTF-compliant word processing programs) instead of being displayed on screen.
April 11, 2007Addition of the POSITION parameter in the definition of tables to put the table on the left side of the page, on the right or centered.
March 31, 2007Using the Control by cookie pound instruction, addition of the capacity to limit the creation of a single questionnaire using cookies.
March 28, 2007Addition of the New question order pound instruction to put questions in an order that is different from the sequential order of the .scw file. This is useful to allow the SUFFIX syntax with non-contiguous questions.
March 18, 2007Addition of security controls to avoid illegitimate form submissions by spammers.
March 16, 2007Addition of the capacity to open a particular record in cwnav.cgi from the integrated interface cw.cgi.
March 14, 2007Addition of the # Button position pound instruction to locate the submission buttons on the page.
March 13, 2007Addition of the V answer category behaviour code to flag missing values in univariate tables in cwfreq.
March 9, 2007The "<", "=" and ">" answer category behaviour codes also control drop-down lists located in tables.
March 8, 2007Addition of three answer category behaviour codes to control the location of open-end boxes within cells of tables.
February 14, 2007Addition of the administrator_email installation parameter used to automatically send information on available system updates.
February 9, 2007Acceleration of the look-up of answer categories.
February 7, 2007Addition of parallel permutations using ROTATON=Qx whereby the permutation of answer categories is made the same as the permutation of answer categories in another question.
February 3, 2007New M open-end part to create "password" fields (M for mot de passe) which display asterisks in the input box upon data entry.
January 31, 2007Data extraction can now respect the width of the closed data fields instead of outputing a fixed number of columns.
January 30, 2007New response category behaviour code B to identify codes which are not subject to permutation, inversion or alpha order.
January 27, 2007Response aliases can be labelled using letters and numbers, not only numbers.
January 24, 2007Hierarchical projects can link to a subset of children not associated with the current parent.
January 12, 2007cwfreq can display absolute-frequency-only tables (without percentages).
January 10, 2007Addition of readable date and date-time values in the context data.
January 8, 2007Addition of the concept of answer code alias which can be used in recalls to display different text without having to create extra questions or use the somewhat involved EXECUTE syntax. See the recipe about it.
January 5, 2007New operators ISEMPTY and ESTVIDE for display conditions and x-base logical expressions generally. They identify fields which contain no data. They replace the ".NOT.field" syntax which is made obsolete by allowing zeros in answer categories.
January 5, 2007Answer categories may now use zero as a code.
December 13, 2006Open-end parts of [D]ate type automatically pop a calendar (as long as the browser accepts JavaScript code) upon clicking into the open-end box. The respondent can pick a date from that calendar.
December 7, 2006The questionnaire progress bar is now based on the number of questionnaire pages displayed to the respondent instead of the number of question prompts.
November 7, 2006cwnav hyperlinks directly to the .wav recordings of telephone interviews (an Asterisk server is used to control the telephone conversation and record the interview).
November 3, 2006New Refuse duplicates in cwprepop pound instruction.
November 2, 2006New random_subset function to select a random subset of responses to a multiple-response question.
November 2, 2006cwprepop flags invalid numeric values associated with close-ended questions.
October 31, 2006Ability to format a 10-digit number as a telephone number when displaying it.
October 25, 2006The integrated module can hide or display BASE projects.
October 24, 2006New CATI selection 3 pound instruction.
September 29, 2006Values can be truncated independently for lines and columns in cwfreq.
September 28, 2006New MySQL engine pound instruction.
September 9, 2006New Display thermometer pound instruction replacing "Thermometer" with a more user friendly interface. "# Thermometer" is maintained for backward compatibility.
September 4, 2006The conditions used to select records in the CallWeb data base may now be entered as a full SQL expression in addition to the dropdown list-assisted traditional mode.
September 3, 2006Addition of the cwcheck module which reports cases with missing data and excess data (stemming from changes to the questionnaire part-way into the data collection) based on existing answers and the questionnaire logic.
August 30, 2006Implementation of a new (and much finer) mechanism to determine the colours in questionnaire tables.
August 26, 2006cwedit can be instructed to display only text fields so that the translation can take place in cwedit without fear of changing the structure of the questionnaire.
August 19, 2006Addition of the T answer behaviour code which asks to confirm a numeric open-end value which is outside the minimum and maximum bounds planned in the questionnaire.
August 11, 2006Default extraction file types and e-mail destinations can be specified in the instance configuration options.
August 2, 2006A report on the result of the most recent update is available from the integrated module.
July 30, 2006Addition of the ability to easily select the language of the questionnaire to extract for data processing purposes.
July 26, 2006Addition of the Extraction width pound instruction.
July 19, 2006Addition of the "ivr" mode to the CATI pound instruction.
May 20, 2006Addition of the ONCEACROSS parameter on the question name line to allow only one respondent to chose any given response category.
May 15, 2006RELATION questions feature a simpler user interface for respondents.
May 10, 2006The demo mode is now fully operational even on Closed, Open Combination and Open Offered survey types.
May 7, 2006The compiler now flags simple skips on non-exclusive codes of multiple-answer categories as errors.
May 5, 2006Production of an English and a French version of a symmary card of CallWeb syntax.
May 5, 2006The Survey type pound instruction can be expressed using clear type names rather than numeric codes.
April 30, 2006It is now possible to perform several extractions concurrently on a given project.
April 27, 2006Addition of the ONLYONCE parameter on the question name line to refuse to change the answer to a question.
April 24, 2006Data modification in cwnav can now be constrained to existing close list codes to simplify coding and to enhance quality control.
April 21, 2006A question name line and a SUFFIX note can modify the CORNER heading of a table.
April 18, 2006Addition of the NOTHERMOMETER parameter on the question name line to avoid displaying the progress bar.
April 15, 2006cwcompile reports duplicate answer codes.
April 11, 2006cwcompile now has an option to beautify scw files (adding indentation, labelling percent and exclamation lines).
April 10, 2006The positional parameters on the TABLE pound instruction are replaced by keywords.
April 10, 2006The positional parameters on the PERMUTATION pound instruction are replaced by keywords.
April 10, 2006The positional parameters for the minimum and maximum numbers of answers on the question name line are replaced by the MIN and MAX keywords.
April 7, 2006The D positional parameter on the question name line is replaced by the DROPDOWN keyword.
April 7, 2006Addition of a "search and replace" function in cwnav.
April 2, 2006Addition of cwupdate.cgi and cwupdate.pl which perform a scheduled update of the CallWeb system software.
March 24, 2006Addition of the CHECKALL question type.
March 24, 2006A CallWeb cookbook has been initiated which offers recipes for common and not so common tasks.
March 16, 2006In matrix format, radio buttons and checkboxes can be selected by clicking anywhere in the table cell.
March 15, 2006It is now possible to back track to a question without responses or allowing no response.
March 10, 2006Addition of the "Second line of buttons" pound instruction.
March 9, 2006Addition of the project name and of the date of the last update to the questionnaire in the context data.
March 8, 2006If the first column of a matrix is empty, it is not displayed.
February 27, 2006Launch of the first version of cwgen which generates random test data to verify the integrity of a questionnaire logic.
February 16, 2006The "value" used in subsetting comparisons in utility programs may be "$today" or "$aujourdhui" or "$yesterday" or "$hier". These expressions are then translated into the appropriate date.
February 10, 2006The new VERBATIM question type (meant for use in CATI mode) allows for the easy cleaning of character open-ends at the end of an interview.
February 9, 2006The frequencies displayed by cwquestionnaire can use a filtering expression so as to report only a subset of the cases.
January 23, 2006The new # Mandatory question instruction can display a signal on every mandatory question in the questionnaire.
January 16, 2006The new _h3 system variable stores the dates and times of modifications performed on data from within cwnav (either in mass edit mode or in individual case edition).
January 16, 2006Dates of data prepopulation are now kept in _prepops; the new field _lastprepop contains the most recent prepopulation action date.
January 13, 2006E-mail messages, be they massive or individual, can now contain an HTML portion.
December 31, 2005cwextr can now extract only a subset of the questionnaire fields.
December 9, 2005cwedit can now copy questions from other projects within the instance of CallWeb.
November 30, 2005Addition of the # Deny access if instruction to block access to questionnaires.
November 15, 2005Addition of the # Thermometer colour instruction to determine the colour of the thermometer.
November 14, 2005Addition of the ability to add attachments to e-mail messages sent via cwemail.
November 10, 2005Addition of the System message pound instruction.
November 3, 2005Images used for the left, right and stop buttons can now be different from language to language.
October 31, 2005Addition of configuration options to define local telephone numbers in CATI mode.
October 25, 2005Addition of the # Master CATI server instruction which identifies which server may manage the CATI operations of a project.
October 24, 2005Addition of the # Copy questionnaire into instruction which sends a copy of a local questionnaire to a secondary CallWeb server.
October 23, 2005Addition of the # Master compilation server instruction which identifies which server may compile the project.
October 22, 2005Addition of the # Only for server instruction which makes a pound instruction conditional to which server the scripts runs on.
October 22, 2005Addition of the ability to switch languages using images rather than HTML buttons using the # Language image instruction.
October 19, 2005Initial launch of the beta version of cwedit which is a visual editing environment for CallWeb questionnaires.
October 14, 2005Optionally, cwquestionnaire can add actual data base frequencies and percentages into the questionnaire output.
October 5, 2005A new mechanism intercepts and reports (by interruption) the presence of infinite loops in questionnaires.
October 4, 2005Simple skips associated with CALCUL questions are now honoured. This simplifies multiple branching.
September 22, 2005The compiler refuses to process a script if a compiled script of the same name exists elsewhere in its CallWeb directory structure.
September 6, 2005The data base server is fully detached from the CallWeb server; it can reside on the same computer or on a separate one and one data base server can serve severa CallWeb servers.
August 30, 2005Individual projects can now have their individual installation (conf) files to specify parameters at the installation level such as the data base engine to use, the location of the data base server or the default language.
August 19, 2005cwtelkeys can now insert the newly created _telkeys directly into the project data base.
August 15, 2005Addition of the "Button Order" pound instruction to control the order of presentation of the buttons and thermometer at the bottom of each question screen.
August 11, 2005Addition of the "HTML Title" pound instruction to provide a title for the questionnaire HTML page.
August 8, 2005Addition of the S behaviour code which gives special formatting to response categories.
August 6, 2005Addition of the SCALE question type which displays the answers as a horizontal scale.
August 4, 2005Text can be added in the title cell above a drop-down list located in a table using the M behaviour code and the [COL] feature.
July 29, 2005Simplification of the integrated module (cw) to focus on key project management functions.
July 26, 2005Addition of a data export format (opn): open end parts along with their question name and _telkey.
July 20, 2005New utility (cwtelkeys) to create lists of _telkeys that are unique within a project.
June 5, 2005It is now possible to create entire batteries of questions much more rapidly, thanks to question cloning.
May 26, 2005The page explaining tables instructs on how to create semantic differential scales or repeated end-point scales.
May 25, 2005Improvements to _print mode which now displays only relevant fields; display conditions and skips are displayed in clear to make this questionnaire format readable as well as informative.
May 17, 2005Addition of the features to make unit-type questions possible.
May 17, 2005The minimum and maximum values of a numeric open-end part may now be Perl expressions (therefore, calculated values).
May 13, 2005Addition of a pound instruction to indicate that a CallWeb project runs in CATI context.
May 5, 2005Addition of function to facilitate the integration of dual-mode (Web + telephone) projects.
April 28, 2005Addition of a method to assign values based on calculated expressions in cwnav.
April 26, 2005A new minimalist URL syntax is now available to initiate questionnaires.
April 19, 2005Addition of the JUMP hyperlink feature to jump to another question of the questionnaire without collecting data (useful for linked menus).
April 8, 2005Addition of the ability to permutate questions within permutations of blocks — down to any chosen depth level.
March 30, 2005Addition of the G behaviour code which ensures proper casing of an open-end part.
March 14, 2005Addition of the TEST pound instructions which implements any logical validation test anywhere in the questionnaire and reports anywhere on the CallWeb page.
February 22, 2005Addition of an option to display only statistics (no frequencies) for continuous data.
January 25, 2005Addition of extended x-base syntax .EQ. and .NE. operators to compare with multiple values at once.
January 20, 2005Addition of a CALCUL function to select random combinations of response choices (e.g., select any 2 choices among 5 possible answers).
January 17, 2005Moved the log of bounced messages to the project directory.
January 16, 2005Capacity to extract data and code to a DOS/Windows file format or a Linux file format.
December 13, 2004Addition of the capacity to run one-way and two-way tables on truncated data values.
December 1, 2004Addition of the INCLUDE pound instruction to include outside text files in .scw scripts.
November 28, 2004Addition of automated e-mails sent on the basis of a preset plan, using all of the information in the questionnaire; ideal for panel management!
November 25, 2004Addition of non-cleaning display conditions.
November 20, 2004Addition of a system to capture bounced messages (cwbounces.pl) in response to CallWeb invitations or other messages sent by CallWeb, and to store the bounces in the CallWeb data base in the relevant questionnaire data string.
November 19, 2004Considerable acceleration of data base prepopulation.
November 18, 2004In utility programs, addition of the ability to reduce the lists of questions to Web-meaninful ones.
November 17, 2004Translation of all pound instruction names into English (the French versions remain valid).
November 15, 2004Addition of the ability to display response categories in alphabetical order of label in all languages.
October 29, 2004Addition of a question type forcing the display of a table banner when questions are arrayed in table mode.
October 28, 2004Addition of a pound instruction to direct e-mail bounces.
October 21, 2004Addition the ability to span pound instructions over several lines and to integrate all linguistic versions of a pound instruction in a single declaration.
October 20, 2004Addition of a pound instruction to specify the text above the progress thermometer.
October 12, 2004Addition of the ability to FORMAT open-ended parts as dollar amounts, percentages, etc.
September 28, 2004Simplification of the syntax of CALCUL questions.
September 24, 2004cwcompile disallows the use of MySQL-reserved keywords as question names.
September 21, 2004Addition of the capacity to insert an open-end box within in the label cell of a matrix row (e.g., to add and "other, specify" entry in a matrix).
September 10, 2004Addition of the # Affiche min max instruction.
September 9, 2004Extractions of csv files create as many files as there are groups of 240 variables, in recognition of the limit imposed by Excel.
August 25, 2004Addition of a second level sort in cwNav.
August 24, 2004Improvement to the cwNav hyperlinks in cwFreq.
August 19, 2004Addition of a CALCUL function to close the browser window.
August 17, 2004Addition of the capacity to stop the questionnaire and direct the respondent to a special section of the script while ensuring that the questionnaire will resume from the page attained before requesting the interruption.
August 16, 2004cwcompile checks that the copy of individual response code texts is done from the default language and not to it.
August 7, 2004Available projects selectable by drop-down menus in cw.
August 6, 2004Addition of a selection criterion which does not discriminate between accentuated and non-accentuated vowels.
August 4, 2004cwNav links child records to parent records when a relation question is displayed.
August 4, 2004Addition of # Type enquete = 3 which allows survey participants to enter an access code and a password of their choosing.
August 3, 2004Additions of "Previous n" and "Next n" buttons in cwNav.
July 25, 2004Permutations and inversions of response categories are stable upon redisplaying a question with such permutated/inverted categories (back-and-forward or reentering a questionnaire).
June 12, 2004Addition of a URL open-end type.
June 11, 2004Addition of the <EXECUTE>Perl expression</EXECUTE> syntax to display the results of complex calculations without storing them.
June 9, 2004A table presentation of the data in RELATION questions can be recalled into other questions.
June 4, 2004Addition of master codes to access CallWeb projects (MASTER CODES pound instruction).
May 16, 2004Addition of the RELATION questions and of hierachical projects.
May 10, 2004Addition of the L (lire) answer behaviour code.
May 7, 2004Addition of a "regular expression" open-end type (R).
April 25, 2004cwQuestionnaire can identify HTML styles in use in a questionnaire and can attempt to replicate the style structure in an RTF file.
April 7, 2004Addition of the M response category behaviour code.
March 31, 2004cwQuestionnaire associates discrete styles to question names and calculated questions.
March 29, 2004Addition of the CORNER option in the TABLE statement to display text in the upper left corner of a table.
March 22, 2004Addition of a mechanism (cwDossier) to view the last few completed questions as part of cwNav (for CATI purposes).
March 18, 2004Addition of the "is empty" and "is not empty" operators in the selection tools of all utility menus.
March 12, 2004Security upgrade for the CallWeb configuration file.
March 11, 2004Addition of a means to display individual cases in legible form from cwNav.
March 10, 2004cwCompare identifies structural differences between two versions of a questionnaire.
March 3, 2004New "Condition de non retour" pound instruction to better control re-entry into the questionnaire.
March 2, 2004Addition of the "Visible depuis" pound instruction to limit project access for utility directories.
February 26, 2004An equal sign can be used to copy text from the default language into a non-default language, anywhere language-based text is used.
February 25, 2004The algorithm used by SUBSET questions is vastly enhanced, making selections in thousands of categories as fast as ordinary small sets.
February 7, 2004Addition of the STOCK question type to store simply information.
February 5, 2004cwCompile senses that questions were moved within the questionnaire script and adjuts the data structure.
January 23, 2004CallWeb script files now bear the .scw extension.
January 21, 2004cwExtr can now create Triple-S code files; it can also include the CallWeb code file in the extraction zip file.
January 12, 2004NEVERUPDATE questions are never displayed on screen.
December 17, 2003New possibility to attribute values to questions upon initial call fo CallWeb.
December 10, 2003Major upgrade to accommodate guidelines for the preparation of pages for the visually impaired (W3C); addition of the _access switch.
December 4, 2003cwPrepop can insert data into existing cases from a tab-delimited file.
December 2, 2003Possibility to calculate the thermometer from a question other than the first question.
November 28, 2003cwNav links into the questionnaire utility.
November 27, 2003cwNav allows the edition of data en masse, several records and several variables at a time.
November 25, 2003The CallWeb questionnaire pages includes only key information on the session; the complete data vector is not carried over from page to page anymore.
November 24, 2003Addition of the capacity to insert standardized formatted tables in any string.
November 23, 2003Addition of the capacity to transpose questions and answers in question tables (i.e., questions as columns).
November 21, 2003Addition of the capacity to reinitialize records to their initial state after prepopulation (assuming proper use of NEVERUPDATE questions).
November 19, 2003Addition of a default back-up strategy for all projects without specific archival settings.
November 16, 2003Addition of a validation condition (MUST) based on any data in the questionnaire, including in the current screen.
November 15, 2003Addition of an option to display question names during a real or simulated interview, including the production of a complete questionnaire printout.
November 12, 2003Implementation of the cwArchive system to perform timed back-ups.
November 8, 2003The thermometer is now calculated using the last question of a screen rather than the first.
November 7, 2003Display conditions can be borrowed from other questions using the "=" operator.
November 5, 2003Possibility to flag individual response categories using a behaviour code (P).
October 25, 2003Addition of an option to not hyperlink the data tables from cwfreq to cwnav.
October 25, 2003Addition of a parameter for the error message displayed upon supplying an incorrect access code.
October 22, 2003Clicking the language button preserves the answers already provided on a page.
October 21, 2003Ability to save responses provided before going backwards using the CallWeb back button (not the browser button).
October 18, 2003Alternating colours of matrix rows.
October 15, 2003Access code pattern can be pre-determined.
October 10, 2003Frequency distributions and two-way tables can be output to a CSV or a tab-delimited format.
October 7, 2003In the CATI version, the number of dossiers available per stratum can be set to a maximum.
October 7, 2003Addition of ability to borrow question and note text from another question.
October 5, 2003Separation of the NOTE text from the question text.
September 28, 2003Customized access code request screen.
September 11, 2003Extractions may be left on the server instead of being sent by e-mail.
September 9, 2003Addition of the telephone number open-end type.
September 8, 2003Addition of the ability to edit only selected variables in cwNav.
September 7, 2003Addition of the ability to select or deselect (for deletion) all displayed cases in cwNav.
September 5, 2003Addition of a open-end type for the first three digits of a Canadian postal code.
August 29, 2003In extracting data, it is possible to subset cases as well as select data and code file types.
August 25, 2003Addition of tool to generate URLs to complex utility requests.
August 25, 2003Addition of a checkbox view for question selection in cwnav and cwfreq.
August 20, 2003Substantial acceleration (and increased sturdiness) of the compilation process when structural changes are required.
August 16, 2003Possible suppression of the SUBSTITUT style in response recall.
August 10, 2003Addition of descriptive statistics in two-way tables (cwfreq).
August 8, 2003Addition of a method to enter a questionnaire elsewhere than at the first question.
August 8, 2003Support for an external library of Perl functions in cwplugins.pl.
August 5, 2003Permutations can be set to display a limited number of randomly chosen questions.
July 30, 2003Permutations can now include all questions on a page.
July 28, 2003Improvements to the validation of display conditions during compilation.
July 25, 2003Solidification of the compilation process to eliminate risks of data corruption.
July 17, 2003Addition of interview type 6.
June 21, 2003Addition of the U behaviour code to make all text in an alphanumeric open part upper case.
June 13, 2003Addition of SUBSET feature to select answer categories using a few characters in the category label.
June 12, 2003Addition of the Forced category behaviour.
June 11, 2003Addition of ability to borrow response categories from another question.
June 5, 2003Addition of the "Changement de langue" pound-option.
May 24, 2003Addition of levels of parentheses in selection menus used in utility programs.
May 23, 2003Users can now use the browser back button without data loss. The CallWeb Back button has become optional (defaulting to no-show) via the # Affiche retour arriere option.
May 21, 2003Addition of a case-level lock to prevent two people from modifying the same information.
May 20, 2003Addition of the "O" category behaviour code (optional open-end parts).
May 20, 2003Addition of an Hour question type with validation within a time range.
May 3, 2003Addition of a Date question type with validation within a date range.
April 19, 2003cwNav can display answer labels in addition to or in replacement of answer codes.
April 18, 2003Addition of a question type to render data unchangeable from within CallWeb (except by prepopulation).
April 17, 2003Addition of a question type that restricts back-tracking in a questionnaire..
April 17, 2003Addition of the capacity to e-mail from within a CallWeb script.
April 12, 2003Addition of the capacity to test questionnaires without affecting permanent files.
April 11, 2003New module to destroy data bases.
April 7, 2003Ability to colour columns of question tables differently.
April 6, 2003New module to handle invitation and reminder e-mails.
April 4, 2003Addition of recalls (piping) of responses to questions allowing multiple selections.
March 31, 2003The compiler detects and reports dangerous structural differences between the untransported data table and the questionnaire.
March 27, 2003Addition of the "~" prefix to create non-cleaning skips.
March 26, 2003Revamping of cw which is now an integrated front-end for all CallWeb functions.
March 20, 2003Addition of the ability to destroy data bases using cwdestruction.
March 19, 2003Addition of the capacity to structure tables using more than one variable in the columns (horizontally joined tables).
March 18, 2003Addition of the quota management system.
March 10, 2003Addition of the CULDESAC question type.
March 9, 2003Migration of data storage to a MySQL data base.
March 3, 2003Addition of the capacity to lay out response categories over several columns, globally or question by question.
March 2, 2003Addition of the _print command line parameter for the callweb module to display the entire questionnaire in a form fit for printing yet similar to the experience provided to the survey respondent.

   

Appendix E

Formatted tabular output syntax

In CallWeb, virtually any character string to be displayed on screen can be formatted as a table using the colours defined for the questionnaire (see Colours and layout) using a standardized tool. This simplifies the creation of tabular layouts and ensures consistency of look throughout the questionnaire. Of course, existing recall protocols can be used within these formatted tables.

To insert a table into a string (the question text segment, for example), surround the table instructions with double braces, i.e. {{ and }}. Within these delimiters, insert the text to be displayed as a table and the special instructions described below (the following table was created using this feature).

CommandAction
{>}Moves over to the next cell.
{<}Moves over to the next line (see it as a carriage return).
{SC}Formats the cell as a column heading (the text is centered in the cell by defaut and the .COLONNE style is applied). To change the justification, add the appropriate justification instruction (see below).
{SL}Formats the cell as a row heading (the text is left-justified in the cell by defaut and the .LIGNE style is applied). To change the justification, add the appropriate justification instruction (see below).
{SS}Formats the cell as a SPECIAL value (see the definition of question tables).
{C}Centers the text in the cell.
{L}Left-justifies the text in the cell.
{R}Right-justifies the text in the cell.
{T}Locates the text at the top of the cell.
{B}Locates the text at the bottom of the cell.
{M}Locates the text in the middle of the cell.
{E}Formats the text with the ERREUR style.
{NW}Avoids text wrapping within the cell.
{number}Spans the content of the cell over "number" columns; if "number" is 0, the cell spans the entire table; if it is negative, it spans over the number of columns in the table minus "number".
{Rnumber}Spans the content of the cell over "number" rows. Rows affected by a rowspan cannot include negative colspan values.
{TC}In the first cell of the table, centers the table horizontally in the page.

The table above was created with the following instructions.

    {{
    {SC}Command{>}{SC}Action{<}
    {>}{>}Moves over to the next cell.{<}
    {<}{>}Moves over to the next line (see it as a carriage return).{<}
    {SC}{>}Formats the cell as a column heading (the text is centered in the cell by defaut and the .COLONNE style is applied). To change the justification, add the appropriate justification instruction (see below).{<}
    {SL}{>}Formats the cell as a row heading (the text is left-justified in the cell by defaut and the .LIGNE style is applied). To change the justification, add the appropriate justification instruction (see below).{<}
    {SS}{>}Formats the cell as a SPECIAL value (see the definition of question tables.{<}
    {C}{>}Centers the text in the cell.{<}
    {L}{>}Left-justifies the text in the cell.{<}
    {R}{>}Right-justifies the text in the cell.{<}
    {T}{>}Locates the text at the top of the cell.{<}
    {B}{>}Locates the text at the bottom of the cell.{<}
    {M}{>}Locates the text in the middle of the cell.{<}
    {E}{>}Affiche le texte avec le style ERREUR.{<} {NW}{>}Avoids text wrapping within the cell.{<}
    {number}{>}Spans the content of the cell over "number" columns; if "number" is 0, the cell spans the entire table; if it is negative, it spans over the number of columns in the table minus "number".{<}
    {Rnumber}{>}Spans the content of the cell over "number" rows. Rows affected by a rowspan cannot include negative colspan values{<}
    {TC}{>}In the first cell of the table, centers the table horizontally in the page.{<}
    }}

   

Annexe F

Security Features

CallWeb incorporates several layers of security features. They are reviewed in this section.

FeaturesExplanation
Minimum direct availability
Erasing .scw filesQuestionnaire script files are openly readable txt files. In that sense and because they temporarily reside in the project directory, they represent a security risk: someone getting a hold of the file would know about the nature of the project. It is good practice to delete, rename or move the .scw files once they have been compiled. The compiled .qcw questionnaire is not in a readable format.
No access to MySQLIn principle, the MySQL server should not serve connections from outside the local computer. This way, only local users with MySQL accounts can access CallWeb data.
No data in HTML pagesCallWeb transmits no questionnaire data within its HTML pages — only a case number and an encoded version of the case number along with the numeric answers provided on the current page. Even if questionnaire pages were intercepted, no personal data would be communicated.
No project directory in URLsThe location of the project directory is not revealed by the URL used to fill out the questionnaire. This way, hackers cannot determine which directory could be the target of their attacks.
Access control
Questionnaire accessAccess to complete a questionnaire can be password-protected such that only those issued a password can provide data and they can answer only once.
Passwords for utilitiesAccess to project data by utility programs can be password protected. Three levels of passwords are available: to access the utility directory (managed by Apache), to read the data and to modify the data.
Utility directoriesThe master utility directory typically contains all of the available utility programs. Other utility directories can be created with a subset of programs to limit what some individuals can do or which data they can access. A pound instructions also exists (# Visible from) to specify which utility directory (other than the master directory) can have access to a given project. This way, the CallWeb administrator can contain access to data by function and by data set.
Data integrity
Lossless page navigationQuestionnaire respondents cannot lose data: whether they proceed forward with the questionnaire, backtrack using the CallWeb button or the browser button, change language part-way through or even close the browser session altogether, data is always secured up to that moment — to the extent that it has been transmitted to the server, obviously.
Lossless structural modificationsAny structural modification can be implemented part-way through data collection: addition of questions, deletion of questions, modifications to skip patterns, moving questions, adding open-end parts, etc. No data will be lost in the process (except if one deletes a question containing data, obviously).
Tab-delimited back-upsCallWeb offers a tool to back up data to a tab-delimited file which can easily be used to repopulate a project in the event of a catastrophe. Back-ups can be performed up to once an hour. They can be left in the project directory or e-mailed (a more secure option since no data is left in the project directory).
Encoded case numberWhen an HTML response page is sent to the server, the corresponding CallWeb case number is sent along to tell the system which data record to update. An encoded version of that case number is also sent so that a hacker could not modify the case number and update someone else's record. If this were attempted, the lack of correspondence between the case number and its encoded version would interrupt the system.

   

Appendix G

Context data

CallWeb stores the following context data in the %contexte hash, referenced as $contexte{key} in Perl expressions.

Key (case sensitive)Data
dategmtcurrent date (YYYYMMDD format), gmt based
dateheuregmtcurrent date and time (YYYYMMDDHHMMSS format), GMT based
dateheureqdate and time of the last update of the questionnaire file (YYYYMMDDHHMMSS format)
dateheuretextecurrent date and time (text format), server based
dateheurecurrent date and time (YYYYMMDDHHMMSS format), server based
dateqlanguedate of the last update of the questionnaire file (readable format)
dateqdate of the last update of the questionnaire file (YYYYMMDD format)
datetextecurrent date (text format), server based
dateunixgmtcurrent date and time in Unix format (seconds since January 1, 1970), GMT based
dateunixcurrent date and time in Unix format (seconds since January 1, 1970), server based
datecurrent date (YYYYMMDD format), server based
directoryname of the directory from which CallWeb is running
heuregmtcurrent time (HHMMSS format), gmt based
heurecurrent time (HHMMSS format), server based
hostname of the server
interviewerinterviewer name
ipIP address of the client computer
javascriptwhether JavaScript is available in the browser (1 = yes); valid starting at the second page of the questionnaire
jourday of the week (0 = Sunday)
mobileis it a mobile device (1 = yes)
navigateurbrowser name
password
encrypted case password in Password mode
projetCallWeb project name
questionname of a question that was displayed on the page (available only once at least one question has been added on the page)
scriptname of the calling script (includes the relative path to the server)
sessionunique session ID produced by the Web server
sourcereferrer page (URL of the page from which the current page was called)

   

Appendix H

TEST pound instruction

The TEST pound instruction defines a logical test which triggers an error message. This generic statement comes in addition to CallWeb built-in tests such as tests on the minimum and maximum number of responses, on the coherence of the selection of answers, on MUST conditions, on table conditions, etc.

Syntax:

    # Test ID = [TRIGGER]trigger [CONDITION]condition [MESSAGE]message [TYPE]type
    or
    # Test ID = [SUR]sur [CONDITION]condition [MESSAGE]message [TYPE]type

Where

ComponentDescription
IDis any character string identifying the test. It is used within the <TEST> tag if the test has a "tag" [TYPE] (see below)
triggeris the name of the question which triggers the test. The test is triggered when an answer to this question is found in a page sent to CallWeb. The question should be one that always appears on screen and that requires an answer to ensure that the test takes place.
conditionis a logical condition describing an error. It can be in xbase syntax (in which case it will be tested during compilation) or in Perl syntax if within braces.
messageis the text of the message to insert if the condition is true (i.e., if there is an error). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes. Recalled values may be used in the message.
typespecifies the type of error message and where to put it on the CallWeb page:
  • [TYPE]QUESTION puts the message where a system message would be if question "trigger" was faulty (above it outside of a table; on the right within a table)
  • [TYPE]TABLE or [TYPE]TABLEAU puts the message before the table to which the "trigger" question belongs
  • [TYPE]TAG puts the message where the <TEST>ID</TEST> mark is located on the page (there must be no spaces from the beginning to the end of this TEST string); this may be anywhere, such as in a response category label (which would show at the top of a column in a table) or in a NOTE field (which would show in the left column in a table)

Any given question may trigger more than one test.

Examples:

    # Test ABC =
    #> [TRIGGER]AQ1
    #> [CONDITION](AQ1+AQ2+AQ3).NE.100
    #> [MESSAGE][EN]Please make these total 100[FR]Veuillez vous assurer que ces valeurs totalisent 100
    #> [TYPE]table

This will display the error message above the table to which AQ1 belongs if the 3 responses don't total 100.

    # Test DEF =
    #> [TRIGGER]Q10
    #> [CONDITION]Q5.AND.Q6.AND.Q7.AND.(.NOT.Q8.AND.NOT.Q9)
    #> [MESSAGE][EN]Please answer Q8 or Q9 since you have answered Q5, Q6 and Q7[FR]Veuillez répondre à Q8 ou Q9 puisque vous avez répondu à Q5, Q6 et Q7
    #> [TYPE]question

This will display the error message above Q10 if Q5, Q6 and Q7 were answered while Q8 and Q9 were not. Note that questions Q5 to Q9 need not be on the same CallWeb page as Q10.

   

Appendix I

System messages

The "System message" pound instruction redefines a system message for a particular questionnaire.

Syntax:

    # System message ID = [EN]English message[FR]French message...

At the time of this writing, there were 38 system messages, available in five languages: English, French, Spanish, German and Portuguese. Another language could be added by re-defining each of the system messages and using the proper ISO-language code between brackets. The table below lists the English and French versions of the messages and associates with each its numeric ID which is used in calling "# System message".

Some messages incorporate variable information such as the minimum or maximum number of responses, or the minimum or maximum allowable value, or the mark of a plural. These are indicated in the messages using a ranking number between brackets. Make sure to not omit them in re-designed messages and to place them in the correct place for the language of your choosing. Use the French of English versions below as indications of the type of information represented by these replacement marks.

IDEnglishFrench
1 and et
2<BIG>The questionnaire number (#[0]) was corrupted during the transmission of the page.<P>Please go back one page with the browser arrows and resume the questionnaire.</BIG><BR><BIG>Le numéro de questionnaire (#[0]) a subi une corruption lors de la transmission de la page.<P>Veuillez revenir en arrière d'une page avec les flèches du navigateur et reprendre le questionnaire.</BIG><BR>
3This questionnaire is already completed. Thank you for your cooperation.Ce questionnaire est déjà complété. Merci de votre collaboration.
4Only whole numbers are accepted here. Please do not use decimals or commas.Seuls les nombres entiers sont acceptés ici. Veuillez ne pas utiliser de points ou virgules décimaux.
5Please choose a value between [0] and [1].Veuillez choisir une valeur entre [0] et [1].
6The information supplied does not resemble an e-mail address.L'information fournie ne ressemble pas à une adresse de courriel.
7The information supplied does not resemble a Web address.L'information fournie ne ressemble pas à une adresse de site Web.
8The information supplied does not resemble an IP address (e.g., 192.168.1.1).L'information fournie ne ressemble pas à une adresse IP (p.ex., 192.168.1.1).
9The information supplied does not resemble a telephone number.L'information fournie ne ressemble pas à un numéro de téléphone.
10The information supplied does not resemble a Canadian postal code.L'information fournie ne ressemble pas à un code postal canadien.
11The information supplied does not resemble the first three characters of a Canadian postal code.L'information fournie ne ressemble pas aux trois premiers caractères d'un code postal canadien.
12The information supplied does not resemble the expected pattern.L'information fournie ne ressemble pas au patron attendu.
13The information supplied does not appear to be a valid date. Please use the YYYYMMDD format (as in [0]).L'information fournie ne semble pas être une date valide. Veuillez utiliser le format AAAAMMJJ (comme [0]).
14Please choose a value between [0] and [1].Veuillez choisir une valeur entre [0] et [1].
15The information supplied does not appear to be a valid time. Please use the HHMM format.L'information fournie ne semble pas être une heure valide. Veuillez utiliser le format HHMM.
16Sorry. The following table demands that you select at least [0] and at most [1] different and consecutive responses.Désolé. Le tableau suivant exige que vous sélectionniez au moins [0] et au plus [1] réponses différentes et consécutives.
17Sorry. The following table demands that you select at least [0] and at most [1] different responses.Désolé. Le tableau suivant exige que vous sélectionniez au moins [0] et au plus [1] réponses différentes.
18Please provide [0] answer[1] to this question.Veuillez fournir [0] réponse[1] à cette question.
19Please provide at least [0] and at most [1] answer[2] to this question.Veuillez fournir au moins [0] et au plus [1] réponse[2] à cette question.
20Sorry. The response "[0]" cannot be chosen at the same time as another response.Désolé. La réponse « [0] » ne peut pas être choisie en même temps qu'une autre réponse.
21Please complete the answer that you have selected.Veuillez compléter la réponse que vous avez choisie.
22Please click the selection that corresponds to your answer or erase the text supplied.Veuillez cliquer sur la sélection qui correspond à votre réponse ou effacer le texte fourni.
23Please enter a value.Veuillez fournir une valeur.
24Please provide a response to this question.Veuillez fournir une réponse à cette question.
25Please provide [0] answer[1] to this question.Veuillez fournir [0] réponse[1] à cette question.
26Please provide at least [0] and at most [1] answer[2] to this question.Veuillez fournir au moins [0] et au plus [1] réponse[2] à cette question.
27Please complete your answer.Veuillez compléter votre réponse.
28Sorry. Access to this questionnaire was denied.Désolé. L'accès à ce questionnaire a été refusé.
29There is no open end part to display.Il n'y a aucune partie ouverte à afficher.
30This choice has already been selected. Please make another selection..Ce choix a déjà été sélectionné. Veuillez faire une autre sélection.
31Please confirm the value [0] which was entered; it is outside of expected limits.Veuillez confirmer la valeur [0] qui a été saisie; elle dépasse les limites prévues.
32You cannot access this questionnaire more than once.Vous ne pouvez pas accéder à ce questionnaire plus d'une fois.
33Please limit your answer to [0] characters (currently [1]).Veuillez limiter votre réponse à [0] caractères (présentement [1]).
34<img src="$_ressourcesdir/erreur_page.gif" align="absmiddle" alt="!" title="!" style="border-style: none" />&nbsp;The system is presently busy. Please try again in a few seconds.<img src="$_ressourcesdir/erreur_page.gif" align="absmiddle" alt="!" title="!" style="border-style: none" />&nbsp;Le système est présentement occupé. Veuillez essayer à nouveau dans quelques secondes.
35The uploaded file is too large (limit of [0] bytes).Le fichier téléchargé est trop gros (limite de [0] octets).
36The uploaded file is too small (limit of [0] bytes).Le fichier téléchargé est trop petit (limite de [0] octets).
37Uploading a file of this type is not allowed.Le téléversement de ce type de fichier n'est pas permis.
38The system was unable to save this file.Le système n'a pas pu sauvegarder ce fichier.
39You must supply the same new password twice.Vous devez saisir deux fois le même nouveau mot de passe.
40You must supply a new password twice in the boxes below.Vous devez saisir un nouveau mot de passe deux fois dans les boîtes ci-bas.
41This message will not be displayed again for this question.Ce message ne sera pas affiché de nouveau pour cette question.
42
This value includes non-numeric characters.Cette valeur inclut des caractères non numériques.

   

Appendix J

System variables

In utility modules like cwfreq and cwnav, all lists of variables, questions and fields begin with a series of entries which start with an underscore (e.g., _telkey, _date); they are system variables which are available in every CallWeb project. The meaning of these system variables is explained in the following table.

System variableMeaning
_telkey Unique identifier of the case; this is the case "number". It can contain up to 64 characters, including only letters and numbers.
_proj Name of the project to which each case is associated.
_demo Binary flag (0|1) indicating whether a case was opened in demo mode. Obsolete.
_lang Language in which the most recent displayed page was shown. This is a two-letter code.
_typeint Type of interview. See the Survey type pound instruction
_cetordre List of questions in the questionnaire, ordered for this case based on PERMUTATIONs. This list is created when the case is first accessed. It is deleted if the questionnaire is re-compiled with a structural change.
_cedossier Encoded value of the _telkey. It ensures that the _telkey information stored in the HTML page has not been tempered with.
_cetecran Name of the question most recently displayed. For multi-question pages, it is the name of the first question on the page.
_h1 String of date-time values documenting each time the questionnaire was initially opened in the callweb module. The system variables _date and _hour are derived from _h1.
_h2 String documenting the cumulative duration of each session in the callweb module. It is expressed in seconds. The system variables _seconds and _minutes are derived from _h2.
_h3 String of date-time values documenting each time the case was modified in cwnav.
_prepops String of date-time values documenting each time the case was affected by a prepopulation operation. The system variable _lastprepop is derived from _prepops.
_verrou Date-time value indicating when a lock was last taken on the case. This works in tandem with the Seconds locked pound instruction.
_telephone Prepopulated telephone number, for CATI purposes.
_gmtoffset Time zone of the prepopulated telephone number, expressed in hours from Greenwich.
_cetappel Data structure documenting each call made in CATI mode.
_stock Date structure containing a variety of information on the case such as the permutation order for response categories.
_dernierprepop _lastprepopMost recent prepopulation date-time. See _prepops above.
_date Date of the most recent access to the case. See _h1.
_week _semaine
Date of the most recent access to the case expressed as a week date. See _date and the week_start installation option.
_heure _hourHour of the most recent access to the case. See _h1.
_minutes Total duration, in minutes, of all accesses to the case. See _h2 above.
_secondes _secondsTotal duration, in seconds, of all accesses to the case. See _h2 above.
_nappels _ncallsNumber of calls documented in the CATI call history. See _cetappel above.
_res Call result code of the most recent CATI call. See _cetappel above.
_dateappel _calldateDate of the most recent CATI call. See _cetappel above.
_heureappel _callhourHour of the most recent CATI call. See _cetappel above.
_tempsappel _calltimeDate-time of the most recent CATI call formatted as YYYYMMDDHHMMSS. See _cetappel above.
_interviewer Name of the interviewer who registered the most recent CATI call result. See _cetappel above.
_daterv _appdateDate of the appointment set on the most recent CATI call. See _cetappel above.
_heurerv _apphourHour of the appointment set on the most recent CATI call. See _cetappel above.
_commentaires _commentsComments left by the interviewer on the most recent CATI call. See _cetappel above.

   

Appendix K

Weights (deprecated)

A WEIGHT question calculates a weighting scheme based on the known marginal distribution of some variables, using the rim weighting algorithm initially proposed by Deming and Stephan (W. Edwards Deming and Frederick F. Stephan, "On a Least Squares Adjustment of a Sampled Frequency Table When the Expected Marginal Totals are Known", The Annals of Mathematical Statistics, volume 11, number 4, December 1940, pp. 427-444). This weighting scheme is stored in the open-end part of the WEIGHT variable; it can be extracted or used in cwfreq to create weighted frequency tables.

Weighting instructions are placed in the question text segment of the question. Each weighting question is listed followed by the weight for each value of the question separated by slashes and ordered according to the numerical list of categories. Questions are separated by commas. Here is an example of the syntax:

QWEIGHT WEIGHT
%
QSEX=0.5/0.5/0
QLANGUAGE = 0.80 / 0.08 / 0.12 / 0 / 0

Weight calculation supports the following (cwnav) options:

  • the calculation can be "prudent" which means that all cases with missing data (e.g., "don't-know" category which get a weight of zero) on any variable get a weight of 1; it can also use "maximum information" which means that cases with partial missing data are assigned a weight based on the available data;
  • the number of iterations performed can be set by the user (default 10). As a result of the calculation, the root mean square value of the difference between the target numbers and the weighted numbers is displayed at each iteration of weighting. Ideally, this value should approach 0.01 for effective weights.
  • the calculation can be limited to a subset of cases using the case selection tools available in all utility programs.

The following rules are enforced:

  • WEIGHT variables must have an open-end part;
  • all questions referenced in the WEIGHT definition must exist;
  • all weights for one question must total 1;
  • all weights must be expressed using a decimal point rather than a comma;
  • there must be one weight for each defined value of the variable; some weights can be set to zero (e.g., "don't-know" category).

Weights are calculated in cwnav by selecting from the WEIGHT variable list shown after the write-access password is entered.

Weights are used in cwfreq by selecting from the WEIGHT variable list offered.

   

Appendix L

Basic HTML tags

TypeTagResult
Paragraph<p>Blabla</p>Blabla
Paragraph with a style definition<p class="ERREUR">Blabla</p>Blabla
Any text with a style definition<span class="ERREUR">Blabla</span>Blabla
Line breakLine1<br />Line2Line1
Line2
Hyperlink<a href="http://callweb.ca">text</a>text
Hyperlink in a new window/tab<a href="http://callweb.ca" target="_blank">text</a>text
Bullet list<ul><li>first bullet</li><li>second bullet</li></ul>
  • first bullet
  • second bullet
Numbered list<ol><li>first bullet</li><li>second bullet</li></ol>
  1. first bullet
  2. second bullet
Horizontal rule<hr />
Image insert<img src="../images/list-arrow.gif" />
Abbreviation<abbr title="Great CAWI/CATI/CAPI product!">CallWeb</abbr>CallWeb

HTML colours

In HTML, colours are defined using RGB (red, green and blue) codes. RGB codes are made up of three pairs of hexadecimal (from 0 to F) characters, followed a pound sign (which is unrelated to CallWeb's pound instructions). Each pair of hexadecimal characters indicates the amount of each base colour (red, green and blue) in the specific colour combination. For example, #FFFFFF is white because it includes a maximum of each of red, green and blue colours; #000000 is black because there is none of any of the colours.

There are many useful on-line tools to help with colour selection. ColorPicker, the Febooti on-line colour chart and the Doughnut Color Picker return colour codes for millions of colours using a familiar interface. Other tools like ColorScheme Designer, Color Palette Creator and kuler help select colour schemes. Finally, pixie (Windows executable) and Colorzilla (Firefox extension) identify colours that the mouse points to on screen.

Basic HTML codes

Block 1Block 2Block 3
CharacterNumeric codeHTML equivalentCharacterNumeric codeHTML equivalentCharacterNumeric codeHTML equivalent
&#32; g&#103; Ï&#207;&Iuml;
!&#33; h&#104; Ð&#208;&ETH;
"&#34;&quot;i&#105; Ñ&#209;&Ntilde;
#&#35; j&#106; Ò&#210;&Ograve;
$&#36; k&#107; Ó&#211;&Oacute;
%&#37; l&#108; Ô&#212;&Ocirc;
&&#38;&amp;m&#109; Õ&#213;&Otilde;
'&#39; n&#110; Ö&#214;&Ouml;
(&#40; o&#111; ×&#215;&times;
)&#41; p&#112; Ø&#216;&Oslash;
*&#42; q&#113; Ù&#217;&Ugrave;
+&#43; r&#114; Ú&#218;&Uacute;
,&#44; s&#115; Û&#219;&Ucirc;
-&#45; t&#116; Ü&#220;&Uuml;
.&#46; u&#117; Ý&#221;&Yacute;
/&#47; v&#118; Þ&#222;&THORN;
0&#48; w&#119; ß&#223;&szlig;
1&#49; x&#120; à&#224;&agrave;
2&#50; y&#121; á&#225;&aacute;
3&#51; z&#122; â&#226;&acirc;
4&#52; {&#123; ã&#227;&atilde;
5&#53; |&#124; ä&#228;&auml;
6&#54; }&#125; å&#229;&aring;
7&#55; ~&#126; æ&#230;&aelig;
8&#56;  &#160;&nbsp;ç&#231;&ccedil;
9&#57; ¡&#161;&iexcl;è&#232;&egrave;
:&#58; ¢&#162;&cent;é&#233;&eacute;
;&#59; £&#163;&pound;ê&#234;&ecirc;
<&#60;&lt;¤&#164;&curren;ë&#235;&euml;
=&#61; ¥&#165;&yen;ì&#236;&igrave;
>&#62;&gt;¦&#166;&brvbar;í&#237;&iacute;
?&#63; §&#167;&sect;î&#238;&icirc;
@&#64; ¨&#168;&uml;ï&#239;&iuml;
A&#65; ©&#169;&copy;ð&#240;&eth;
B&#66; ª&#170;&ordf;ñ&#241;&ntilde;
C&#67; «&#171;&laquo;ò&#242;&ograve;
D&#68; ¬&#172;&not;ó&#243;&oacute;
E&#69; ­&#173;&shy;ô&#244;&ocirc;
F&#70; ®&#174;&reg;õ&#245;&otilde;
G&#71; ¯&#175;&macr;ö&#246;&ouml;
H&#72; °&#176;&deg;÷&#247;&divide;
I&#73; ±&#177;&plusmn;ø&#248;&oslash;
J&#74; ²&#178;&sup2;ù&#249;&ugrave;
K&#75; ³&#179;&sup3;ú&#250;&uacute;
L&#76; ´&#180;&acute;û&#251;&ucirc;
M&#77; µ&#181;&micro;ü&#252;&uuml;
N&#78; &#182;&para;ý&#253;&yacute;
O&#79; ·&#183;&middot;þ&#254;&thorn;
P&#80; ¸&#184;&cedil;ÿ&#255;&yuml;
Q&#81; ¹&#185;&sup1;Œ&#338; 
R&#82; º&#186;&ordm;œ&#339; 
S&#83; »&#187;&raquo;Š&#352; 
T&#84; ¼&#188;&frac14;š&#353; 
U&#85; ½&#189;&frac12;Ÿ&#376; 
V&#86; ¾&#190;&frac34;ƒ&#402; 
W&#87; ¿&#191;&iquest;&#8211; 
X&#88; À&#192;&Agrave;&#8212; 
Y&#89; Á&#193;&Aacute;&#8216; 
Z&#90; Â&#194;&Acirc;&#8217; 
[&#91; Ã&#195;&Atilde;&#8218; 
\&#92; Ä&#196;&Auml;&#8220; 
]&#93; Å&#197;&Aring;&#8221; 
^&#94; Æ&#198;&AElig;&#8222; 
_&#95; Ç&#199;&Ccedil;&#8224; 
`&#96; È&#200;&Egrave;&#8225; 
a&#97; É&#201;&Eacute;&#8226; 
b&#98; Ê&#202;&Ecirc;&#8230; 
c&#99; Ë&#203;&Euml;&#8240; 
d&#100; Ì&#204;&Igrave;&#8364;&euro;
e&#101; Í&#205;&Iacute;&#8482; 
f&#102; Î&#206;&Icirc;   

   

Appendix M

Project initiation checklist

The following checklist is offered as a guide to control that all steps of the project installation process have been completed. A CATI-specific project initiation checklist is also available.

1

         

Use the project flow diagram to guide project initiation.
2

         

Create a directory. Its name should start with "cw" (lower case) for CallWeb to recognize it as a project directory. Note that, under Linux, capitalization counts, such that file or directory "cwProject" is different from file or directory "cwproject".
3

         

The Apache Web server must have permission to write in this new directory. If the directory was created using CallWeb's file manager (cwdocs), it is automatically so. Otherwise, either make the Apache user the owner of the directory or give "the world" write permission to the directory.
4

         

Place a questionnaire script file (.scw file) in the project directory. This could be a copy of an existing questionnaire.
5

         

If necessary, place a style.css file in the project directory to control the appearance of the questionnaire. Without one, the default style.css file from the gr/ directory is used.
6

         

Modify the questionnaire according to your specifications, either in cwedit or in a text editor such as gedit, TextPad or UltraEdit. If you modify the questionnaire in a text editor, use the file manager (cwdocs) or a communication program (such as gftp, ws_ftp or Directory Opus) to upload the .scw file to the server.
7

         

Compile the questionnaire from cwedit or from the integrated module (cw) and correct any error that may be flagged.
8

         

Throughout the programming of the questionnaire, keep a second browser window open to fill out and test the questionnaire as you add questions and otherwise modify the questionnaire.
9

         

Repeat steps 6, 7 and 8 until you have finished the programming of the questionnaire.
10

         

If you want to insert data in the project database (e.g., to create access codes and/or to make data available during questionnaire completion), package the data in a tab-delimited file where field names are on the first line. Upload that file (using the file manager or a communication program) and import the data using the cwprepop module.
11

         

Ensure that the "survey type" pound instruction corresponds to your questionnaire access control needs.
12

         

Build a URL to access the questionnaire as a respondent.
13

         

Send e-mail invitations.

   

Appendix N

File types

A CallWeb project directory often contains a series of files that testify to the unfolding of the project. Here is a list of files that can be found in project directories.

NameDescription
project.scwQuestionnaire script file in text format.
project.qcwCompiled and verified version of the questionnaire used by callweb.cgi and cwx.cgi.
project.scw.lastproject.scw corresponding to the current project.qcw, that is, the project.scw that was last compiled successfully.
project_cwcompile_datetime.zipAssortment of project files as they existed when the compilation was performed at datetime; this file includes a dump of the actual data if the compilation required a change to the structure of the data base.
project.change.logLog of changes made to the structure of the CallWeb data base.
project_cwarchive_h_datetime.zipArchival copy of the data created by cwarchives.pl based on the hourly schedule.
project_cwarchive_d_datetime.zipArchival copy of the data created by cwarchives.pl based on the daily schedule.
project_cwextr_datetime.zipInformation extracted by cwextr at datetime if the request included leaving the extraction in the project directory.
project.cwedit.lockLock file left by cwedit.
project.ipaddress.debugIf this file is present, questionnaire pages requested by ipaddress include debug information.
project-datetime-datetime-number.catiCATI: call queue management parameters for project.
project.actuhistoCATI: history of call queue management results for project.
project.ccwCATI: CATI code behaviour features specific to the project.
style.cssCascading style sheet file controlling the appearance of the questionnaire.

   

e-mail technical support!