Jump to: navigation, search

Migration Procedures

This section describes how to upgrade to the latest version of Genesys Intelligent Automation, without incurring a service outage in all but the smallest (only one VUI) configurations.

Prerequisites

Before you start to upgrade your Intelligent Automation installation, be sure that you meet the following prerequisites:

  • You are running an instance of Intelligent Automation, of any previous version, with more than one VUI.
  • If you are using an Oracle database, a SYS user has executed the following command in Oracle:
ALTER SYSTEM SET open_cursors = 600 scope=BOTH;
  • If you are going to use a new or different DBMS for your Intelligent Automation core and/or reporting databases, you have set up the database, as described in the Database requirements section of 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.


Important
  • Before installing new version of IA or before migrating databases to a new version, ensure that you take a backup of the existing database before proceeding.
  • Ensure that you always migrate the IA databases before upgrading the IA application.
  • Even though you can migrate your database during the first server upgrade, DO NOT perform any post-migration activities until you have upgraded all of your servers.
  • Starting from 9.0.121+, the OpenJDK runtime environment is no longer packaged with the GIA installer. Install OpenJDK separately and set the environment variable GIA_JAVA_HOME to "C:\Program Files\Java\jdk-17" or the path where the JDK is installed.
  • When upgrading from the previous version, please test all existing call flows in a test environment.

Stop the server

Select one of the servers to upgrade and then deactivate it within the GUI, as follows:

  1. Log in to Intelligent Automation.
  2. Go to Administration > Servers. Intelligent Automation displays a list of servers in your environment.
    Tip
    Note the name and ID number of servers in this list (for example, FishGUI and 1) as this information will be required later in this process.
  3. Select one server to upgrade. Click Edit. A server details screen appears.
  4. De-select the Server Status check box, thereby making the server inactive.
  5. Click Save.
  6. 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.
  7. 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 Intelligent Automation 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 your current Intelligent Automation server

Warning
Before you start to uninstall the existing Intelligent Automation server, be sure to make a backup of the existing folder structure. If you used the default install location for Intelligent Automation, go to C:\SpeechStorm\Platform and copy its contents to another location.

Open the C:\SpeechStorm\Setup folder, right-click SS_FW_Uninstall.bat, and select Run as administrator. Like when installing this file's predecessor, SS_FW_Install.bat, you must select Run as administrator to ensure that the server is uninstalled correctly.

Tip
Remember the tip about noting server names? This information will be used here.

This file prompts you for information about your current installation, prompting you as follows:

Enter the name of the GUI service. For example: FishGUI.
Enter the name of the TomcatGUI service; for example, FishGUI.
Enter the name for the TomcatVUI Windows Service; for example, FishVUI
Enter the name of the TomcatVUI service; for example, FishVUI.
Enter the name for the TomcatMessaging Windows Service; for example, FishMessaging
Enter the name of the TomcatMessaging service; for example, FishMessaging.
Enter the name for the License Manager Windows Service; for example, SpeechStorm License Manager
Enter the name of the SpeechStorm License Manager; for example, "SpeechStorm License Manager". Be sure to put the name in quotation marks, since there are blank spaces in the name.
Would you like to delete the SpeechStorm Platform directory? (Y/N)
Enter y to remove all contents of the folder in which you installed SpeechStorm; for example, C:\SpeechStorm\Platform' if you used the default. This is also the folder that you backed up before starting this uninstall.
Important
This path is case sensitive. If incorrect, the installer prompts you to enter the path again.

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. Do one of the following:
    • Use the 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.
    • Update the database connection details in the TomcatVUI database.properties file to point to the existing databases that will be used for this install. The file is located here: C:\SpeechStorm\Platform\TomcatVUI\lib\database.properties Inside each database.properties file are sets of template connection strings for SQL Server and Oracle with all but the SQL Server strings commented out. You must update these details to match your new environment. Ensure you only uncomment one set of connection strings for each database—the core database and the reports database. For example, if you are using SQL Server for your core database and Oracle for your reporting database, make sure that all other strings are commented out in the sections for each database.
      SQL Example 
      #######################################
#
#  SQL Server
#
#######################################
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 12c and 19c
#
#######################################
Database.JDBC.Driver=oracle.jdbc.OracleDriver
Database.JDBC.ConnectionURL=jdbc:oracle:thin:@localhost:1521:db01
Database.JDBC.Username=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:db01
ReportsDatabase.JDBC.Username=fishreports_USER
ReportsDatabase.JDBC.Password=speechstorm
ReportsDatabase.Pool.ConnectionValidationQuery=SELECT 1 FROM DUAL
      Important
      If you are upgrading from GAAP 3.2.3 or earlier, you must also insert the following lines into the database.properties file: 
      Database.Pool.ConnectionValidationQuery=SELECT 1
