Deploying Advisors Genesys Adapter

You run a .jar installation file to deploy Advisors Genesys Adapter (AGA). The installation wizard guides you through the deployment. The screens displayed during your deployment are dependent on the selections you make on the Module to Install and Server Type screens. Information about each screen is available in the Installer Screens descriptions, below.

Important

In release 9.0, there are changes to the installation wizard screens; therefore, you cannot reuse your previous setup for silent installation or any saved ant.install.properties file.

If you will be configuring multiple Genesys Adapters, note the following:

• Each primary AGA among the multiple adapters configured should use Stat Servers different from those used by other primary adapters.
• The primary and the backup AGA in a pair must be configured with the same Stat Servers.

For example, if there are two pairs of adapters configured (AGA1 and AGA2, and AGA3 and AGA4). AGA1 and AGA2 form a primary-backup HA pair. AGA3 and AGA4 form another primary-backup HA pair. The Stat Servers configured for the AGA1/AGA2 pair must not be the same Stat Servers configured for the AGA3/AGA4 pair. The Stat Servers configured for AGA1 and AGA2 must be the same Stat Servers, and the Stat Servers configured for AGA3 and AGA4 must be the same.

The preceding rules ensure the following:

1. On restart of the system, based on the last persisted Stat Server–object mapping, the statistics are requested with the same adapters, and each adapter queries the same Stat Servers as previously.
2. On switching over from the primary adapter to the backup adapter, the statistics are requested with the same Stat Servers as previously.

Important

Genesys recommends that the AGA metrics database selected for the primary and the backup AGA instances of a given adapter pair should be the same metrics database.

Deployment Roadmap

The arrow icon in the following roadmap indicates where you are in the Advisors deployment process.

1. Install the databases that correspond to the Advisors products that you will deploy. Perform the database installation in the following order:
   1. AGA metrics database
   2. Grant select privileges on all AGA metrics views to the Platform user.
   3. Metric Graphing database
   4. Advisors Platform database
      [+] REVIEW IMPORTANT INFORMATION HERE

      If the Oracle Platform deployment script issues the following error, ORA-20001: spCreateOneSourceView ORA-01031: insufficient privileges, and you are sure that the Platform user has been issued all necessary privileges, then you might have role-based Oracle security set for the Platform user by your DBA. Make sure you take the deployment script from the current_user sub-folder in the installation package. You can apply the correct script on top of the one that you applied previously, ignoring the exceptions about existing objects and primary key violations. Alternatively, you can ask your DBA to recreate the user and the privileges and apply the correct script.

      If your installation package does not contain a current_user folder, edit the following scripts by replacing all entries of DEFINER with CURRENT_USER and repeat the database deployment process.

      • If initially you used advisors-platform-<version>_Schema.sql or advisors-platform-<version>_ObjectsPlus.sql, edit these scripts:
        advisors-platform-<version>_CUSTOM_ROUTINE.sql
        advisors-platform-<version>_PIMPORT_xxx.sql
        advisors-platform-<version>_Routine1.sql
      • If initially you used advisors-platform-<version>_ObjectsCustom.sql or advisors-platform-<version>_ObjectsDefault.sql, this would be the only script to edit.

      If you prefer, you can contact Genesys Support to obtain the edited scripts.

      Alternatively, you can set up the enhanced Oracle security to run Advisors applications as an application user with least privileges. For instructions, see Least Privileges: How to Configure Advisors Database Accounts with Minimal Privileges.

      If necessary, run the Advisors Object Migration utility. You must run the Advisors Object Migration utility when:

      • You first install Advisors in an environment with a new Configuration Server or when you move an existing Advisors installation to a new Configuration Server.
      • If any of the required Business Attributes folders that Advisors components use are not already present in the Configuration Server.
      • If you decide to enable metrics that are not yet present in your Configuration Server.
      • If you decide to use the Advisors default rollup configuration. Starting with Advisors release 9.0.001.06, a brand new Platform database contains a set of Advisors default hierarchy objects that must be added to the Configuration Server to make the automatic configuration visible on the dashboard. The automatic configuration consists of all base objects mapped to the default hierarchy. For more information, see Contact Center Advisor Default Rollup Configuration in the Contact Center Advisor and Workforce Advisor Administrator User's Guide.
      • If you perform a new installation in an environment that previously had an Advisors release installed that was older than release 8.5.1. In this case, remove all FA metrics that are in the Configuration Server and then run the migration wizard to populate all FA and CCAdv metrics and hierarchy business attributes.
2. Create the Advisors User account in Genesys Configuration Server.
3. Install the Platform service on servers where it is required for Advisors components. The Platform service is a prerequisite for installing the following components:
   • Advisors Administration
   • Advisors Web Services
   • WA Server
   • FA Server with rollup engine
   • CCAdv/WA/FA Accessibility services
   • CCAdv/WA Resource Management console
4. Install each adapter that you will use and configure the adapter Application objects with Stat Server connections. See additional information for CCAdv/WA installations.
5. Install the Advisors components for your enterprise.
   • Contact Center Advisor server (CCAdv XML Generator)
   • Workforce Advisor server
   • Frontline Advisor server
   • SDS and the CCAdv/WA Resource Management console
6. Make any required configuration changes.

You can deploy AGA on a Red Hat Linux or a Windows platform, and with Oracle or MS SQL databases.

Migration Notes

If you are migrating to a new software release, and not installing Advisors Genesys Adapter (AGA) for the first time, there is an existing AGA entry in the ADAPTER_INSTANCES table in the Platform database. You have two options when upgrading your AGA instance:

1. Install the new AGA instance with the same host name and port number as the previous installation. The previous adapter is updated with the new configuration. For this option, you must have information about the earlier adapter to ensure you overwrite it successfully: host and port number. Ensure you enter that information on the Adapter Port and Registration Option installation screen to match the previous entry exactly. If this information is unavailable, you can find it in the ADAPTER_INSTANCES database table on the Platform database.
2. Install the new AGA instance with a different adapter host name and port number; it is added as a second adapter in the Platform database. Use this option to install a new adapter instance, or if you need to move the adapter to a new host name or port number. If moving the adapter to a new host name or port number, you must manually remove the previous adapter entry from the Platform database.

Migrating the AGA Metrics Database or Schema

You use scripts supplied by Genesys to simply remove old objects and then add new objects to the Advisors Genesys Adapter metrics database. Genesys provides two scripts for Oracle and one for MS SQL; see the following procedures. Review the Readme.txt file included with the scripts. The Readme file includes important information, including which tools Genesys recommends to execute the scripts.

Procedure: Migration of AGA Oracle METRICS Schemas

Steps

1. Connect to your database management interface as the AGA METRICS user.
2. Execute one of the following scripts:
   • gc_metrics_<version>_ObjectsPlus.sql (if you use SQL*Plus)
   • gc_metrics_<version>_ObjectsDefault.sql (if you use sqlDeveloper and all objects reside in the default tablespaces assigned to the METRICS user)
   • gc_metrics_<version>_ObjectsCustom.sql (if you use sqlDeveloper and you want to specify explicit names for tablespaces)
3. Re-issue the GRANT SELECT commands on each METRICS schema view to the Platform user.

Procedure: Migration of AGA MS SQL Databases

Steps

1. Connect to the AGA metrics database.
2. Execute gc_metrics_db_<version>.sql.

Deploying Advisors Genesys Adapter

Procedure:

Prerequisites

• Review the General Prerequisites and prerequisites specific to Advisors Genesys Adapter deployment before beginning deployment.

Steps

1. Launch the AGA installation file.
   [+] Show Steps for Linux

   
   

   1. As root, navigate to the Advisors home directory:
      

      cd /home/advisors

   2. As root, run the AGA installer. The page format of this document might cause a line break in the following command, but you must enter it on one line in the command prompt window. The following example uses jdk1.8.0. When you run the command in your environment, be sure to enter the JDK version number that you use in your installation.

      ./jdk1.8.0_<version>/bin/java -jar aga-installer-<version>.jar

      See the Genesys Supported Operating Environment Reference Guide for information about Java versions supported with each Advisors release.

   
   [+] Show Steps for Windows

   
   Do one of the following:

   • Open a command line window, and enter the following command:
     

     java -jar aga-installer-<version>.jar

   • Double-click the aga-installer-<version>.jar file in the release bundle.

   Double-clicking might not work due to system settings, but using the command line terminal should always work. Genesys recommends using the command line window to launch the installer.

   For 64-bit systems, if double-clicking to launch the installer, please ensure that the Java instance associated with the jar file type is 64-bit. Running the installer with a 32-bit Java instance will create a Windows service with the wrong executable.

