Tracking configuration

<accesscontrol>Main:MyGroup</accesscontrol>

Introduction

Version

This documentation is updated in February 2009 for Catglobe version 5.6. Catglobe menus and commands are in English.

Automated tracking

Catglobe offers a suite of best practices CG Scripts, which partners will be provided with upon request. Automated tracking is one of these scripts. The automated tracking CG script serves two main purposes:

• Automatically sending the optimal number of emails in order to reach the weekly target.
• Automatically direct the outgoing emails to specific target groups according to demands and continuously adjusted in accordance with the response.

Additionally, the system can be configured to send reminder emails to panelists who have not completed the survey within a certain time limit, if their quota is not closed.

Prerequisites

It is assumed that the reader is familiar with the general concepts of the Catglobe system, such as users, groups, rules, access rights, questionnaires, samples and quotas. Additionally, basic understanding of CG Script is required. This level of knowledge should be achieved with a Catglobe Data course I and II and some experience.

Requirements and limitations

The tracking should continue in one questionnaire for a certain (preferably long) period of time.

The tracking quotas used for targeting certain target groups must be based on weeks, must be labeled according to certain rules, and categorized into a maximum of 3 categories (see description below and appendix 2 - quotas).

The respondents must be existing users in the Catglobe system, and must be part of an existing panel with a questionnaire keeping information necessary for stratification (i.e. gender and age).

Group rules must be according to description in this document.

No guarantee is given regarding the scripts. Please contact Catglobe if any trouble is experienced. Functions included in the scripts are valid for the stated version of Catglobe.

Preparing the CG Ssript for a project

The main parts of the script

The script consists of two main parts, as shown in the image below; part 1, which must be modified according to project specifications, and part 2, which is a standard script that should not be modified. (some declarations)

//=======================================================
//PROJECT SPECIFIC CONSTANTS - BELOW THIS LINE ONLY =====
//=======================================================
(part 1 - project specifications)
//=======================================================
//PROJECT SPECIFIC CONSTANTS - ABOVE THIS LINE ONLY =====
//=======================================================
(part 2 - standard script)

In part 1 of the script, the following information must be filled in:

STEP 1. Choose test mode (test = true) or real mode (test = false)
STEP 2. Add receipients for status email
STEP 3. Specify a factor for each day of the week (no mails = 0)
STEP 4. Keep quota time frames up-to-date
STEP 5. Categorize quotas (type 1-3) and specify quota labels
STEP 6. Specify rule id's for rules in group used by Bulk Mail
STEP 7. Specify rule lables (for the same rules)
STEP 8. Specify Bulk Mail id
STEP 9. Specify RPQ id for a dummy user in the questionnaire
SCRIPT EXTENSION FOR REMINDERS ------------------------------------
STEP R1. Choose if reminders should be sent (Additional groups required)
STEP R2. (if reminders) Specify reminder delay days (max 7 days)
STEP R3. (if reminders) Reminder day groups
STEP R4. (if reminders) Reminder Temporary group id
STEP R5. (if reminders) Specify rule id's for rules in group used by BulkMail
STEP R6. (if reminders) Reminder bulkmail-id

Step 1. Test mode or real mode

Use test mode (test = true) to test the script without actually rebuilding the group or sending any emails. Set test = false for real mode when the script has been tested.

Example:

//STEP 1. Choose test mode (test = true) or real mode (test = false)
bool test = true;

Step 2. Email recipients

Each time the script is being executed, an email will be sent to recipients specified here. There is no limitation to the number of recipients. For each recipient, email address and name should be added as shown in the example.

Example:

//STEP 2. Add receipients for status email
// (Each respondent will need: email_recipient[] and
email_recipient_alias[])
arrayAdd(email_recipient, "john.smith@company.example");
arrayAdd(email_recipient_alias,"John Smith");
arrayAdd(email_recipient, "one.more@company.example");
arrayAdd(email_recipient_alias,"One More");

Step 3. A factor for each weekday

For each day of the week, the total number of mails sent will be calculated as:

Number of mails = factor x (week quota target - week quota current)

For example if the week target is 100 and 40 respondents have completed until now, and today’s factor is 1.5; a total of 1.5 x (100-40) = 90 emails will be sent.

All seven weekday variables must be specified. If no emails are to be sent for a certain day of the week, set the factor = 0 for that day.

Example:

//STEP 3. Specify a factor for each day of the week (no mails = 0)
number factor_monday = 0.8; // normal in this project = 0.8
number factor_tuesday = 1.0; // normal in this project = 1.0
number factor_wednesday = 1.2; // normal in this project = 1.2
number factor_thursday = 1.5; // normal in this project = 1.5
number factor_friday = 2.0; // normal in this project = 2.0
number factor_saturday = 3.0; // normal in this project = 3.0
number factor_sunday = 4.0; // normal in this project = 4.0

It is recommended to send out every day. In case a mail out will have to wait, for example for modifications in the questionnaire, just change the questionnaire status to closed/paused/open for test. Emails will only be sent if the questionnaire status is open.

Which factors to choose will depend on the quality of the panel, the survey penetration, and other local variables. As a main rule, the factor should increase gradually from day to day during the week.

Step 4. Quota time frames

If additional quotas are being used for stratification (see the quota section,) time frames must be specified.

A time frame has a start (time_frame_start) and an end (time_frame_end). The following rules must be complied with:

• The number of time_frame_start and the number of time_frame_end must be equal.
• For any time frame; time_frame_end <= time_frame_start
• Two different time frames must never overlap each other.

Example:

//STEP 4. Keep quota time frames up-to-date
arrayAdd(time_frame_start,200751);
arrayAdd(time_frame_end ,200802);
arrayAdd(time_frame_start,200803);
arrayAdd(time_frame_end ,200806);
arrayAdd(time_frame_start,200807);
arrayAdd(time_frame_end ,200810);

Step 5. Quota categorization and quota labels

One quota for each week must be created, and labeled according to the quota labeling convention (appendix 2). These quotas controls the total number of emails being sent. (These quotas should not be inserted in the script.)

When the only respondent requirement of a survey is the total number of interviews pr. week, no additional quotas will be needed. However, if we have more specific requirements, like i.e. 50/50 male/female, etc. additional quotas will be needed. The automated script supports stratification for up to 3 categories of additional quotas, for example gender, age group and geographical region.

If additional quotas (in addition to the week quota) are being used for stratification, these must follow the standard in appendix 2.

Additional quotas will not influence on the total number of emails.

Examples of quota categories are gender, age and geography. Typically one would have 2 gender quotas, a number of age quotas and / or geographic and/or other quotas.

For each quota, one arrayAdd() statement should be added as shown in the example below. The labels must match the last part of the quota labels exact.

//STEP 5. Categorize quotas (type 1-3) and specify quota labels
//project specific labels for quotas type 1
arrayAdd(quota_type_1_suffix,"Males");
arrayAdd(quota_type_1_suffix,"Females");
//project specific labels for quotas type 2
arrayAdd(quota_type_2_suffix,"Age 15-25");
arrayAdd(quota_type_2_suffix,"Age 26-39");
arrayAdd(quota_type_2_suffix,"Age 40-59");
arrayAdd(quota_type_2_suffix,"Age 60+");
//project specific names for quotas type 3
arrayAdd(quota_type_3_suffix,"Region 1");
arrayAdd(quota_type_3_suffix,"Region 2");

Step 6. Rule ids

A group for emails must be created.

If the only quotas are one pr. week, the group should consist of 1 rule only. This rule should include your normal sampling rules, and a usage variable: "Users who did not participate in the following questionnaire" (tracking questionnaire). If additional quotas are used, the number of rules is calculated by the following equation:

Number of rules = type 1 quotas x type 2 quotas x type 3 quotas

In the example above, 2 x 4 x 2 = 16 rules is required. The following table show which rules should be created for the quotas in the example above.

Rule #	Gender	Age	Geography
Rule 1	Males	15-25	Region 1
Rule 2	Males	15-25	Region 2
Rule 3	Males	26-39	Region 1
Rule 4	Males	26-39	Region 2
Rule 5	Males	40-59	Region 1
Rule 6	Males	40-59	Region 2
Rule 7	Males	60+	Region 1
Rule 8	Males	60+	Region 2
Rule 9	Females	15-25	Region 1
Rule 10	Females	15-25	Region 2
Rule 11	Females	26-39	Region 1
Rule 12	Females	26-39	Region 2
Rule 13	Females	40-59	Region 1
Rule 14	Females	40-59	Region 2
Rule 15	Females	60+	Region 1
Rule 16	Females	60+	Region 2