ReportsDatabase.Pool.ConnectionValidationQuery=SELECT 1
  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
    6. Tip
    Remember the note above about 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 Intelligent Automation 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 Intelligent Automation components

To install Intelligent Automation components, and set up the corresponding Windows services, follow the instructions for a new Intelligent Automation installation.


Warning
If you're upgrading from a version prior to GAAP 3.6, upgrade the GUI server first.

Encrypting the Database Password

You can encrypt the password to your database at any time by running the Encryption.bat database script file. If you have entered y in response to the prompt Would you like to encrypt the database password in the database.properties file? during installation, the installer will run this file for you. You can also run the script yourself at any time, either to activate encryption after installation, or to encrypt the password after it has been changed. Even if you start the script but decide you still don't want to perform the encryption, just click press CTRL-C, and you will exit the script with no changes being made.

Use the instructions in the Encrypting the Database Password section of the Intelligent Automation Deployment Guide to encrypt, or un-encrypt, at any time, the passwords to your databases.

Populating the Databases

Use the Migrate.bat and Post Migrate.bat scripts to set up the database schema for Intelligent Automation.

Important
  • Migrate.bat needs to be run only once 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 exit the script (press CTRL-C).
  • Run Post Migrate.bat only if this is the last server installation to be done. DO NOT perform any post-migration activities until you have updated all the servers.

Use Flex to license Intelligent Automation server

Important

If you're upgrading from an older version (before 9.0.108.xx), follow these steps

    • Delete the old License Manager Windows service "SpeechStorm License Manager".
    • Create a copy of the License manager file before deleting the Speechtsorm/Platform folder.
    • Old license file should work with products prior v9.0.108.
    • For the Custom NLM in this release you will need to request a new license from your Genesys representative.

Next, you must license the Intelligent Automation server within Flex before you can start the Intelligent Automation 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. Each instance must have an extra FlexLM license server and license file. Remote licensing is not possible.


  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 Properties. Then, in the Log On tab, select Local System Account.
  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. 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.

Check connector settings

Next, you must check that the connector settings in the new server.xml files matches the settings from your previous installation.

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
  • C:\SpeechStorm\Platform\TomcatIntegration\conf\server.xml
Example of HTTP connector
<Connector port="8080" protocol="HTTP/1.1"
       connectionTimeout="20000"
       redirectPort="8443"
       URIEncoding="UTF-8"
       maxThreads="500"
       />
Example of HTTPS connector
<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 Intelligent Automation services

In Windows Services, start the following services:

  • Apache Tomcat 9.0 FishGUI
  • Apache Tomcat 9.0 FishMessaging
  • Apache Tomcat 9.0 FishVUI
  • Apache Tomcat 9.0 FishIntegration

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 Intelligent Automation release.
  1. Log in to Intelligent Automation.
  2. Go to Administration > Certificates.
  3. Click Import a new Certificate.
  4. Perform the following actions:
    • For each GUI, Messaging server, and Genesys 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.
      Important
      To use TLS 1.2 connections with other Genesys servers, you must set the following Default Server Settings:
      • Set GenesysSDK.ConfigServer.IsTLSEnabled to true
      • Set GenesysSDK.PlatformServer.IsTLSEnabled to true
      • Set HttpClient.Security.SSLContext to TLSv1.2
      • Set HttpClient.Security.SupportedProtocols to TLSv1.2
      Optionally, you can set HttpClient.Security.SupportedCipherSuites to restrict the available cipher suites by adding a comma-separated list of cipher suite names. See this page for more information on valid values.
    • 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 Intelligent Automation 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.


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 'Chat Default Persona', 'Visual Default Persona' check box is enabled.
    5. Click Import.


Next, return to Windows Services and restart the TomcatVUI.

Reintegrate this Intelligent Automation server

You have upgraded the server and copied resource files from your previous Intelligent Automation 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 Intelligent Automation.
  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 Intelligent Automation 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, do the following:
    1. 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.
    2. 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 Intelligent Automation 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 Configuration and make any changes necessary to complete the setup of the upgrade.

This page was last edited on October 5, 2023, at 13:05.
Comments or questions about this documentation? Contact us for support!