VIS 7.6+ installation guide

Prerequisites

If not already installed, install the following components before installing VXML Interaction Server (VIS).

Java

In accordance with the Oracle OpenJDK8 end of public updates process, the use of Java-8 requires a Java SE Subscription. When a subscription is already in place, download Oracle JDK from the Oracle Technology Network (OTN).

Alternately, the latest updates of Java are available at no cost from Oracle under an open source license from the archived "OpenJDK General-Availability Releases" site under public license at jdk.java.net.

Installing Java for Windows

  1. Download the supported version of Java from OpenJDK.
  2. Extract the Java artifacts from the compressed download file.
  3. Place the extracted jdk folder inside the Java folder on the VIS server.
  4. Edit the Java_HOME environment variable to point to the correct directory.
  5. Edit the Path environment variable, and add the Java bin directory path %JAVA_HOME%bin; to the beginning of the entry.

Add the Java bin directory path to be beginning of the entry in order to point all Java files and directories to the correct Path variable.

Installing Java for Linux

  • Extract the downloaded file to /user/lib/jvm directory.
  • Run the following command to install the Java version:
update-alternatives --install /usr/bin/java java /usr/lib/jvm/<JDKVersion>/bin/java 1
  • Run the following command to set the Java version:
update-alternatives --set java /usr/lib/jvm/<JDKVersion>/bin/java
  • Run the following command to verify the correct version of Java is pointed to:
java -version

Looking for an OpenJDK version?

Locate the OS and Windows specific version of JDK from the OpenJDK archive.

Apache Tomcat Web Server

For details about which versions of Apache Tomcat are compatible with VIS, refer to the system requirements for your version of VIS.

Windows Installation

  1. Download Tomcat from the http://tomcat.apache.org/. Apache provides both 32-bit and 64-bit versions. Download the version that is compatible with your server.
    • Server 2003: 32-bit/64-bit Windows Service Installer

    • Server 2008 and later: 64-bit Windows zip

  2. Install Tomcat on the server. During the installation process, accept all of the default values.

  3. Modify the context.xml file so that Tomcat can use cookies properly. Perform the following steps:
    1. Navigate to the conf folder in the root of the Tomcat directory.

    2. Open the context.xml file in a text editor.

    3. Search for Context. If you find <Context>, replace it with <Context useHttpOnly="false">.

  4. Disable the localhost logs because they are only used during in-depth troubleshooting and unnecessarily consume memory space. Perform the following steps:
    1. Navigate to the conf folder in the root of the Tomcat directory.

    2. Open the context.xml file in a text editor.

    3. Comment out the following:
      <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %l %u %t &quot;%r&quot; %s %b" />

      For example:

      <!--<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %l %u %t &quot;%r&quot; %s %b" />-->
    4. Restart Tomcat.

  5. Install the log4j logging package to provide a rolling log for Tomcat. See below for instructions.

Note:
  • Change the Maximum memory pool setting to 25% of the total system memory (e.g., set to 2,048 MB for an 8-GB system). This setting is located under the Java tab in Apache Tomcat Properties, which typically may be opened from C:\Program Files (x86)\Apache Software Foundation\Tomcat x.\bin\Tomcatxw.exe on Windows Server.
  • If you use load balancing or failover features, you must install Apache Tomcat on both of the servers where VIS will be installed.

Linux Installation

  1. Download and install Java if not already completed in previous steps.
  2. Download and install the appropriate version of Tomcat. See the system requirements for your version of VIS to determine the required Tomcat version.
    1. Extract the files from the archive to a temporary location.
  3. Move the extracted files to a location of your choice. Remember this location for future use.
    1. For example, place in the local directory:

      # tar xzf apache-tomcat-x.x.xx.tar.gz

      # mv apache-tomcat-x.x.xx /usr/local/tomcat<version>

  4. To start Tomcat:

    # cd /usr/local/tomcat<version># ./bin/startup.sh

  5. To stop Tomcat:

    # ./bin/shutdown.sh

Note:
  • Change the Maximum memory pool setting to 25% of the total system memory (e.g., set to 2,048 MB for an 8-GB system).
  • Modify the JAVA_OPTS variable in the tomcat<version>.conf file, which typically may be opened from $CATALINA_HOME/conf (by default, $CATALINA_HOME resolves to /usr/share/tomcat 7/conf) by adding JAVA_OPTS="${JAVA_OPTS} -Xmx2048M"
  • Save the file and restart Tomcat after completing the previous step.

Installing Microsoft IIS

Microsoft Internet Information Services (IIS) on Windows Server is not required by VIS itself. However, VIS Version 5.0 and later allows voice prompts to be stored on a media server separate from VIS, and IIS is a supported media server platform.

For details about which versions of Microsoft IIS are compatible with VXML Interaction Server, see the system requirements for your version. For details about the components and roles which are required, refer to the installation guide for your version of On-Premise Callback.

Visit www.iis.net for instructions to download and install IIS.

(Optional) Installing Apache Web Server

