14   JavaScript Functions and Objects

This chapter describes JavaScript functions and objects that are available to BeVocal VoiceXML applications. These are all extensions to the VoiceXML specification.

For general information on using JavaScript in BeVocal VoiceXML applications, see JavaScript Quick Reference.

JavaScript Constants

bevocal.outboundrequestid

Extension. For calls initiated using the Outbound Notification Service, the value of bevocal.outboundrequestid provides the Outbound Request ID associated with the call. This value can be used to map specific application invocations with the request used to initiate the application.

bevocal.sessionid

Extension. Provides a unique ID for each call. This value can be used to keep track of call-specific information in the server-side component of your application if cookies cannot be used for any reason.

_addHeader

Extension. Method of a JavaScript SOAP proxy object. Specifies an additional SOAP header for the SOAP service that the proxy object represents.

Once the SOAP header is set on a service object, the SOAP header element is part of the SOAP message for every method executed on that service object.

Syntax

 _addHeader(
   String headerNamespace, 
   String headerName, 
   Object headerValue, 
   String actor, 
   String mustUnderstand 
 )

Parameters

Parameter	Description
headerNamespace	The namespace component of the desired header's name.
headerName	The local component of the desired header's name.
headerValue	The value of the header.
actor	The value of the actor attribute for this header. Optional.
mustUnderstand	The value of the mustUnderstand attribute for this header. Optional.

See Also

Example

You can use the Call Detail Record Access Service to access information about individual calls to a VoiceXML application. You might decide to write another VoiceXML application that presents information retrieved using the CDR service. Because this is a BeVocal platform service, you must pass security information in SOAP request headers to the service.

You could do so as follows:

 <script> 
   var service = bevocal.soap.serviceFromWSDL(
 "http://cafe.services.bevocal.com/CDRAccessService_v2/services/CDRAccessServic
e_v2?WSDL",
     "CDRAccessService_v2", 
     "http://www.bevocal.com/soap/services", 
     "CdrAccessService", 
 "http://cafe.services.bevocal.com/CDRAccessService_v2/services/CDRAccessServic
e_v2" 
   );
 
   service._addHeader(
     "http://www.bevocal.com/soap/headers/", 
     "platformServicesSessionID", 
     "ACB035CB-C307-472e-99BA-3D5B8468BB76");
 
   ...
 </script>

After the call to _addHeader, SOAP headers using that proxy object would include this information:

 <soapenv:Header>
   <ns1:platformServicesSessionID 
       xsi:type="xsd:string"
       xmlns:ns1="http://www.bevocal.com/soap/headers/" >
     ACB035CB-C307-472e-99BA-3D5B8468BB76
   </ns1:platformServicesSessionID>
 </soapenv:Header>

bevocal.cookies.addClientCookie

Extension.Sets a cookie on the VXML client. The created cookie is treated as HTTP cookies and is passed over the subsequent fetches in the application. The cookie lasts for the duration of the call or the session.

Syntax

 bevocal.cookies.addClientCookie(
   String domain, 
   String key, 
   String value, 
 )

Parameters

Parameter	Description
domain	A valid domain. If a valid domain is passed, the created cookie is passed as a HTTP header for subsequent fetches matching the same domain.
key	The name of the cookie
value	The value of the cookie.

See Also

Example

This example demonstrates the bevocal.cookies.addClientCookie, bevocal.cookies.deleteClientCookie, bevocal.cookies.getClientCookie, and bevocal.cookies.getClientCookies methods.

