Deploying Advisors Platform

You run a .jar installation file to deploy Advisors Platform.

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

Roadmap

1. [+] Install the databases that correspond to the Advisors products you will deploy.
   1. Advisors Genesys Adapter metrics database
   2. Advisors Platform database
   3. Advisors Cisco Adapter database (if you use ACA)
   4. Metric Graphing database
2. Create the Advisors User and the Object Configuration User in Configuration Server.
3. Install the Platform service (Geronimo) on all servers on which you will deploy one of the Advisors components.
   • Contact Center Advisor
   • Workforce Advisor
   • Frontline Advisor
   • Contact Center Advisor–Mobile Edition
   • Resource Management Console
4. Install each adapter you will use (AGA and ACA).
5. [+] Install the Advisors components for your enterprise.
   • Contact Center Advisor
   • Workforce Advisor
   • Contact Center Advisor – Mobile Edition
   • Frontline Advisor
   • SDS and Resource Management
6. Make any required configuration changes.

<tabber>

Procedure=

1. If you are deploying Advisors platform on a Linux system, you must first create the Advisors group and user. The Advisors Platform is run as the advisors user, which belongs to the advisors group. [+] Show Steps Open the shell. As root, create the Advisors group: groupadd advisors As root, create the Advisors user in the Advisors group: useradd -s /bin/bash -g advisors advisors The preceding command creates the /home/advisors directory. If you want a different directory, you can use the following command: useradd -g advisors -d <path to the desired directory> advisors You can optionally set a password for the Advisors user: passwd advisors Genesys recommends that you mount /home as a separate partition.

2. Install Oracle Java Development Kit (JDK). [+] Help with Linux environments Download the latest version of an Advisors-supported Oracle JDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html The correct file is an archive binary file (.tar.gz). In the following Steps of this procedure, JDK 7 is used as an example. Ensure you enter the correct version number of the Oracle JDK you use in your installation. As root, navigate to the directory that has the downloaded Oracle JDK and copy the Oracle JDK archive binary file to the Advisors home directory: cp ./jdk-7u<version>-linux-x64.tar.gz /home/advisors Navigate to the Advisors home directory: cd /home/advisors As root, unpack the archive and install the JDK: tar zxvf jdk-7u<version>-linux-x64.tar.gz As root, change the owner of the installed JDK: chown -R advisors:advisors jdk1.7.0_<version> As root, change to the Advisors user and test JDK: su - advisors ./jdk1.7.0_<version>/bin/java -version You should see output similar to the following: java version "1.7.0_40" Java(TM) SE Runtime Environment (build 1.7.0_40-b43) Java HotSpot(TM) 64-Bit Server VM (build 24.0-b56, mixed mode)

3. Place the advisors-platform-installer-<version>.jar file into the Advisors home directory. [+] Show additional information for Linux environments You can start the installer locally or from a remote desktop. To run the installer remotely, use SSH with X11 forwarding enabled: ssh -X root@<host> As root, place the advisors-platform-installer-<version>.jar file into the Advisors home directory.

4. Launch the installation file. [+] Show Steps for Linux As root, navigate to the Advisors home directory: cd /home/advisors As root, run the Advisors platform 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: ./jdk1.7.0_<version>/bin/java -jar advisors-platform-installer-<version>.jar [+] Show Step for Windows Do one of the following: Open a command line window, and enter the following command: advisors-platform-installer-<version>.jar Double-click the advisors-platform-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.

5. On the Module to Install screen, install the Administration workbench, if required. [+] Show Important Notes On the Module to Install screen, select the Administration workbench checkbox to install this package. Selecting this option installs the Administration module. Starting in Release 8.1.5, Frontline Advisor administration is combined with the Administration workbench (module). To administer FA, you must install the Administration workbench with at least one FA instance. If you are installing Advisors Platform to support a clustered Advisors suite server, then install only one instance of the Administration workbench, on one system in the cluster. It is best to install the Administration workbench on a system that is not running the web services for one of the Advisors applications. For more information about a clustered Advisors suite server, see Scaling the System to Increase Capacity.

