Scripts in the CATI folder

The CATI folder contains sample management scripts for use with outbound telephone interviewing projects, including a script that supports chaining in telephone interviews. See Chaining projects for phone (CATI) interviews for more information.

This script is suitable for projects that allow a combination of inbound calling for self-completion interviews, outbound telephone interviewing for interviews conducted by interviewers, and personal interviewing conducted by interviewers in homes or other locations. The script also supports autodialing for outbound interviewing.

The script is a client specific framework script that includes the functions most likely to require modification for client specific processing and stub functions to support additional client specific processing. The script includes the following support scripts that are in the [INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\DDL\Scripts\Interview\Sample Management – Scripts\Debugging folder:

Defines all constants used in the script. Misspelled constants are caught during the parsing phase while misspelled queues, fields, and properties are not caught until execution.

▪All three scripts are shared with the basic_sample.mrs and personal_sample.mrs scripts. As a result, the scripts include a #define INCLUDE_TELEPHONE property that removes code that is not required in the shared files.

You can modify any of the scripts, but updating to the latest UNICOM Intelligence software version will be easier when modifications are restricted to the multimode1_sample.mrs script. New features can be used by directly incorporating the support scripts and merging only the client-specific script.

The following functions, and stub functions, are available for customization:

Allows the client to change which queues are acceptable for HandleSpecificRequests and change the DisplayText when a record is not found. It is also possible to force the recording of specific contacts by setting the RecordCall interview property to True.

Called when getting sample records, after a record has been retrieved and checked for usability and setup for use with phone interviewing. Allows the client to add or update any extra sample fields that are required.

Called when getting sample records, after a record has been retrieved and checked for usability and setup for use with personal interviewing. Allows the client to add or update any extra sample fields that are required.

Called when getting sample records, after a record has been retrieved and checked for usability and setup for use with web interviewing. Allows the client to add or update any extra sample fields that are required.

Allows the client to process rejected samples based on specific rejection reasons (for example when records are rejected due to being past the expiration time, not passing Quota, and so on). The client can write a history record based on the reason for a record's rejection.

When a survey is run against an Expired sample, a new IVW log entry is created (for example, RejectRecord_ClientSpecific, Reason: Expired); when a survey is run against an OverQuota sample in a Quota project, a new IVW log entry is created (for example, RejectRecord_ClientSpecific, Reason: OverQuota). In both cases, the user is not provided the true reason behind the rejected sample (they will instead receive a message such as Thank you for your interest in the survey. This survey is closed for respondents matching your characteristics). Refer to the IVW log file for more information on the rejection reasons.

It could prove helpful to familiarize yourself with the interface to the IBM SPSS Dialer: see Dialer Interface component. The system supports extension dialing where the dialer dials one number on demand for each extension (also known as power dialing), and group dialing where interviewers are allocated into groups and the dialer dials numbers for the group as a whole. Predictive dialing is a form of group dialing where several calls are made for each interviewer in the group on the assumption that not all calls will result in connections. The system also supports preview dialing while group dialing. This requires a record to be returned to the interviewer without dialing (so that the record can be previewed). The record is then extension dialed, allowing it to be returned to the previewing interviewer.

To support preview dialing, UNICOM Intelligence Interviewer - Server retrieves records from sample management as follows:

4 If additional records are required by group dialing, GetSampleRec is again called. On this second call, the UNICOM Intelligence Interviewer - Server may request the sample management script retrieve multiple sample records to return the number of records required for the group (as determined by the predictive algorithm). The GroupDial property is used to ensure that preview records are not returned.

▪The GetSampleRec function selects records to pass to interviewers for calling in the following order of priority: appointments, recalls (busy or no-answer callbacks, for example), new numbers. Supervisors can use the Interviewing Options activity to give new numbers priority over recalls.

▪Appointments are agreements that an interviewer makes with a respondent during the initial contact. Appointments may also be arranged to continue an interview. If the current time is between AppointmentMarginBefore minutes before and AppointmentMarginAfter minutes after the record's AppointmentTime, and the interviewer requesting a record is the same as the interviewer who made the previous call, then the record is chosen. If it is a different interviewer, sample management searches for a different record. Once a record has an appointment time outside the AppointmentMarginAfter boundary, it may be given to any interviewer. Appointments are returned sorted by appointment time from the APPOINTMENT queue so that the first appointment chronologically is chosen. If an appointment is missed, it is called as soon as it can be retrieved.

▪Appointments to recall a number are made automatically by the script for numbers that are busy, unanswered or answered by an answering machine. Recalls are considered suitable for calling up to RecallMarginBefore minutes before and RecallMarginAfter minutes after the RecallTime stored in the sample record. Recalls are returned sorted by recall time from the RECALL queue.

Note When RecallMarginBefore is greater than, or equal to, the smallest specified delay, the following warning message displays: The time before a recall value must be less than the defined delay times. A delay value of 0 is the same as no delay setting. As such, a delay value of 0 is not compared to the RecallMarginBefore value.

▪The script takes account of any telephone interviewing parameters that have been set using the Interviewing Options activity in UNICOM Intelligence Interviewer - Server Admin. This is how supervisors may alter the workings of the sample management script.

▪If PrioritizeRecalls is True (the default) then Recalls take priority over Fresh records as described above. If PrioritizeRecalls is False, then Fresh records take priority over Recalls.

Note Prioritizing recalls to less than 100% is the best option for reducing clumping. However, if there are no yet any FRESH records, randomizing the recall times can reduce the clumping of recalls after the first clump in a shift or daypart. The multimode1_sample.mrs script randomizes the recall time around the specified delay (using the specified before a recall time as the margin, and adjusting that recall time between 2 and 10 minutes as the recall time after). For example, when the busy delay is 30 minutes and the before a recall time is 10 minutes, numbers will be recalled between 20 and 40 minutes from their return time.

▪If WebCallbackDelay is set to a nonzero value (the default is zero), then interviews started via the Web with a PhoneNumber will be called. The script checks for these records after checking for recalls. Web interviews are returned sorted by ReturnTime from the TIMEDOUT, STOPPED, or TRANSFER TO WEB queues.

▪The maximum number of times a record can be called is held in MaxTries. If an Appointment is made, then an additional MaxTries tries can be made to connect the appointment.

▪If UseInterviewerQualifications is set to True via the Interviewing Options activity, then any interviewer qualifications of the form HandleQueue_QueueName are handled first. This means that if an interviewer has HandleQueue_QueueName=True, then the named queue should be searched before any other queues.

The time zone, valid participant calling times, and day parts setup (if applicable) that the supervisor sets in Interviewing Options are passed to the script in the CATIParameters property collection. The script creates an SQL WHERE clause based on these properties and the current time and passes the clause to the searches of the queues. For example, if the supervisor enters four respondent time zones in the Time Zone field and only two are valid based on the current day, time, and allowed calling period, then the two valid time zones are specified on the WHERE clause. If the Time Zone field is empty, and day parts are not being used, time zone checking is disabled and any respondent can be called. If day parts are in use, all time zones are checked. This can result in long WHERE clauses so it is best to specify time zones whenever possible.

A UserProperties property collection is available to the script in the same way as the InterviewProperties and CATIParameters properties. If user properties have been set up for the CATIinterviewer role in the Users activity, the UserProperties collection will contain an InterviewerQualifications property collection. The script handles two types of InterviewerQualification:

▪Queue-related qualification properties of the form HandleQueue_QUEUENAME indicate that the interviewer receive records that have been moved to the named queue. Queues named in this way are searched before all other queues.

▪Qualifications where the qualification name matches the name of a field in the sample record. If a match is found, the script creates a WHERE clause based on the contents of the InterviewerQualification. For example, if the interviewer has the qualification Language={English, French}, the following WHERE clause will be added to the searches of the queues: WHERE (Language IS NULL) OR (Language='English') OR (Language='French'). This means that the interviewer will receive records where the language field contains English or French, or is blank.

If the script does not find a match between interviewer qualification name and sample field name, it exits without retrieving records. This highlights any mistyped sample fields that should match interviewer qualifications. If you want to ignore mismatched interviewer qualifications (possibly due to many project specific interviewer qualifications), set the FAIL_ON_MISMATCHED_INTQUAL constant at the top of the multimode1_sample.mrs script to False; this logs a warning, and then continues to retrieve records.

▪Calls whose outcomes are Busy, NoAnswer, or AnswerMachine are scheduled for recall. They are placed in the RECALL queue with the RecallTime set using the appropriate telephone interviewing parameter (for example, BusyDelay for Busy numbers). Records that have passed the maximum tries are moved to the MAX_TRIES queue.

▪Call outcomes of Completed, Stopped and OverQuota are also possible but cannot be not set by the interviewer. Completed interviews are sent to the COMPLETED queue. Stopped interviews are sent to the STOPPED or TIMEDOUT queue depending on the value of the TimedOut interview property. Interviews that are terminated by a signal statement in the questionnaire script are sent to the OVERQUOTA queue if the signal is 5. Otherwise they are sent to the UNUSABLE queue. The value of the signal is stored in the respondent's data record.

▪Call result codes returned by the dialer after making a call are mapped to sample management call outcomes. The call outcomes for the result codes generally place records in the UNUSABLE, CHECK NUMBER, or RECALL queues depending on the result of the call. For example, the NETWORKBUSY call outcome is used when the dialer is unable to place a call because the telephone network is busy. The sample record is placed in the RECALL queue and is scheduled for calling in one minute's time. If the network is still busy, the sample record remains in the RECALL queue but is then treated as a No Answer and is scheduled for recall after the NoAnswerDelay period. Numbers that connect, but cannot be connected to an extension, are moved to the SILENT queue and must be manually returned to a dialing queue before re-dialing.

▪This script supports calling of timed out and stopped Web (respondent-completed) interviews. It also allows interviews in any queue other than COMPLETED or OVER QUOTA to be started or restarted as self-completion interviews. This is handled in the AuthenticateSampleRec function.

▪When group dialing, the predictive algorithm will calculate the number of additional records required and pass this to the sample management script in the SMRecordsRequired property. The sample management script will then attempt to retrieve the defined number of records. The script may return fewer records, as it returns records from only one queue, and may not find the required number of records in one of the initial queues.

▪Defines the maximum number of records to pass to the sample management script. The maximum value defaults to 25 when the property is not defined. The SMRecordsRequired property is set as the batch size if its value is greater than NumSampleRecsInBatch with a maximum value as defined by the MaxRecordsInBatch property value.

▪When scanning queues for an appropriate record to call, NumSampleRecsInBatch number of records that match the selection criteria are returned. Each of these records is checked and, if appropriate, locked and returned for dialing.

▪NumSampleRecsInBatch should be set to the smallest number that will have a high percentage likelihood of getting a record in the first batch. To produce a suitable number, calculate the maximum number of clients that could be attempting to request records for a single project at one time. This will equal the number of interviewer session engines times the number of projects that share the sample management table. For example, five interviewer session engines times one project using the Sample table gives an answer of 5. This script uses a default of 5.

▪Telephone interviews that time out cannot currently be restarted except by retrieving the sample record. It is therefore suggested that telephone interviewing projects reset the default time-out of five minutes to a higher value. This script uses a default of 20 minutes.

This function is called by the telephone interviewing activity to select a sample record for calling. The function supports the retrieval of multiple records. The following flowcharts illustrate the function's logic. Separate flowcharts are provided for the blue-shaded items. Purple-shaded items, with dotted outlines, indicate client modifiable functions or stubs.

Scans queues based on priorities. Recalls can be prioritized based on a requested percentage of FRESH versus RECALL queue.

Retrieves unexpired records that pass quota from the specified queue using the specified WHERE and ORDER BY clauses. When successful, typically returns between 1 and NumSampleRecsInBatch records. SMRecordsRequired records are not required, which allows the calling provider to recall GetSampleRec and return records from multiple queues.

The Weekday function can be used to retrieve a number indicating the day of the week. The WeekdayOrWeekend function uses Saturday and Sunday as weekend days, but can be modified to use the value passed in TimeZone to determine whether the day is a weekday or weekend in the time zone.

InterviewerQualifications may contain multiple values formatted as a Categorical. SampleFields will contain only one value. Empty SampleFields should match any interviewer qualification.

This function is called by the core interviewing component to authenticate respondent details and to pass the corresponding respondent record to the interviewer. The AuthenticateSampleRec function implemented in multimode1_sample.mrs is very similar to the standard version of the function implemented in basic_sample.mrs (see Scripts in the UNICOM Intelligence Sample Management folder). You can setup chaining using constants in the multimode1_sample.mrs script and add their specific processing in AuthenticateSampleRec_ClientSpecific.

This function implements the project's call outcome rules and is called by the core interviewing component when an interview completes, times out, or is stopped. It is also called by the telephone interviewing activity when an interviewer chooses a call outcome.