Note that the first two cookies are sent as HTTP cookies because the domain parameter is set to cafe.bevocal.com.

 <!-- clientcookies.vxml -->
 
 <?xml version="1.0" encoding="iso-8859-1"?>
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" 
 xmlns:bevocal="http://www.bevocal.com/">
 <var name="user_1"/>
 <var name="user_2"/>
 <var name="user_3"/>
 <var name="user"/>
 <form id="form1">
 <block>
 <prompt>Testing client cookies</prompt>
 <script>
 bevocal.log("setting cookies now");
 bevocal.cookies.addClientCookie("cafe.bevocal.com", "user_1", "1234");
 bevocal.cookies.addClientCookie("cafe.bevocal.com", "user_2", "hello world");
 bevocal.cookies.addClientCookie(null, "user_3", "xyz123");
 
 user_1 = bevocal.cookies.getClientCookie(null, "user_1");
 user_2 = bevocal.cookies.getClientCookie(null, "user_2");
 user_3 = bevocal.cookies.getClientCookie(null, "user_3");
 bevocal.log("user_1 = " + user_1 + "; user_2 = " + user_2 + "; user_3 = " + 
 user_3);
 
 user = bevocal.cookies.getClientCookies(null);
 bevocal.log("The value from map is " + user.get("user_1"));
 </script>
 </block>
 <block>
 <prompt><value expr="user_1"/><value expr="user_2"/><value expr="user_3"/>
 </prompt>
 <goto next="clientcookies_2.vxml"/>
 </block>
 </form>
 </vxml>
 
 <!-- clientcookies 2.vxml -->
 
 <?xml version="1.0" encoding="iso-8859-1"?>
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" 
 xmlns:bevocal="http://www.bevocal.com/">
 <var name="user_2"/>
 <form id="form1">
 <block>
 <prompt>Testing client cookies in second document </prompt>
 <script>
 user_2 = bevocal.cookies.getClientCookie(null, "user_2");
 bevocal.log("user_2 = " + user_2);
 bevocal.cookies.deleteClientCookie("user_2");
 </script>
 </block>
 <block>
 <prompt><value expr="user_2"/></prompt>
 <goto next="clientcookies_3.vxml"/>
 </block>
 </form>
 </vxml>
 
 <!-- clientcookies_3.vxml -->
 
 <?xml version="1.0" encoding="iso-8859-1"?>
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" 
xmlns:bevocal="http://www.bevocal.com/">
 <var name="user_2"/>
 <var name="user_3"/>
 <form id="form1">
 <block>
 <prompt>Testing client cookies in third document </prompt>
 <script>
 user_2 = bevocal.cookies.getClientCookie(null, "user_2");
 user_3 = bevocal.cookies.getClientCookie(null, "user_3");
 bevocal.log("user_2 = " + user_2 + "; user_3 = " + user_3);
 </script>
 </block>
 <block>
 <prompt><value expr="user_2"/><value expr="user_3"/></prompt>
 </block>
 </form>
 </vxml>

bevocal.cookies.deleteClientCookie

Extension.Deletes a cookie on the VXML client.

Syntax

 bevocal.cookies.deleteClientCookie(
   String domain, 
   String key, 
 )

Parameters

Parameter	Description
domain	A valid domain. If a valid domain is passed, a cookie with name key that matches the domain is deleted. Otherwise, a cookie with that name is deleted.
key	The name of the cookie

See Also

Example

See bevocal.cookies.addClientCookie

bevocal.cookies.getClientCookie

Extension. Gets the value of a cookie.

Syntax

 bevocal.cookies.getClientCookie(
   String domain, 
   String key, 
   )

Parameters

Parameter	Description
domain	A valid domain. If a valid domain is passed, a cookie with name key that matches the domain is returned. Otherwise, a cookie with that name is returned.
key	The name of the cookie

See Also

Example

See bevocal.cookies.addClientCookie

bevocal.cookies.getClientCookies

Extension. Returns a HashMap of all key/value cookie pairs.

Syntax

 bevocal.cookies.getClientCookies(
   String domain, 
   )

Parameters

Parameter	Description
domain	A valid domain. If a valid domain is passed, cookies matching that domain are returned. Otherwise, all cookies are returned.

See Also

Example

See bevocal.cookies.addClientCookie

bevocal.decrypt

