In the first two parts of this series about back-end integration with VoiceObjects we have seen an overview of the different approaches that are available with VoiceObjects 9.1 as well as a detailed examination of the Java Connector. Now, in this third part, we will take a closer look at the CGI Connector.
Basics
The basic idea of the CGI Connector is that you implement an integration layer that provides an HTTP interface for the VoiceObjects Server. To communicate with the back-end system, the VoiceObjects Server sends an HTTP POST request to your integration layer, which talks to the beck-end and sends an HTTP response back to the VoiceObjects Server. The integration layer is typically deployed on a separate web server.
As the communication between VoiceObjects Server and the integration layer is plain HTTP, there are no restrictions or constraints to use a specific programming language, framework, technology for the implementation of the integration layer (Java Servlets, PHP, Perl, ASP, …) – it’s completely up to you.
For the integration layer’s HTTP interface, two different CGI Connector options are available – an XML API and a simple plain HTTP mode.
- XML API: In this mode, the VoiceObjects Server sends one single HTTP parameter called OVAPRequest, which contains an XML structure (request XML). This XML structure contains all parameters that are defined in the VoiceObjects Connector object. The response of the integration layer contains an XML structure (result XML) with all return values, error code, and error message. All of these will automatically be assigned to the appropriate objects in the VoiceObjects application. Request XML and result XML have a predefined structure (see the VoiceObjects Object Reference Guide).
- Simple HTTP mode: In this mode, the VoiceObjects Server sends each parameter that is defined in the VoiceObjects Connector object as a single HTTP POST parameter. The integration layer can return an arbitrary value (e.g. XML documents or plain text). The interpretation and/or parsing of this return value is left to the VoiceObjects application.
A very basic implementation of the integration layer using PHP and simple HTTP mode can look like this.
This code expects 2 HTTP POST parameters – myFirstParam and mySecondParam. It just adds the values of both parameters and returns the sum as the result (as a single plain text result value).
How it works (using XML API)
Now, let’s take a look at how you can pass your parameters to your integration layer and retrieve the return values using the XML API.
First, you create your integration layer that accepts HTTP requests from the VoiceObjects Server, processes the parameters, communicates with your back-end system and returns result values (for XML API, a Java Servlet based framework is available that allows an easy implementation of the CGI layer – see below for an example).
Now, you create a Connector object in your VoiceObjects application that will use the integration layer. The following figure shows an example based using the CGI Connector in XML API mode.
Here are the key things you need in your Connector object (also see the documentation of the Connector object in the VoiceObjects Object Reference Guide):
- Location: a Resource Locator pointing at the location of your integration layer (e.g. http://myIntegrationServer/CGIConnector/)
- File: the name of the CGI script, Servlet, JSP, ASP you are calling
- Parameter Set: a list of parameters you want to exchange with your integration layer. For each parameter, enter the parameter ID that the integration layer is expecting in the Alias/Property filed. If you leave if empty, the Reference ID of your parameter object will automatically be sent as the parameter ID.
You also might want to set the HTTP connector timeout value. This defines the maximum time the Connector object will be waiting for a response from your integration layer. The default value is defined at the Service level. You can also access the HTTP status code if required by linking a Variable object to the Return value field. The status code will be assigned to that Variable object.
When the Connector object is executed in XML API mode, it sends an HTTP POST request to the URL that is constructed out of the values in the Location and File fields. The HTTP POST will contain one single parameter OVAPRequest and the value of that parameter will be an XML structure containing the parameters from your parameter list.
Here is an example request XML (for more information about the XML structures, please see the documentation of the Connector object in the VoiceObjects Object Reference Guide):
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<root>
<row>
<col name=”type”>expression</col>
<col name=”name”>dialogID</col>
<col name=”referenceID”>dialogID</col>
<col name=”value”><![CDATA[OVAPac16172d000000000000058e000000f490ffef8b]]></col>
</row>
<row>
<col name=”type”>expression</col>
<col name=”name”>ANI</col>
<col name=”referenceID”>ANI</col>
<col name=”value”><![CDATA[12345]]></col>
</row>
<row>
<col name=”type”>expression</col>
<col name=”name”>DNIS</col>
<col name=”referenceID”>DNIS</col>
<col name=”value”><![CDATA[4085371847]]></col>
</row>
<row>
<col name=”type”>variable</col>
<col name=”name”>Company Stock Symbol</col>
<col name=”referenceID”>stockName</col>
<col name=”value”><![CDATA[GOOG]]></col>
</row>
<row>
<col name=”type”>variable</col>
<col name=”name”>Stock Quote</col>
<col name=”referenceID”>stockPrice</col>
<col name=”value”><![CDATA[]]>
</col>
</row>
</root>
</request>
As you can see, there is one row element per parameter item. In addition to the parameter items that you define in your parameter set, the dialog ID, the ANI, and the DNIS of the current session will always be sent automatically. In the col element with name=”referenceID” you will find the name you entered in the Alias/Property field of your parameters. This is used to identify your parameters.
Now, the integration layer has to parse this XML structure, extract all values it needs to process the request and communicate with the back-end system and finally send a result XML containing the result values back to the VoiceObjects Server. This is an example for a result XML:
<?xml version=”1.0″ encoding=”UTF-8″?>
<result>
<root>
<row>
<col name=”referenceID”>stockPrice</col>
<col name=”value”><![CDATA[509.42]]></col>
</row>
</root>
<error>
<code>0</code>
<message>No error</message>
</error>
</result>
So in this case, the parameter with the referenceID stockPrice is returned to the Connector object which assigns the value to the Variable object in your parameter list accordingly (the one where we entered stockPrice in the Alias/Property field). In the error node, the result XML contains an error code and an error message. These are treated the same way as the error code and error message that we already saw with the Java Connector. The error codes 0 (Zero) and below 0 indicate that no error occurred. Values above 0 indicate an error and will trigger an Error-Connector in VoiceObjects. In the VoiecObjects application the error code and error message can be accessed using the Expression functions ERRORCODE and ERRORMESSAGE.
That were the basics of XML API mode.
How it works (using simple HTTP mode)
To use simple HTTP mode, you only have to check the Use simple HTTP mode check-box.
In simple HTTP mode, all parameters that are defined in the parameter set are sent as separate CGI parameters in the HTTP POST request. The name of the CGI parameter is defined by the Alias/Property field. So in this example, the name of the CGI parameter will be stockName containing the value of Variable object Company Stock Symbol. In simple HTTP mode, the parameter set is only used for the input parameters.
The content of the HTTP response is accessible via the Return value. If you link a Variable object to the Return value field, the complete content of the HTTP response will be assigned to this Variable. Depending on the interface of your integration code, this can be a single value (e.g. a number or a string) or some complex structure like XML or something similar. If this return value is an XML document, you can use the result mapping section to directly assign certain parts of your XML (e.g. node values or attribute values) to Variable, Collection, or Layer objects using XPath expressions.
A Sample Implementation Using Simple HTTP Mode
Now, let’s take a look at a first sample application using simple HTTP mode. We will re-use our sample application from VoiceObjects Back-End Integration Part II: Java Connector. The application asks for a company name, retrieves the stock quote for this company using a Connector and says the stock quote (the export of the VoiceObjects application can be found in the resources section at the end of this article).
This time we just use a CGI Connector to retrieve the stock quote instead of the Java Connector we were using last time. We will use the simple HTTP mode and implement our integration layer in PHP. Here is our PHP code (the source code can be found in the resources section at the end of this article):
Our integration layer expects a CGI parameter stockName and will just return one single value – the stock quote for this name that has been given. As we don’t have a real back-end system to connect to, we are just returning a random stock quote. In the real world you would get it from a database or from some other external system.
Here is the Connector object definition for our sample application:
The Resource Locator Connector Locator contains the base URL. Together with the content of the File field it defines the URL of our PHP script. The Connector has one single parameter in the parameter set – the input parameter stockName. The result of our PHP script is available in the Return value which is assigned to Variable Stock Quote. As the return value is the plain stock quote (i.e. no structured XML data), we don’t need any Result Mapping definition. Please note that the Use simple HTTP mode checkbox is checked.
A Sample Implementation Using XML API
Now we will take a look at a sample implementation using the XML API. For this purpose we will re-use another sample application form VoiceObjects Back-End Integration Part II: Java Connector. It will fetch multiple stock quotes at once which will then be presented using a List object (the export of the VoiceObjects application can be found in the resources section at the end of this article).
The basic idea is that it works based on a Collection of stock quotes. The Collection has the following format:
<root>
<row>
<col name=”name”>cmp1</col>
<col name=”fullname”>company1</col>
<col name=”price”>12.34</col>
</row>
<row>
<col name=”name”>cmp2</col>
<col name=”fullname”>company2</col>
<col name=”price”>9.12</col>
</row>
<row>
<col name=”name”>cmp3</col>
<col name=”fullname”>company3</col>
<col name=”price”>543.23</col>
</row>
</root>
The application sends a Collection with name and fullname columns filled but with empty price column to the CGI layer:
<root>
<row>
<col name=”name”>cmp1</col>
<col name=”fullname”>company1</col>
<col name=”price”></col>
</row>
<row>
<col name=”name”>cmp2</col>
<col name=”fullname”>company2</col>
<col name=”price”></col>
</row>
<row>
<col name=”name”>cmp3</col>
<col name=”fullname”>company3</col>
<col name=”price”></col>
</row>
</root>
The CGI layer iterates over all rows in the Collection, determines the stock quote for each company and writes it into price column accordingly. Then it returns the Collection containing the price info to the VoiceObjects application. In the VoiceObjects application, the List object is used to present the stock quote for each company in the Collection.
For the implementation of the CGI layer, the CGI Connector Framework that is part of the VoiceObjects distribution (see VoiceObjects Object Reference Guide) is used. It provides an easy way to implement a Java Servlet based CGI integration layer for the XML API without having to worry about Servlets, JSPs, parsing XML, etc. The actual source code of this example is part of your VoiceObjects installation and can be found in the Platform/Resources/CGIConnector/Sources/SampleConnector directory of your installation. The relevant part of the code is shown here (the full source code can be found in the resources section at the end of this article).
It just consists of a single Java class that extends ConnectorServlet (which is part of the framework) and implements a single method. This method gets a parameter map as an input parameter and returns a ConnectorResult. It uses the VOCollection utility class that is part of the framework to access the Collection data structure. This class is deployed in a Java Servlet container (e.g. Tomcat) and acts as our CGI integration layer.
Here is the Connector object definition for this sample application:
The Resource Locator Connector Locator together with the value from the File field again build the URL of our CGI integration layer. In this scenario we only have one single parameter in the Parameter Set, which is used as input and output parameter. The Stock List Collection is sent to the integration layer, which returns a modified version of the Collection. The new Collection definition is assigned to the Stock List Collection. As we are using XML API mode, the Use simple HTTP mode checkbox is unchecked.
Pros and Cons of the CGI Connector
Here is a quick overview of the Pros and Cons of the CGI Connector to help you assess if the CGI Connector is the adequate connector type for your use-case (for a direct comparison with the other connector types, please see VoiceObjects Back-End Integration – Part I: Overview).
Pros
- Dedicated, decoupled integration layer: As the CGI Connector is executed in a separate web server, the integration layer is decoupled from the VoiceObjects Server. This gives you a dedicated integration layer that does not impact stability or performance of your VoiceObjects Server.
- Full flexibility: As the communication between the VoiceObjects Server and your integration layer is plain HTTP, you have the choice to use the technology, the programming language, and any existing libraries for integration with your back-end system that you consider as appropriate.
Cons
- Requires a web server: As the CGI Connector works via HTTP, a web server (e.g. Apache, Tomcat, IIS, etc.) is required for the deployment of your integration code.
Is the CGI Connector the Right Thing for me?
It is, if
- you prefer a dedicated data access layer in your integration architecture
- you want to have all options for the choice of programming languages, frameworks, libraries, etc for integration with your back-end system
- you have to implement custom code for back-end integration and you don’t want to risk stability or performance of your VoiceObjects server instances
It is not, if
- a web server is not an option in your integration architecture
Resources
<?xml version=”1.0″ encoding=”ISO-8859-1″?>
<request>
<root>
<row>
<col name=”type”>expression</col>
<col name=”name”>dialogID</col>
<col name=”referenceID”>dialogID</col>
<col name=”value”>
<![CDATA[OVAPac16172d000000000000058e000000f490ffef8b]]>
</col>
</row>
<row>
<col name=”type”>expression</col>
<col name=”name”>ANI</col>
<col name=”referenceID”>ANI</col>
<col name=”value”>
<![CDATA[12345]]>
</col>
</row>
<row>
<col name=”type”>expression</col>
<col name=”name”>DNIS</col>
<col name=”referenceID”>DNIS</col>
<col name=”value”>
<![CDATA[4085371847]]>
</col>
</row>
<row>
<col name=”type”>variable</col>
<col name=”name”>Company Stock Symbol</col>
<col name=”referenceID”>stockName</col>
<col name=”value”><![CDATA[GOOG]]></col>
</row>
<row>
<col name=”type”>variable</col>
<col name=”name”>Stock Quote</col>
<col name=”referenceID”>stockPrice</col>
<col name=”value”><![CDATA[]]>
</col>
</row>
</root>
</request>
RSS FEED