Existing Installation

This page describes how to upgrade an existing instance of GAAP without a service outage.

Installation prerequisites

• A running instance of GAAP on any previous version with more than one VUI.
• If using an Oracle database, a SYS user has modified the open_cursors setting as documented in the Pre-Installation Checklist.

You can update a production or production-like environment without a service outage if there is more than one VUI to process calls. To do so, you must isolate a single instance at a time, update the application, and then return it to the cluster. You can repeat this process for each of the VUIs in your environment.

Warning

While you can execute database migration during the first server upgrade, DO NOT execute post-migrate activities until you update the last server.

Stop the server

Select one of the servers to upgrade, and then deactivate it within the GUI.

1. Log in to GAAP.
2. Go to Administration > Servers. GAAP displays a list of servers in your environment.
3. Note the name and ID number of servers in this list (for example, FishGUI and 1) as this information is required later in this process.
4. Select one server to upgrade. Click Edit. A server details screen appears.
5. De-select the Server Status check box, thereby making the server inactive.
6. Click Save.
7. Wait for the VUI to process its current calls (the server does not accept new calls once it is inactive). In the Administration > Servers page, wait for the Active Sessions count to show 0. You can refresh the Administration > Servers page as necessary to view the latest Active Sessions count.
8. After the Active Sessions count is 0, you can stop all services on that specific machine.
   1. Open the Windows Services manager on the machine that hosts the VUI to be upgraded. Choose one of the following methods:
      • Open the Start menu, click Search, and enter Services.
      • Open the Control Panel and select Services.
   2. In the Windows Services manager, identify all GAAP components. Right-click each component and select Stop. It might take up to one minute for the service to actually stop. You can confirm it has stopped by refreshing the window until the component status displays Stopped.

Uninstall the previous GAAP server

1. Make a backup of the existing folder structure. If you used the default install location for GAAP, go to C:\SpeechStorm\Platform and copy its contents to another location.
2. Go to C:\SpeechStorm\Setup, right-click SS_FW_Uninstall.bat, and select Run as administrator. This file presents the following prompts:
   Tip

   Remember the step above about noting server names? We will use this information in the steps below.
   1. Enter the name for the TomcatGUI Windows Service e.g. FishGUI

   Enter the name of the GUI service. For example: FishGUI.

   2. Enter the name for the TomcatVUI Windows Service e.g. FishVUI

   Enter the name of the VUI service. For example: FishVUI.

   3. Enter the name for the TomcatMessaging Windows Service e.g. FishMessaging

   Enter the name of the Messaging service. For example: FishMessaging.

   4. Enter the name for the License Manager Windows Service e.g. SpeechStorm License Manager

   Enter the name of the SpeechStorm License Manager. For example: "SpeechStorm License Manager". Note that quotes are necessary, as the name uses spaces.

   5. Would you like to delete the SpeechStorm Platform directory? (Y/N)

   Enter y to remove all contents in the Platform directory, which you previously backed up to a different folder location.

Create the directory structure and prepare the environment

1. Go to C:\SpeechStorm and remove all files - including the Setup folder, which contains install and uninstall batch files.
2. Copy the installer zip file to this machine.
3. Unzip the installer file into the existing C:\SpeechStorm folder on this machine. Ensure the folder structure is exactly as follows, without any additional directory levels:
   • C:\SpeechStorm\Platform\..
   • C:\SpeechStrorm\Setup\..
4. Update the database connection details in the database.properties file to point to your existing databases that will be used for this install. 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
   Optionally, you can use your existing database.properties files that you backed up earlier in this process and overwrite the files created by the installer. If so, proceed to the next step after you overwrite the database.properties files with your backup files. If you do not want to use your backup database.properties files, continue with the instructions in this step. Inside each database.properties file are template connection strings for SQL 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, make sure Oracle is commented out).
   SQL 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. Restore the log4j.properties files that you backed up earlier. You must place each file in the same directory from which it was backed up. The locations are:
   • 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
Tip
Remember the step above about noting server ID numbers? We will use this information in the step below.
6. Restore the *.local.properties files that you backed up earlier in this process. You must place each file in the same directory from which it was backed up. The locations are:
   • C:\SpeechStorm\Platform\TomcatGUI\lib\fish-gui-local.properties
   • C:\SpeechStorm\Platform\TomcatVUI\lib\fish-vui-local.properties
   • C:\SpeechStorm\Platform\TomcatMessaging\lib\fish-loadbalancer-local.properties
   • C:\SpeechStorm\Platform\TomcatMessaging\lib\fish-messaging-local.properties
   These files must contain information similar to the following: ThisServer.ID=# (where # is replaced by the server ID that you noted earlier.
7. (Optional) If your GAAP environment uses the Integration Hub, copy the file indy-keys.properties from the backup folder to C:\SpeechStorm\Platform\TomcatIntegration\webapps\fish-integration\WEB-INF\classes\indy-keys.properties.

Install GAAP components

