Run VBScript Module
This module will run a VBScript or ECMAScript / JScript.
Result Variables can be used throughout the script.
After starting the script VoiceGuide can:
- Continue, without waiting for script to complete.
- Wait until script completes.
- Wait until script and sound file completes.
Continue, without waiting for script to complete option
VoiceGuide will immediately continue down the "Success" path once script was started successfully. If script could not be started successfully then the "Fail" path is taken. If the path that VoiceGuide should be following is not defined then VoiceGuide will hang up the call.
Wait until script completes option
VoiceGuide will wait until the script finishes running, or a response from the executing script is received.
Script can send responses back to VoiceGuide while it is executing by calling one VoiceGuide's ActiveX/COM functions. The functions which are considered to return a result back to VoiceGuide are: Run_ResultReturn(), Script_Gosub(), Script_Goto(), Script_Return(). For more information on VoiceGuide's ActiveX/COM interface please see the COM Interface section of Help file.
Once VoiceGuide detects that a script has completed and no COM response was received beforehand then VoiceGuide will see if a "Result File" has been created by the script. If one has been created then VoiceGuide will read in it's contents and then determine what to do next based on the contents of the file.
The syntax of the Result File is the same as that used by the Run Program module. Please refer to the Run Program module Help file's section for more information.
A "Success" or Result Variable list must be returned to VoiceGuide
(either though a Run_ResultReturn COM function or a Result File) in order for it to go down the Success path.
If no result is returned then the "Fail" path is taken after the VBScript completes.
Calls to Script_Gosub(), Script_Goto() and Script_Return() functions result in immediate running of the next module.
Any sound files still playing when VBScript completes will be stopped.
Wait until script and sound file completes option
VoiceGuide will wait until the script finishes running (or a response from the executing script is received) and until the sound file playing completes. Sound file to play can be specified either using the "sound file to play" text box or can be started from with the script itself using the Play_Start COM function.
Other functionality is similar to the "Wait until script completes" option above.
Limiting maximum execution time
To limit the length of time the script is allowed to run for, a Timeout Path should be defined. If the script does
not finish before the timeout occurs the script will be terminated and the timeout path will be taken. The timeout value is in seconds and should not be
set to 0 - a value of 0 will result in the script being aborted immediately after it is started, without giving it any chance to run.
Minimum timeout value used should be 2 seconds.
If "Wait Until script Finishes" option is selected, the sound file specified in the Play tab will be played while the started program is executing.
Some books on VBScript:
Here is a VBScript editor which you can use to develop your scripts before moving them over the the Run VBScript module: www.vbsedit.com.
Following are some examples of VBScripts which can be ran in the Run VBScript module. Extensive use of VBScripting is also made by the VoiceGuide's Voicemail system. See VoiceGuide's \system\vm\ directory.
Using ECMAScript / JScript instead of VBScript
To have the module execute JScript the first line of the script must begin with this:
This indicates to VoiceGuide that the contents of this module are JScript and not the default VBScript.
Using Result Variables in VBScripts
Before running the VBScript VoiceGuide will first see if there are any Result Variables specified within the script, and if there are then VoiceGuide will first replace them with their current values and run the resulting script then.
If the Result Variable is not defined then VoiceGuide will replace it with an empty string.
For this reason it is often desirable to have the Result Variables used with quotes specified around them.
eg: If Caller ID information did not arrive then VoiceGuide will replace $RV_CIDNUMBER with an empty string before letting the VBScript run.
So, if Caller ID information did not arrive then this VBScript code:
would be changed to
Which is not valid VBScript and hence and error will occur.
But if you write the code using quotes around the RVs, like this:
and Caller ID information did not arrive,
then the resulting VBScript which VoiceGuide actually runs would be:
Which is a valid VBScript and when running it no errors will be generated and the script will work as expected.
Result Variables should not be directly used in places where replacement with a blank would cause a syntax error.
Instead a variable which gets set to the RV value beforehand should be used in those situations.
That way there is no syntax error and the check for whether RV holds any data can be made earlier in the script and the appropriate action taken if RV does not hold a value.
After the Result Variables have been replaced in the VBScript, the new VBScript can be optionally saved in VoiceGuide's \temp\ sub-directory, named as vbs_LineId_ThisCallScriptIndex.vbs Viewing this file will allow you to confirm that Result Variable replacement was done correctly.
This saving to .vbs file can be enabled/disabled in VG.INI, in [moduleRunScript] section.
Running VBScripts from Command Line
VBScript .vbs files can be executed by by using the Windows' wscript.exe and cscript.exe utilities.
On curent versions of Windows, which are all 64-bit open a command prompt (best to use the 'Administrator Command Prompt'),
then change directory to the VoiceGuide's \temp\ sub-directory and run this command line:
Where vbs_x_y.vbs is the filename of the .vbs file which you wish to run.
VoiceGuide is 32-bit software so any VBScripts that use the VoiceGuide COM interface need to be ran using the 32-bit version of VBScript interpreter.
On 64-bit systems if you change the Registry Key:
to use the 32-bit C:\Windows\SysWOW64\cscript.exe or C:\Windows\SysWOW64\wscript.exe then the .vbs files can be ran by just being double-clicked.
On 32-bit versions of Windows the .vbs files can be ran by just double clicking on them.
How VoiceGuide's Run VBScript module runs the Scripts
By default VoiceGuide uses its own built-in script interpreter to run scripts from the Run VBScript module.
This built-in script interpreter is based on Microsoft's ClearScript engine.
VoiceGuide can be instructed to use an external application to execute the script instead.
An external interpreter is chosen if the script that is to be ran uses objects that cannot be handled by the internal interprter. Some Database related COM objects fall into this category.
The external interpreter often used is Windows' own C:\Windows\SysWOW64\cscript.exe
Configuring VoiceGuide to always use the 'external interpreter' can be done by setting the entry Engine in VG.INI's [moduleRunScript] section to cscript
Another approach is to set the $RV[ini_moduleRunScript_Engine] in the VoiceGuide script to cscript
just before running the Run VBScript module that needs to use the external interpreter, and then set it to ClearScript
for following Run VBscript modules to use the internal interpreter.
This allows the setting of interpreter to be used by the Run VBScript module to be done dynamically, during the call.
Example : Save to File
The VBScript below will append a line of text to the file C:\LogCall.txt - the line of text will contain information about start of the call, caller's telephone number and information entered by caller in module "EnterClientNumber". Result Variables are used in this script to allow information from VoiceGuide to be visible to the VBScript.
Example : Read from File
The VBScript below will read the contents of file C:\CurrentPrices.txt and will assign them to VoiceGuide Result Variable $RV[ReadInPrice]
Example : Read from Excel
The VBScript below retrieves information from an Excel spreadsheet.
Example: Save to Excel
The VBScript below saves information to an Excel spreadsheet.
Example : Creating Result File
The VBScript below demonstrates how the $RV_LINEID Result Variable is used to generate a Result file from which the data is read back into VoiceGuide. Please note that using the COM function Run_ResultReturn() is a preferable way of returning information to VoiceGuide (it's faster) - but a result file can be used if there is no other way.
It is recommended that the full path to the result file be specified, otherwise the Windows' current 'default' path will be used by the file subsystem - and that does not always point to the same path as the script's.
Example : MS Access Database read/write
Retrieving data from an MS Access database using an SQL query, and then updating the same record with new values:
Example : MS SQL Server Database read/write
A script like this can be used :
Example : Stored Procedure defined in the database (no parameters)
Let's assume that you have defined in your database a stored procedure named RetrieveUserNames that returns a recordset but takes no parameters. (note this example assumes that the database connection cn and VoiceGuide CommandLink vg are defined outside this function). The following code will retrieve the records.
Example : Stored Procedures defined in the database (with parameters)
Let's assume that you have defined in your database a parameterized stored procedure query named UpdateUser as follows: