Connector

Overview

The Connector object enables access to external data sources and back-end systems. It provides an open API (Application Programming Interface) for bi-directional data exchange, such that dynamic content can be integrated into the dialog flow. The Connector object can also be used to establish a connection with various other communication channels such as SMS, MMS, e-mail, fax or Web sites.

The Connector object supports three different ways to execute operations against external systems: CGI scripts (Common Gateway Interface - i.e. JSP, ASP, Perl script, etc.), Java programs, and Web services calls.
All of them support the exchange of data through an optional parameter set.
For CGI scripts, parameters are part of the HTTP request and the script needs to return to the connector a result set in a specific XML format that contains the result of the requested operation (e.g. the outcome of a database query).
When using Java code, a simplified bean interface is used to exchange data with getter and setter methods.
Web Service connectors can receive a set of parameters and typically return an XML structure that will be made available to the application through a Variable or Collection object.

Usage examples for the Connector object are:

· Retrieving dynamic content from a content management system

· Accessing information through Web services

· Retrieving customer profiles from CRM (Customer Relationship Management) systems at the beginning of the call and writing back updates after the call has ended

· Making a transaction on a back-end system, e.g. booking a flight

· Sending an e-mail or a text message (SMS) to confirm a transaction

CGI Connectors can use an HTTP proxy, which can be set in a Service object. For more information on this, refer to Default parameters in Chapter 2 – Configuring Servers and Services in the Deployment Guide.

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

The Connector object belongs to the object category Resources.

Dialog Flow Scenario

The following dialog flow shows a database transaction while the caller is logging into a brokerage service. The personal stock portfolio of the caller is retrieved and played back as a list.

Object – Caller		Dialog Flow
		Please wait while I check your data.
		A wait loop audio file is played until the connector has finished.
		Connects to a Java program that accesses a database holding customer data.
		[ Earcon for positive confirmation ]
		Welcome to the brokerage service. Here’s a list of all the companies in your portfolio…

Object Definition

The Definition of the Connector object provides the following sections:

· Connector
To define one or more Connector items.

· Authentication
To define the user ID and password for HTTP authentication, and a certificate URL for HTTPS connections.

· Process Notification
To optionally specify a notification to the caller that the connector processing has started.

· Wait Loop Audio
To optionally specify an audio file that is played back while the connector process is running.

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

Connector

In the Connector section, define at least one Connector Item that will process a CGI script, a Web services call, or a Java program.
The following screenshot shows the definition of a Java connector:

Each Connector Item contains a set of fields. It depends on the type of connector (CGI, Java, or Web Service) which fields need to be filled out.

A connector definition is interpreted as a CGI connector if the Class/Port and WSDL file fields are empty (the Method field is ignored in this case).

It is interpreted as a Java connector if the Class/Port field is filled and WSDL file is empty.

If the WSDL file is filled, it is interpreted as a Web Service connector.

The fields applicable to all types are:

Property	Description
Label	Optional parameter to identify the Connector item in a list.
Layer	Optional parameter to indicate the layer that the Connector item belongs to. For more information on layers, see Chapter 7 – How to Use Layers in the Design Guide or the Layer object in this Object Reference.

The interpretation of the remaining fields depends on the connector type.

Location
Specifies a Resource Locator object.

For CGI scripts, it defines the URL where the script is located.

For Java connectors, it defines the URL where the corresponding JAR files are located. Note that JAR files cannot be retrieved using HTTPS URLs; only HTTP and file URLs are supported.

For Web Service connectors, it defines the URL of the service provider node, in case it is different from the location of the WSDL file. Typically, the location of the service provider node is the same as that of the WSDL file, in which case you can leave this field empty.

File
Specifies a file name.

For CGI scripts, it is the name of the script file.

For Java connectors, it is the name of the JAR file. It is also possible to define a comma-separated list of JAR files.

For Web Service connectors, it is the name of the service provider node, in case it is different from the name of the WSDL file. Typically, the location of the service provider node is the same as that of the WSDL file, in which case you can leave this field empty.

Class/Port
For CGI scripts, this setting is ignored.

For Java connectors, it defines the name of the class, prefixed by its package name, which contains the method to call.

For Web Service connectors, it defines the name of the port to be used. If the WSDL file provides only one port, this field can be left empty.

Method
For CGI scripts, this setting is ignored.

For Java connectors, it defines the method to be called.

For Web Service connectors, it defines the Web service method to be called. If there is more than one method with the same name available at the service endpoint, these methods are distinguished by the name of the input and output message. If this is the case, append the names of the input and output message to the Method field, using colons as separators.
Example: The method to be called is "add". There are two versions available; the WSDL description of the first version is

<wsdl:operation name="add" parameterOrder="num1 num2">

<wsdl:input message="impl:add2NumsRequest" name="add2NumsReq"/>

<wsdl:output message="impl:add2NumsResponse" name="add2NumsResp"/>

</wsdl:operation>

whereas the description of the second version is

<wsdl:operation name="add" parameterOrder="num1 num2 num3">

<wsdl:input message="impl:add3NumsRequest" name="add3NumsReq"/>

<wsdl:output message="impl:add3NumsResponse" name="add3NumsResp"/>

</wsdl:operation>

If the first version is to be called, the Method field looks as follows:

WSDL location
Specifies a Resource Locator object.

For CGI and Java connectors, this setting is ignored.

For Web Service connectors, it defines the URL of the WSDL file that describes the available Web services of the service provider.

WSDL file
Specifies a file name.

For CGI and Java connectors, this setting is ignored.

For Web Service connectors, it defines the name of the WSDL file.

Class persistence level
For CGI and Web Service connectors, this setting is ignored.

For Java connectors, it defines if class instances of Connector items are to be persisted, either at dialog, service or server instance level:

· None
The server creates a new class instance every time this Connector item is processed.

· Dialog
The server creates a class instance the first time the Connector item is processed and then persists this instance for any subsequent processing of this Connector item during the current dialog session.

· Service
The server creates a class instance the first time any dialog for this service processes this Connector item and then persists this instance at service level.

· Server Instance
The server creates a class instance the first time any dialog for any service uses the JAR file and class defined in the Connector item; the instance is then persisted for any subsequent processing in any dialog of any service.

By default, the Class persistence level option is set to None and a new class instance is created every time the Connector item is processed.

8 Caution: If a connector instance is shared between multiple calls on service or server level an instance of the connector class is stored on that level and shared between multiple threads (one per call). This means that there is concurrency on instance and not just on class level. The implementer of the connector code has the responsibility to ensure thread-safety, which means that the connector should be either stateless or use appropriate synchronization mechanisms to ensure consistency of the state at any time.

HTTP connector timeout
For Java connectors, this setting is ignored.

For CGI and Web Service connectors, it specifies the time after which the request is aborted if no answer is received from the back-end. If the connector takes longer to process than the time specified in this field, an Error – Connector event is activated.
You can select one of the values of the drop-down list or enter a custom value. Custom values are interpreted as seconds. If you leave it at Default, the setting from the corresponding Service object definition is taken. See Processing the Connector Object for interactions with the VoiceXML fetchtimeout property.

Return value
Allows to link a Variable, Collection, or Layer object which will be set to the return value of the connector.

For CGI connectors, the return value is used in two different ways.
In the default mode, the return value is the HTTP return code received from the Web application server that took the request. It can be 200 for successful requests, 404 for "File not found" exceptions, or any other HTTP return code. Note that the return value is set even if the back-end access did not succeed, e.g. in case of a 404 error.
If the connector fails because it runs into the HTTP connector timeout (see above), the return value is set to 999.
When the option Use Simple HTTP Mode is selected, the return value receives the actual return value produced by the CGI script.

For Java connectors, it is the return value of the method called. If the return type of the method is void, the return value is empty and the linked object will not be overwritten.

For Web Service connectors, it is the content of the response. Variable objects are typically used to store the result. Apply the XPath function of the Expression object to examine the result, if desired, or directly use Result Mapping, as described below. Only the first XML node (including all of its child nodes) of the response is accessible for VoiceObjects. The content of this first node is accessible as the return value.

The individual Connector items are processed one after the other in the order in which they are defined. The failure of any one of these can be handled by defining event handling for the event type Error – Connector. For more information, refer to Event Handling in this Object Reference. If no such event handling is defined and a Connector item fails, an error message is played and the dialog ends.

i8 Note: When using Java code within a Connector item, it needs to be kept in mind that this Java code is executed within the same JVM as VoiceObjects Server. Thus the performance of the custom Java code may negatively impact the performance of the server. This also concerns such issues as garbage collection if the custom code creates large numbers of objects.

By default, when calling Java code within a Connector item, it is required to restart the JVM which runs the server to enforce changes made to the JAR file. This can be modified in the configuration file by setting <monitorJarFiles> to true (the default is false). The location for the configuration file is:

../VoiceObjects/Platform/WEB_INF/config/components.xml

If set to true, JAR files are dynamically reloaded if they are referenced via relative file paths denoted as

file:../Resources/

where the relative path starts at the ../VoiceObjects/Platform/WEB-INF directory.

Dynamic JAR reloading using absolute paths only works on Microsoft Windows. Absolute file paths need to be denoted as

file:/C:/MyJavaCode/

8 Caution: Using dynamic JAR reloading is discouraged in production environments. Moreover, it only works under certain circumstances. Under Windows, a file cannot be copied or moved over, as an open file handle prevents that. Under UNIX, a file can be copied or moved over, but it will not be reloaded in this case. So in all cases, make sure to copy or move the JAR to a new filename, adjust the Resource Locator definition in the Connector object and redeploy the application. In addition, dynamic JAR reloading does not work when the JAR file is referenced using an HTTP or file URI.

Use Simple HTTP mode

For Java and Web Service connectors, this setting is ignored.

For CGI connectors it indicates that instead of using the XML data format described in Exchanging Data via an XML API, the parameters defined in the Parameter Set are sent as simple HTTP POST parameters. In this case the single return value of the CGI script is assigned to the Return Value instead of the HTTP response code.

Parameter Set

The Parameter Set section of a Connector Item enables the exchange of processing information with the CGI, Web Service or Java connector. Possible parameter types are constants, Resource Locator, Variable, Collection, Expression, Layer, and Script objects. The parameter set is optional.

Any number of parameters can be exchanged with a connector. Note that writing parameters back is only possible for CGI and Java connectors. Web Service connectors can only return values through the Return value object.

When working with a CGI script, the Alias/Property field is optional (except for constants) and can be used to assign a name to the parameter by which it can be referenced within the script. If the field is left empty, the reference ID of the respective object is used. For constants, providing an alias is required (otherwise they will not be passed to the script).

The paragraph Exchanging Data via an XML API explains how the CGI script can pass back data.

When working with a Web Service connector, the exact usage of the parameter set depends on the type of input parameters that are expected by the Web Service (based on the WSDL). If the input parameters consist of a sequence of simple types, each of the input parameters can be specified as a separate item in the parameter set. If one of the input parameters has a complex type, only one item is defined in the parameter set. In this case the single parameter contains the complete XML structure (the request message) that is part of the SOAP body. This XML structure will directly be copied into the SOAP body. The following two examples show the details for both scenarios.

Example 1 (with simple types):

This is an example for a WSDL with an operation that only uses simple data types as input parameters.

<?xml version="1.0" encoding="utf-8"?>

<wsdl:definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:tns="http://www.voiceobjects.com/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

targetNamespace="http://www.voiceobjects.com/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

<wsdl:types>

<s:schema elementFormDefault="qualified" targetNamespace="http://www.voiceobjects.com/">

<s:element name="MyOperationRequest">

<s:complexType>

<s:sequence>

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter1" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter2" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter3" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter4" type="s:string" />

</s:sequence>

</s:complexType>

</s:element>

<s:element name="MyOperationResponse">

<s:complexType>

<s:sequence>

<s:element minOccurs="0" maxOccurs="1"

name="MyOperationResult" type="tns:ResponseData" />

</s:sequence>

</s:complexType>

</s:element>

<s:complexType name="ResponseData">

<s:sequence>

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue1" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue2" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue3" type="s:string" />

<s:element minOccurs="1" maxOccurs="1"

name="MyResultValue4" type="s:double" />

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue5" type="s:string" />

</s:sequence>

</s:complexType>

</s:schema>

</wsdl:types>

<wsdl:message name="MyOperationSoapIn">

<wsdl:part name="parameters" element="tns:MyOperationRequest" />

</wsdl:message>

<wsdl:message name="MyOperationSoapOut">

<wsdl:part name="parameters" element="tns:MyOperationResponse" />

</wsdl:message>

<wsdl:portType name="MyServiceSoap">

<wsdl:operation name="MyOperation">

<wsdl:input message="tns:MyOperationSoapIn" />

<wsdl:output message="tns:MyOperationSoapOut" />

</wsdl:operation>

</wsdl:portType>

<wsdl:binding name="MyServiceSoap" type="tns:MyServiceSoap">

<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />

<wsdl:operation name="MyOperation">

<soap:operation soapAction="http://www.voiceobjects.com/MyOperation" style="document" />

<wsdl:input>

<soap:body use="literal" />

</wsdl:input>

<wsdl:output>

<soap:body use="literal" />

</wsdl:output>

</wsdl:operation>

</wsdl:binding>

<wsdl:service name="MyService">

<wsdl:port name="MyServiceSoap" binding="tns:MyServiceSoap">

<soap:address location="http://www.voiceobjects.com/ws/MyService.asmx" />

</wsdl:port>

</wsdl:service>

</wsdl:definitions>

The operation MyOperation is expecting an input structure MyOperationRequest that is a sequence of strings (i.e. simple types). The corresponding parameter set would look like this:

Example 2 (with complex types):

This is an example for a WSDL with an operation that uses a complex type as input parameter.

<?xml version="1.0" encoding="utf-8"?>

<wsdl:definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:tns="http://www.voiceobjects.com/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

targetNamespace="http://www.voiceobjects.com/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

<wsdl:types>

<s:schema elementFormDefault="qualified" targetNamespace="http://www.voiceobjects.com/">

<s:element name="MyOperationRequest">

<s:complexType>

<s:sequence>

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter1" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter2" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter3" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyInputParameter4" type="tns:ComplexParameter" />

</s:sequence>

</s:complexType>

<s:element name="ComplexParameter">

<s:complexType>

<s:sequence>

<s:element minOccurs="0" maxOccurs="1" name="A"

type="s:string" />

<s:element minOccurs="0" maxOccurs="1" name="C"

type="s:string" />

<s:element minOccurs="0" maxOccurs="1" name="C"

type="s:string" />

</s:sequence>

</s:complexType>

</s:element>

<s:element name="MyOperationResponse">

<s:complexType>

<s:sequence>

<s:element minOccurs="0" maxOccurs="1"

name="MyOperationResult" type="tns:ResponseData" />

</s:sequence>

</s:complexType>

</s:element>

<s:complexType name="ResponseData">

<s:sequence>

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue1" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue2" type="s:string" />

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue3" type="s:string" />

<s:element minOccurs="1" maxOccurs="1"

name="MyResultValue4" type="s:double" />

<s:element minOccurs="0" maxOccurs="1"

name="MyResultValue5" type="s:string" />

