The ProjectConfiguration.xml file contains the settings that define how to run VIVR VXML Connector. Each VIVR VXML Connector project has its own ProjectConfiguration.xml file. The file is found in the folder of the individual project.

In order to properly run your VIVR VXML Connector project, the appropriate settings need to be configured in ProjectConfiguration.xml. The default projects folder (provided with the application) contains sample projects for Avaya and Cisco. These sample projects can be used as templates for other Voice IVR systems as well.

The settings and variables that need to be defined in ProjectConfiguration.xml are listed and described in the following table.

Setting/Variable Description/Notes
A friendly name for your project.

The URL or the file name of the .vxml that is set
as the start
element in the project. For example:

Note: If a load balancer is used, verify that this setting is the IP address of the load balancer.

The folder path to the XML files that define
mapping between audio prompts and the
VIVR VXML Connector visual annotations
that are displayed to the user.
If this setting is left empty, the default setting is the
AudioToText folder inside the project.
The IVR vendor to which the VXML connects.
Currently, certified vendors include Avaya and Cisco. (Additional vendors will be certified in the coming
If you use Genesys 7.6 with ASP and Vox files, the value should be Asp. Otherwise, the value should be empty.
The version of your IVR. This setting is for future use.
Defines grammar compatibility. The following
values are supported:
  • semantics/1.0-literals: SRGS-Literals
  • semantics/1.0: SRGS-SISR
  • application/x-nuance-osr: Nuance OSR
  • application/x-ibm: IBM
Defines the title that is displayed at
the top of each pageof the Interaction.
A flag that determines the extent of detail
of the error messages presented to the user:
  • true:
    Extensive error messages are displayed.
  • false:
    A generic error message is displayed.

This property contains a script that is
executed at the beginning of each session. The code of this script customizes VXML Connector to specific IVR providers. For more information, refer to Writing the sessionScript (below). 

onCallHangup Determines the behavior of the Visual IVR Interaction if the call to the Voice IVR disconnects. Possible values are:
  • Continue:
    If the Voice IVR call disconnects, the Visual IVR Interaction continues. (This is the default value.)
  • Finish:
    If the Voice IVR call disconnects, the Visual IVR Interaction ends.
sendInteractionKeepAlive  Determines whether the Visual IVR indicates to the Voice IVR that the Visual Interaction is active. Possible values are:
  • false:
    No signals are sent from the Visual IVR. (This is the default value.)
  • true:
    The Visual IVR sends a signal to the Voice IVR each time the user clicks a navigation button.

Ensures that the VXML Connector communicates successfully with the Voice IVR by replacing the path of the application element (see example below) with the path specified in the Start property. The application element is part of the VXML documents sent by the Voice IVR. Some of these elements contains references to the address of the Voice IVR. The value of the application element contains the actual location of the Voice IVR.

Host correction is essential when the VXML Connector and the Voice IVR communicate via a load balancer or other servers. To perform the correction, in the HostCorrection tag, verify that the URL specified in the FromHost element is that of your Voice IVR. For example:

If your IVR provides a specific DTMF combination which indicates ‘Back’, use this setting to indicate it.

Visual IVR will check each step to see if this DTMF combination appears in the current step Grammars and will display a Back button on the screen. (If the current Grammars don't include this DTMF combination, the Back button will be disabled.)

When the Back button is pressed, Visual IVR will emulate entering this DTMF combination.

Note: If you use the ampersand character (&) in the ProjectConfiguration.xml file, the syntax needs to be as follows: &amp;

Writing the sessionScript

This JavaScript code, which is executed at the beginning of each session, is used to customize VXML Connector to specific IVR providers. Code that you write in the sessionScript section can:

  • Add and set required variables (e.g., populate the IVR telephony variables)
  • Use customized logic to make the project platform specific
  • Add required parameters to the session URL

Managing Required Variables

 In most cases, connecting to a VXML Server requires that built-in variables in the Voice XML specifications should be set (e.g., the ANI). In addition, each platform vendor usually has its own set of variables (not listed in the specification). 

To enable you to set and work with these variables, the sessionScript contains the following built-in functions:

  • setVariable (key,value): Sets a JavaScript variable (usually the VXML variables and the vendor-specific variables). 
    The setVariable method ensures that the path of the variable exists. For example, if session.avaya doesn’t exist, and you try to set session.avaya.telephone, the path will be created.
  • getVIVRParam(paramNumber): Retrieves a specified VIVR parameter passed in the URL when the Interaction was launched. 

Avaya Example:

setVariable('session.avaya.telephone.uui', getVIVRParam(1));
setVariable('session.avaya.telephone.ucid', getVIVRParam(2));
setVariable('session.avaya.ucid', getVIVRParam(2));
setVariable('session.avaya.mediaType', 'Voice');

Cisco Example:


The following general example shows how to set the variables that are dynamic for a call by retrieving parameters passed in the Interaction URL:<ProjectName>&mode=vivr&appkey=52bc2aa7e424569558ac5cc9&accountId=vivr

Calling getVIVRParam(0) will retrieve +972524740111, while calling getVIVRParam(1) will retrieve 1234567890.

Customizing the VXML Connector Project

You can use JavaScript code in the sessionScript to make the project platform specific. The externalObjectsHandler object is a special variable (fixed name) that is supplied in the sessionScript. This object can be used to support any object behavior of a platform.

One use of the externalObjectsHandler object object is to handle the call attached data. This data is collected as the user navigates through the visual Interaction, and is stored in the Voice Proxy. In the event that the user is transferred to an agent, the data is retrieved and passed with the call.

In the example presented below, the VXML Connector accesses attached data through specific Genesys Object commands called CRData Get and CRData Put. The externalObjectsHandler object is used to pass and receive attached data to and from the VoiceProxy, which is used as a memory buffer. In the code, this is initiated by setting initial values on the externalObjectsHandler which are then saved in the VoiceProxy. The list of variables initiated should be in key value format. (In the example, the values are connectionId and ani.) Additional variables to be passed in attached data can be added to the list, as required.

Note: Keep in mind that the code written in this section must conform to all JavaScript rules. In addition, HTML encoding needs to be used.

// Support for Objects elements for Genesys Legacy
var externalObjectsHandler;
externalObjectsHandler = {
CRData: {
put: function (params) {
var result = new Object();
for (var i=0 ; i &lt; params.length ; i++) {
var param = params[i];
var value = param.value;
session.vivrProxy.variables[] = param.value;
result = {
ResultCode: 'Success'
return result;

get: function (params) {
var result = '&lt;crGetData&gt;';
for (var i=0 ; i &lt; params.length ; i++) {
var param = params[i];
result = result + '&lt;key name=&quot;'
+ + '&quot; value=&quot;' + session.vivrProxy.variables[] + '&quot;/&gt;';
result = result + '&lt;/crGetData&gt;';
return result;

var params = [];

var param = new Object(); = 'UD_connid';
param.value = connectionId;

param = new Object(); = 'ANI';
param.value = ani;


Adding Session URL Parameters

Sometimes it is necessary to add parameters to the access URL after the Interaction is launched. This can be done by defining the required parameters in
var sessionUriParam. For example:

var sessionId = getVIVRParam(0);
var fcr = getVIVRParam(1);
var sessionUriParam = 'SESSIONID=' + sessionId + '&amp;FCR=' + fcr; 

ProjectConfiguration.xml: Examples

The following example shows sample content for a ProjectConfiguration.xml file in an Avaya project:

The next example shows sample content for a ProjectConfiguration.xml file in a Cisco project: