Script

Overview

The Script object allows the specification of server-side scripting language code to control any kind of business logic within the dialog flow. The script code can either be embedded within the object definition itself, or it can be referenced as an external file source. With the file referencing option an existing script file (e.g. from an operating Web service) can be reused for building a voice service.
VoiceObjects Server comes with a built-in JavaScript 1.5 engine, but any other script engines can be integrated through the so-called Script bus. See Appendix C – How to Use the Script Bus in the Administration Guide for more information on this.

8 Caution: Processing script code is considerably more time-consuming than processing Expression objects. Note that the execution will be done within the VoiceObjects Server framework and not on the media platform (e.g. by embedding the script code into the rendered VoiceXML). If a Script object is only to perform simple calculations use an Expression object instead which offers a variety of frequently used functions. Also avoid using Script objects as part of Resource Locator or Layer objects as these tend to be evaluated in each dialog step. Under high call volume, this can impose high memory and CPU load upon VoiceObjects Server.

Any number of parameters from the dialog context can be passed into the Script object. These parameters can be a mix of constants, Variable, Expression, Collection, Layer, or other Script objects and will be transferred with the script invocation. The value of each transferred Variable object will be assigned back to the dialog context when the script execution is finished. During execution, the Script object has its own context. Any assignment to a script variable has no impact on the dialog context before ending the script evaluation.

The Script object has a return value that is defined by the return value of the script instruction last processed. This can be, for example, the return value of a function which is called from the main scripting block, or it can be a script variable which is assigned a certain value. A Script object can therefore be used in the same way as a Variable, Expression, or Layer object within almost any other object to control certain object properties or processing conditions dynamically at call time. When a Script object does not return a value it is handled as a variable with an undefined value (empty string), which is equivalent to NULL. A Script object not returning any defined value can be tested with the Expression function ISNULL (), which will return true, or ISNOTNULL (), which will return false. In a Boolean context the Script object evaluates to true unless its return value is an empty string, 0 (zero), or FALSE (in any combination of upper and lower case letters).

For more information on JavaScript, refer to the JavaScript Language Resources available at http://www.mozilla.org/js/language/.

The Object Definition below covers the configuration of the Script object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph.

The Script object belongs to the object category Resources.

Dialog Flow Scenario

The following dialog flow example demonstrates the use of a Script object to format a variable for text-to-audio (TTA) output (see the Format object for more information on text-to-audio). The script builds a TTA–XML string that represents a sequence of audio files to read out amounts. Example: a variable content 4901 is transformed into the sequence 4000.wav 900.wav 1.wav, resulting in the output “four thousand nine hundred one”.

Object – Caller	Dialog Flow
	How much money do you want to transfer?
Caller	4901 euros.
	[ Transforms the string “4901” to a TTA – XML structure ]
	You said four thousand nine hundred one. Is that correct?

The JavaScript sample code for the transformation may look like the following:

var result = "<root>";

var tens;

var hundreds;

var thousands;

tens = amount % 100;

hundreds = (amount - tens) % 1000;

thousands = amount - hundreds - tens;

if (thousands > 0)

{

result += "<row><col name=\"file\">";

result += thousands.toFixed(0);

result += ".wav</col></row>";

}

if (hundreds > 0)