</s:sequence>

</s:complexType>

</s:schema>

</wsdl:types>

<wsdl:message name="MyOperationSoapIn">

<wsdl:part name="parameters" element="tns:MyOperationRequest" />

</wsdl:message>

<wsdl:message name="MyOperationSoapOut">

<wsdl:part name="parameters" element="tns:MyOperationResponse" />

</wsdl:message>

<wsdl:portType name="MyServiceSoap">

<wsdl:operation name="MyOperation">

<wsdl:input message="tns:MyOperationSoapIn" />

<wsdl:output message="tns:MyOperationSoapOut" />

</wsdl:operation>

</wsdl:portType>

<wsdl:binding name="MyServiceSoap" type="tns:MyServiceSoap">

<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />

<wsdl:operation name="MyOperation">

<soap:operation soapAction="http://www.voiceobjects.com/MyOperation" style="document" />

<wsdl:input>

<soap:body use="literal" />

</wsdl:input>

<wsdl:output>

<soap:body use="literal" />

</wsdl:output>

</wsdl:operation>

</wsdl:binding>

<wsdl:service name="MyService">

<wsdl:port name="MyServiceSoap" binding="tns:MyServiceSoap">

<soap:address location="http://www.voiceobjects.com/ws/MyService.asmx" />

</wsdl:port>

</wsdl:service>

</wsdl:definitions>

In this case the operation MyOperation is expecting an input structure MyOperationRequest that contains a complex data type (MyInputParameter4). The complete MyOperationRequest XML structure is defined as one single parameter in the parameter set. The parameter set would look like this:

There is only one single parameter in the parameter set and the Variable object MyOperationRequest contains the following XML structure:

<ns1:MyOperationRequest xmlns:ns1="http://www.voiceobjects.com">

<ns1:MyInputParameter1>value 1</ns1:MyInputParameter1>

<ns1:MyInputParameter1>value 2</ns1:MyInputParameter1>

<ns1:MyInputParameter1>value 3</ns1:MyInputParameter1>

<ns1:MyInputParameter4>

<ns1:ComplexParameter>

<ns1:A>value A</ns1:A>

<ns1:B>value B</ns1:B>

<ns1:C>value C</ns1:C>

</ns1:ComplexParameter>

</ns1:MyInputParameter1>

</ns1:MyOperationRequest>

When working with Java code, the name of a class property (e.g. carMake), which has to be defined based on the Java Bean specification, needs to be specified in the Alias/Property field. In order for the value to be passed to the Java code, a corresponding set method (e.g. setCarMake()) needs to be provided, which is called before the Connector item method is processed. If the Java code also provides a get method (e.g. getCarMake()) for this property, and the entry in the Parameter field is a Variable, Collection or Layer object, this get method is called after the Connector item method has been executed, and the resulting value is assigned to the respective Variable, Layer, or Collection object. Special get and set methods can be provided to pass error codes and messages to the server. See Error Handling for more details on this.

Both the get and the set methods need to be of type public String.

i8 Note: Collection objects are passed to the Java code as an XML string that needs to be interpreted within the Java code itself. Collection values being passed back must also be provided (using the respective getter method) in this XML format. For a definition of the format itself, see the Collection object in this Object Reference.

When using special XML characters within a parameter (like ampersand “&”), make sure to mask them using the correct XML entity (e.g. “&” for “&”).

Note also that with Web Service connectors, only document-style SOAP Web Services are supported. Web Service connectors do not support RPC-style Web Services. If you are calling an RPC-style Web Service, you need to use a custom Java or CGI connector instead, which will call the Web Service method itself and process the return data appropriately.

Result Mapping

The Result Mapping section allows extracting specific values from a CGI, Java or Web Service connector by applying an XPath expression to the return value. Any number of result mappings can be defined. The expression specified in the XPath field will be applied to the return value of the connector. The result of this operation will be assigned to the Variable, Collection or Layer object defined in the Variable field. As XPath is designed to retrieve values from a well-formed XML structure, the Connector item must return such a value. If the Connector item returns nothing or a non-XML value the Error – Internal event is activated.

The Return Value field must not necessarily contain a Variable, Collection or Layer object. The result mapping items will be assigned nevertheless. If this field contains an object, the unchanged return value will be assigned to it.

Example:

Given a Connector item that returns the following XML structure:

</quote>

The following XPath expression can be used to retrieve the last trade value:

/quote[@symbol=”IBM”]/lastTradeValue

The Result Mapping section in the Connector editor would look like this:

When using Web Service connectors, the XML structure that is returned by the service (as defined in the WSDL) is assigned to the return value and can be accessed using the Result Mapping.

In the WSDL examples above a return value can look like this example structure.

<MyResultValue1>Some value</MyResultValue1>

<MyResultValue2>Some other value</MyResultValue2>

</MyOperationResult>

In this example the following XPath expression can be used to retrieve the value of MyResultValue1:

/MyOperationResult/MyResultValue1

More information about XPath can be found at http://www.w3.org/TR/xpath.

Only the first XML node (including all of its child nodes) of the response is accessible for VoiceObjects. The content of this first node is the top-level node for the XPath expressions (MyOperationResult in the example above).

Authentication

In the Authentication section the user ID and password for the HTTP authentication are specified, plus an optional certificate URL for HTTPS connections.

For Java connectors, the settings made in the Authentication section are ignored.

For CGI and Web Service connectors, define a user ID and password that will be used for single sign-on HTTP authentication, in case the Web application server or Web service provider requires this. If authentication fails, a corresponding HTTP return code will be made available through the return value of the Connector item definition. At the same time, an Error – Connector event is activated.
If the connection is via the HTTPS protocol, a URL to a certificate must be provided. This URL can itself only use the HTTP or FILE protocol. Note that if more than one Connector item is specified in the Connector item list of a Connector object, the same certificate URL will be applied to all items. If different certificates are required, different Connector objects must be defined.

Note that User ID and Password can also be defined using e.g. Variable objects that are filled by an external configuration using Application Defaults. See the corresponding section in Chapter 4 – Service Deployment of the Deployment Guide for details.

Process Notification

In the Process Notification section, an embedded Output object can be specified that gives the caller a notification that the connector 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 connector process is running. This parameter is optional and only applies to the voice and video channel. It is typically used for time-consuming connector operations, e.g. to play hold music.

For further details on the possible settings, 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 Connector object. On other platforms, an audio file that is shorter than the processing time required by the connector 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.

Processing the Connector Object

This section contains some technical remarks on the treatment of Connector objects in VoiceObjects Server.

For each Connector object used in the voice or video channel, the server sends a VoiceXML document (a single one for all Connector items) to the media platform, even though there is no interaction with the caller. The document consists of a <submit> element including the fetchaudio attribute. If a wait loop audio is specified for the object, the audio is mentioned in this attribute, so that the platform plays this file while the connector is processed. Any output defined before the Connector object (either in the Process Notification section within the object, or in Output objects prior to the Connector object in a sequence) will be "flushed" by the platform, i.e. played back before the wait loop audio is applied, which is a desirable effect. To achieve this effect even if no wait loop audio is defined, the server renders a reference to an empty audio file (taken from the system resource folder of the VoiceObjects installation) in the fetchaudio attribute. Without this "flush" effect, a media platform might withhold the output defined prior to the Connector object until the connector has been processed, which would result in undesirable delays.

At the same time, a fetchtimeout attribute is rendered and set to the value of 10000s (ten thousand seconds). The effect of this is that the media platform is forced to wait until the connector has been processed and does not try to request another VoiceXML document from the server before the connector has been processed. If it did, the server would reject the request. Note that due to this, any user-defined setting of fetchtimeout (e.g. through the tuning property Resource Fetching – Fetch Timeout) will be ignored for CGI and Web Service connectors. If you want to define a timeout value for these connectors, use the HTTP connector timeout setting instead.

In the text and Web channel, there will be no intermediate page rendered, unless there is a process notification defined which is rendered as a standalone output.

Exchanging Data via an XML API

In the case of CGI scripts, data is usually exchanged by means of an XML API. There are two different types of XML:

· Request XML

· Result XML.

For simpler cases, there is the lightweight Simple HTTP Mode in which parameters are passed as normal HTTP POST parameters, and a single return value can be provided by the CGI script. This return value may either be a string, or a collection structure that can then also use Result Mapping to be inspected and assigned to other variables.

Request XML

The Request XML is generated by the server and contains processing information like the dialog ID (a globally unique string created by the server that identifies the dialog session), the ANI (Automated Number Identification), the DNIS (Dialed Number Identification Service) and the optional parameters from the parameter set.

The Request XML is sent via the HTTP connection method POST. The CGI program needs to extract the request information string via the request parameter OVAPRequest. VoiceObjects provides a framework for Java Servlets that encapsulates the extraction of the request parameter (refer to CGI Connector Framework for further details).

The XML consists of a single <root> … </root> block containing any number of rows encapsulated in <row> … </row> tags. Each row contains one parameter to be transmitted to the CGI script. Within each row, there are four columns providing the relevant aspects of the parameter:

· <col name=”type”> … </col>
Provides the type of the parameter, which can be expression, variable, collection, layer, or constant. Note that Resource Locator and Script objects are categorized under expression (see examples below).

· <col name=”name”> … </col>
Provides the name of the object that is passed. This column is empty for constants.

· <col name=”referenceID”> … </col>
Provides the reference ID or the alias (if defined) of the object that is passed. For constants, it provides the alias specified in the Alias/Property field of the parameter set.

· <col name=”value”> … </col>
Provides the value of the object that is passed, wrapped in CDATA[]. In the case of collections, this value is an XML structure itself. See the Collection object in this Object Reference for a definition of the structure.

The XML always contains general information about the dialog, including the dialog ID, the ANI, and the DNIS.

Below is an example of a Request XML with an empty parameter set definition:

<?xml version="1.0" encoding="ISO-8859-1"?>

<root>

<row>

<col name="type">expression</col>

<col name="name">dialogID</col>

<col name="referenceID">dialogID</col>

</row>

<row>

<col name="type">expression</col>

</row>

<row>

<col name="type">expression</col>

</row>

</root>

</request>

Any number of constants or Variable, Expression, Collection, Script or Layer objects can be transmitted to the script. To transfer them to the CGI script, they need to be defined in the parameter set of the Connector object.

Each constant in the parameter set creates a block of the following form in the Request XML:

<row>

<col name="type">constant</col>

<col name="referenceID">YearOfBirth</col>

</row>

Note that constants do not have names. The alias defined in the parameter set is provided in the column referenceID.

Each Variable object in the parameter set creates a block of the following form in the Request XML:

<row>

<col name="type">variable</col>

<col name="name">MyVariable</col>

<col name="referenceID">myvariable</col>

</row>

Each Expression object in the parameter set creates a block of the following form in the Request XML:

<row>

<col name="type">expression</col>

<col name="name">MyExpression</col>

<col name="referenceID">myexpression</col>

</row>

Each Collection object in the parameter set creates a block of the following form in the Request XML:

<row>

<col name="type">collection</col>

<col name="name">MyCollection</col>

<col name="referenceID">mycollection</col>

</row>

Each Script object in the parameter set creates a block of the following form in the Request XML:

<row>

<col name="type">expression</col>

<col name="name">MyScript</col>

<col name="referenceID">myscript</col>

</row>

Each Layer object in the parameter set creates a block of the following form in the Request XML:

<row>

<col name="type">layer</col>

<col name="name">MyLayer</col>

<col name="referenceID">mylayer</col>

<![CDATA[The active states of the layer.]]>

</col>

</row>

Each Resource Locator object in the parameter set creates a block of the following form in the Request XML (note that only the URL is passed to the connector):

<row>

<col name="type">expression</col>

<col name="name">MyResourceLocator</col>

<col name="referenceID">mylocator</col>

</row>

The following is an example of a request with a Variable object and an Expression object added to the parameter set.

<?xml version="1.0" encoding="ISO-8859-1"?>

<root>

<row>

<col name="type">expression</col>

<col name="name">dialogID</col>

<col name="referenceID">dialogID</col>

</row>

<row>

<col name="type">expression</col>

</row>

<row>

<col name="type">expression</col>

</row>

<row>

<col name="type">variable</col>

<col name="name">Variable</col>

<col name="referenceID">myvariable</col>

<col name="value">abcde</col>

</row>

<row>

<col name="type">expression</col>

<col name="name">Expression</col>

<col name="referenceID">myexpression</col>

</row>

</root>

</request>

Result XML

The CGI script may assign return values to any (or all) of the Variable, Layer, or Collection objects transmitted to it. Note that it is not possible to assign a return value to a Variable, Layer, or Collection object that is not part of the parameter set. It is also not possible to assign return values to constants or Expression and Script objects. To assign a return value to a Variable, Layer, or Collection object, the respective reference ID or alias is used.

For each assignment, two lines in the result XML are required: One to provide the reference ID of the respective Variable, Layer, or Collection object, and one to provide the value.

As an example, the following XML assigns 128 to the variable with reference ID myvariable, and the table ((John,Smith),(Bob,Miller)) to the collection with reference ID mycollection.

<?xml version="1.0" encoding="ISO-8859-1"?>

<root>

<row>

<col name="referenceID">myvariable</col>

</row>

<row>

<col name="referenceID">mycollection</col>

<col name="value"><![CDATA[

<root>

<row>

<col name="last_name">Smith</col>

</row>

<row>

<col name="last_name">Miller</col>

</row>

</root>]]></col>

</row>

</root>

<error>

<message>No error</message>

</error>

</result>

Error Handling

For CGI and Java connectors, VoiceObjects provides a way to define error codes and messages within the connector and retrieve them later in the dialog using event handling and the two Expression functions ERRORCODE and ERRORMESSAGE. This allows you to catch errors and take appropriate actions at call time, like playing error messages to the caller or writing code and messages to a log file or database.

Note that Web Service connectors do not support this. The value of the two functions will not be changed in case of an error; only the return value will be set to the HTTP error code if an object is specified in the Return value field of the Connector item definition.

Error codes can be used in event handling to define specific handlers for certain error types. An event handler of type Error – Connector is activated if an error code above 0 (zero) is returned to the application. For more information on this, refer to Event Handling in this Object Reference.

The definition of the error code and message depends on the connector type.

Java connectors

If the connector is a Java program, error codes and error messages can be set using the two getter methods public String getErrorCode() and public String getErrorMessage(), respectively. The return value of getErrorCode should be a positive number that is associated with a certain (custom) type of error. The error code 0 (zero) and codes below 0 indicate that no error occurred. The return value of getErrorMessage is an arbitrary string.

CGI connectors

If the connector is a CGI script, error codes and error messages can be set within an explicit error handling section in the Result XML. This section starts with the tag <error> and contains two sub-tags

· <code> defining the code for the error.

· <message> defining the message for the error.

The code should be a positive number that is associated with a certain (custom) type of error. The error code 0 (zero) and codes below 0 indicate that no error occurred. The message is an arbitrary string.

8 Caution: When using the HTTP connector, make sure that the back-end system that is being called does not close the socket being used for the request while leaving the HTTP session itself open. This can lead to subsequent problems since open HTTP sessions are pooled for re-use. When closing the socket, always close the HTTP session, too.

