New Installation

This page describes how to install a new instance of GAAP into a test or production environment.

Installation prerequisites

Important

Before proceeding, refer to the prerequisites document to review minimum specifications, including database requirements, that must be met before installation begins.

Set up databases

[+] Click to show instructions for SQL Server

1. Open SQL Server Configuration Manager.
2. In the list, navigate to SQL Server Network Configuration > Protocols for <database_instance_name>.
3. In the right pane, double-click on TCP/IP to open TCP/IP Properties. Perform the following actions:
   1. In the Protocol tab, ensure that TCP/IP is enabled. The Enabled value must be Yes.
   2. In the IP Addresses tab, go to the IPAll section and set TCP Port 1433.
   3. Click OK.
4. Close SQL Server Configuration Manager.
5. Open Windows Services.
6. Right-click on your SQL Server and select Restart.
7. Close Windows Services.
8. Open SQL Server Management Studio.
9. In the Connect to Server dialog box, log in as an Administrator (Windows Authentication).
10. In the Object Explorer panel, right-click on Security > Logins and select New Login.
11. In the Login - New dialog box, perform the following actions:
    1. In the Login name field, enter speechstorm.
    2. Select SQL Server Authentication.
    3. Disable the Enforce password expiration check box.
    4. In the Server Roles page, ensure public is checked.
    5. Click OK.
12. In the toolbar, click New Query.
13. In the query window, enter the following:

        use master;
        create database fish;
        create database fishreports;
        GO
        alter database fish set ALLOW_SNAPSHOT_ISOLATION ON;
        alter database fishreports set ALLOW_SNAPSHOT_ISOLATION ON;
        GO
    
        use fish;
        create user speechstorm for login speechstorm;
        exec sp_addrolemember N'db_ddladmin', N'speechstorm';
        grant SELECT, DELETE, INSERT, UPDATE, EXECUTE, VIEW DATABASE STATE to speechstorm;
    
        use fishreports;
        create user speechstorm for login speechstorm; 
        exec sp_addrolemember N'db_ddladmin', N'speechstorm';
        grant SELECT, DELETE, INSERT, UPDATE, EXECUTE, VIEW DATABASE STATE to speechstorm;

14. Click Execute to run the SQL query.
15. Close SQL Server Management Studio.

[+] Click to show instructions for Oracle

1. Open Oracle SQL Developer.
2. Log in as the SYSTEM user.
3. Open a new SQL Worksheet for that connection.
4. In the new editor window, use one of the following examples:

Example for Oracle 11g

CREATE BIGFILE TABLESPACE fish        DATAFILE 'fish.dbf'        
                                      SIZE 20M AUTOEXTEND ON;
CREATE BIGFILE TABLESPACE fishreports DATAFILE 'fishreports.dbf' 
                                      SIZE 20M AUTOEXTEND ON;

CREATE USER C##fish        IDENTIFIED BY speechstorm 
                           DEFAULT TABLESPACE fish;
CREATE USER C##fishreports IDENTIFIED BY speechstorm 
                           DEFAULT TABLESPACE fishreports;

GRANT "RESOURCE" TO C##fish;
GRANT "RESOURCE" TO C##fishreports;
GRANT "CONNECT" TO C##fish;
GRANT "CONNECT" TO C##fishreports;
GRANT CREATE ANY VIEW TO C##fish;
GRANT CREATE ANY VIEW TO C##fishreports;
GRANT INSERT ANY TABLE TO C##fish;
GRANT INSERT ANY TABLE TO C##fishreports;
GRANT UNLIMITED TABLESPACE TO C##fish;
GRANT UNLIMITED TABLESPACE TO C##fishreports;
GRANT SELECT_CATALOG_ROLE to C##fish;
GRANT SELECT_CATALOG_ROLE to C##fishreports;
GRANT SELECT ANY DICTIONARY to C##fish;
GRANT SELECT ANY DICTIONARY to C##fishreports;

Example for Oracle 12c