Extension. The BeVocal VXML Interpreter decrypts the text (in HEX format) using the private key using the RSA/ECB/OAIPPadding algorithm. This public/private encryption has been tested with Bouncy Castle's implementation of JCE. The decrypted text is returned in clear text.

Syntax

 bevocal.decrypt(
   String text, 
   String privateKey, 
   )

Parameters

Parameter	Description
text	Text to be decrypted (in HEX format).
privateKey	Private key to be used for decryption.

See Also

bevocal.encrypt

Extension. The BeVocal VXML Interpreter encrypts the text using this public key using the RSA/ECB/OAIPPadding algorithm. This public/private encryption has been tested with Bouncy Castle's implementation of JCE. The encrypted text is returned in HEX format.

Syntax

 bevocal.encrypt(
   String text, 
   String publicKey, 
   )

Parameters

Parameter	Description
text	Text to be decrypted (in HEX format).
publicKey	Public key to be used for encryption.

See Also

bevocal.enroll.removeEnrolledPhrase

Extension. Deletes enrolled phrases from grammars.

Syntax

 bevocal.enroll.removeEnrolledPhrase(grammar, speakerid, phraseid, key, 
xml:lang)

Parameters

Parameter	Description
grammar	The name of the grammar containing the enrolled phrase to delete. Required.
speakerid	The id of the speaker who enrolled the phrase to be deleted. Required.
phraseid	The id of the phrase to be deleted. Required.
key	The security key for accessing the specified enrollment grammar. Optional when running on the BeVocal Café. (You must pass a key argument, but it can be null or an empty string). Required when running in other environments such as Enterprise Hosting.
xml:lang	The language of the enrolled phrase to delete. Optional. The value of this attribute must be the same as the value of the xml:lang attribute of the <vxml> tag for the document.

Description

If you are using enrollment to maintain a voice address book or other dynamic lookup mechanism, you need to be able to delete phrases from the grammar in addition to adding them.

bevocal.getProperty

Extension. Gets the value of a VoiceXML property.

Syntax

 bevocal.getProperty(String name)

Parameters

Parameter	Description
name	The name of the property.

Returns

The value of the specified property in the current scope.

bevocal.getVersion

Extension. Returns the VoiceXML interpreter version.

Syntax

 bevocal.getVersion()

Parameters

None.

Returns

The version number of the VoiceXML interpreter, as a string. Currently, this function always returns "2.4".

bevocal.log

Extension. Writes a message to the BeVocal Café website.

Syntax

 bevocal.log(String message)

Parameters

Parameter	Description
message	The message to be written to the website.

Description

The log function writes the specified message to the BeVocal Café call log, which you can view on the Café website. This function performs the same operation as a <log> VoiceXML element with no label or expr attribute.

bevocal.soap.serviceFromWSDL

Extension. Method of the bevocal.soap object. Given the URL for a WSDL file, create an object to act as a proxy for one of the services described in the file.

This is the preferred way to create a service proxy object. The WSDL file allows the interpreter to pre-load the proxy object with information about all of the service's methods and their parameter types, making the mapping from JavaScript types to SOAP encodings much more accurate.

Syntax

 bevocal.soap.serviceFromWSDL(
   String WSDLUrl, 
   String port, 
   String svcNamespace, 
   String svcName, 
   String endpointURL
 )

Parameters

Parameter	Description
WSDLUrl	The URL of the WSDL file describing this service. Information on the endpoint, method names, argument types, and namespaces will be retrieved from the file.
port	The port name of the service, as given in a <port name="..."> element inside the <service> element for the service.
svcNamespace	The namespace used on the <service> element for the desired service. If the <service> element does not have its own namespace (that is, it does not have its own xmlns attribute), use the value of the targetNamespace attribute from the WSDL file's <definition> element. If neither of these is present, leave the parameter blank.
svcName	The name of the service, as given in a <service name="..."> element for the service.
endpointURL	Optional. If provided, the SOAP endpoint for this service. If this parameter is not provided, the endpoint retrieved from the WSDL will be used.

Error Handling