{

result += "<row><col name=\"file\">";

result += hundreds.toFixed(0);

if (tens > 0)

{

result += ".wav</col></row>";

}

else

{

result += ".wav</col></row>";

}

if (tens > 0)

{

result += "<row><col name=\"file\">";

result += tens.toFixed(0);

result += ".wav</col></row>";

}

result += "</root>";

result;

In this example, the variable to pass into the script would be amount.

Object Definition

The Definition of the Script object provides the following sections:

· Script Resource
To specify the script code to be processed.

· Parameter Set
To specify the set of parameter objects and/or constants.

· Process Notification
To define a message to be played before processing the script.

· Wait Loop Audio
To define an Audio object to play in a loop while processing the script.

· Formatting
To define formatting instructions for playback within an Output object.

For information regarding additional object configuration refer to Pre-/Postprocessing, Event Handling, or Properties in this Object Reference.

Script Resource

The Script Resource section defines the code to be processed within the Script object. It can either be provided as an embedded definition typed into the Embedded definition field (as shown in the example below), or as a reference to a file. In the latter case, the name of the file needs to be provided in the File field, and an optional Resource Locator object can be specified in the Location field.

i8 Note: If both an embedded definition and a file reference are given, the embedded definition takes precedence.

The JavaScript resource can also be defined dynamically by using a Variable, Expression, Layer, or another Script object.

The Type field allows selecting between the script engines defined through the Script bus. This drop-down list initially consist of only one entry, JavaScript 1.5, which is built into VoiceObjects Server.

A Script object can provide a return value, and thus act as a replacement for an Expression object. The return value of the Script object is defined by the value of the last statement that is evaluated within the JavaScript code. The following two examples demonstrate this.

In the first example, the Script object calls a function defined within the JavaScript code.

function addNumbers(x,y) {return x+y}

addNumbers(value1, value2);

The two values value1 and value2 are passed into the script using the parameter set. The return value of the script then is the sum of these two values. Note that in this example, neither value1 nor value2 are modified.

In the second example, an assignment is used as the final statement of the JavaScript code.

value1 = value1 + value2;

Here the return value of the script is the value of the assignment, namely the sum of value1 and value2. In addition, if value1 was passed into the script as a variable via the parameter set, then after the script has been processed successfully, this Variable object also contains the sum.

Re-assignments of this type are also possible using a Layer object. In this case, the script needs to return a state ID, so that the layer is switched to the corresponding state.

Should the execution of the JavaScript code fail for any reason (e.g. due to a syntax error in the JavaScript code), an event Error – Internal is activated. It can be caught and handled appropriately by using event handling. This can be defined either within the Script object itself, or e.g. in a parent module of the Script object, through inheritance.

You can manually provoke an error by assigning values to the automatically declared variables errorCode and errorMessage in your code. errorCode must be a value other than 0 (zero) to be interpreted as an error, and errorMessage can be any string. When the script has been processed and errorCode is not 0, the server activates the Error – Internal event.

Parameter Set

The Parameter Set section defines an optional list of parameters to enable the exchange of processing information with the script code.

Each Parameter section provides the following properties:

Property	Description
Parameter	Specifies the value of the parameter. Possible parameter types are Variable, Collection, Expression, Layer, Resource Locator or Script objects, and constants. When using a Resource Locator object as a parameter, its URL definition is passed to the script. The field can be left empty to denote an empty value.
Alias	Optionally specifies the name under which the parameter is accessible within the script code. If left empty, the reference ID of the object defined in the Parameter field will be used as the name. This means in particular that for constant values an alias needs to be defined (as they do not have a reference ID). Constant parameters without a defined alias are ignored.

Variables that are passed into the Script object using the parameter set do not need to be declared within the script code. Note, however, that the script engine may interpret the parameters as they are passed to it. This means, for instance, that parameters that “look like numbers” will be interpreted as numbers by the engine even if they were intended as strings. This might for example happen to a value reflecting a date, like 21.02.99. To prevent the engine from converting this to some number, you can prefix the value with a non-numerical character (like “x”) to make it a string, before passing it to the script, i.e. before processing the Script object. Make sure to delete this additional character again within the script code before processing it any further.
In other cases you might need to explicitly cast values back within the script code, e.g. when you pass a variable into the script that currently holds a number, but within the script you want to treat it like a string and perform string operations on it.

After the script code has been processed successfully, all Variable, Collection, and Layer objects are written back. Note that Resource Locator objects can not be written back like this.

Any number of parameters can be exchanged with the script code.

i8 Note: JavaScript has a set of reserved words that may not be used as variable names. This implies that these words may also not be used in the Alias field.
JavaScript reserved words include e.g. continue, debugger, default, delete, false, function, import, package, private, protected, return, super, switch, true.

In addition to passing parameters, the script code also has access to a certain set of functions. Note that this is only the case for JavaScript code, not for any other script engines attached to the Script bus. The functions are:

Boolean Functions
Name and Arguments	Description
vo.and (arg1, arg2 [, .., arg6])	Returns true if all arguments are true; otherwise returns false.
vo.between (arg, lowerLimit, upperLimit)	Returns true if the specified argument is between the lower and upper limit, or equal to the lower or upper limit; otherwise returns false.
vo.in (arg, delimitedString, [separator])	Returns true if the specified argument is within the list of entries provided within the delimited string; otherwise returns false. The default separator is a comma, but a custom separator can optionally be provided as a third argument.
vo.matchesRegExp (txt, regExp, [caseSensitive])	Returns true if txt matches the regular expression regExp, otherwise returns false. The optional parameter caseSensitive indicates whether the comparison should be case sensitive (true or false; default is false).
vo.nand (arg1, arg2 [, .., arg6])	Returns true unless all its arguments are true; otherwise returns false. NAND is the logical complement of AND.
vo.nor (arg1, arg2 [, .., arg6])	Returns true if none of its arguments is true; otherwise returns false. NOR is the logical complement of OR.
vo.not (arg)	Returns the reversed value of its argument.
vo.notbetween (arg, lowerLimit, upperLimit)	Returns true if the specified argument is not between the lower and upper limit; otherwise returns false.
vo.notin (arg, delimitedString, [separator])	Returns true if the specified argument is not within the list of entries provided within the delimited string; otherwise returns false. The default separator is a comma, but a custom separator can optionally be provided as a third argument.
vo.or (arg1, arg2 [, .., arg6])	Returns true if any argument is true; otherwise returns false.
vo.xor (arg1, arg2 [, .., arg6])	Returns true if exactly one argument is true; otherwise returns false. XOR (arg1, arg2 [, ..., arg6]) stands for exclusive OR (arg1, arg2 [, ..., arg6]).

Information Functions
Name and Arguments	Description
vo.isAfter (date1, date2)	Returns true if date1 occurs chronologically after date2; otherwise returns false. The parameters date1 and date2 must be specified in the format yyyyMMdd or yyyyMMddhhmmss.
vo.isBefore (date1, date2)	Returns true if date1 occurs chronologically before date2; otherwise returns false. The parameters date1 and date2 must be specified in the format yyyyMMdd or yyyyMMddhhmmss.
vo.isLogical (arg)	Returns true if the specified argument is a logical value (true or false, regardless of capitalization); otherwise returns false.
vo.isNotNull (arg)	Returns true if the specified argument is defined; otherwise returns false.
vo.isNull (arg)	Returns true if the specified argument is undefined or empty; otherwise returns false.
vo.isNumber (arg)	Returns true if the specified argument is a number; otherwise returns false.
vo.isText (arg)	Returns true if the specified argument is a text; otherwise returns false. A number is not interpreted as text, thus ISTEXT(5) returns false.
vo.isValidDate (date)	Returns true if date is a valid date otherwise returns false. The parameter date must be specified in the format yyyyMMdd or yyyyMMddhhmmss.

Arithmetic Functions
Name and Arguments	Description
vo.abs (nbr)	Returns the absolute value of the specified number. The absolute value of a number is the number without its sign.
vo.ceil (nbr)	Returns a number rounded up, away from zero (0).
vo.floor (nbr)	Returns a number rounded down, toward zero (0).
vo.ln (nbr)	Returns the natural logarithm of the specified number. Natural logarithms are based on the constant “e” (2.71828182845904). The specified number must be positive.
vo.pow (nbr, power)	Returns the value of the specified number to the power specified by the second argument.
vo.rand ( )	Returns a Float random number between 0 (inclusive) and 1 (exclusive).
vo.randint (start, end)	Returns a random Integer value between start (inclusive) and end (exclusive). Both arguments start and end must be Integer values, and end must be greater than start.
vo.round (nbr, nbrDigits)	Returns the result of rounding the specified number to at most nbrDigits decimal digits.
vo.sign (nbr)	Returns the sign of the specified number. Returns 1 if the number is positive, zero (0) if the number is 0, and -1 if the number is negative.
vo.sqrt (nbr)	Returns the square root of the specified number. The number must be positive or zero (0).
vo.trunc (nbr, nbrDigits)	Returns the result of truncating the specified number to at most nbrDigits decimal digits.

Text Functions
Name and Arguments	Description
vo.find (findTxt, txt, startPos)	Returns the index at which findTxt was found within txt, starting the search at position startPos (where the first character is position 1). If findTxt could not be found, 0 (zero) is returned.
vo.insert (oldTxt, startPos, newTxt)	Returns a modified version of the string oldTxt in which the string newTxt has been inserted, starting at position startPos.
vo.lower (txt)	Returns a new string in which all uppercase letters of the specified string txt are converted to lowercase.
vo.ltrim (txt, [char])	Returns a modified version of the string txt in which white space characters (blanks and tabs only) are removed at the left end. Optionally a char can be specified which will be removed instead of white space characters.
vo.mid (txt, startPos, nbrChars)	Returns a substring for the specified string txt, starting at position startPos for the specified number of characters.
vo.replace (oldTxt, startPos, nbrChars, newTxt)	Returns a modified version of the string oldTxt in which the substring starting at position startPos containing nbrChars characters has been replaced by the string newTxt. Example: replace(hello, 3, 2, r) = hero
vo.rtrim (txt, [char])	Returns a modified version of the string txt in which white space characters (blanks and tabs only) are removed at the right end. Optionally a [char]can be specified which will be removed instead of white space characters.
vo.substitute (string, pattern, replacement, [patternIsRegExp])	Returns a string in which all occurrences of the pattern are substituted by the replacement string. The original string is provided as first argument and will not be modified. The optional parameter patternIsRegExp indicates whether pattern has to be interpreted as a regular expression (true or false; default is true).
vo.trim (txt, [char])	Returns a modified version of the string txt in which white space characters (blanks and tabs only) are removed at the left and right end. Optionally a [char]can be specified which will be removed at both ends instead of white space characters.
vo.upper (txt)	Returns a new string in which all lowercase letters of the specified string txt are converted to uppercase.

Date & Time Functions
Name and Arguments	Description
vo.addDate (date, increment, [unit])	Adds the increment to date and returns the new date in the format yyyyMMddhhmmss. The parameter date must be specified in the format yyyyMMdd or yyyyMMddhhmmss. If increment is less than 0, date is decreased accordingly. The optional parameter unit can be used to define the unit as one of "years, months, days, hours, minutes, seconds" (default is days).
vo.convertDate (txt, outputFormat, [inputFormat], [languageCode])	If txt is a date following the format yyyyMMdd or yyyyMMddhhmmss this returns the date in the specified outputFormat using the Java SimpleDateFormat convention. If txt is a date following a custom format the optional parameter inputFormat must be used to specify the format syntax in order to enable the correct conversion internally (e.g. if txt contains "23102008" the inputFormat should be set to "ddMMyyyy"). The optional parameter languageCode can be used to define the language code, based on which the regional setting is determined (e.g. en-US or de-DE; default is the language code of the current call). This information will be used to localize the returned date format if necessary, e.g. if the call is processed in en-US a date may contain the abbreviation AD, when switching the language code to de-DE this would be changed to n.Chr.
vo.lastDayInMonth (date)	Returns the last day in the month represented by date in the format yyyyMMddhhmmss. The parameter date must be specified in the format yyyyMMdd or yyyyMMddhhmmss.
vo.nextWeekDay (date, weekday, [languageCode])	Returns the date of the next weekday, which is represented by an integer from 1 (first day in week) to 7 (last day in week), in the format yyyyMMddhhmmss starting from date. The parameter date must be specified in the format yyyyMMdd or yyyyMMddhhmmss. Depending on the regional setting this may differ as the week in Europe typically starts with Monday, whereas the US week starts with Sunday. The optional parameter languageCode can be used to define the language code based on which the regional setting is determined (e.g. n-US or de-DE; default is the language code of the current call).
vo.now ([format])	Returns the current timestamp in the specified format using the Java SimpleDateFormat convention. Sample formats and return values are: yyyy.MM.dd G 'at' HH:mm:ss z 2001.07.04 AD at 12:08:56 PDT EEE, MMM d,''yy Wed, Jul 4,'01 h:mm a 12:08 PM hh 'o''clock' a, zzzz 12 o'clock PM, Pacific Daylight Time K:mm a, z 0:08 PM, PDT yyyyy.MMMMM.dd GGG hh:mm aaa 02001.July.04 AD 12:08 PM EEE, d MMM yyyy HH:mm:ss Z Wed, 4 Jul 2001 12:08:56 -0700 YyMMddHHmmssZ 010704120856-0700 If no format is specified, the default format yyyyMMddHHmmss is used. A detailed definition can be found at: http://java.sun.com/j2se/1.4.1/docs/api/java/text/ SimpleDateFormat.html
vo.timeBetween (date1, date2, [unit])	Returns the number of days between date1 and date2. The parameters date1 and date2 must be specified in the format yyyyMMdd or yyyyMMddhhmmss. The optional parameter unit can be used to define the unit as one of years, months, days, hours, minutes, seconds (default is days). The calculation ignores everything below unit (e.g. if unit is set to hours, minutes and seconds of date1 and date2 will be ignored).
vo.timeZoneInfo()	Returns a collection with four columns. The first column Offset shows the offset in hours to add to UTC to get local time (e.g. "-0500" or "0230"). The second column StandardName contains the standard name of the local timezone (e.g. PST or CET). The third column DaylightName shows the daylight name of the local time zone (e.g. PDST or CEDT). The fourth column DSTInEffect indicates whether the local time is Daylight Saving Time or not (true, false or unknown).
vo.timer (option)	Provides a stopwatch functionality. When called with argument start it resets the timer. When called with argument interval it returns the time difference between now and the last start or interval request (in milliseconds).
vo.weekDay (date, [languageCode])	Returns the weekday of date represented by an integer from 1 (first day in week) to 7 (last day in week). The parameter date must be specified in the format yyyyMMdd or yyyyMMddhhmmss. Depending on the regional setting this may differ as the week in Europe typically starts with Monday, whereas the US week starts with Sunday. The optional parameter languageCode can be used to define the language based on which the regional setting is determined (e.g. en-US or de-DE; default is the language code of the current call).

Statistics Functions
Name and Arguments	Description
vo.eventCounter (event, [scope])	Returns the number of times the specified event has occurred during the most recent input state (scope = local) or during the entire dialog (scope = global). If the scope is not defined, it defaults to global. The third argument allows distinguishing between the collection and confirmation phase of OSDM objects. The default value is global, covering both phases. Example: eventCounter(nomatch) will return the number of No Match events that have been triggered in the current dialog. For more information on the different events, refer to Event Handling in this Object Reference.
vo.eventList (scope)	Returns a comma-separated list of events, which have occurred either in the most recent input state (scope = local) or in the entire dialog (scope = global). The second argument allows distinguishing between the collection and confirmation phase of OSDM objects. The default value is global, covering both phases.
vo.lastResult (type, [index], [phase])	Returns information on the most recent recognition result, as well as information on results from recordings and transfers. The first argument can be confidence, interpretation, length, recordingpath, or recordingurl (for recognition results), inputmode (for recognition results or transfers), utterance (for recognition results, transfers, and recordings), markname or marktime (for prompt markers and barge-in point detection), size or maxtime (for recordings), duration (for recordings and transfers), transferstatus (for transfers). For recognition results, if the recognizer returns more than one result, the optional second argument can be used to specify the desired result. Index must then be a number between 1 and Max N-Best (a tuning property). If index is greater than the maximum number of results, the function returns an empty string. The type length returns the number of results. The third argument can be used to distinguish between the collection (the default) and confirmation phase in OSDM objects. If it is set, the second argument must also be defined. Markname returns the name of the last prompt marker processed (a <mark> statement in an Output item). Marktime returns the time elapsed since the last marker was processed. For more information on the recording and transfer related types, see the Recording and Transfer object documentation. Recordingpath returns the path and recordingurl returns the URL of the last recorded utterance, in case utterance recording was enabled.
vo.lastTransition (value)	Returns the mode (for value = mode) or type (for value = type) of the most recent dialog transition. Possible modes are Standard Navigation, Auto Advance, Recognition, Hyperlink, Hangup, and Error. The type holds more fine-grained information on how the caller left the last input state.

Business Task Functions
Name and Arguments	Description
vo.startTask (task)	Starts the business task that is specified in the first argument.
vo.finishTask (task, status)	Finishes the business task that is specified in the first argument with the status specified in the second argument. This can be one of backEndError, businessLogic, callerAbort, recognitionFailure, technicalError, or complete. Optionally, the first argument can be all to finish all tasks or active to finish the currently active task. All values are case-sensitive.
vo.taskRefID ()	Returns the reference ID of the currently active business task. If no task is active an empty string is returned.
vo.taskStatus (task)	Returns the most recent status of the business task specified in the first argument. If the task has not been finished yet, it returns active or inactive. If the task has never been started, it returns notStarted.

Dialog Context Functions
Name and Arguments	Description
vo.bargein ([arg])	When used without an argument, indicates whether barge-in is activated by default (true) or not (false). When used with an argument (either true or false), it sets the default barge-in behavior.
vo.applyConfiguration (configurationXML)	Applies the assignments defined in configurationXML. The XML format used is the same as for application defaults. For further details refer to Application Defaults in Chapter 4 – Service Deployment in the Deployment Guide.
vo.callID ( )	Returns the unique ID of the call as a string of 40 characters.
vo.channel ( )	Returns the code of the channel (voice, video, text, Web) currently used for this service.
vo.databaseType ( )	Returns the type of the database used as VoiceObjects Custom DB logging repository, e.g. Oracle or SQLServer.
vo.databaseURL ( )	Returns the URL that is required to connect to the VoiceObjects Custom DB logging repository.
vo.dialogID ( )	Returns the unique ID of the dialog as a string of 44 characters.
vo.dialogStepID ( )	Returns the index of the current input state in the dialog, starting with 0. Before the first caller interaction, it returns -1. When Infostore logging on input state level is enabled, the return value matches the entry of column VOLDDSSEQ.DS_STEP for the most recently processed input state.
vo.driver ( )	Returns a string that represents the media platform driver information of the corresponding service (e.g. Nuance_VWS_2_0_VXML_2_0 or IBM_WVS_2_0_VXML_1_0).
vo.driverASREngine ( )	Returns a string that represents the name of the ASR engine (e.g. Nuance or IBM).
vo.driverID ( )	Returns the ID of the media platform driver of the corresponding service.
vo.driverProductName ( )	Returns a string that represents the media platform product name of the corresponding service (e.g. VWS or OCSW).
vo.driverProductVersion ( )	Returns a string that represents the media platform product version of the corresponding service (e.g. 1.2 or 2.0).
vo.driverVendorName ( )	Returns a string that represents the media platform vendor name of the corresponding service (e.g. Nuance or IBM).
vo.driverVXMLVersion ( )	Returns a string that represents the VoiceXML version of the corresponding service (e.g. 1.0 or 2.0).
vo.errorCode ( )	Returns the error code of the most recently processed Connector item, or zero.
vo.errorMessage ( )	Returns the error message of the most recently processed Connector item, or the empty string.
vo.exitEvent ( )	Returns a string providing the corresponding exit event ending the dialog. Valid return values are: None, Timeout, Exception, EndOfDialog, CallerHangup, CallerExit, and Transfer. For information on how to exploit this function in dialog end processing, refer to the Module object in this Object Reference.
vo.grammarControl ([arg])	When used without an argument, indicates whether grammar-driven application control is activated by default (true) or not (false). When used with an argument (either true or false), it sets the default grammar control behavior.
vo.grammarType ([type])	When used without an argument, returns the code of the currently active grammar type (one of gsl, jsgf, sgrs_xml, precompiled, regex, abnf, none). When used with an argument, it sets the currently active grammar type to this value. The argument must be one of the grammar type codes listed above. Note that the underlying media platform must be configured appropriately to support the grammar type that is being set.
vo.init (arg)	Resets a variable or collection to its initial value, which was determined when it was first used. Note: If the initial value is not specified, the variable or collection is not reset to an empty string, but to the first value it received during the current call.
vo.inputMode ([mode])	When used without an argument, returns the code of the currently active input mode (voice, dtmf, or voicedtmf). When used with an argument, it sets the currently active input mode to this value.
vo.language ([languageCode])	When used without an argument, returns the code of the currently active language (e.g. en-US or de-DE). When used with an argument, it sets the currently active language to this value. Note that the underlying media platform must be configured appropriately to support the language that is being set.
vo.masterDialogID ( )	Returns the unique master dialog ID of the session as a string of 44 characters. The master dialog ID is used when chaining services. If the current service is not part of a chain, this ID is the same as the dialog ID.
vo.md5Sum (txt)	Returns the 128 bit MD5 hash of txt as a sequence of 32 hexadecimal digits. Hashing is performed according to RFC 1321, e.g. supplying the string VoiceObjects will result in the following hash value: 31414f01914a0366ef9f247bb2eaa9f5.
vo.moduleHistory ([level])	Returns a comma-separated list of reference IDs of Module objects visited so far in the current dialog. When used without an argument the entire list of all visited Module objects will be returned, with the most current Module object at the top of the list. When used with an argument the value of the argument defines how far to go back in the processing history specifying where to start the list (e.g. level = 1 means that the list starts with the previously processed Module object instead of the current one). If the specified level exceeds the size of the processing history an empty string is returned. Note: Only Module objects with the option Enable history tracking set to true are considered.
vo.moduleRefID ([level])	Returns the reference ID of a Module object processed in the current dialog. When used without an argument the reference ID of the currently processed Module object is returned. When used with an argument (level) the reference ID of a parent object of the currently processed Module object is returned. The value of the argument specifies how far to go up in the tree of parent modules (e.g. level = 1 means that the reference ID of the first parent of the currently processed Module object is returned). If the specified level exceeds the depth of the module tree an empty string is returned.
vo.moduleSet ([level])	Returns a comma-separated list of reference IDs of Module objects processed so far in the current dialog. The list is sorted alphabetically, and each module only occurs once. When used without an argument the entire list will be returned. When used with an argument the value of the argument defines how far to go back in the processing history specifying where to start the list (e.g. level = 1 means that the list starts with the previous Module object instead of the current one). If the specified level exceeds the size of the processing history an empty string is returned. NOTE: Only Module objects with the option Enable history tracking set to true are considered.
vo.notification (message)	Sends a notification with a predefined ID (1.3.6.1.4.1.24140.1.2.5.8.1) and the specified message.
vo.outputMode ([mode])	When used without an argument, returns the code of the currently active output mode (audio:tts or tts:audio). When used with an argument, it sets the currently active output mode to this value.
vo.projectInfo (mode)	Provides information on the project that contains the start object of the current service. For mode = project, it returns the name of the project. For mode = version, it returns the name of the project version.
vo.pronunciation (var)	Returns the pronunciation pattern associated with the variable provided as first argument.
vo.refresh (arg)	Re-evaluates the initial value of a variable or collection in the current dialog context. For a static initial value, this is the same as INIT(). Note: If the initial value is not specified, the variable or collection is not reset to an empty string, but to the first value it received during the current call.
vo.recordingScope ([value])	When used without an argument, returns the current value of the corresponding dialog context setting (nomatch, recognition, or all). When used with an argument, it sets the recording scope dialog context setting.
vo.recordUtterances ([value])	When used without an argument, returns the current value of the corresponding dialog context setting (true or false). When used with an argument, it sets the record utterances dialog context setting.
vo.resetVisitCounter (referenceID)	Resets the visit counter for the object with the specified reference ID. When all is given as argument, the visit counters for all objects are reset.
vo.serverContextMappingURL ( )	Returns the complete URL string for the context mapping of the corresponding server instance (e.g. http://localhost:8099/VoiceObjects/).
vo.serverHostname ( )	Returns the host name of the corresponding server instance.
vo.serverhostIP ([servletEngine])	Returns the IP address of the corresponding server instance. If the optional parameter servletEngine is set to true (the default), the address is retrieved from the servlet engine. If it is false, it is retrieved from the server configuration.
vo.serverInstanceName ( )	Returns the name of the corresponding server instance.
vo.serverName ( )	Returns the logical name of the corresponding VoiceObjects server.
vo.serverPort ([servletEngine])	Returns the port of the corresponding server instance. If the optional parameter servletEngine is set to true (the default), the port is retrieved from the servlet engine. If it is false, it is retrieved from the server configuration.
vo.serverServletContext ( )	Returns the servlet context of the corresponding server instance (e.g. /VoiceObjects).
vo.serverURL ([servletEngine])	Returns the URL leading to the corresponding server instance (e.g. http://172.22.23.45:8099/ VoiceObjects/DialogMapping). If the optional parameter servletEngine is set to true (the default), IP and port are retrieved from the servlet engine. If it is false, the corresponding values are retrieved from the server configuration.
vo.sessionVariable (varName, [value])	Returns or sets information from the session context. The following arguments are supported: · ANI Calling number; same as ANI() · DNIS Called number; same as DNIS() · RDNIS Redirecting number; not available on all media platforms · MPSID Media platform session ID; not available on all media platforms · AAI Application to Application Information; not available on all media platforms · GCID Global call ID; not available on all media platforms · UA User-agent information; only available for mobile Web driver · CRMID Unique caller or customer ID; can be used to join Infostore data with the CRM data warehouse Availability of the information depends on the media platform. In addition, custom arguments can be used.
vo.visitCounter (objRefID)	Returns the number of times the object with the specified reference ID has been visited within the current dialog.
vo.vsn ()	Returns the name of the VoiceObjects service associated with the current dialog.

Miscellaneous Functions
Name and Arguments	Description
vo.conditional (cond, truevale, falsevalue)	If cond is true, returns truevalue. Otherwise, returns falsevalue. cond can be a Variable, Expression, Script, or Collection object, or a layer condition.

For more information about the context functions and their arguments, refer to the Expression object in this Object Reference.

i8 Note: The values returned from these functions are of type object. If you want to perform, for example, string operations on the return value of such a function, you need to convert the data type first, e.g. by appending the empty string, as in

var lang = vo.language() + '';

Process Notification

In the Process Notification section, output can be specified that gives the caller a notification that the script process is starting. This parameter is optional.

For further details, refer to the Output object in this Object Reference.

Wait Loop Audio

In the Wait Loop Audio section, an audio file can be specified that is played back while the script process is running. This parameter is optional. It is typically used for time-consuming Script object operations, e.g. to play hold music.

For further details, refer to the Audio object in this Object Reference.

i8 Note: On some media platforms, the duration of the audio file must be at least as long as the processing time needed by the Script object. On other platforms, an audio file that is shorter than the processing time required by the script will be looped continuously as needed. For further information on the behavior of audio processing refer to the local documentation of the media platform vendor.

Formatting

The Formatting section defines how the result of the Script object is played back to the caller when it is used within an Output object.

Two different categories of formatting types are offered:

· Text-To-Audio (TTA)
The object content is played back to the caller via the concatenation of prerecorded audio files.

· Text-To-Speech (TTS)
The object content is played back to the caller via text-to-speech synthesis provided by the media platform.

The formatting instructions can be defined as an embedded definition as part of the Script object, or can be linked to an autonomous Format object.

For further details on formatting capabilities refer to the Format object in this Object Reference.

Usage Examples

Usage examples for the Script object are:

· Computing complex formulae that are cumbersome to represent with expressions (e.g. interest rates)

· Evaluating multiple interconnected conditions, and translating them into a finite set of dialog options (which can then be evaluated in a Case object)

· Dynamically creating grammars based on variable content

· Parsing and/or checking validity of data retrieved from back-end systems

· Formatting dynamic content to be played back as a concatenation of audio files (refer to the Format object for more details)

VoiceObjectsXML Definition

The Script object is represented by the VoiceObjectsXML element <script>. It has four attributes and nine groups of children.

In addition, the element has the standard attributes described in the XDK Guide.

The <script> element uses the embedded <value> and <parameterSet> elements.

Script

Attributes

· location
Defines the location from where the JavaScript file is to be retrieved. Must be a reference to a Resource Locator object.

· file
The file name of the JavaScript file. Can be a constant name, or a reference to a an Expression, Script, or Variable object.

· embeddedRef
Defines the Script code using a reference to an Expression, Script, or Variable object.

· scriptType
Defines the type of scripting language to be used. Legal values include javascript and any type that is defined using the Script bus.
If not specified, defaults to javascript.

Children

· <expression usage=”precondition”> or
<variable usage=”precondition”> or
<collection usage=”precondition”> or
<script usage=”precondition”>
Defines the precondition for the Script object.

· <sequence usage=”preprocessing”>
Defines the preprocessing sequence for the Script object.

· <value>
Optional embedded constant definition of the script code.

· <parameterSet>
Defines the parameter set for the Script object.

· <output>
Defines an optional process notification output for the Script object. This child is only relevant if the Script object is used directly within the dialog flow.

· <audio>
Defines an optional wait loop audio for the Script object. This child is only relevant if the Script object is used directly within the dialog flow.

· <format>
Defines the output formatting for the script return value.

· <eventHandling>
Defines the event handling for the Script object.

· <sequence usage=”postprocessing”>
Defines the postprocessing sequence for the Script object.

Example

<value>

<![CDATA[

// Compute the life insurance fee based on gender and age

if (gender == "male")

{fee = 35;}

else

{fee = 27;}

if (age> 30)

{fee = fee + (age - 30);}

]]>

</value>

</parameterSet>

</script>

Value

Children

· CDATA
Embedded code for a Plug-In or Script object, or embedded value for a Variable object, Collection object, or argument.

Example

<value>

<![CDATA[

// Compute the life insurance fee based on gender and age

if (gender == "male")

{fee = 35;}

else

{fee = 27;}

if (age> 30)

{fee = fee + (age - 30);}

]]>

</value>

ParameterSet

Children

· +<item>
Defines the list of entries in the parameter set. The use of the alias attribute is optional when the object attribute is used, and required when the value attribute is used.

Example

</parameterSet>

Item

Attributes

· object
Defines a reference to an object. If this attribute is defined, the value attribute must not be defined.

· value
Defines a constant value. If this attribute is defined, the object attribute must not be defined.

· alias
Defines the parameter alias.

Example

Object Interoperability

The Script object is compatible with any other object type and can be used to dynamically control certain properties or preconditions. The following objects reference Script objects most frequently:

Icon	Object Name	Use Case Example
	Expression	A Script object can be used as an argument within an Expression object.
	Connector	A Script object can be used within the parameter set of a Connector object when connecting to an external resource.
	Database	A Script object can be used in the SQL statement definition of a Database object.
	Script	A Script object can be used within the parameter set of another Script object when processing any business logic.
	Plug-In	A Script object can be used within the parameter set when processing a resource of a Plug-In object.
	Log	A Script object can be used in the log statement definition of a Log object.
	Grammar	A Script object can be used to assign a dynamically generated grammar definition to a Grammar object.
	OSDM	A Script object can be linked within the parameter set of any OSDM object.
Any object with a layer or precondition		A Script object can be used anywhere as a layer or precondition.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explaining object names and descriptions.

The Script object name should inform the user what the script code does. The short description should describe which parameters are exchanged, and whether the Script provides a return value. Several examples are listed in the table below:

Name	Description
Sort Numbers Ascending	Sorts the values of the six variables Number 1 to Number 6 in ascending order and assigns the sorted values in that order to variable Number 1 to Number 6. The return value is “0” if all numbers are provided and no duplicates exist. Otherwise the return value is a comma-separated list of IDs, which contain duplicates. “2, 6” for example means that the value of the variable Number 2 and Number 6 are duplicates.
Validate Phone Number	Validates if the provided phone number via the variable Phone Nbr is complete and correct. The result is true if valid; otherwise false.
Calculate Discount Amount	Returns the discounted amount based on the actual shopping cart content.