CREATE BIGFILE TABLESPACE fish DATAFILE 'fish.dbf' SIZE 20M AUTOEXTEND ON;
CREATE BIGFILE TABLESPACE fishreports DATAFILE 'fishreports.dbf' SIZE 20M AUTOEXTEND ON;
CREATE USER fish IDENTIFIED BY speechstorm DEFAULT TABLESPACE fish;
CREATE USER fishreports IDENTIFIED BY speechstorm DEFAULT TABLESPACE fishreports;
GRANT "RESOURCE" TO fish;
GRANT "RESOURCE" TO fishreports;
GRANT "CONNECT" TO fish;
GRANT "CONNECT" TO fishreports;
GRANT CREATE ANY VIEW TO fish;
GRANT CREATE ANY VIEW TO fishreports;
GRANT INSERT ANY TABLE TO fish;
GRANT INSERT ANY TABLE TO fishreports;
GRANT UNLIMITED TABLESPACE TO fish;
GRANT UNLIMITED TABLESPACE TO fishreports;
GRANT SELECT_CATALOG_ROLE to fish;
GRANT SELECT_CATALOG_ROLE to fishreports;
GRANT SELECT ANY DICTIONARY to fish;
GRANT SELECT ANY DICTIONARY to fishreports;

5. Click Execute Script.

Create the directory structure and prepare the environment

1. Upload a copy of the GAAP installer ZIP file onto each of the machines that will be used.
2. Create a folder called SpeechStorm (case sensitive), preferably in the same location on all of the machines that will be used. This folder acts as the base folder location for the install. In most instances, you can use the following location: C:\SpeechStorm. This document references this location throughout. You can use a different drive and folder name, but Genesys recommends you create it on or close to the root or top level of the drive.
3. Unzip the GAAP installer into each of the SpeechStorm folders that you created on various machines in the previous step. Ensure the folder structure is exactly as follows, without any additional directory levels.
   • C:\SpeechStorm\Platform\..
   • C:\SpeechStorm\Setup\..
4. Update the database connection details in the database.properties file to point to your databases. The database.properties files are set per Tomcat instance and are found in the following locations:
   • C:\SpeechStorm\Platform\TomcatGUI\lib\database.properties
   • C:\SpeechStorm\Platform\TomcatVUI\lib\database.properties
   • C:\SpeechStorm\Platform\TomcatMessaging\lib\database.properties

   Inside each file are template connection strings for SQL Server and Oracle, with the Oracle connection string commented out. You must update these details to match your environment. Ensure you only uncomment one set of connection strings (for example, if you are using SQL Server, make sure Oracle is commented out).

   SQL Server Example

   #######################################
   #
   #  SQL Server 2008
   #
   #######################################
   Database.JDBC.Driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
   Database.JDBC.ConnectionURL=jdbc:sqlserver://localhost:1433;Database=fish;Trusted_Connection=False;loginTimeout=1
   Database.JDBC.Username=speechstorm
   Database.JDBC.Password=speechstorm
   Database.Pool.ConnectionValidationQuery=SELECT 1
   
   ReportsDatabase.JDBC.Driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
   ReportsDatabase.JDBC.ConnectionURL=jdbc:sqlserver://localhost:1433;Database=fishreports;Trusted_Connection=False;loginTimeout=1
   ReportsDatabase.JDBC.Username=speechstorm
   ReportsDatabase.JDBC.Password=speechstorm
   ReportsDatabase.Pool.ConnectionValidationQuery=SELECT 1

   Oracle example

   #######################################
   #
   #  Oracle 11g
   #
   #######################################
   Database.JDBC.Driver=oracle.jdbc.OracleDriver
   Database.JDBC.ConnectionURL=jdbc:oracle:thin:@localhost:1521:xe
   Database.JDBC.Username=C##fish_USER
   Database.JDBC.Password= speechstorm
   Database.Pool.ConnectionValidationQuery=SELECT 1 FROM DUAL
   
   ReportsDatabase.JDBC.Driver=oracle.jdbc.OracleDriver
   ReportsDatabase.JDBC.ConnectionURL=jdbc:oracle:thin:@localhost:1521:xe
   ReportsDatabase.JDBC.Username=C##fishreports_USER
   ReportsDatabase.JDBC.Password= speechstorm
   ReportsDatabase.Pool.ConnectionValidationQuery=SELECT 1 FROM DUAL