The rules should be labeled so they are easy to recognize.

The script will need a rule id and a label for each rule.

The only way to make sure the system can figure out the relation between the quotas and the rules is if the rules are declared in a specific order. Therefore it is very important to declare the rules in the following order:

• All rules covering the first quota in quota type 1
  • All rules also covering the first quota in quota type 2
    • One rule for each quota in quota type 3, (in the same order the quota type 3 quotas is specified.)
  • All rules covering the second quota in quota type 2
    • One rule for each quota in quota type 3, (in the same order the quota type 3 quotas is specified.)
  • Etc...
• All rules covering the second quota in quota type 1
  • Etc...
• Etc...

The following example would be the correct declaration of rules for the example used above:

//STEP 6. Specify rule id's for rules in group used by Bulk Mail
//It is crucial that rules are added in correct order.
Follow instructions from Catglobe
arrayAdd(rule_id,2584170); // Males 15-25 Region 1
arrayAdd(rule_id,2584169); // Males 15-25 Region 2
arrayAdd(rule_id,2584168); // Males 26-39 Region 1
arrayAdd(rule_id,2584167); // Males 26-39 Region 2
arrayAdd(rule_id,2584174); // Males 40-59 Region 1
arrayAdd(rule_id,2584173); // Males 40-59 Region 2
arrayAdd(rule_id,2584172); // Males 60+ Region 1
arrayAdd(rule_id,2584171); // Males 60+ Region 2
arrayAdd(rule_id,2584178); // Females 15-25 Region 1
arrayAdd(rule_id,2584177); // Females 15-25 Region 2
arrayAdd(rule_id,2584176); // Females 26-39 Region 1
arrayAdd(rule_id,2584175); // Females 26-39 Region 2
arrayAdd(rule_id,2584182); // Females 40-59 Region 1
arrayAdd(rule_id,2584181); // Females 40-59 Region 2
arrayAdd(rule_id,2584180); // Females 60+ Region 1
arrayAdd(rule_id,2584179); // Females 60+ Region 2

Step 7. Rule Labels

For each rule id, one rule label should be specified. The order must be the same as the orders in the rule declaration above. These labels are being used in the status info email.

In the example above, the following rule labels would be appropriate:

//STEP 7. Specify rule lables (for the same rules)
arrayAdd(rule_label,"Males 15-25 Region 1");
arrayAdd(rule_label,"Males 15-25 Region 2");
arrayAdd(rule_label,"Males 26-39 Region 1");
arrayAdd(rule_label,"Males 26-39 Region 2");
arrayAdd(rule_label,"Males 40-59 Region 1");
arrayAdd(rule_label,"Males 40-59 Region 2");
arrayAdd(rule_label,"Males 60+ Region 1");
arrayAdd(rule_label,"Males 60+ Region 2");
arrayAdd(rule_label,"Females 15-25 Region 1");
arrayAdd(rule_label,"Females 15-25 Region 2");
arrayAdd(rule_label,"Females 26-39 Region 1");
arrayAdd(rule_label,"Females 26-39 Region 2");
arrayAdd(rule_label,"Females 40-59 Region 1");
arrayAdd(rule_label,"Females 40-59 Region 2");
arrayAdd(rule_label,"Females 60+ Region 1");
arrayAdd(rule_label,"Females 60+ Region 2");

Step 8. Bulk mail id

In the communicator tab of the tracking questionnaire, a bulk mail must be prepared with a link to the tracking questionnaire. Choose the group to send to. It is crucial that the group is put in the field: Groups to be rebuilt.

Insert the bulk mail id like this:

//STEP 8. Specify Bulk Mail id
number bulkmailid = 393621;

Step 9. RPQ Id for dummy user

The script must be executed in the context of a RPQ (Questionnaire answer sheet). Thus a dummy user should be sampled to the questionnaire. Get the RPQ Id for this user either by performing an export, or get it by batch executing a small CG script.

	CATINÉT NOTICE: A user has been created on mycatinet for this purpose. Add the user with username ‘Automated_mailout’ to the questionnaire and get the RPQ id of this user.

Example:

//STEP 9. Specify RPQ id for a dummy user in the questionnaire
number neededRPQId = 621758923;

Step 10. Multiple countries in one PQ

In this case, Multiple countries in one PQ means each country is running as an independent survey with its own quotas.

Each country will also have its own workflow.

Example 1 (Not using this feature):