2. On the Module to Install screen, select the Adapter Server radio button.
3. Use the Next and Back buttons on the installer to navigate through the installation screens. Enter your information on each screen. Use the information provided in the Installation Screens section on this page to complete the remaining deployment screens. Ensure you provide complete information on each screen.
4. Click Show Details and verify that there were no errors reported during installation.

Installation Screens

[+] Adapter Metrics Database

On the Adapter Metrics Database screen, specify the parameters for the metrics database:

• Database Server—The host name or IP address of the database server. When using numerical IPv6 addresses, enclose the literal in brackets.
• Database name/Service name—The unique name of the database instance; for example, advisors_gametricsdb.
• Database port—The database server’s port number.
• Database user—The Advisors user that will be used by the Adapter to access the database.
• Database password—The password associated with the Advisors user that will be used by the Adapter to access the database.
  Important

  The CCAdv/WA metrics database password is encrypted and saved in the ...\GCTI\Advisors\Genesys\Adapter\conf\ inf_genesys_importer.properties file by default. To change the password, see Change Encrypted Passwords.

[+] Adapter Metrics Database - Advanced

You will see this screen only if you select Oracle as the database type and Advanced as the JDBC connectivity setup type on the RDBMS Type And JDBC Connectivity installer screen. On the Adapter Metrics Database - Advanced screen, enter the database connectivity parameters for the already created or upgraded database (that is, the database must be present and at the current version prior to running the installer).

Specify the following parameters for the metrics database:

• Database user—The Advisors user that will be used by the Adapter to access the database.
• Database user password—The password associated with the database user.
• Locate file—Enter the location of the file that contains the advanced database connection string. If you do not know how to correctly build the advanced database connection string, contact your database administrator. The installation wizard applies the specified advanced connection string when configuring the data sources.

[+] Adapter Port And Registration

On the Adapter Port and Registration screen, you enter information that the Advisors Platform database requires to register this adapter instance.

You must enter the following information about your adapter:

• The port number on which the Genesys Adapter web services will run. You can use the default port, 7000, if no other application is using that port.
• The IP address of the host.
• A description of the AGA server.

[+] Advisors Platform Database

On the Advisors Platform Database screen, specify connection information for the the Advisors Platform database with which this AGA will be registered.

If you use numerical IPv6 addresses, enclose the literal in brackets.

You are prompted for the following information on the Advisors Platform Database screen:

• Database server—The host name or IP address of the database server. When using numerical IP v6 addresses, enclose the literal in brackets.
• Database name/Service name—The unique name of the database instance.
• Database port—The database server’s port number.
• Database user—The Advisors user with full access to the Advisors Platform database.
• Database user password—The password created and used for the Advisors Platform database.

[+] Advisors Platform Database - Advanced

You will see this screen only if you select Oracle as the database type and Advanced as the JDBC connectivity setup type on the RDBMS Type And JDBC Connectivity installer screen. On the Advisors Platform Database - Advanced screen, enter the database connectivity parameters for the already created or upgraded database (that is, the database must be present and at the current version prior to running the installer).

Specify the following parameters for the Advisors Platform database:

• Database user—The database user created and used for the Platform database.
• Database user password—The password associated with the database user.
• Locate file—Enter the location of the file that contains the advanced database connection string. If you do not know how to correctly build the advanced database connection string, contact your database administrator. The installation wizard applies the specified advanced connection string when configuring the data sources.

[+] Genesys Config Server Connection Details

On the Genesys Config Server Connection Details screen, configure the connection to the Genesys Configuration Server(s).

1. To connect to the primary (mandatory) Configuration Server in the Genesys environment, enter information in the following text fields:
   • Config Server name – The name of the primary configuration server. The name is obtained from your Genesys configuration interface (for example, Genesys Administrator) and is case sensitive.
   • Config Server address – The name or IP address of the machine hosting the Configuration Server. When using numerical IPv6 addresses, enclose the literal in brackets.
   • Config Server port number – The port that the configuration server is listening on. If you enter a port number in this field, and then enable a TLS connection, this port number is ignored.
   • Config Server client name – The name of the application that Advisors Platform will use to log in to the Configuration Server (for example, default).
   • Config Server user – The user name of the account the Adapter will use to connect to the Configuration Server.
   • Config Server user password – The corresponding password of the account the Adapter will use to connect to the Configuration Server.
     Important

     The Genesys Configuration Server password is encrypted and saved in the <adapterhome>\conf\inf_genesys_adapter.properties file by default. To change the password, see Change Encrypted Passwords.
2. If you use a TLS connection to the Configuration Server, also complete the following:
   • Enable TLS connection – To configure a TLS connection to the Configuration Server, select this option on the installation screen. If you have a backup Configuration Server, AGA also connects to it using TLS if you enable a TLS connection to the primary Configuration Server.
   • Config Server TLS Port Number – Enter the Configuration Server TLS port number. If you enable a TLS connection, the TLS port number is used for both the primary and backup Configuration Servers. The port number for an unsecured connection is ignored. The primary and backup Configuration Servers must use the same TLS port number.
   • Locate TLS properties file – Identify the location of the TLS properties file. The TLS properties file contains all the properties required to connect successfully using TLS, as well as any other optional TLS attributes that you use. If you use a backup Configuration Server, the TLS properties for the primary server are also used for the backup server.
3. Add backup server – Select this checkbox only if you have a backup Configuration Server. The backup Configuration Server can be, but does not need to be, configured in a high-availability pair in Genesys.

[+] Backup Config Server

You see the Backup Config Server screen only if you opted to add a backup Configuration Server on the Genesys Config Server Connection Details screen.

Enter the information required to connect to the backup Configuration Server:

• Backup server name – The name of the backup configuration server. The name is obtained from your Genesys configuration interface (for example, Genesys Administrator) and is case sensitive.
• Backup server address – The name or IP address of the machine hosting the backup Configuration Server. When using numerical IPv6 addresses, enclose the literal in brackets.
• Backup server port number – The port that the backup Configuration Server is listening on. If you enter a port number in this field, but enabled a TLS connection for the primary Configuration Server, this port number is ignored. If the primary server connection uses a TLS connection, then the backup server connection is also a TLS connection. When you enable the TLS connection, you must enter the Configuration Server TLS port number; Advisors uses that port for the connection for both the primary and backup Configuration Servers.

[+] Installation Details

On the Installation details screen, specify the installation directory and the directory in which the log files will appear. The default installation directory is C:\Program Files\GCTI\Advisors\Genesys\Adapter.

[+] Java Development Kit

On the Java Development Kit screen, specify the location of the root directory of the Java installation.

[+] Log Files Directory

Starting with release 9.0.001, the installation wizard prompts you to provide the log file storage location, and provides a default path. If you plan to use a log file storage location that is not the default location, then specify the location on the Log Files Directory screen. The installation wizard checks that the selected storage directory is present; if not present, then the wizard creates it. The installation wizard stores the selected log file storage location in one of the following files:

• The properties file specific to the module that you are installing. The log file configuration file picks up the location from the module's properties file.
• The log4j configuration file.

Specifying the log file directory in the installation wizard will not change the directory that was set for previous installations.

For more information about log files, see Adjust Logging Settings and Configure Administrative Actions Logs.

[+] Oracle JDBC Driver

On the Oracle JDBC Driver screen, specify the location of the Oracle Java Database Connectivity (JDBC) driver. See the Genesys Supported Operating Environment Reference Guide for information about drivers supported in the current release.

[+] RDBMS Type and JDBC Connectivity

On the RDBMS Type And JDBC Connectivity screen, select either the SQL Server or the Oracle option – whichever you use for database(s). You must also select the Java Database Connectivity (JDBC) type that matches your environment. Select Basic for standalone databases or Advanced for clustered database configurations. The screens that follow are dependent on your selections on this screen.

[+] SCS Integration Configuration

You enter information about the AGA connection to the Genesys Management Layer on the SCS Integration Configuration screen. You must configure these properties even if you are not configuring warm standby mode of operation.

• Adapter application name—The application name specified in Genesys Administrator for this AGA instance.
• LCA port—Unless you changed the LCA port number, accept the default.
• SCS application name—The name of the Solution Control Server application object as it appears in Genesys Administrator.

[+] Server Type

On the Server Type screen, select the radio button that corresponds to the Advisors module for which you are deploying this AGA instance. The options are Contact Center Advisor/Workforce Advisor and Frontline Advisor. You can select only one option on this screen.

Multiple instances on a server

It is possible to deploy multiple instances of the Genesys Adapter core service on a single server. If you do use the same metrics database for more than one adapter, each adapter must monitor a completely distinct set of objects. For each installation, you should create the metrics database.

Deploy the second, and subsequent AGA instances, using the same procedure you use to deploy a single instance, and follow these rules:

• You must install each Genesys Adapter instance in a different directory. For example, the first instance could use the following location:
  C:\Program Files\GCTI\Advisors\Genesys\Adapter
  and the second instance could be located at:
  C:\Program Files\GCTI\Advisors\Genesys\Adapter2.
• You must specify a unique log directory for each Genesys Adapter instance.
• You must specify a unique port number for each Genesys Adapter instance.
• You must select a unique application name for each Genesys Adapter instance.

Troubleshooting

The following Table shows parameter validation errors that you may encounter at the end of installation.

Installation Error Message	Cause
[java] Failed to connect to the database using connection URL: [java] jdbc:sqlserver://192.168.xx.yy:nnn;DatabaseName=ys_gadb;user=sa;password=very_secure_pwd; selectMethod=cursor [java] The following exception was thrown: com.microsoft.sqlserver.jdbc.SQLServerException: The TCP/IP connection to the host 192.168.xx.yy, port nnn has failed. Error: "Connection refused. Verify the connection properties, check that an instance of SQL Server is running on the host and accepting TCP/IP connections at the port, and that no firewall is blocking TCP connections to the port.	Wrong database server name / IP address or port number
[java] Failed to connect to the database using connection URL: [java] jdbc:sqlserver://192.168.xx.yy:nnnn;DatabaseName=NotAPlatformDB;selectMethod=cursor;user=sa; password=very_secure_pwd [java] The following exception was thrown: com.microsoft.sqlserver.jdbc.SQLServerException: The TCP/IP connection to the host 192.168.xx.yy, port nnnn has failed. Error: "connect timed out. Verify the connection properties, check that an instance of SQL Server is running on the host and accepting TCP/IP connections at the port, and that no firewall is blocking TCP connections to the port."	Wrong database name
[java] Exception while connecting: Login failed for user 'badUserId'. [java] url used: jdbc:sqlserver://192.168.xx.yy:nnnn;DatabaseName=ys_gadb;selectMethod=cursor;user=badUserId; password=very_secure_password	Wrong database user name or password
[loadfile] Unable to load file: java.io.FileNotFoundException: C:\ (The system cannot find the path specified)	Produced in error and can be ignored.
C:\Users\<USERNAME>\AppData\Local\Temp\antinstall\ build.xml:189: The following error occurred while executing this line: C:\Users\<USERNAME>\AppData\Local\Temp\antinstall\ installer-common.xml:468: java.lang.NoClassDefFoundError: javax/xml/bind/DatatypeConverter at com.microsoft.sqlserver.jdbc.SQLServerConnection.sendLogon(SQLServerConnection.java:4061) ...	Ensure that you are launching the installer with a supported version of the Java Development Kit (JDK). You can type java --version in a Windows command prompt window or in the Linux terminal to see which version is currently configured on your system. If you are using a Windows OS, add the JDK folder path to both JAVA_HOME and PATH in environment variables. If you use Red Hat Enterprise Linux, add the JDK folder path to the PATH variable.