5. Download the following file: log4j.properties.
6. Place a copy of the log4j.properties file in the following locations:
   • C:\SpeechStorm\Platform\TomcatGUI\webapps\fish-gui\WEB-INF\classes
   • C:\SpeechStorm\Platform\TomcatVUI\webapps\fish-vui\WEB-INF\classes
   • C:\SpeechStorm\Platform\TomcatMessaging\webapps\fish-messaging\WEB-INF\classes
   • C:\SpeechStorm\Platform\TomcatMessaging\webapps\fish-loadbalancer\WEB-INF\classes

Install GAAP components and Windows Services

Navigate to C:\SpeechStorm\Setup, right-click on SS_FW_Install.bat and select Run as Administrator.

Warning

You must select Run as Administrator or the services will be installed with insufficient privileges.

SS_FW_Install.bat sets the paths for Java and Catalina home, creates self-signed certificates for HTTPS, and creates Windows Services to start automatically for the GAAP software and Flex licensing component.

During execution, the batch file prompts you to select different options depending on your environment.

1. Enter the path to the Platform folder e.g. C:\SpeechStorm\Platform :

Enter the path to where you created the SpeechStorm folder and unzipped the installer. For example, C:\SpeechStorm\Platform.

Important
This path is case sensitive. If incorrect, the installer prompts you to enter the path again.
2. Would you like to install a GUI server? (Y/N)

Answer y or n and press Enter.

This option asks if you want to run a GUI (administrator) web application on this machine. Choose this option if this machine will be used for authoring call flows, viewing reports, and general setup. You must have at least one GUI per installation. If this is a single-server install, you must install this component now.

3. Would you like to install a VUI server? (Y/N)

Answer y or n and press Enter.

This option asks if you want to run a VUI (call-handling) web application on this machine. A VUI handles customer calls, and in a production environment there might be several VUIs that service calls. If this is a single-server install, you must install this component now. Generally, companies install one VUI per server, as this is the component that handles calls and is the most commonly clustered component.

4. Would you like to install a Messaging server? (Y/N)

Answer y or n and press Enter.

This option asks if you want to install a messaging server and load balancer. These are specifically for visual IVR and Facebook Messenger.

5. Now we will generate and install the certificate for the GUI.
   Please enter the server FQDN or Fully Qualified Domain Name.

Enter the computer’s FQDN to generate a self-signed SSL certificate for the GUI. This value is case sensitive.

After the installer generates a self-signed SSL certificate, you can view it in the following location: C:\SpeechStorm\Platform\TomcatGUI\conf.

6. Enter pass phrase for speechstorm.key

Enter the password to create the self-signed certificate for the GUI.

The installer asks you to enter this password three times. Ensure you remember this password, as it will be used later in this install.

7. Setting up the Windows service for TomcatGUI.
   Enter the name for the TomcatGUI Windows Service e.g. FishGUI:

If you chose to install a GUI server on this machine, the installer asks you to select a unique name for the Windows Service. Genesys recommends the name FishGUI. After you enter this name, the installer creates a Windows Service set to automatically start.

8. Now we will generate and install the certificate for the Messaging server.
   Please enter the server FQDN -Fully Qualified Domain Name-

Enter this computer’s FQDN to generate a self-signed SSL certificate for the Messaging server. After the installer generates a self-signed SSL certificate, you can view it in the following location: C:\SpeechStorm\Platform\TomcatMessaging\conf.

9. Enter pass phrase for speechstorm.key

Enter the password to create the self-signed certificate for the Messaging server.

The installer asks you to enter this password three times. Ensure you remember this password, as it will be used later in this install.

10. Setting up the Windows service for TomcatMessaging
    Enter the name for the TomcatMessaging Windows Service e.g. FishMessaging

If you chose to install a Messaging server on this machine, the installer asks you to select a unique name for the Windows Service. Genesys recommends the name FishMessaging. After you enter this name, the installer creates a Windows Service set to automatically start.

11. Setting up the Windows service for TomcatVUI
    Enter the name for the TomcatVUI Windows Service e.g. FishVUI

If you chose to install a VUI server on this machine, the installer asks you to select a unique name for the Windows Service. Genesys recommends the name FishVUI. After you enter this name, the installer creates a Windows Service set to automatically start.

12. Note: Make sure you modify the database.properties file for all Tomcat’s for connection to MSSQL environment

This note reminds you to update the database.properties file to reflect the configuration of your environment (Oracle or SQL Server).

13. Installing License Server…