If an error occurs while locating a SOAP service or creating a SOAP proxy object, an exception of type bevocal.soap.SoapException will be thrown. Possible errors include:

See Also

bevocal.soap.serviceFromEndpoint

Extension. Method of the bevocal.soap object. Given the name and endpoint URL of a SOAP service, create an object to act as a proxy for the service. This method should be used only when the WSDL for a service is not available, since the proxy it creates does not have information on method names and parameter types available, and thus has to make more assumptions when it makes SOAP method calls.

Syntax

 bevocal.soap.serviceFromEndpoint(
   String endpointURL, 
   String svcNamespace, 
   String svcName
 )

Parameters

Parameter	Description
endpointURL	The SOAP endpoint for this service.
svcNamespace	The namespace component of the desired service's name.
svcName	The local component of the desired service's name.

Error Handling

If an error occurs while locating a SOAP service or creating a SOAP proxy object, an exception of type bevocal.soap.SoapException will be thrown. Possible errors include:

See Also

Example

To use a temperature service available from www.xmethods.net, go there and see that the WSDL for this service is at http://www.xmethods.net/sd/2001/TemperatureService.wsdl. The content of the WSDL is:

 <?xml version="1.0"?>
 <definitions name="TemperatureService"
     targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl" 
     xmlns:tns="http://www.xmethods.net/sd/TemperatureService.wsdl"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
     xmlns="http://schemas.xmlsoap.org/wsdl/">
   <message name="getTempRequest">
     <part name="zipcode" type="xsd:string"/>
   </message>
   <message name="getTempResponse">
     <part name="return" type="xsd:float"/>
   </message>
   <portType name="TemperaturePortType">
     <operation name="getTemp">
       <input message="tns:getTempRequest"/>
       <output message="tns:getTempResponse"/>
     </operation>
   </portType>
   <binding name="TemperatureBinding" type="tns:TemperaturePortType">
     <soap:binding style="rpc" 
         transport="http://schemas.xmlsoap.org/soap/http"/>
     <operation name="getTemp">
       <soap:operation soapAction=""/>
       <input>
         <soap:body use="encoded" namespace="urn:xmethods-Temperature"
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
       </input>
       <output>
         <soap:body use="encoded" namespace="urn:xmethods-Temperature"
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
       </output>
     </operation>
   </binding>
   <service name="TemperatureService"> 
     <documentation>Returns current temperature in a given U.S. zipcode 
     </documentation>
     <port name="TemperaturePort" binding="tns:TemperatureBinding"> 
       <soap:address 
           location="http://services.xmethods.net:80/soap/servlet/rpcrouter"/> 
     </port> 
   </service>
 </definitions>

The bold lines in the defintion provide the rest of the information you need to create a proxy object for this service in your VoiceXML application:

 <script> 
 <![CDATA[
 var service = 
   bevocal.soap.serviceFromWSDL(
     // WSDL URL
     "http://www.xmethods.net/sd/2001/TemperatureService.wsdl",  
 
     // name attribute of port
     "TemperaturePort", 
 
     // targetNamespace attribute of definitions
     "http://www.xmethods.net/sd/TemperatureService.wsdl", 
 
     // name attribute of service
     "TemperatureService",
 
     // location attribute of soap:address child of port element
     "http://services.xmethods.com:80/soap/servlet/rpcrouter" // 
   );
 ]]> 
 </script>   

bevocal.soap.locateService

Extension. Method of the bevocal.soap object. Uses the BeVocal SOAP service registry to locate either the standard BeVocal SOAP service whose id is serviceId or a particular version of that service. Returns a proxy object that can be used to call its methods.

Currently, there are not services in the BeVocal SOAP service registry.

Syntax

 bevocal.soap.locateService(
   String serviceId, 
   String version
 )

Parameters

Parameter	Description
serviceId	The ID of the SOAP service you wish to locate and create a proxy for.
version	Optional. The desired version of the service. If not present, returns a proxy for the highest-numbered version of the service (if there multiple versions).