Apache Web Server (Apache HTTP Server) is not required by the VXML Interaction Server (VIS) itself. However, VIS Version 5.0 and later allows voice prompts to be stored on a media server separate from VIS, and Apache Web Server is a supported media server platform.

Installing the Windows Apache Web Server

Download the software from http://httpd.apache.org/download.cgi and install on the server you will be using for voice files.

Installing PHP for the Windows Apache Web Server

If your installation did not include PHP, follow these instructions to install it:

  1. Download PHP 5.3.5.

  2. Run the installer package.

  3. Click Next on the Welcome Screen.

  4. Accept the License Agreement and click Next.

  5. Accept the default location to install PHP, or browse to a different location if desired. Click Next.

  6. On the Web Server Setup screen, select the Apache 2.2.x Module option and click Next.

  7. On the next screen, browse to the configuration directory for your Apache Web Server installation. This will be similar to C:\Program Files\Apache Software Foundation\Apache2.2\conf\ if you used the default install location when installing the Apache Web Server. Click Next.

  8. On the Choose Items to Install screen, keep the selected components. You may install additional components if desired. Click Next.

  9. Click Install to install PHP.

  10. Click Finish when the installation completes.

  11. Navigate to your Apache Web Server configuration directory and open the httpd.conf file in a text editor.

  12. Locate the <IfModule dir_module> section and change the text from DirectoryIndex index.html to DirectoryIndex index.html index.php.

  13. Save the file.

  14. Restart the Apache Web Server service.

Installing the Linux Apache Web Server

Perform the following steps to download and install the Apache Web Server on servers using the Linux operating system:

  • Download the latest version of the server.
  • Enter the following commands to extract the Apache software:
$ gzip -d httpd-package_version_provided_during_download.tar.gz$ tar xvf httpd-package_version_provided_during_download.tar$ cd httpd-package_version_provided_during_download
  • Enter the following command to configure the Apache source tree:
$ ./configure --prefix=apache_install_file_path
  • Enter the following command to build the various component parts of the Apache software:
$ make
  • Enter the following command to install the Apache software into the apache_install_file_path:
$ make install
  • Enter the following command to customize the Apache server by editing the configuration files located under the apache_install_file_path/conf/ directory:
$ vi apache_install_file_path/conf/httpd.conf
  • Enter the following commands to test (start and stop) the Apache Web Server:
$ apache_install_file_path/bin/apachectl -k start$ apache_install_file_path/bin/apachectl -k stop

Installing File Extraction Software

File extraction software compatible with .7z archive files is recommended on all servers running VIS. We recommend 7-zip. Go to www.7-zip.org for more information.

Installing the VIS application and media files

Three components are required to install VXML Interaction Server (VIS):

  • VIS.war - contains the VIS application
  • Voices - contains the media .wav files
  • vht_ivg.war - contains the Call Control Interaction Server (CCIS)

The vht_ivg.war file only applies to IVG installations.

To install VIS and its components:

  • Download the VIS .zip file from the VHT Download Center.
  • Stop the Tomcat service.
  • Delete any existing files.
    • In systems using Apache Tomcat, delete the following:
      • From the \\Tomcat\webapps folder:
        • VIS.war
        • Voices
        • vht_ivg.war
      • From the \\Tomcat\work\Catalina\localhost folder:
        • VIS.war
        • Voices
        • vht_ivg.war

Only delete the files that are being replaced.

  • Copy the new files into the Apache Tomcat webapps folder (\\Tomcat\webapps).
  • Restart the Tomcat service.
    • Tomcat copies the files into the \\Tomcat\work\Catalina\localhost folder.
  • Wait one or two minutes and place an inbound test call. This verifies the system has started up completely and is functioning correctly.

Not waiting for the system to start up completely can cause issues with the first inbound calls (failure to write to the database properly for example).

Important:

This note only applies to standalone VIS deployments.

The Apache Tomcat AJP Connector is not disabled by default during the installation of VIS in a standalone deployment. For standalone deployments, we recommend disabling the connector manually.

To disable the AJP Connector manually, remove the following line from the server.xml file:

Connector port="8009" protocol="AJP/1.3" redirectPort="8443"

Using external media files

A client's collection of voice files can reside on a media server separate from the VIS application server. This external voice project can be edited independently outside of Eclipse and then deployed to the server without building a new VXML project or .war file. This allows for quicker deployment and easier customization of the voice files.

Any number of media servers may be configured for the external voice projects. If multiple media servers are set up, they can be used either in a distributed (balanced) fashion or in a failover mode. This helps to ensure that voice files will still be played if a server stops responding.

VHT provides a .zip file containing a set of voice files in the Download Center. Clients should download this folder first and deploy it to the media server(s). Clients who use customized voice files must create a new folder for each set of custom files. The new folders will also be deployed to the media server(s). This process now requires fewer steps than previous versions of VIS and can be performed outside of Eclipse.

VIS will use the configuration details set up in the toolkit.properties file and the Language Settings section of the On-Premise Callback Configuration UI. This configuration information tells VIS where to look for the voice files. When VIS needs to play a voice prompt, it will look for a customized voice file first and play that file if found. Otherwise, the default voice file is played.