The installer is implementing the Flex licensing component as a Windows Service set to automatically start. This is required to license GAAP and a valid license must be imported into Flex before GAAP starts.

14. Populating Database…

Database scripts execute Migrate.bat and Post Migrate.bat to set up the database schema for GAAP.

Important
This database script only needs to run one time per installation, as all servers connect to this central database. If you have already run this script during an install on another machine, you can quit the script.
15. (Optional) Install additional GAAP servers to handle call load. For example, most GAAP users set up multiple VUI servers to process calls. To add additional VUI servers, complete the following steps on each host machine:
    [+] Click to show section
    1. Follow the steps in the section Create the directory structure and prepare the environment. You can copy the database.properties files from the machine on which you previously installed GAAP.
    2. Follow the steps in this section, Install GAAP components and Windows Services, but note the following changes:
       • Press n (no) when asked to install a GUI server or Messaging server.
       • Press y (yes) when asked to install a VUI server.

Use Flex to license GAAP server

Next, you must license the GAAP server within Flex before you can start the GAAP services. To do this, you need a license file that was provided with the installer files.

Important

License files are explicitly generated using the MAC address of the machines intended for the installation. License files cannot be used on a different machine.

1. Open Windows Services using one of the following methods in Windows:
   • Open the Start menu, click Search, and enter Services.
   • Open the Control Panel and select Services.
   In Windows Services, right-click on SpeechStorm License Manager and select Start.
2. After the service initializes, open a web browser and navigate to http://localhost:8090 to open the Flex web interface.
3. After the webpage loads, click on the Administration tab and use the following login:
   • Username: admin
   • Password: 123456789
4. After logging in, click Vendor Daemon Configuration to display a list of licenses. For the single entry in the list, click Delete.
5. Click Import License to upload the license file that was delivered with the installer and specific for this machine. Select the license file and ensure you enable the Overwrite License File on License Server check box. After you import the file, check the list of licenses again. If the import is successful, the list displays your license with a status of Up.

Update SSL certificates

Next, update the password for the SSL certificates that were created earlier. You must update the passwords listed in the following locations:

• C:\SpeechStorm\Platform\TomcatGUI\conf\server.xml
• C:\SpeechStorm\Platform\TomcatVUI\conf\server.xml
• C:\SpeechStorm\Platform\TomcatMessaging\conf\server.xml

In each file, locate the SSLPassword value and update it to the one you created when generating the SSL certificates.

Start GAAP services

In Windows Services, start the following services:

• Apache Tomcat 7.0 FishGUI
• Apache Tomcat 7.0 FishMessaging
• Apache Tomcat 7.0 FishVUI

Use the GUI server to configure GAAP

Now you can access the GAAP administrator (GUI) server via a web browser.

1. Open a web browser and enter http://localhost:8080/fish-gui. After the page loads, confirm that the browser correctly redirected to use https.
2. The browser displays a security warning because you created a self-signed certificate during the install. In Google Chrome, click ADVANCED and then click Proceed to localhost (unsafe). This indicates to the browser that you understand the certificate is self-signed. This process might vary in other browsers.
3. The browser displays the GUI authentication screen. Enter the following:
   • Username: gaap.admin@genesys.com
   • Password: 123456
   After you log in, GAAP redirects you to change your password.
4. Go to Administration > Servers and perform the following actions:
1. (Optional) For each of the following rows, click the delete link and delete the servers:
   • Default SMS Server
   • Default Outbound Server
   • Default Mobile Server
Important
In the following steps, the hostname you enter must be reachable from the MCP servers, as this hostname is sent in the rendered GAAP VXML. For example:
• If you enter localhost as a hostname but the MCP server is not installed on the same machine, the hostname localhost does not work.
• If you enter gaapvui1 as a hostname but the MCP server cannot reach this server without a FQDN such as gaapvui1.genesys.com, the hostname gaapvui1 does not work.
2. In the Default VUI Server row, click edit. Set the hostname to the name of your VUI server and port to 8082. Click Save.
3. (Optional) If you installed additional VUI servers, perform the following steps.
   [+] Click to show section
   1. Click Create a New Server and select New Voice Server.
   2. Enter the following information:
      • Server Name - Enter a descriptive name for the server. For example, VUI_2.
      • Server Connection Details - Select a connection type (HTTP or HTTPS) and enter a hostname and port.
      • Cluster - Specify which cluster to attach this server. Typically, this setting is unchanged from the Default Voice Cluster.
      • Server Status - Select the Active check box to make this server active and therefore able to process calls.
      • Click Save.
   3. In the Servers list, look for your new server and note its ID value.
   4. On the server host machine, go to C:\SpeechStorm\Platform\TomcatVUI\lib\.
   5. Open the fish-vui-local.properties file for editing.
   6. Look for the following line: ThisServer.ID=#. Replace # with the Server ID value you noted earlier.
   7. Go to Windows Services and restart the FishVUI service.
4. In the Default Admin Server row, click edit. Set the hostname to the name of your GUI server. Click Save.
5. (Optional) This step applies only if you installed the Messaging server. [+] Click to show section

   Go to Administration > Clusters and click Create a new Cluster. In the New Cluster Type: pop-up, select New Load Balancer Cluster. In the next screen, enter the following information:

   • Cluster Name - Specify a unique name.
   • Load Balancer Servers Will Balance Requests Arriving at This Port - Select http and a port number that is not used by anything else on this machine.
   • Hostname Used in External Links to this Cluster - Specify the machine's host name.
   • Click Save.

   Go to Administration > Servers. If there is no Load Balancer server, click Create a New Server. In the New server type: pop-up, select New Load Balancer Server. In next screen, enter the following information:

   • Server Name - Specify a unique name.
   • Server Connection Details - Specify a server name and port number.

   Important

   By default, the port number by 8081. To verify, open C:\SpeechStorm\platform\TomcatMessaging\conf\server and check the value for Connector port.

   • Cluster - Select the cluster you created in Administration > Clusters.
   • Server Status - Enable the Active check box.
   • Click Save.
6. Click Re-run Server Checks to refresh the server list and ensure all servers are functioning normally.
Important
Servers set to use HTTPS do not report as being available until the next step is performed.
5. (Optional) Set up HTTPS for Voice, Messaging and Load Balancer servers.
   1. Go to Administration > Certificates.
   2. Click Import a new Certificate.
   3. In Remote Server Details, enter the hostname and port number of the server for which you want to import the certificate.
   4. Click Get Certificate. The page updates to show the certificate has been fetched successfully.
   5. Enter a description in the Description field.
   6. Click Save.
   Important

   You might see a message stating the cache cannot be flushed on the server. This is because the HTTPS server cannot communicate until the certificate has been uploaded and services have been restarted. If you see this error, go to Administration > Certificates again and you can see the certificate you uploaded. Repeat this process for all servers that use HTTPS, then restart those servers. When they come back on, they appear as Online in the Administration > Servers tab.
6. Go to Administration > Default Server Settings and update the following settings:
   • GraphViz.DotPath - Specify the path to the GraphViz executable. Usually, this is C:/SpeechStorm/Platform/Apps/GraphViz/bin/dot.exe (use forward slashes).
   • (Optional) Login.Security.Strict - Set to true if you are in a PCI environment.
   • Email.SMTP.Host - Specify the hostname of your SMTP server (for example, mail.speechstorm.com).
7. Click Save.
8. Go to Windows Services and restart GAAP services, including FishGUI, FishMessaging, and optionally FishVUI.
9. After the services restart, log in again and go to Administration > Servers. Ensure all components are online.

Import products and templates

Important

Before proceeding, ensure you are still in the Templates company by checking the company name beside your username in the top-right corner.

1. To import products, go to Administration > Products.
   1. Click Import a Product to display a new page.
   2. Click Import Product and select the All Production Definitions.zip file, usually found at the following location: C:\SpeechStorm\Platform\AppsToBeInstalled\Products and templates\All Product Definitions.zip.
   3. Select the option Overwrite Product ID if it Already Exists.
   4. Click Import Product.
2. To import templates, click Import in the top-level navigation bar.
   1. Select Import everything.
   2. Click Choose File and select the All Production Templates.zip file, usually found at the following location: C:\SpeechStorm\Platform\AppsToBeInstalled\Products and templates\All Product Templates.zip.
   3. Click Choose Modules to Import.... A pop-up displays a list of templates that will be imported.
   4. Scroll to the bottom of the list and ensure the Create new persona for 'Visual Default Persona' check box is enabled.
   5. Click Import.