Web Service Module

This module lets VoiceGuide communicate with HTTP and HTTPS Web Services.

Following request types can be used:

• GET
• POST
• DELETE
• PUT
• UPDATE

Module supports setting of:

• URL Address
• Post Data
• Headers
• Authentication

After issuing the request to the Web Service, VoiceGuide can:

• Continue, without waiting for web service query to complete.
• Wait until web service query completes.
• Wait until web service query and sound file completes.

Continue, without waiting for web service to complete :
VoiceGuide will immediately continue down the "Success" path once the web service query was started successfully. If web service query 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 web service query completes :
VoiceGuide will wait until the web service query completes. Any sound files still playing when the web service query completes will be stopped.

Wait until web service and sound file completes :
VoiceGuide will wait until the web service completes and until the sound file playing completes.

Limiting maximum execution time

To limit the length of time the system waits for the web service to return, a Timeout Path should be defined. If the web service does not return before the timeout occurs the web service query will be terminated and the timeout path will be taken. \The timeout value is in seconds and should be set to a value of 1 or higher.

Play Tab

If "Wait Until Web Service Completes" option is selected, the sound file specified in the Play tab will be played while the web service query is performed.

Using Result Variables

Before running the web service VoiceGuide will first see if there are any Result Variables specified within the web service's HTTP address (URI), Post Data, Headers etc. and if present then VoiceGuide will first replace them with their current values.

If the Result Variable is not defined then VoiceGuide will replace it with an empty string.

If after replacing the Result Variables in Data ad/or Headers the outcome points to a valid file then the contents of that file will be read in, any $RVs within that read in file contents replaced, and that result will then be used as the Data and/or Header for that Web Service interaction.

Returned Result Variables

A Result Variables ($RV) is created for each data item returned by the Web Service. The $RVs are named:

$RV[ModuleTitle_XPathToDataNode]

Where XPathToDataNode is the XPath or JsonPath to the returned data.

It is recommended to look at VoiceGuide's vgEngine log (in VoiceGuide'S \log\ subdirectory) to establish what $RVs are created when a particular web service is called. Created $RVs will not all be saved in the Script's Log.

The following $RVs are always created:

$RV[ModuleTitle_Result_Code] : Returned Status code

$RV[ModuleTitle_Result_Desc] : Returned Status description

$RV[ModuleTitle_Result_Data] : Data received from by the web service

$RV[ModuleTitle_Result_Data_QE_Doubled] : Data received, with all Double Quote characters " replaced (escaped) with "" . This $RV can be used in scripting modules etc.

$RV[ModuleTitle_Result_Data_QE_Backslash] : Data received, with a backslash \ added before all Double Quote characters " This $RV can be used in scripting modules etc.

The Headers of the returned response are also saved as Result Variables.

Individual data elements also have $RVs created for them.

Please consult VoiceGuide's vgEngine log (in VoiceGuide'S \log\ subdirectory) to establish what $RVs are created when a particular web service is called.

If other information needs to be retrieved from the returned data then VBScript modules can be used to process the returned data, which is stored in $RV[ModuleTitle_Result_Data] etc. $RVs.

Paths

The following are valid path options:

• Success/Fail
• HTTP Response Codes
• Timeout

eg: The following HTTP Response Code paths are all valid:

on {200} goto [Say all went OK]
on {OK} goto [Say all went OK]
on {406} goto [Say trans not accepted]
on {Not Acceptable} goto [Say trans not accepted]

$RV[moduleTitle_PathTaken]
Stores which path was taken when exiting the module.

Script Examples

Sample scripts are provided in VoiceGuide's \Scripts\Web Service\ subdirectory.
Script provided there demonstrate the use of the various HTTP request methods.
See here for another example of use.

Example : GET Request (XML returned)

If the response to a HTTP GET request is:

<?xml version="1.0" encoding="utf-8" ?>
<WeatherReturn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Success>true</Success>
<ResponseText>City Found</ResponseText>
<State>NY</State>
<City>New York</City>
<WeatherStationCity>White Plains</WeatherStationCity>
<WeatherID>4</WeatherID>
<Description>Sunny</Description>
<Temperature>46</Temperature>
<RelativeHumidity>17</RelativeHumidity>
<Wind>NW16G26</Wind>
<Pressure>30.20F</Pressure>
<Visibility />
<WindChill />
<Remarks />
</WeatherReturn>

Then the following Result Variables would be created by VoiceGuide for this response (module's title is "getweather"):

The above Result Variables can then be used for the remainder of the call.

Example : GET Request (JSON returned)

If the response to a HTTP GET request is:

{
   "cod":"200",
   "message":0.0254,
   "cnt":39,
   "list":[
      {
         "dt":1493002800,
         "main":{
            "temp":297.06,
            "temp_min":295.641,
            "temp_max":297.06,
            "pressure":1027.34,
            "sea_level":1033.43,
            "grnd_level":1027.34,
            "humidity":81,
            "temp_kf":1.42
         },
         "weather":[
            {
               "id":800,
               "main":"Clear",
               "description":"clear sky",
               "icon":"01d"
            }
         ],
         "clouds":{
            "all":0
         },
 ... etc.

Then the following Result Variables ($RVs) would be created by VoiceGuide for this response (module's title is "getweather"):

Above example was taken by accessing the OpenWeatherMap.org API at: http://api.openweathermap.org/data/2.5/forecast?id=6619279&APPID=6ef9cb723afa6226e5e7628d83094aec

Example : POST Request : Add Ticket to Zendesk

Zendesk (http://www.zendesk.com/) provides a HTTP REST API.

Following example shows show VoiceGuide's Web Service module can be used to add a new ticket to your Zendesk account:

NB. this POST request will require authentication, and hence would require that your own Zendesk account is set up first. The URL would need to be modified accordingly.

Example : POST Request to ASMX Web Service

Issuing a SOAP 1.2 POST request to an ASMX Web Service:

Then SOAP XML structures to use is displayed when the Web Services' ASMX URL is viewed in a web browser.

Most ASMX Web Services support SOAP 1.2 format. Issuing a SOAP 1.1 format POST request is only slightly different:

HTTPS

TLS 1.1 and TLS 1.2 are supported (in VoiceGuide v7.6 and later). The older TLS 1.0 and SSL3 are also supported.

Client Certificates

Token Based Authentication

Web Services that use Token Based Authentication will need to be accessed using two 'Call Web Service' modules.
The first module would be used to obtain the token (by passing to web service the login credentials) and the subsequent modules can use the tone to call the web service API.
The token is sometimes supplied in the headers section.
'Call Web Service' module supports setting of custom headers, and hence supports passing of Authentication Tokens in that way as well.

Password Security

If passwords need to be used to access the web service, it is recommended that entire VoiceGuide script is saved as a Protected Script.
This way the passwords will be encrypted and not readable unless the VoiceGuide script password is known.