GetCatiDialingAttempts
The GetCatiDialingAttempts function retrieves information about all dialing attempts made during the current interview attempt by the integrated dialer.
The function returns an array of CatiDialingAttempt objects. Each object contains the following fields:
DialId – Unique identifier of the dialing attempt.
TelephoneNumber – The respondent phone number that was dialed.
DialerCallerId – The caller ID presented to the respondent.
RingTime – The ring duration in seconds.
DialerCallOutcome – The outcome code reported by the dialer. See GetDialStatus() for the list of possible call outcome codes.
GetMetadata(key: String) – A function that retrieves any additional metadata provided by the dialer.
The CatiDialingAttempt object also contains the DialerTelephoneNumber field.
DialerTelephoneNumber is the DDI telephone number from which the respondent’s call was received in the case of an inbound call. Only the last element of the array will contain a value.
declare interface CatiDialingAttempt {
DialId: Int64
TelephoneNumber: String
DialerTelephoneNumber: String
DialerCallerId: String
RingTime: Int32
DialerCallOutcome: Int32
GetMetadata(key: String): String
}
GetCatiInterviewerDisplayName()
GetCatiInterviewerDisplayName() returns the display name value of the currently logged on interviewer. This is the optional display name property defined for the interviewer account in the CATI supervisor. This is typically used during the initial greeting with the respondent, for example as follows:
GetCatiInterviewerName()
GetCatiInterviewerName returns the username of the currently logged on interviewer. This is the Login column in the CATI interviewer list in the CATI supervisor. This is typically used during the initial greeting with the respondent, for example as follows:
Figure 16 - GetCatiInterviewerName example
Redo
Redo() forces a redo of a specific question:
Redo('qid')where qid is the question ID of the question that is to be re-done.
Redo can be used together with SetErrorMessage to provide a redo-context sensitive error message (this can be defined per language). Example:
SetErrorMessage(LangIDs.en, 'Error Message')Considerations regarding use of Redo:
-
Redocan only be used for surveys that use the optimized database format. -
Redocan only be used in CATI, CAPI or AskMe survey channels. If, however, a survey is running in the CATI channel thenRedois available for CAWI interviewing also. No error will be reported at launch time if the survey contains an 'unsupported'Redo, instead the survey will produce an internal error at runtime. - The question id has to be a question that the interviewer has seen before (i.e. a question that has already been processed).
- The question id can be a question inside a callblock. If the callblock has been called multiple times, the the most recent call the callblock will be chosen.
- The question id can be a question inside a loop. The first iteration of the loop is chosen.
- The function is supported by quick test.
Invoking the Redo() will cause the engine to return to the specified question ID. Having then answered this question the engine will fast forward back to the script that invoked the Redo. If during fast forward the interview cannot progress due to a change in the interview path or due to some validation the interview will continue from that point.
Important
When fast forwarding through the project, the Redo() WILL be re-executed. Therefore an example such as:
q1 - Gender question
Script: Redo('q1')
will produce a loop, repeating q1 over and over again. This is intentional behavior. It is the survey author's responsibility to use the function in a way that takes this into account. The Redo is intended to be based on a particular condition that must be resolved to bypass the Redo, so it will typically be placed within a condition or similar.
GetTelephoneNumber and SetTelephoneNumber
Two functions exist for dealing with the telephone number of the respondent in CATI surveys. This can either be to access the value of the respondent's telephone number, or to explicitly set the value of the respondent's telephone number. The telephone number is a special field that is displayed in the survey's call list in CATI supervisor as well as on the manual selection screen for interviewers.
GetTelephoneNumber()will return the value of the current respondent's telephone number (string).
An example of retrieving the value of the respondent's telephone number may be as part of an initial contact screen, such as the infomation node below:
Figure 1 - Information node example
This would be represented as follows in the CATI interviewing Console:
Figure 2 - Information node result
Similarly the telephone number can be set inside a script node in Survey Designer as follows:
SetTelephoneNumber(value)Where value is the (string) value that is to be assigned as the respondent's telephone number.
GetExtensionNumber and SetExtensionNumber
Two functions exist for dealing with the telephone number extension of the respondent in CATI surveys. This can either be to access the value of the respondent's telephone number extension, or to explicitly set the value of the respondent's telephone number extension.
GetExtensionNumber()will return the value of the current respondent's telephone number (string).
An example of retrieving the value of the respondent's telephone number extension may be as part of an initial contact screen, such as the info node below:
Figure 3 - Information node example
This would be represented as follows in the CATI interviewing Console:
Figure 4 - Information node result
Similarly the telephone number extension can be set inside a script node inSurvey Designer as follows:
SetExtensionNumber(value)Where value is the (string) value that is to be assigned as the respondent's telephone number extension.
Note: On a supporting dialer the system field for ‘ExtensionNumber’ will be sent to the dialer as a call property to specify the desired Caller ID (CLID). This means that individual CLIDs can be set by supplying the desired values in a sample file (using a column headed ‘ExtensionNumber’). Contact support to check if your system supports this functionality.
GetTimeZoneId and SetTimeZoneId
Two functions exist for dealing with the time zone that the respondent resides in CATI surveys. It is possible to either retrieve or set a value for the respondent’s time zone. The time zone associated with the respondent corresponds to the time zone list from the resources tab inside of the CATI supervisor. An example list is as follows:
Figure 5 - Retrieving respondent's time zone
The first ‘ID’ column corresponds to the respondent's time zone Id.
GetTimeZoneId()will return the numeric Id stored for the current respondent.
It is also possible to define the time zone for the respondent; this can be achieved using a script node. Here
SetTimeZoneId(value)can be used to set the value of the time zone, where value is an valid integer time zone Id value. In the following example the respondent's time zone is changed to time zone Id 3 (GMT+1).
Figure 6 - SetTimeZoneId example
GetExtendedStatus and SetExtendedStatus
The Extended Status is the status primarily used for CATI interviewing that stores the call outcome of the interview record. The extended status is a numeric value corresponding to the extended status list within the CATI Supervisor. An example list is shown below:
Figure 7 - GetExtendedStatus and SetExtendedStatus example
GetExtendedStatus()will return the value of the current interview's extended status value (integer). If no value is set 0 will be returned.
A typical example of where this may be used is in the End block of a CATI interview. When an interviewer terminates the interview during an interview, the interview is immediately given a GetExtendedStatus() value of 6. The End block can then be used to react to this termination. In the example below, for interview terminations the type of termination is sub-classified by a termination question and then the interview is further dispositioned to a new extended status value depending on the termination type:
Figure 9 - End block example
It is also possible to define the extended status value for an interview. This can be achieved using a script node. Here,
SetExtendedStatus(value)can be used to set the value of the extended status, where 'value' is a valid integer extended status value; an integer between 1 and 120.
The initial contact screen that is used to record the call-outcome of the call demonstrates the use of this function. Here we can see the Dial_Outcome question where the call-outcome is recorded:
Figure 10 - The Dial_Outcome question
This contains the following answer list:
Figure 11 - Resulting answer list
The codes here correspond to the extended status code list within the CATI supervisor. Therefore the script node s1 is used to disposition the interview with a SetExtendedStatus() value corresponding to the code for the selected category in the Dial_Outcome question.
GetLastInterviewStart
GetLastInterviewStart()GetLastInterviewStart returns the date/time of the previous call attempt made to this respondent.
GetLastChannelId
GetLastChannelId()GetLastChannelId returns the ID (integer) corresponding to the channel used during the last interview attempt
| ID | Channel |
| 0 | None |
| 1 | Web |
| 2 | CAPI |
| 4 | Random Data Generator |
| 8 | CATI |
GetCatiInterviewerId
GetCatiInterviewerId()GetCatiInterviewerId returns the ID corresponding to the CATI interviewer as defined by the ID column in the CATI interviewer list in the CATI supervisor.
GetCallAttemptCount
GetCallAttemptCount()The GetCallAttemptCount function is used to return the number call attempts made to this respondent. For example the following info node would display the number of attempts made:
Figure 12 - GetCallAttemptCount in use
This function is for CATI only, not CAPI.
GetTotalAttempts
GetTotalAttempts()The GetTotalAttempts function is used to return the number of attempts made to this respondent in either CATI or Web interview modes. For example,
^GetTotalAttempts()^used in an info node would display the total number of attempts made to this respondent in either CATI or Web interviewing.
Note: This function is not available for CAPI interviewing and is only available for surveys that have the CATI channel enabled.
GetDialMode, SetDialMode and GetDialingMode
Three functions exist for dealing with the dial mode in use when a company has the CATI Telephony add on enabled. GetDialMode checks the respondent data value, and SetDialMode explicitly sets the value of the dial mode. GetDialingMode gets the "live" in-progress dial mode assigned to this call in the dialer.
GetDialMode()and
GetDialingMode()will return a numeric value corresponding to the list below.
1 = Manual
2 = Preview
3 = Automatic
4 = Predictive (requires the additional predictive telephony add on)
The dial mode can be set inside a script node in Survey Designer as follows:
SetDialMode(value)
Where value is either 1, 2, 3 or 4 based on the list above.
GetDialStatus
A function exists that returns the outcome of a dial attempt made by the dialer (when a company has the CATI telephony add on enabled). The GetDialStatus() function call will return a numeric value corresponding to the outcome list below.
| Dial status value | Description |
| 0 | Connected call |
| 2 | Busy |
| 3 | No reply |
| 7 | Answer phone |
| 8 | Modem |
| 9 | Fax |
| 10 | Congestion |
| 11 | Unobtainable |
| 12 | Nuisance |
| 15 | Returned not dialed |
| 25 | Returned dialer expired |
| 28 | Stopped |
| 29 | Telephony failure |
| 30 | Error |
Typically this would then be used to control either continuing the call or finishing the interview, as shown in the screens below:
Figure 13 - GetDialStatus function in use
With the script doing the following:
Figure 14 - Script example
Note: The GetDialStatus() function should not be called before the dial command has been issued for this interview. If it is, it will return the last DialStatus value from the previous call, or a “0” if it is the first call. For surveys using more than 1 dial mode (for example a predictively dialed survey that has preview in predictive calls), ensure that appropriate logic surrounds the function such that it is only retrieved once the dial command has been issued.
GetDialType
GetDialType()GetDialType() can be used to obtain information about how the current phone interview was dialed, either manually (by hand) or automatically (using an autodialer).
GetTotalDuration
GetTotalDuration()The GetTotalDuration function is used to return the number of seconds spent interviewing cumulatively across all interview attempts. For example the follow info node would display the amount of time spent on this interview across all interview attempts:
Figure 15 - GetTotalDuration info node
GetCatiInterviewerDisplayName returns the display name value of the currently logged on interviewer. This is the optional display name property defined for the interviewer account in the CATI supervisor. This is typically used during the initial greeting with the respondent, for example as follows:
GetCatiInterviewerName() when you want to dynamically show the interviewer display name value instead of just the login name (which might not be suitable in the context of the survey text). In the event that no display name value has been provided for the interviewer the function will show the Interviewer login ID instead. IsCatiInbound()Use the IsCatiInbound function to determine if the current interview was initialized via an inbound call to the call center. If this is the case then the function will return true.
GetCatiAppointmentTime
GetCatiAppointmentTime()GetCatiAppointmentTime returns the time (in local respondent time) for the CATI appointment that has just been made. This is designed to be used in the Exit block at the end of the current interview only. For example the following survey would display the time and also capture it to a hidden variable to be used at the start of a subsequent call. An example of such a survey is:
Figure 17 - GetCatiAppointmentTime example
Where the captureAppointmentTime script contains the following:
Figure 18 - captureAppointmentTime script
This is then piped in during the Start block in the i3 info node.
GetCatiRespondentUrl
This is GetRespondentUrl for CATI.
Using a redirect inside a CATI survey that jumps to a specific question in the survey (for example Redirect(GetRespondentUrl("q1")) results in the interview continuing in Web mode with a number of negative implications because GetRespondentUrl is not supported in CATI. The GetCatiRespondentUrl() function has the same signatures as GetRespondentUrl() and is intended for use in CATI interviewing to safely jump to a specific question.
The same rules apply as for GetRespondentUrl()(go to GetRespondentUrl for more information).
Note: The GetCatiRespondentUrl() function must ONLY be used in conjunction with redirects to questions inside of the same CATI survey. The GetCatiRespondentUrl() function only applies in the CATI interviewing mode. If it is used in other modes it behaves like GetRespodnentUrl().
GetCatiStationId
GetCatiStationId()GetCatiStationId() can be used to obtain the CATI interviewer station ID of the device being used to conduct the current interview. Each workstation in a CATI call center has its own workstation label (Station ID) – specified as a string when making a fresh console installation.
StartVoiceRecording and StopVoiceRecording
StartVoiceRecording('label')StartVoiceRecording is only applicable when connected to a supported Forsta Local Dialer. When issued inside of a script node, sectional voice recording will begin. This will continue to run until a StopVoiceRecording() function call is made or the interview finishes. The user-supplied text label passed is incorporated into the filename of the .wav sound file created.
StopVoiceRecording(stopRecordingMode: String)Where:
stopRecordingMode is an optional parameter that can either be "WholeInterview", "Sectional" or "Both".
StopVoiceRecording is only applicable when connected to a supported Forsta Local Dialer. When issued inside of a script node, if voice recording is enabled for this interview then the specified voice recording type will be stopped on the dialer. If no value is supplied, the default is “Both”.
Depending on which dialler is being used, different recording methods are available:
- TCI and ProTS: whole interview recording and sectional recording are available. However it is not possible to have concurrent whole interview recording and sectional recording; if whole interview recording is enabled when a
StartVoiceRecording()function call is made the whole interview recording will be stopped - Open Dialler API diallers: whole interview recording and sectional recording are available, even concurrently.
Whole interview recording cannot be controlled with scripting functions – for example StopVoiceRecording(‘WholeInterview’) or StopVoiceRecording(‘Both’) - unless ‘Enable whole interview audio recording’ is checked in Survey Designer > Survey Settings > CATI - Telephone.
If only sectional recording is required, ‘Enable whole interview audio recording’ must be unchecked.
fr
fr()Note: This function is obsolete; you should use GetRespondentValue() instead (go to GetRespondentValue and SetRespondentValue for more information).
This function is only available in survey scheduling within the CATI supervisor. The function can be used to reference the value of CATI replicated background variables in a scheduling script. Only variables with the "Available as CATI filter" question-level property can be referenced. The following demonstrates how a filter can be used when referring to the value of the CATI replicated variable named gender:
Figure 19 - fr function in use
IsCallExpired
IsCallExpired()This function is only available inside of survey scheduling inside of the CATI supervisor. CATI scheduling is invoked when a call expired event occurs. Typically, this would be due to an appointment expiry timeout being reached. During scheduling execution the IsCallExpired function returns true if scheduling has been invoked due to a call expiry event. This allows a new call to be scheduled in this scenario, here the actions are to remove assignment locking, set the call priority to be 2000 and set the time to call to be now.
Figure 20 - IsCallExpired function in use
AddToCatiBlacklist
AddToCatiBlacklist()This function is available in Survey Designer for CATI-enabled projects. When this function is called, the current respondent’s telephone number (contained within the respondent data variable named TelephoneNumber) will be added to the company's telephone blacklist. The telephone blacklist can be managed from the CATI Supervisor, from the Resources tab > Telephone Blacklist item. When telephone blacklist support is enabled at the survey level in Survey Designer, any attempt to call one of the blacklisted numbers will not be processed and the respondent extended status will automatically be changed to 'Blacklist'. Duplicate numbers or numbers containing spaces or special characters such as ( ) + # - will not be added to the list. Refer to the separate CATI Supervisor documentation for further information on creating and maintaining a telephone blacklist.
GetParamValue
GetParamValue(value)This function is only available in survey scheduling in the CATI supervisor. If the scheduling script contains some defined parameters then these parameters can be referenced in filters in scheduling. In this example a scheduling parameter named TimeFrame exists, where ID is 1.
To refer to these parameters, use the GetParamValue(value) function where you can either pass the GetParamValue("ParameterName") or GetParamValue(ParameterId) to reference by name or ID. For example, GetParamValue(“TimeFrame”) or GetParamValue(1). The example below shows this being used in the filter for the Busy call outcomes.
Figure 21 - GetParamValue function in use
StartCATIAudioPlayback
^StartCatiAudioPlayback('http://<dialer IP or DNS name>/<folder structure>/<filename>,[auto-start])^This function is only applicable for CATI-enabled projects, in the CATI channel and when working with a supported Dialer. When this function is called a command is sent to the dialer to play the specified sound file. The function can be used in any interactive text that will be displayed to the CATI interviewer; typically this would be a question relating to the sound file being played. This function should not be used inside of non-interactive nodes such as script nodes or hidden questions as this will result in nothing being played to the CATI interviewer.
Where and how the audio files are uploaded depends on the dialer type (Sytel or Invade) and it may be that with hosted dialer solutions, you will need to contact the vendor to upload the files and be provided with a URL for that file for use in the StartCATIAudioPlayback() function.
The parameters are the filename (including path) of the .WAV file to be played and optionally a Boolean for automatically starting the sound file playback when the function is invoked. The auto_start parameter determines whether the sound file should immediately start playing when the function is invoked, if this is not specified the default value is false (or 0) meaning the file will not start playing immediately. Example of usage is as follows:
Figure 22 - StartCATIAudioPlayback function in use
In this example, the CATI interviewer console will activate the sound playback buttons on this page allowing the CATI interviewer to play, pause or stop the sound clip, “radio1.wav”, it will not start automatically. Using this syntax: ^StartCatiAudioPlayback("radio1.wav", 1)^ upon displaying this page the sound file would immediately be played.
A CATI interviewer can use the play, pause and stop toolbar buttons to control the playback of the audio file and whenever the audio file is playing both the interviewer and the respondent will hear it. These buttons are only active for questions that make use of the sound playback capabilities. Sound file playback will automatically be stopped if the CATI interviewer submits the current page.
Note: It is the responsibility of the survey author or the person who manages the local dialer to ensure that the sound file has been placed in the appropriate directory on the dialer(s). This task is not automated in any way by the Forsta Plus system. If the file cannot be located and played by the dialer the interview will continue as if the there was no request to play a sound file.
IsInOpenendReviewMode
IsInOpenendReviewMode()This function is only applicable for CATI-enabled projects, being interviewed in the CATI channel. IsInOpenendReviewMode returns true if the function is executed during CATI openend reviewing, false otherwise. You may use this function to prevent questions with text responses appearing during openend reviewing either as part of a question mask or from condition logic. This would typically be used for open text questions that do not require review at the end of the CATI interview.
Note: If you use this masking, remember to check the "No cleaning on question masking" property (refer to the separate Survey Designer documentation for more information). If this property is not checked, then the data will be cleared if the page is empty.
AddRespondentToCati
AddRespondentToCati(extendedStatus)The AddRespondentToCati function can be called in CATI mode, but only when the function includes the respondent.respid parameter. This allows the creation of a new respondent record and schedules a call for that respondent in the CATI system.
Example:
AddRespondentToCati(1, respondent.respid)
The extendedStatus parameter that is supplied is the numeric value of the extended status (between 1 and 120) that will be assigned to the respondent in the CATI system; call scheduling will be executed on this call using this extended status value.
The following example demonstrates how this could be used in an open Web survey:
Figure 23 - AddRespondentToCati example
If the answer to the question in “transferToCati” is “Yes” (code 1) then the respondent name and telephone number is collected and initialized via the script node initializeCati. The call is then initialized in the CATI interviewing channel with an extended status value of 21 (“Transfer to CATI”). The script contains the following code:
SetRespondentValue("respondentname", f("respName"));
SetTelephoneNumber(f("telNumber"));
AddRespondentToCati(21);
Note: You must ensure that a scheduling rule is defined to handle calls with the specified extended status to ensure that an appropriate CATI call is created.
CreateCatiAppointment
CreateCatiAppointment()This function is available for CATI-enabled projects in Survey Designer. When this function is called, the appointment dialog will appear on the CATI interviewing console. The interviewer will be able to make an appointment and on clicking OK the survey will finish with an appointment status. If the interviewer clicks Cancel, they will be allowed to continue the interview without making an appointment.
Note: This function is only effective if there is an interactive question located after it in the survey. If there are no interactive questions in the survey after this function is called then the function will be ignored, the appointment dialog will not appear and the interview will merely continue until it is finished.
CreateCustomAppointment
This function can be used when CAWI respondents would like to set up an appointment to be called back via CATI. The CreateCustomAppointment function can be used in a CATI schedule custom script to create an appointment for CATI using date and time information captured from survey variables.
The function 'CreateCustomAppointment' will accept parameters for date/time in the respondents time zone.
JScript example:
function CreateAppointment()
{
var time: DateTime = DateTime.Parse('2021-01-25 13:00');
CreateCustomAppointment(time);
}
JavaScript example:
function CreateAppointment() {
var time = new Date(2021,0,25,13);
CreateCustomAppointment(time);
}
Note: See how the Javascript example uses a Date object which takes a month index from 0-11 compared to the jScript example which uses a DateTime object using a month value 1-12.
EnableLiveMonitoring and StartScreenRecording
Legislation in some countries prohibits live monitoring of respondent's answers until they provide their explicit consent for such live monitoring. To comply with these rules the Forsta software provides means of disabling and enabling the interview live monitoring and video recording functions. Two controls which make it possible to only enable live call monitoring and/or video recording of the interviewers screen if the respondent has given explicit consent are activated by settings in the survey's Survey Settings > CATI Options tab (refer to the separate Survey Designer documentation for further details).
Figure 24 - Disabling and Enabling the interview live monitoring and recording functions
The Monitoring and recording options in the CATI Options tab
When the second option for either of these settings is selected, the call monitoring and/or video recording features will only be permitted after explicit consent has been obtained in the survey. This requires that the survey includes the corresponding script functions:
EnableLiveMonitoring()StartScreenRecording()A simple method of achieving this is to add the functions to a script node inside a condition that is activated by a "Yes/No" consent question. No parameters are required for the functions.
Figure 25 - Adding functions to a script node inside a condition activated by a Yes/No consent question
The functions in a script node in the survey
IsCatiGroupMember
IsCatiGroupMember()The IsCatiGroupMember function can be used to check if the interviewing agent conducting the current interview belongs to a given group (as specified by the function by referring to it with its applicable group name). The function returns FALSE if the interviewer is not a member of the specified group.
Figure 26 - IsCatiGroupMember function example
Example of usage
IsCatiIvr
IsCatiIvr()Use the IsCatiIvr function to determine if the current interview is operating in IVR mode. If this is the case then the function will return true.
IsCatInbound