//STEP 10.
bool   useCountryId = false;
string country = "";

Example 2 (Using the feature multiple countries in one PQ):

//STEP 10.
bool   useCountryId = true;
string country = "DK";

	CATINÉT NOTICE: This feature was added in 2009, and many of the older workflows do not have this capability.

Multiple countries impact on quotas

When one questionnaire holds quotas for multiple countries. The country information must be included in all quota names.

In these cases, the naming convention will be different, (see appendix about quotas.)

Scheduling the script

For each tracking questionnaire, a workflow must be created. (Tools -> Administration -> Work flow). When the CG script is ready, it should be pasted into the Script tab of the workflow.

Always test the script by setting test = true. (Remember to set test = false after testing.)

When the script is ready and tested, schedule it for daily execution. In the workflow list, highlight the workflow, choose schedule, choose Re-occurrence build, set Interval = 1 day, set an appropriate time for first time and last time.

When the script is scheduled, it will be displayed in the "Scheduled CatTask" list. (In the current version, you will only be able to see CatTasks you have created yourself.

Appendix 1 - Week system

The script supports the European week system (ISO 8601)

• The week with the year’s first Thursday in it, is week 01.
• The first day of a week is always a Monday.
• A week always consist of 7 days.

To make sure the same week system is used in the questionnaire, it is recommended to insert a dummy question of type number labeled YEARWEEK in the questionnaire, with the following CG script:

array dateTime  = getDateTime();
number year_    = convertToNumber(dateTime[0]);
number month_   = convertToNumber(dateTime[1]);
number week_    = convertToNumber(dateTime[7]);
number wyear;
number YWnumber;

if(week_ > 51 && month_ == 1){
  wyear = year_ -1;
}
else if(week_ == 1 && month_ == 12){
  wyear = year_ +1;
}
else wyear = year_;

YWnumber = (wyear * 100) + week_;
YEARWEEK = YWnumber;

A solution for tracking weeks starting on any weekday has been requested, but this is not yet supported.

Appendix 2 - Quotas

The PQ is configured for one country

All quotas to be part of the automated tracking must be based on weeks. At least one quota must exist for each week, labeled [YYYYWW], for example 200810, 200811, etc. See also Appendix 1: Week system.

Up to 3 categories of additional quotas are allowed. These must be based on weeks (one or multiple weeks), all additional quotas must follow the same time frame scheme, and the quotas must be labeled according to specifications below.

These additional quotas must be labeled [YYYY WW - YYYY WW: [free text]].

Quota examples:

• 200801
• 2008 01 - 2008 04: Males
• 2008 01 - 2008 04: Females
• 2008 01 - 2008 04: Age 15-25

One group must be created according to specifications below.

The sum of target for quotas in one category must be equal to or more than the sum of the week quotas for the same interval of weeks.

Example:

Assume the following week quotas have been defined:

Quota label	Quota target
200801	100
200802	100
200803	100
200804	100

Also assume that other quotas are based on 4 weeks. The following targets will be allowed.

Quota label	Quota target
2008 01 - 2008 04: Males	200
2008 01 - 2008 04: Females	200

The following targets will also be allowed. These targets will never be reached, but it is a useful method to allow a little deviation from the perfect target.

Quota label	Quota target
2008 01 - 2008 04: Males	220
2008 01 - 2008 04: Females	230

The following targets will not be allowed. In this case the sum of the sub targets are less than the main target.

Quota label	Quota target
2008 01 - 2008 04: Males	190
2008 01 - 2008 04: Females	190

Remember, the week quota target is the quota used to calculate the total number of emails to send. Other quotas are used for targeting specific target groups.

100% of the respondents must be included in each quota category.

The PQ is configured for multiple countries

The same general rules applies as for single countries PQ, but with the following modifications:

If the PQ is configured for multiple countries, the country identifier (assigned to the variable country in the workflow) should be appended at the end of the quota name.

Example:

If the above example was part of a multiple country survey, the multiple conotry configuration of the script would look like below for Denmark.

//STEP 10.
bool   useCountryId = true;
string country = "DK";

In that case, the quota names from the example above, would be like:

Quota label	Quota target
200801 DK	100
200802 DK	100
200803 DK	100
200804 DK	100

Quota label	Quota target
2008 01 - 2008 04 DK: Males	200
2008 01 - 2008 04 DK: Females	200