6. On the Languages for E-mail Templates screen, specify the languages to use in e-mail templates. [+] Show Notes If no languages are selected, English is used. You can select one option, or more than one, regardless of the regional and language setting of the system on which you are installing the platform.

7. On the Destination Directory screen, specify the directory for your Advisors installation. [+] Show Notes Select the directory in which the files will be installed (the Advisors base directory). The default directory is ..\GCTI\Advisors. If this directory does not yet exist, you will be prompted to create it.

8. On the Java Development Kit screen, enter or select the root directory of the Java Development Kit (JDK).

9. On the Application Server Configuration screen enter the port numbers that the Geronimo application server will use. If you are installing only one deployment of Advisors, then accept the defaults that the installer offers. Important If you install Advisors on Linux and need to change the naming port, update the Advisors Platform service startup script as specified in Step 18.

10. On the Cluster Node configuration screen, configure the Advisors Platform installation as a unique node in the cluster. Each server on which you install Advisors Platform requires a unique cluster node ID. On this screen you also enter the port number that nodes in this cluster use to communicate. [+] Show Notes Configure the node with the following information: Node ID – A unique ID across all Platform installations. The ID must not contain spaces or any special characters, and must be only alpha numeric. Node IDs are not case sensitive. Within one cluster, Node1, node1, and NODE1 are considered to be the same ID. You can use node1, node2, and so on. IP Address/Hostname – The IP address or host name that other cluster members will use to contact this node, for example, 192.168.100.1. It is not localhost or 127.0.0.1. When using numerical IP v6 addresses, enclose the literal in brackets. 35px|link= Port number that the nodes in this cluster use to communicate. If you are installing only one deployment of Advisors, accept the default that the installer offers. The port number must be unique to this deployment of Advisors. All nodes in one cluster must use the same port number. Localhost address – The local host address: localhost or 127.0.0.1.

link=] On the Cache Configuration screen, specify the port to be used by the distributed cache for communication. If you are installing only one deployment of Advisors, accept the default that the installer offers. The port number must be unique to this deployment of Advisors. All nodes in one cluster must use the same port number.

12. On the Genesys Config Server Connection Details screen, configure the connection to the Genesys Configuration Server. [+] Show Notes Config Server Name – The name of the primary configuration server; for example, confserv. The name is obtained from the Configuration Manager 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 on which the configuration server is listening; for example, 2020. If you enter a port number in this field, and then enable a TLS connection, this port number is ignored. Config Server Client Name – Enter 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 that Advisors Platform will use to connect to the Configuration Server; for example, default. Config Server password – The password of the account that Advisors Platform will use to connect to the Configuration Server. The Genesys Configuration Server password is encrypted and saved in the ..\GCTI\Advisors\conf\GenesysConfig.properties file by default (unless altered in Step 5). To change the password, see Change Encrypted Passwords. Enable TLS connection – To configure a TLS connection to the Configuration Server, select this option on the installation screen. Config Server TLS Port Number – Enter the Configuration Server TLS port number. When TLS is enabled, Advisors Platform uses the TLS port number instead of the unsecured 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. Add backup server – Select this checkbox if you have a backup Configuration Server for this installation. If you select the Add backup server checkbox, the Backup config server screen displays after you click Next. Enter the backup Configuration Server details on the Backup config server screen: Backup Server Name Backup Server Address Backup Server Port Number

13. On the CCAdv/WFAdv Object Configuration User screen, enter the name of the Object Configuration User account (configured in Configuration Server). You must enter this information if you use a Genesys data source and will be deploying Contact Center Advisor/Workforce Advisor (CCAdv/WA). This is not applicable on a Platform installation if CCAdv/WA is deployed with only Cisco data sources, or if you intend to deploy only Frontline Advisor (FA). [+] Show Notes The Object Configuration User account is used by Data Manager for object configuration for the CCAdv/WA modules. You are not prompted for the password for this user account because there is no user authentication performed for this user.

14. On the User Management Options screen, configure options associated with user activities. [+] Show Steps To synchronize user updates, select the checkbox. Selecting this option controls whether update events from the Configuration Server result in updating the Advisors database with the new information. In a clustered environment, a single Platform instance must be designated as responsible for maintaining the user account synchronization. Enabling this option on multiple clustered instances of Platform will result in redundant updates to the database. Other Platform instances in the cluster will continue to provide PSDK access to Advisors modules, so for them, this configuration option can be deselected. Genesys recommends selecting the Synchronize user updates? checkbox on a node that is not running the web services for one of the Advisors applications. Add the name of the default Genesys tenant to which new users will be added. The name of the tenant is case sensitive. Select the Allow Password Modification? checkbox to enable the Forgot your password? functionality in the Advisors login page, the Administration module, and the dashboards. If you leave this option unselected, you still see the functionality in the user interface, but if you try to use it, Advisors tells you that password modification is not enabled. Note that the user’s ability to see this functionality depends on the Advisors.ChangePassword.canView privilege being granted to the user in Configuration Manager. Warning Performance Management Advisors support Genesys Management Framework Release 8.1.x, but do not fully support the password security authentication options available in Management Framework. Users can be locked out of Advisors if you use Genesys Management Framework 8.1.x in your enterprise. To avoid lockouts, do one or both of the following: Change the following two options in Management Framework to true: the no password change at first login option and the override password expiration option. Assign the Advisors.ChangePassword.canView privilege to all users. For information about the no password change at first login and override password expiration options, see Genesys Framework Configuration Options Reference Manual.

15. On the Database Type screen, select either the SQL Server or the Oracle option – whichever you use for Advisors platform database(s). The screens that follow are dependent on your selection: [+] Show Step for SQL Server On the Genesys Advisors Platform Database 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). If the database server is a named instance, then omit the port number. If you use numerical IPv6 addresses, enclose the literal in brackets. [+] Show Steps for Oracle On the Oracle setup type screen, select the Basic option. On the Genesys Advisors Platform Database screen, specify the parameters for the Advisors platform database: Database server—The host name or IP address of the database server. When using numerical IP v6 addresses, enclose the literal in brackets. Database port number—The database server’s port number. SID—The unique name of the database instance. 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. On the Oracle JDBC Driver screen, specify the location of the Oracle JBDC driver. The following Oracle JDBC drivers can be used: Oracle database 10g release 2 (10.2.0.4). The download file is ojdbc14.jar. Oracle database 11g release 2 (11.2.0.2.0). The download file is ojdbc6.jar. [+] Show Steps for Oracle RAC On the Oracle setup type screen, select the RAC connectivity setup option. On the Genesys Advisors Platform Database screen, specify the parameters for the Advisors platform database: Database user and Database user password—The database schema and password created and used for the Platform database. 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. On the Oracle JDBC Driver screen, specify the location of the Oracle JBDC driver. The following Oracle JDBC drivers can be used: Oracle database 10g release 2 (10.2.0.4). The download file is ojdbc14.jar. Oracle database 11g release 2 (11.2.0.2.0). The download file is ojdbc6.jar.

16. On the Mail Service Configuration screen, specify the e-mail settings that the Forgot Password functionality will use to send e-mail. SMTP Server—The SMTP service to use. Application from address—The sender of this e-mail; for example, DO-NOT-REPLY@genesys.com. Application to address—The recipient of this e-mail; for example, admin@genesys.com.

17. Click Install. If errors display, diagnose them in the Errors tab, or refer to the Troubleshooting tab on this page.

18. If you use a Windows platform, install the Advisors windows service as follows: [+] Show Steps Open a command prompt, and change directory first to your Advisors base directory (for example, Program Files\GCTI\Advisors), then to bin\windows-x86. Run InstallAdvisorsServer.bat. If you use a Linux platform, validate that Advisors Platform installed successfully and then configure Advisors Platform to run automatically as a system service: [+] Show Steps Open the shell. As root, run the following export command to add the JDK to your path: export PATH=/home/advisors/jdk1.7.0_<version>/bin:$PATH As root, change the owner of the directory in which you installed the Advisors Platform to the Advisors user: chown -R advisors:advisors <Advisors directory> Test the installation as the Advisors user. Specify the JDK path for this session (temporarily): export JAVA_HOME=/home/advisors/jdk1.7.0_<version> Start Advisors Platform: ./<Advisors directory>/geronimo-tomcat6-minimal-2.2.1/bin/geronimo.sh run Ensure that there are no errors reported and that the Advisors Administration module is available at http://<host>:8080/admin/. Configure Advisors Platform to run automatically as a system service. As root, create an /etc/init.d/advisors file with the following contents; remember to replace <version> with the version number of your file and <Advisors directory> with your directory’s name: #!/bin/bash # description: Advisors Platform Start Stop Restart # processname: advisors # chkconfig: 235 20 80 JAVA_HOME=/home/advisors/jdk1.7.0_<version> export JAVA_HOME PATH=$JAVA_HOME/bin:$PATH export PATH GERONIMO_BIN=/home/advisors/<Advisors directory>/geronimo-tomcat6-minimal-2.2.1/bin case $1 in start) /bin/su advisors $GERONIMO_BIN/startup.sh ;; stop) $GERONIMO_BIN/shutdown.sh --user system --password manager ;; restart) $GERONIMO_BIN/shutdown.sh --user system --password manager /bin/su advisors $GERONIMO_BIN/startup.sh ;; esac exit 0 Important If you modified the default naming port when running the installer, and the naming port number is no longer 1099, then your non-default port number should be added to the above service control script. For example, if your naming port is 7075, you should add this port to the shutdown and restart sections: stop) $GERONIMO_BIN/shutdown.sh --port 7075 --user system --password manager ;; As root, make the startup script executable: chmod 755 /etc/init.d/advisors As root, configure the system to start the Advisors process at boot time: chkconfig --add advisors chkconfig --level 235 advisors on As root, check that the configuration is correct: chkconfig --list advisors The output should be similar to the following: advisors 0:off 1:off 2:on 3:on 4:off 5:on 6:off As root, test the service startup script: service advisors start Wait until startup is complete and then open the browser (http://<host>:8080/admin/). The Administration module should be available after you log in. As root, test the service stop script: service advisors stop Wait until shutdown is complete and then open the browser (http://<host>:8080/admin/). The page should be unavailable. As root, test that Advisors Platform starts automatically after a reboot: Warning The following command restarts the whole system. shutdown -r now Wait until the system reboots, and then open the browser (http://<host>:8080/admin/). The Administration module should be available after you log in.

19. If you are running Platform with a 64-bit JVM, Genesys recommends that you increase your Geronimo PermGen memory settings.

|-| Troubleshooting=

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

Installation Error Message	Cause
[echo] Setting up cluster member configuration for this node [java] Connecting to database: inf-wolf.us.int.genesyslab.com;oracle:1521;DatabaseName=orcl;user=yevgeny_plt_81 ... [java] updating node: KoolNode ipAddress: 138.120.xx.xx localhost: localhost [java] java.sql.SQLException: ORA-01013: user requested cancel of current operation [java] at oracle.jdbc.driver.Database Error.throwSqlException(DatabaseError.java:112) [java] at oracle.jdbc.driver.T4CTTIoer.process Error(T4CTTIoer.java:331) [java] at oracle.jdbc.driver.T4CTTIoer.process Error(T4CTTIoer.java:288) [java] at oracle.jdbc.driver.T4C8Oall.receive(T4C8Oall.java:745) [java] at oracle.jdbc.driver.T4CPreparedStatement. doOall8(T4CPreparedStatement.java:219) [java] at oracle.jdbc.driver.T4CPreparedStatement. executeForRows(T4CPreparedStatement.java:970) [java] at oracle.jdbc.driver.OracleStatement. doExecuteWithTimeout(OracleStatement.java:1190) [java] at oracle.jdbc.driver.OraclePreparedStatement. executeInternal(OraclePreparedStatement.java:3370) [java] at oracle.jdbc.driver.OraclePreparedStatement. executeUpdate(OraclePreparedStatement.java:3454) [java] at com.informiam.installer.DAO.executeTimedOutUpdate (DAO.java:214) [java] at com.informiam.installer.ConfigureClusterMember. performActivities(ConfigureClusterMember.java:60) [java] at com.informiam.installer.AbstractDatabaseUtility. doMain(AbstractDatabaseUtility.java:56) [java] at com.informiam.installer.ConfigureClusterMember. main(ConfigureClusterMember.java:34)	This type of error may happen when the installer attempts to update a table which is locked by a not-committed transaction (usually with Oracle database). The wording of the error may differ, but the key phrase to look for is ORA-01013: user requested cancel of current operation. Typically this could happen with an Oracle database when someone runs a query such as DELETE FROM <TABLE_NAME> without then executing COMMIT; and the installer tries to update the same table. In this case, the installer will wait for 20 seconds and fail with an error similar to the above. To correct this, execute COMMIT; after the DELETE statement and re-run the installer. To prevent this situation, always run COMMIT; when manually updating tables in Oracle.
[java] Failed to connect to the database using connection URL: [java] jdbc:sqlserver://192.168.xx.yy:nnn;DatabaseName=ys_pldb;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_pldb;selectMethod=cursor; user=badUserId;password=very_secure_password	Wrong database user name or password
[echo] pinging cluster node IP address 138.120.yy.zz... [java] WARNING! Host 138.120.yy.zz is unknown - java.net.UnknownHostException: 138.120.yy.zz. This may be due to a firewall blocking requests or a specific server configuration, e.g.: permissions. [java] ERROR! Host 138.120.yy.zz is unknown - java.net.UnknownHostException: 138.120.yy.zz. This may be due to a firewall blocking requests or a specific server configuration, e.g.: permissions. [java] Exception in thread "main" java.security.InvalidParameterException: Host 138.120.yy.zz is unknown - java.net.UnknownHostException: 138.120.yy.zz. This may be due to a firewall blocking requests or a specific server configuration, e.g.: permissions.	The cluster member node identified by the IP address specified is not reachable. This may be for one of the following reasons: The host is not online A firewall is blocking access to the host The IP address of the host is incorrect The host is configured to not respond to ICMP ping requests
Apr 11, 2011 3:53:46 PM oracle.jdbc.driver.OracleDriver registerMBeans WARNING: Error while registering Oracle JDBC Diagnosability MBean. java.security.AccessControlException: access denied (javax.management.MBeanTrustPermission register) at java.security.AccessControlContext.checkPermission(Unknown Source) at java.lang.SecurityManager.checkPermission(Unknown Source) at com.sun.jmx.interceptor.DefaultMBeanServerInterceptor.checkMBeanTrust Permission(Unknown Source) at com.sun.jmx.interceptor.DefaultMBeanServerInterceptor.registerMBean(Unknown Source) at com.sun.jmx.mbeanserver.JmxMBeanServer.registerMBean(Unknown Source) at oracle.jdbc.driver.OracleDriver.registerMBeans(OracleDriver.java:360) at oracle.jdbc.driver.OracleDriver$1.run(OracleDriver.java:199) at java.security.AccessController.doPrivileged(Native Method) at oracle.jdbc.driver.OracleDriver.<clinit>(OracleDriver.java:195)	Produced in error and can be ignored. Displays in the Errors tab when installing Platform with Oracle JDBC driver ojdbc6-11.2.0.2.0, and accurately reports that installation was successful.
Exception in thread "AWT-EventQueue-0" java.lang.ArrayIndexOutOfBoundsException: 32 at sun.font.FontDesignMetrics.charsWidth(Unknown Source) at javax.swing.text.Utilities.getTabbedTextOffset(Unknown Source) at javax.swing.text.Utilities.getTabbedTextOffset(Unknown Source) at javax.swing.text.Utilities.getTabbedTextOffset(Unknown Source) at javax.swing.text.PlainView.viewToModel(Unknown Source) at javax.swing.text.FieldView.viewToModel(Unknown Source) at javax.swing.plaf.basic.BasicTextUI$RootView.viewToModel(Unknown Source) at javax.swing.plaf.basic.BasicTextUI.viewToModel(Unknown Source)	Produced in error and can be ignored.
[loadfile] Unable to load file: java.io.FileNotFoundException: C:\ (The system cannot find the path specified)	Produced in error and can be ignored.
link=]java.sql.SQLRecoverableException: IO Error: Connection reset	Related to the operation of the Oracle JDBC driver. Use the following workaround. Edit the <jdk>/jre/lib/security/java.security file: Change securerandom.source=file:/dev/urandom to securerandom.source=file:///dev/urandom.