In this article
A scheduling script is a set of rules which contain instructions describing what the CATI Supervisor module is to do with a specific call and under which conditions. The rules are applied to all calls that are created for a survey. Scheduling scripts use a number of parameters, some of which are predefined, and some can be configured, saved and reused in any scheduling script. This part of the documentation describes the rules used to manage telephone rotation scheduling.
Customized Extended Status
The rules use the following custom Extended Statuses:
31 Max number of calls attempts reached
32 All numbers unobtainable
33 Soft Appointment
34 Changed Tel Number
Rules
The scheduling set up consists of 2 rules, with several sub-rules.
Figure 1 - The rules
Extensive use is made throughout the Custom Scheduling Script of the following functions/call properties:
SetRespondentValue() – to set a value to a background question
GetRespondentValue() – to retrieve the content of a background question
Scheduling.Interview.TelephoneNumber – the telephone number of the current call
Scheduling.Interview.TransientState – the Extended Status (call outcome) of the current call
For example
SetRespondentValue('ActiveTelNumber',"Tel1")
SetRespondentValue('ConnectedCallCount', 0);
Scheduling.Interview.TransientState == 8
Rule 1 - Survey Data Update
This rule is used for:
Updating the call history fields in the survey data using the SaveCallHistory custom script.
Removing records with more than the maximum number of valid call attempts allowed (defined as a scheduling parameter) from the Scheduled (active) call list.
Figure 2 - Rule 1: Survey Data Update
Rule 2 - Handling Call Outcomes
Rule 2 deals with the standard call outcomes. An important point to bear in mind is that during respondent upload, two custom scripts are run (this is why the Full Scheduling option is required when uploading respondents (go to Respondent File and Upload for more information)).
Figure 3 - Rule 2: Handling Call Outcomes
Extended Status - Fresh
The InitialiseActiveNumber rule sets the Tel1 number as the first number to call (Telephone Number), and the UpdateUsablePhoneCount counts the number of telephone numbers available per respondent and flags them as StatusTelN 0 (Not tested number).
Important
If more than six Telephone numbers per respondent are required, the nophones var must be changed to match in the UpdateUsablePhoneCount() and the scheduling rules must be relaunched.
function UpdateUsablePhoneCount() {
var nophones = 6; //**** IMPORTANT Change this if there are more than 6 phone numbers *
…
... and add the extra Tel fields to the phoneArray on line 82 (function SelectNextNumber())
Figure 4 - Adding the extra Tel fields
Important
The value of nophones and the number of elements in the phoneArray must be the same. Any extra telephone fields must be also added to the Telephony Folder with their corresponding StatusTel and CountTel fields.
Extended Status - Appointments
"Hard appointments" are locked to the interviewer who made the call. The appointment is set with an expiration time in case the interviewer is not available when the appointment time arrives.
"Soft appointments" are not locked.
It is assumed that the system should continue calling the respondent on the telephone number that connected when the appointment was made. So to stop the Telephone rotation for both hard and soft appointments, run the StopRotation custom script function.
Figure 5 - Running the StopRotation custom script function
The StopRotation function sets the StopRotation background question to 1
Extended Status - No Reply / Busy / Answer Phone
If more than one telephone number is available, the system will attempt to move to the next available number for these three call outcomes.
Figure 6 - Setting up for call outcomes
ActivePhone
For Busy and Answer Phone (Voice Mail) outcomes, the system will attempt the same telephone number three times before it moves to the next available number. To edit this setting, modify the condition on line 54 in the function SaveCallHistory()).
Figure 7 - Setting the number of times a call will be attempted
For example, >=2 will attempt the same number three times, >=1 will attempt it twice, etc.
If temporarily fixing the number for calls that are busy or go to answer phones is not required, remove the code within the red box shown below from line 138 (function NextNumberAction()).
Figure 8 - Remove the code if a fix is not required
Moving to the next available number
Three functions are used in the telephone rotation process
UpdateUsablePhoneCount() - to check if more than 1 number is available.
NextNumberAction() - if more than one number is available the next function is called.
SelectNextNumber() - to rotate through the TelN fields to find the next number available.
The function uses the ActiveTelNumber (this will be Tel1 for on the first call)
var currNum = GetRespondentValue('ActiveTelNumber');
to loop through the TelN fields until it finds a valid next number (nextphone will be set)
if (nextphone) {
var nextNum = GetRespondentValue(nextphone);
SetRespondentValue('TelephoneNumber', nextNum);
Scheduling.Interview.TelephoneNumber = nextNum;
SetRespondentValue('ActiveTelNumber', nextphone);
If nextphone is set, the function will update the TelephoneNumber and ActiveTelNumer to this nextphone (i.e. the rotation has taken place).