Error Handling

If an error occurs while locating a SOAP service or creating a SOAP proxy object, an exception of type bevocal.soap.SoapException will be thrown. Possible errors include:

See Also

bevocal.soap.SoapException

Extension. Exception object. If an error occurs while creating a SOAP proxy object, an exception of type bevocal.soap.SoapException will be thrown. This object has two dynamic properties and a number of constants:

Property	Description
type	String constant. bevocal.soap.SoapException.
message	String. A message describing the reason for the exception.
cause	Number. A number giving the reason for the exception. It will be one of the following constants.
BAD_SERVICE_ID	Number constant. The serviceId passed to locateService could not be found in the registry.
BAD_VERSION	Number constant. The version number passed to locateService could not be found in the registry.
INVALID_URL	Number constant. The endpoint or WSDL URL was malformed.
NETWORK_ERROR	Number constant. A network error occurred while accessing the registry or the WSDL file. This can include an error fetching the WSDL file, a timeout error, and so on.
UNKNOWN_ERROR	Number constant. The exact error could not be determined; see the message for details. Currently, errors parsing the WSDL fall into this category; in a future release we hope to split them into a separate category.

Example

 <script>
   var service;
    try {
     service = bevocal.soap.locateService("myservice", "2.0");
   }
   catch (error if error.type == "bevocal.soap.SoapException") {
     if (error.cause == error.BAD_VERSION) {
       service = bevocal.soap.locateService("myservice", "1.0");
     } else {
       throw error;
     }
   }
 </script>

If the exception is not caught in JavaScript code in the <script>, it will propagate to the VoiceXML interpreter and be re-thrown as an error.semantic in VoiceXML.

See Also

bevocal.soap.SoapFault

Extension. Fault object. This object has the following properties:

Property	Description
type	String constant. bevocal.soap.SoapFault.
faultString	String. A message describing the reason for the exception.
faultCode	String. A code describing the reason for the failure. See section 4.4.1 of the SOAP 1.1 specification for details.
faultActor	Number. The serviceId passed to locateService could not be found in the registry.
detailString	String. A String representation of the detail element of the fault. The detail element is present whenever a fault is caused by processing of the Body element.
details	FaultDetails. An object whose properties are the detail elements; that is, the immediate child elements of the detail element in the fault element. See section 4.4 of the SOAP 1.1 specification.
MUST_UNDERSTAND	String constant. SOAP fault code: A child of the SOAP Header element that contained a mustUnderstand attribute equal to "1" was not understood.
VERSION_MISMATCH	String constant. SOAP fault code: The processor found an invalid namespace for the SOAP Envelope.
SERVER	String constant. SOAP fault code: Processing of the call failed due to an error on the server. The failure was not directly related to the contents of the message, and the message may succeed at a later point in time.
CLIENT	String constant. SOAP fault code: Processing of the call failed due to the contents of the message. This failure code is returned when a function is called with invalid parameters, bad data, and so on.

See Also

bevocal.soap.FaultDetails

Extension. FaultDetails object. Essentially, bevocal.soap.FaultDetails is an object whose property names are the local components (without namespaces) of the names of the elements under the details element, and whose property values are the text contents of those elements.

Property	Type	Description
type	String constant	bevocal.soap.FaultDetails
(String)	String	If you try to use a FaultDetails object as a String, the BeVocal interpreter returns a String representation of the details elements. This is intended primarily for debugging.
(Number)	Number	If you try to use a FaultDetails object as a Number, the BeVocal interpreter returns the number of detail elements represented by the FaultDetail object. This is intended primarily for debugging.
element id	String	Given a property name that is the local name (without namespace) of one of the child elements of the details element, the property value is the text contents of the child element.

See Also

Café Home | Developer Agreement | Privacy Policy | Site Map | Terms & Conditions Part No. 520-0001-02 | © 1999-2007, BeVocal, Inc. All rights reserved | 1.877.33.VOCAL