Accessing the Call Object in Custom Scripting

This article describes how the call object can be accessed in custom scripting, inside of CATI scheduling.

This functionality is available through the "Scheduling" object which is available in custom scripts. The "Scheduling" object has the following properties:

Type	Name	Description
BvSurveyEntity	Survey	This object provides data for the survey which contains the current interview. ReadOnly.
BvInterviewEntity	Interview	This object provides data for interview which is scheduled. Read/Write.
BvCallEntity	LastCall	If the scheduling script is run for interview which previously had a call, then this object contains info about the call, otherwise null. ReadOnly.
BvCallEntity	NewCall	If the scheduling script creates a call, this object provides info about the new call. If the object is null, call will not be created upon scheduling completion. Read/Write.
DateTime	Time	Scheduling time.
ShiftService	Shifts	This object provides for shift functionality.

A function exists to initialize a new call inside of the scheduling object when used via a custom scheduling script: CallShouldBeCreated()

Once initialized Scheduling.NewCall will be initialized and available.

To cancel the creation of the new call set Scheduling.NewCall to Null.

Object breakdown

BvSurveyEntity object provides access to survey data as follows:

Type	Name	Description
Int	SID	Internal object ID
String	Name	Project ID
String	Description	Project name
Int	ScheduleID	Scheduling script ID

BvInterviewEntity object provides access to interview data as follows:

Type	Name	Description
Int	ID	ID of interview
String	TelephoneNumber	Respondent telephone number
String	RespondentName	Respondent name
Int	TimezoneID	ID of respondent timezone
Int	TransientState	Extendend status
DateTime	LastCallTime	Last call time
Int	LastCallPersonSID	User ID of last interview
byte	DialingMode	Dialing mode

BvCallEntity object provides access to call data as follows:

Type	Name
int	CallID
int	SurveySID
int	InterviewID
int	Phase
int	RoleID
int	ShiftID
DateTime	TimeInShift
DateTime	TimeToExpire
int	Priority
int	Resource
int	ApptID
int	ResourceType
Guid	RuleNumber

Shift functionality is available through the ShiftService object supporting methods when working with shifts:

• MatchingShift GetExactShift(DateTime utcNowTime, int tzID)
• MatchingShift GetMatchingShift(DateTime utcTime, int tzID)
• DateTime GetMatchingTime(DateTime utcNowTime, int tzID)
• MatchingShift GetNextShift(MatchingShift currentShift, int tzID)
• MatchingShift GetNextShift(MatchingShift currentShift, int tzID, out int countSkipShifts)
• MatchingShift GetNextShiftByID(DateTime utcTime, int tzID, int scriptShiftID)
• MatchingShift GetNextShiftOfSpecifiedType(DateTime utcTime, int tzID, int scriptShiftTypeID)
• MatchingShift GetShiftAfterNumberOfMinutes(DateTime utcNowTime, int tzID, int countMinutes)
• MatchingShift GetShiftAfterNumberOfShifts(DateTime utcNowTime, int tzID, int numberOfShifts)
• MatchingShift GetShiftAfterNumberOfShifts(MatchingShift curentShift, int tzID, int numberOfShifts, bool isTakingExclusionIntoAccount)

Custom code examples

Custom script creates new call with priority 10

Copy

function ScriptFunction()
{
  CallShouldBeCreated();
  Scheduling.NewCall.Priority = 10;
}

Custom script creates new call with priority which is taken from number variable with 'num_prior' name

Copy

function ScriptFunction()
{
  CallShouldBeCreated();
  Scheduling.NewCall.Priority = f("num_prior").get();
}

Custom script creates new call with time to call on next shift

Copy

function ScriptFunction()
{
  CallShouldBeCreated();
  var shift = Scheduling.Shifts.GetMatchingShift( Scheduling.Time, 1/*Timezone*/ );
  shift = Scheduling.Shifts.GetNextShift( shift, 1/*Timezone*/ );
  Scheduling.NewCall.ShiftID = shift.ShiftTypeID;
  Scheduling.NewCall.TimeInShift = shift.StartDate;
}

Custom script creates new call and assigns the interviewer with the ID from variable ‘inter’

Copy

function ScriptFunction()
{
  CallShouldBeCreated();
  var name = f("inter").get();
  Scheduling.NewCall.Resource = GetInterviewerByName( name ).Id;
}

Custom script writes the interviewer's SID to variable 'history' (for all interviewers who have conducted an interview)

Copy

function ScriptFunction()
{

 if( Scheduling.Interview.LastCallPersonSID == 0 )
    return;
    
  var person =  GetInterviewerById(Scheduling.Interview.LastCallPersonSID);
  if( person == null )
    return;

  var history = f("history").get();

  if(String.IsNullOrEmpty(history))
    history = person.Name;
  else
  { 
    var containsName: Boolean = false;
    var names = history.split(',');
    for(var i = 0; i < names.length; i++)
    {
      if(names[i] == person.Name)
      {
        containsName = true;        
      }
    }

    if(!containsName)
      history = history + "," + person.Name;
    else
      return;
  }

  f("history").setValue(history);

}