Navigate to C:\SpeechStorm\Setup, right-click 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 services in Windows 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. If this is a multi-server install, you must choose at least one machine on which to install the GUI instance.

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. If this is a multi-server install, you can choose which machines on which to install VUI instances. 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 the 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:

Genesys recommends 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 or 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 the phrase for speechstorm.key messaging 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:

Genesys recommends 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:

Genesys recommends 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.

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
• Migrate.bat only needs to run one time per installation, as all servers connect to this central database. If you have already ran this script during an install on another machine, you can quit the script.
• You must only run Post Migrate.bat if this is the last server installation. DO NOT execute post-migrate activities until you update the last server.

Run SS_FW_Install.bat again on all other machines used for GAAP in your environment.

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. Either:

• Use the license file that you backed up earlier in this process. (For example, C:/<Backup_Location>/Platform/Apps/Flex/licenses/).
• Use a new license file that was provided to you by Genesys.

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.
2. In Windows Services, right-click SpeechStorm License Manager and select Start.
3. After the service initializes, open a web browser and navigate to http://localhost:8090 to open the Flex web interface. Click 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 specific for this machine. 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.

Copy connector settings

Next, you must copy the connector settings from your backup server.xml files into the new files created by the GAAP installer. In each backup server.xml file, copy:

• the HTTP connector settings
• (If applicable) the HTTPS connector settings. Ensure the HTTPS connector section contains the key SSLPassword and the password matches the one you specified when generating the SSL certificates in one of the following steps:
  • GUI server
  • Messaging server

Paste the contents of these sections into the server.xml files created by the GAAP installer. In most environments, these files are 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

You can toggle the following sections to see examples of connector sections:

[+] Click to show HTTP connector example

<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
			   URIEncoding="UTF-8"
			   maxThreads="500"
			   />

[+] Click to show HTTPS connector example

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="500" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" 
			   SSLCertificateFile="${catalina.base}/conf/speechstorm.cer" 
			   SSLCertificateKeyFile="${catalina.base}/conf/speechstorm.key"
			   SSLPassword="password"   
		       URIEncoding="UTF-8"

/>

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

Create SSL certificates

Important

Genesys recommends that you create new SSL certificates to ensure your environment uses the latest security enhancements. Contact your Genesys representative if you prefer to use the SSL certificates from a prior GAAP release.

1. Log in to GAAP.
2. Go to Administration > Certificates.
3. Click Import a new Certificate.
4. Perform the following actions:
   • For each GUI and Messaging server:
     1. Enter the host name of the server and the SSL port configured in the server.xml file for that server.
     2. Click Get Certificate.
     3. Enter a description for the certificate.
     4. Click Save.
   • For each VUI server:
     1. Click Create a Self Signed Certificate.
     2. Enter the following information:
        • Server(s) - FQDN of the VUI server.
        • Pass Phrase - Enter a secure pass phrase. This value must match the SSLPassword value from the server.xml file for this VUI Tomcat server.
        • Add to Trusted Certificates List - Ensure this option is checked.
        • (Optional) Enter information in the Organisation Unit, Organisation, City, State, and Two-Letter Country Code fields.
     3. Click Generate.
     4. A ZIP file downloads to the machine that contains a certificate and key. Extract the certificate and key, and place the files into the conf folder of the VUI server (for example, C:\SpeechStorm\Platform\TomcatVUI\conf\server.xml).

Copy resources from previous version

Copy resources from the previous version of GAAP to the new version.

1. Copy C:\<BackupFolder>\Platform\TomcatVUI\webapps\fish-vui\resources to C:\<InstallFolder>\Platform\TomcatVUI\webapps\fish-vui\resources.
2. Copy C:\<BackupFolder>\Platform\TomcatGUI\webapps\fish-gui\products to C:\<InstallFolder>\Platform\TomcatGUI\webapps\fish-gui\products.

Next, return to Windows Services and restart the TomcatVUI.

Reintegrate this GAAP server

You have upgraded the server and copied resource files from your previous GAAP version to the upgraded version. Next, you must reintegrate this server into the active servers group.

1. Open a web browser and enter https://localhost:8080/fish-gui/Login.jsp.
2. Login to GAAP.
3. Go to Administration > Servers.
4. Select the VUI that you just upgraded and click Edit. A server details screen appears.
5. Enable the Server Status check box, thereby making the server active. The VUI server's flag turns to green and it is available to take calls again.
6. Monitor the GAAP logs for this instance to ensure it is processing calls as expected.

You can now update the remaining servers in your environment by following all of the steps previously described on this page. Remember to only run Post Migrate.bat on the last server that you upgrade.

Final Setup

Warning

Do not proceed unless you have upgraded all servers in your environment.

1. If you installed a Messaging server, expand the toggle below. Otherwise, continue to the next step.
   [+] 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.
2. Restart GAAP services, including FishGUI and FishMessaging. Do not restart FishVUI.
3. After the services restart, log in again and go to Administration > Servers. Ensure all components are online.

Next Step

Go to Post-Installation Configuration to complete setup.