Run Script Module

This module will run a VBScript or JavaScript or JScript.

After starting the script this module 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.

 

Play Tab

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.

 

VBScript

VBScript is the default language used by the Run Script module, and the VBScript interpreter will be used if no special tags are specified on the first line of the script file.
VBScript is a scripting language developed by Microsoft. It is similar to Visual Basic for Applications (VBA) used in Microsoft Office.
VoiceGuide can run VBScripts internally, using the built-in VBScript-ClearScript engine.
VoiceGuide can also run VBScripts using an external interpreter, which by default is WSH's cscript.exe

VoiceGuide's interface can be called from VBScript using the predefined object: vgo like this:

The vgo object is automatically created and made available to all VBScripts ran by VoiceGuide internally by the ClearScript engine.

If running the VBScripts using the external interpreter the VoiceGuide's vgServices.CommandLink COM object needs to be created in order to be able to access the VoiceGuide interface.
eg:

It is fine to create vgServices.CommandLink COM object in VBScript's ran internally by the ClearScript engine, but using the predefined vgo object is faster.

VBScript Books:

VBScript Step by Step - Ed Wilson

"VBScript in a Nutshell" by Ron Petrusha, Matt Childs, Paul Lomax

Here is a VBScript editor which can be used to develop scripts before moving them over the the Run Script module: www.vbsedit.com.

 

JavaScript

VoiceGuide can run JavaScript internally, using the built-in V8-ClearScript engine.

To have the module execute JavaScript, the first line of the script must begin with this:

"//JavaScript" indicates to VoiceGuide that the contents of this module are JavaScript and not the default VBScript.
V8 JavaScript engine is used to interpret JavaScript code.

If no special tags are specified on the first line, then module will execute the code as VBScript.

VoiceGuide's interface can be called from JavaScript using the predefined object: vgo like this:

The vgo object is automatically created and made available to all JavaScripts ran by VoiceGuide.

COM objects cannot be created in JavaScript.

 

JScript

JScript is Microsoft's version of JavaScript.
VoiceGuide can run JScripts internally, using the built-in JScript-ClearScript engine.
COM objects can be created in JScript.

To have the module execute JScript, the first line of the script must begin with this:

"//JScript" indicates to VoiceGuide that the contents of this module are JScript and not the default VBScript.
ClearScript's JScriptEngine is used to interpret JavaScript code.

VoiceGuide's interface can be called from JScript using the predefined object: vgo like this:

The vgo object is automatically created and made available to all JScripts ran by VoiceGuide.

VoiceGuide's vgServices.CommandLink interface COM object can be created in JScript, this however would be rarely required as the vgo object is available. Example is provided for completeness:

 

Using Result Variables

Result Variables can be used throughout the script. 

Before running the Script, 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 script run.

So, if Caller ID information did not arrive then this script code:

would be changed to

Which is not valid VBScript and hence an 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.

Notes:

After the Result Variables have been replaced in the script, the new script 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.

 

How VoiceGuide's Run Script module runs the Scripts

By default VoiceGuide uses its own built-in script interpreter to run scripts from the Run Script 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 interpreter. 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
Like this:

[moduleRunScript]
Engine=cscript

Another approach is to set the $RV[ini_moduleRunScript_Engine] in the VoiceGuide script to cscript just before running the Run Script module that needs to use the external interpreter, and then set it to ClearScript for following Run Script modules to use the internal interpreter.
This allows the setting of interpreter to be used by the Run Script module to be done dynamically, during the call.

 

Running VBScripts from Command Line

VBScript .vbs files can also just be executed by by using the Windows' wscript.exe and cscript.exe utilities.

On current 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:

C:\Windows\SysWOW64\wscript.exe vbs_x_y.vbs

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:

Computer\HKLM\SOFTWARE]\Classes\VBSFile\Shell\Open\Command

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.

 

Examples

Following are some examples of VBScripts which can be ran in the Run Script module.
VoiceGuide's Voicemail system also uses the Run Script modules extensively.
See VoiceGuide's \system\vm\ directory.

 

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:

The only thing you need to do is to match the order and data type of the parameters that are 'appended' to the command object with those of the MS Access query.

 

Example : Retrieving data from an ASMX / SOAP Web Service

NOTE: We recommend using the Web Service module when interacting with web services.

The VBScript below retrieves the WSDL from the ASMX / SOAP Web Service provided by cdyne.com, and then calls the Web Service function

GetCityWeatherByZIP.

In this example the ZIP code 10004 (New York, NY) was used.

Returned data is then formatted as a Result Variable list and returned to VoiceGuide.

Microsoft's SOAP Toolkit must be installed on system to use the MSSOAP.SoapClient30 COM object.

The Result Variables list returned would be something like this:

[Success]{true}[ResponseText]{City Found}[State]{NY}[City]{New York}[WeatherStationCity]{White Plains}[WeatherID]{4}[Description]{Sunny}[Temperature]{46}[RelativeHumidity]{17}[Wind]{NW16G26}[Pressure]{30.20F}[Visibility]{}[WindChill]{}[Remarks]{}

 

Example : Retrieving data from a HTTP / REST Web Service using HTTP GET

NOTE: We recommend using the Web Service module when interacting with web services.

Request to a Web Service can be made directly to the service/function URL.

eg. a GET call to cdyne.com GetCityWeatherByZIP function can be made directly to this HTTP address:

http://wsf.cdyne.com/WeatherWs/Weather.asmx/GetCityWeatherByZIP?ZIP=10004

and since the GetCityWeatherByZIP function returns data in XML format we can use the XML functions to to extract the required data.

 

Example : Uploading data to HTTP / REST Web Service using HTTP POST

NOTE: We recommend using the Web Service module when interacting with web services.

Request to a Web Service can be made directly to the service/function URL.

eg. a POST call to cdyne.com GetCityWeatherByZIP function can be made directly to this HTTP address:

http://wsf.cdyne.com/WeatherWs/Weather.asmx/GetCityWeatherByZIP and since the GetCityWeatherByZIP function returns data in XML format we can use the XML functions to to extract the required data.

eg. a new ticket in the zendesk.com system can be created using a HTTP POST call to URI:

https://yourname.zendesk.com/api/v1/tickets.xml

with ticket data provided as data attached to the POST:

 

Example : Screen Scraping from Web Page

If the required information is not available through a web service but is shown on the web page itself, a screen-scraping approach can be used.

The VBScript below retrieves stock market levels from www.finance.yahoo.com and returns this data to VoiceGuide. (Please see the Web Site Scraping demo script).

 

VoiceGuide

© Katalina Technologies Pty. Ltd.