CGI Connector Framework

To ease development of Java Servlet-based back-end connectivity via a CGI Connector, VoiceObjects provides the CGI Connector Framework that provides an easy way to implement Java-based back-end connectivity without having to deal with the details of Servlets and JSPs.

The CGI Connector Framework is located in the Platform\Resources\CGIConnector directory of your VoiceObjects installation. This directory contains a Web application that can be deployed to a Java Web application server. It includes the source code of two sample connectors that can be found in the subdirectory \Sources\SampleConnector in the CGIConnector directory.

To implement the Java part of a new CGI Connector, a Java class has to be implemented that extends the class com.voiceobjects.connector.util.ConnectorServlet. The new class needs to implement the method:

public ConnectorResult perform(HttpServletRequest servletRequest,

Map<String, ConnectorParameter> parameterMap)

This method is expecting two parameters – the original Servlet request that is received by the Web application server and a map containing the parameters sent by the VoiceObjects Connector object. In this map, reference IDs of the parameters are mapped to the actual parameters (instances of ConnectorParameter). This allows easy access to the parameters.

The method returns a ConnectorResult containing the return parameters for the VoiceObjects Connector object, the error code, and the error message.

A JavaDoc documentation of the framework classes can be found in the subdirectory \doc in the CGIConnector directory.

The following code is an excerpt of the GetSingleStockQuote example implementation. The full source code can be found in the \Sources\SampleConnector directory.

The example shows the implementation of the perform method for a connector that is using two parameters – stockName and stockValue. The example shows how the framework classes can be used to get the connector parameters, check the types of the parameters, and to assemble the result values.

The GCIConnector directory also contains the source code of another example (GetMultipleStockQuotes) using collections as input and output parameters.

If the CGIConnector directory is deployed to your Java Web application server, the sample connectors are available at http://server:port/CGIConnector/GetSingleStockQuote and http://server:port/CGIConnector/GetMultipleStockQuotes

“server” and “port” need to be substituted by the appropriate values for your application server.

To implement the HTTP server side for a CGI Connector using the CGI Connector Framework, the following steps are required:

1. Implement a Java class that extends com.voiceobjects.connector.util.ConnectorServlet. As shown above, this class receives the connector parameters and connects to your back-end system.

2. Compile the class and put the class files into the subdirectory \WEB-INF\classes in the CGIConnector directory. Alternatively you can create a jar file and put it into the subdirectory \WEB-INF\lib.

3. Edit the file web.xml in the subdirectory \WEB-INF in the CGIConnector directory. Add a servlet and a servlet-mapping section for your new class (see below for an example).

4. Deploy the CGIConnector directory to your Java Web application server.

The following example shows the web.xml file for the sample connector implementations.

i8 Note: The CGI Connector framework requires version 6 of the Sun Java Runtime Environment.

To test the HTTP server side for a CGI Connector, the CGI Connector Framework contains the VoiceObjects Backend Launcher, which is a HTML testing page. The file is called test.html and is located in the CGIConnector directory. If the CGIConnector directory is deployed to a Java Web application server, the test page can be reached at http://server:port/CGIConnector/test.html.

The Backend Launcher allows specifying the path of the Servlet to be tested and a set of parameters that will be sent to the Servlet. For each parameter, name, type, and value can be specified. The following example shows how the Backend Launcher can be used to call the GetMultipleStockQuotes sample implementation.

By clicking the plus button (+) you can add additional parameters; clicking the minus button (-) removes them. Show Request shows the request XML structure that will be sent to the Servlet. Submit sends the actual request.

Based on the sample implementation the request that is shown in the example above will return the following result:

i8 Note: The Backend Launcher has only been tested with the Mozilla Firefox browser.

Using HTTPS Connectors

When a secure connection to a back-end system is required, you can call a CGI connector using the HTTPS protocol. The Web application server of VoiceObjects Server needs to be adjusted so that HTTPS requests are possible.

The following is an example of necessary changes to the configuration file of a Jetty installation:

1. First, create a keystore by using the java keytool utility.
Example:
keytool -genkey -keystore vokeystore -keyalg RSA

2. Place the generated keystore file in the Jetty home directory.

3.   Within the configuration file VOServer.xml, which is located below the Platform\WEB-INF\etc folder of your VoiceObjects installation, add the following code:

<Call name="addListener">
<Arg>
    <New class="org.mortbay.http.SunJsseListener">
      <Set name="Port">8443</Set>
      <Set name="Keystore">
        <SystemProperty name="jetty.home"
                        default="."/>
        /vokeystore
      </Set>
      <Set name="Password">ABC</Set>
      <Set name="KeyPassword">CDE</Set>
   </New>
</Arg>
</Call>

4. Replace ABC and CDE with the passwords created in the first step.

VoiceObjectsXML Definition

The Connector object is represented by the VoiceObjectsXML element <connector>. It has two attributes and eight groups of children.

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

The <connector> element uses the embedded <connectorItem>, <parameterSet> and <resultMapping> elements.

Connector

Attributes

· user
User ID used for optional HTTP authentication in CGI and Web Service connectors. If authentication fails, a corresponding HTTP return code will be made available through the returnValue of the Connector item definition. At the same time, an Error – Connector event is activated.