Deploying External Media Files

VIS can play voice prompts hosted on other media servers as well.

The following Web servers have been verified to use external media files with the VXML Interaction Server:

  • Apache Tomcat

  • Apache Web Server

  • Microsoft IIS

You can set up any number of servers using any combination of the platforms listed above. Be sure each media server is configured in the toolkit.properties file. You may deploy the voices folder as-is from the Virtual Hold Download Center, or you may customize the folder first. Refer to the Configuration Guide for your version of VIS for more information.

After new voice files are deployed, they will be cached and played from the media server within a matter of seconds, depending on the voice browser and media server's cache settings. (The VXML Interaction Server itself does not perform any caching.)

Deploying to Apache Tomcat

  • Copy the voices folder and its contents to the \webapps folder in Tomcat.

    • In Windows, C:\Program Files (x86)\Apache Software Foundation\Tomcat 7.0\webapps, for example

    • In Linux, /usr/local/tomcat7/webapps, for example

  • Navigate to the \conf folder in Tomcat (in the same location as the \webapps folder) and open the web.xml file in a text editor.
    • Locate the <param-name>listings</param-name> line in the default servlet section and change its <param-value> to true as shown below:
      <servlet>    
      	<servlet-name>default</servlet-name>    
      	<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>    
      	<init-param>            
      		<param-name>debug</param-name>            
      		<param-value>0</param-value>    
      	</init-param>    
      	<init-param>            
      		<param-name>listings</param-name>            
      		<param-value>true</param-value>    
      	</init-param>
  • Test the files by browsing to this path in a Web browser. The browser should be able to locate the folder.

Deploying to Apache Web Server (Linux)

  • Copy the voices folder and its contents to /var/www/html/.

  • Test the files by browsing to this path in a Web browser. The browser should be able to locate the folder.

Deploying to Microsoft IIS

Deploying to Microsoft IIS 6 (Windows)

Follow these steps to create a virtual directory to include the media files from the media server without having to physically copy them to the IIS 6 server.

  1. Open IIS Manager. In the left pane, navigate to the folder under which you want to create the virtual directory. Right-click this folder and select New > Virtual Directory.

  2. The Virtual Directory Creation Wizard will display. Click Next.

  3. In the Virtual Directory Alias window, type a name in the Alias field. This alias is used to access the content from a URL. Click Next.

  4. In the Web Site Content Directory window, enter the path to the voices folder in the Path field, or click Browse to navigate to the folder. Click Next.

  5. In the Virtual Directory Access Permissions window, select the Read, Run Scripts, and Browse options. Click Next.

  6. Click Finish.

  7. Test the setup by right-clicking the virtual directory and selecting Manage Virtual Directory > Browse. The browser should be able to locate the folder.

Any changes to the files in the voices folder in the virtual directory are automatically detected. No extra deployment steps are needed.

Deploying to Microsoft IIS 7 (Windows)

Follow these steps to create a virtual directory to include the media files from the media server without having to physically copy them to the IIS 7 server.

  1. Open IIS Manager. In the Connections pane, navigate to the Sites node, then select the site in which you want to create the virtual directory.

  2. In the Actions pane, click View Virtual Directories.

  3. In the Actions pane, click Add Virtual Directory.

  4. In the Add Virtual Directory dialog box, type a name in the Alias field. This alias is used to access the content from a URL.

  5. In the Physical path field, type the path to the voices folder, or click Browse to navigate to the folder.

  6. Click OK.

  7. Under the Sites node, select the new virtual directory. In Features View, double-click Directory Browsing.

  8. In the Actions pane, click Enable to enable browsing to this directory.

  9. Test the setup by right-clicking the virtual directory and selecting Manage Virtual Directory > Browse. The browser should be able to locate the folder.

Any changes to the files in the voices folder in the virtual directory are automatically detected. No extra deployment steps are needed.

Additional Information

Increasing the Java heap space

This guide will walk you through the steps to set the Memory Pool for Apache Tomcat.

There is a memory pool limitation using Java 32 bit. We recommend the client uses Java 64 bit and Tomcat.

This article will resolve the "java.lang.OutOfMemoryError: Java heap space" errors that occur.

If Tomcat is upgraded, the default memory size is restored back to a default value (128 startup 256 max memory).

Opening Apache Tomcat Properties

Begin by browsing to the "bin" folder inside the Apache Tomcat directory. The default filepath is "C:\Program Files\Apache Software Foundation\Tomcat 7.0\bin." Once here, open Tomcat7w.exe. This should open Apache Tomcat's Properties.

image of tomcat properties

Configuring the Maximum Memory Pool

Next, go to the Java tab. Here you will find the "Maximum memory pool" setting, which is what you want to set. The recommended size is 5120 (MB). However, if your server does not allow this much memory to be consumed, you can set this lower.

image of tomcat properties

After completing this, hit Apply. Then restart Apache Tomcat and check for stability. If it crashes immediately, you may have set the memory pool too high for the server.