· password
The password for the user ID provided in user.

Children

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

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

· +<connectorItem>
Defines the list of Connector items.

· <output>
Defines the “process notification” output for the Connector object.

· <audio>
Defines the wait loop audio. Alternative text for this audio is ignored.

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

· <tuning>
Defines the tuning settings for the Connector object.

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

Example

</parameterSet>

</connectorItem>

</connector>

ConnectorItem

Attributes

· label
A text string providing a name for the Connector item.

· layer
Defines the layer for the Connector item. Can either be a reference to a Collection, Expression, Script, or Variable object; or a layer state reference of the form “Layer=State” or “Layer!=State” where “State” is the label of a state for the layer “Layer”.

· location
Defines the location from where the CGI or JAR file is to be retrieved. Must be a reference to a Resource Locator object.
For Web Service connectors, it defines the URL of the service provider node, in case it is different from the location of the WSDL file. Typically, the location of the service provider node is the same as that of the WSDL file, in which case you can leave this attribute empty.

· file
The file name of the CGI or JAR file. Can be a constant name, or a reference to a Variable, Expression, or Script object.
For Web Service connectors, it is the name of the service provider node, in case it is different from the name of the WSDL file. Typically, the location of the service provider node is the same as that of the WSDL file, in which case you can leave this attribute empty.

· class
For Java connectors, the class name within the JAR file.
For Web Service connectors, it defines the name of the port to be used. If the WSDL file provides only one port, this attribute can be left empty.

· method
For Java connectors, the method name within the class.
For Web Service connectors, it defines the Web service method to be called. If there is more than one method with the same name available at the service endpoint, these methods are distinguished by the name of the input and output message. If this is the case, append the names of the input and output message to the method attribute, using colons as separators.

· wsdlLocation
Defines the URL of the WSDL file that describes the available Web services of the service provider. Must be a reference to a Resource Locator object. Only relevant for Web Service connectors.

· wsdlFile
Defines the name of the WSDL file. Only relevant for Web Service connectors.

· persist
Defines whether the class should be persisted, and if so at which level. Only relevant when using a Java connector. Legal values are none, dialog, service, server. If not specified, defaults to none.

· timeout
For CGI and Web Service connectors, it specifies the time after which the request is aborted if no answer is received from the back-end. If the connector takes longer to process than the time specified in this field, an Error – Connector event is activated. If you leave it at Default, the setting from the corresponding Service object definition is taken.

· returnValue
For CGI connectors, the return value is the HTTP return code received from the Web server that took the request. It can be 200 for successful requests, 404 for "File not found" exceptions, or any other HTTP return code. Note that the return value is set even if the back-end access did not succeed, e.g. in case of a 404 error.
For Java connectors, it is the return value of the method called. If the return type of the method is void, the return value is empty and the linked object will not be overwritten.
For Web Service connectors, it is the content of the response. Variable objects are typically used to store the result. Apply the XPath function of the Expression object to examine the result, if desired.
Must be a reference to a Variable or Collection object.

Children

· <parameterSet>
Defines the parameter set for the Connector item.

· <resultMapping>
Defines the result mapping for the Connector item.

Example

</parameterSet>

</connectorItem>

</parameterSet>

</connectorItem>

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 under which the parameter is accessible in the external code.

Example

ResultMapping

Children

· +<resultMappingItem>
Defines the list of entries in the result mapping. Both the object and value attribute must be defined.

Example

</resultMapping>

ResultMappingItem

Attributes

· object
Defines a reference to a Variable, Collection or Layer object.

· value
Defines the XPath expression that will be applied to the return value. The result of this expression will be assigned to the object under object.

Example

Object Interoperability

The following table contains all object types that can refer to a Connector object:

Icon	Object Name	Use Case Example
	Module	A Connector object can be used within the embedded sequence of a Module object.
	Sequence	Most commonly, a Connector object is used within a Sequence object in a dialog flow.
	Menu	A Connector object can be used as the destination object within a Menu item in a Menu object.
	Confirmation	A Connector object can be used as the destination object within a Correction item inside a Confirmation object. While technically possible, this is not typically useful.
	If	A Connector object can be used within either the THEN or the ELSE item of an If object.
	Case	A Connector object can be used in any WHEN item of a Case object.
	Loop	A Connector object can be used within the embedded sequence of a Loop object.
	Goto	A Connector object can be referenced via a Goto object.
	Hyperlink	A Connector object can be the destination of a Hyperlink object.

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 name of a Connector object should indicate the task it performs. The short description should contain a brief explanation of the data exchanged, as well as assumptions and restrictions. The long description should give a full description of the parameters exchanged in the Connector object, indicating whether they are read, write, or read/write. In case of finite value sets, these should also be listed (e.g. Variable can have the values yes, no, or maybe). The table below lists three examples:

Name	Description
Retrieve caller profile	Retrieves caller profile from database based on ANI. The profile is provided in the Collection object Caller Profile.
Obtain flight options	Retrieves list of possible flight connections from back-end, based on date, time, origin, and destination. Note that the list may be empty.
Store caller preferences	Writes the modified caller preferences (persona, output style, barge-in setting) to the database.