Deploying Advisors Platform

You run a .jar installation file to deploy Advisors Platform. Use the procedure below to start your installation. The installer guides you through the deployment. The screens displayed during your deployment are dependent on the selections you make on the Module to Install screen. Information about each screen is available on the Installation Screens tab below.

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

Deployment 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 servers on which you will deploy one of the following Advisors components:
   • Contact Center Advisor Web Services
   • Workforce Advisor
   • Frontline Advisor
   • Contact Center Advisor–Mobile Edition
   • Resource Management Console
4. Install each adapter you will use (AGA and ACA).
5. Register the Stat Servers that you plan to use with Advisors.
6. [+] Install the Advisors components for your enterprise.
   • Contact Center Advisor
   • Workforce Advisor
   • Contact Center Advisor – Mobile Edition
   • Frontline Advisor
   • SDS and Resource Management
7. Make any required configuration changes.

<tabber>

Procedure=

Procedure: Deploying Advisors Platform

Prerequisites

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

Steps

1. Launch the installation file.
   [+] Show Steps for Linux
   1. As root, navigate to the Advisors home directory:
      

      cd /home/advisors

   2. 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.

2. Use the Next and Back buttons on the installer to navigate through the installation screens. Enter your information on each screen; see the Installer Screens descriptions for additional information. Ensure you provide complete information on each screen.
3. On the final screen, click Install.
   If errors display, diagnose them in the Errors tab, or refer to the Troubleshooting tab on this page.
4. If you use a Windows platform, install the Advisors windows service as follows:
   [+] Show Steps

   
   

   1. Do this only for Advisors servers that will not be controlled by Solution Control Server. For a list of those, see Integration With Genesys Management Layer.
   2. Open a command prompt, and change directory first to your Advisors base directory (for example, Program Files\GCTI\Advisors), then to bin\windows-x86.
   3. 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

   
   

   1. Do this only for Advisors servers that will not be controlled by Solution Control Server. For a list of those, see Integration With Genesys Management Layer.
   2. Open the shell.
   3. As root, run the following export command to add the JDK to your path:
      

      export PATH=/home/advisors/jdk1.7.0_<version>/bin:$PATH

   4. 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>

   5. Test the installation as the Advisors user.
      1. Specify the JDK path for this session (temporarily):
         

         export JAVA_HOME=/home/advisors/jdk1.7.0_<version>

      2. Start Advisors Platform:
         

         ./<Advisors directory>/geronimo-tomcat6-minimal-2.2.1/bin/geronimo.sh run

      3. Ensure that there are no errors reported and that the Advisors Administration module is available at http://<host>:8080/admin/.
   6. Configure Advisors Platform to run automatically as a system service.
      1. 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
         ;;

      2. As root, make the startup script executable:
         

         chmod 755 /etc/init.d/advisors

      3. As root, configure the system to start the Advisors process at boot time:
         

         chkconfig --add advisors
         chkconfig --level 235 advisors on

      4. 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
      5. 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.
      6. 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.
      7. 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.
5. If you are running Platform with a 64-bit JVM, Genesys recommends that you increase your Geronimo PermGen memory settings.

|-| Installer Screens=

[+] Administration Configuration - CCAdv XMLGen

35px|link= The Administration Configuration - CCAdv XMLGen screen displays for nodes on which you opted to install the Administration module (on the Module to Install screen). If your Advisors deployment includes XML Generator, you must enter information on this screen. This ensures XML Generator stays up-to-date with changes made in the Administration module.

If you are not deploying Advisors in a warm standby configuration, then enter information about the XML Generator application in the fields for the primary application.

If your deployment does not include XML Generator (for example, if you are installing only Frontline Advisor in this deployment), then leave the fields on the Administration Configuration - CCAdv XMLGen screen blank.

[+] Administration Configuration - SC Server

35px|link= The Administration Configuration - SC Server screen displays for nodes on which you opted to install the Administration module (on the Module to Install screen). If your Advisors deployment includes XML Generator, you must enter information on this screen. This ensures XML Generator stays up-to-date with changes made in the Administration module.

If your deployment does not include XML Generator (for example, if you are installing only Frontline Advisor in this deployment), then leave the field on the Administration Configuration - SC Server screen blank.

[+] Application Server Configuration

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 the Procedure, Step 5.

[+] Backup Config Server

The Backup Config Server screen displays only if you selected the Add backup server checkbox on the Genesys Config Server Connection Details screen.
Enter the backup Configuration Server details:

• Backup Server Name
• Backup Server Address
• Backup Server Port Number

[+] Cache Configuration

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.

[+] CCAdv/WA Object Configuration User

On the CCAdv/WA 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).

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.

[+] Cluster Node Configuration

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.

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.

[+] Destination Directory

On the Destination Directory screen, specify the directory for your Advisors installation.

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.

[+] Genesys Advisors Platform Database

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.

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.
• Database name (SQL Server) or Service name (Oracle)—The unique name or service 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.

[+] Genesys Advisors Platform Database - Advanced

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.

On the Genesys Advisors Platform Database - Advanced 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.

[+] Genesys Config Server Connection Details

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

• 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). 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.

[+] Java Development Kit

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

[+] Language Options

On the Language Options screen, specify the languages to use in e-mail templates. 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. You can also specify which language to use as the default language; you can select only one default language. The default language is the language in which metric names and descriptions will be shown if there are none provided for the language in which the user is viewing the dashboard.

[+] Mail Service Configuration

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.

[+] Module to Install

On the Module to Install screen, select the Administration workbench checkbox to install this package. Selecting this option installs the Administration module and adds an Administration.properties file to the <advisors>\conf folder.

In previous releases, if you were installing Advisors Platform to support a clustered Advisors suite server, then you installed only one instance of the Administration module on one system in the cluster. That restriction is no longer applicable; you can install more than one instance of the Administration module in a clustered environment.

For more information about a clustered Advisors suite server, see Scaling the System to Increase Capacity.

[+] 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 release 8.5.1.

[+] RDBMS Type And JDBC Connectivity

35px|link= 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.

[+] User Management Options

On the User Management Options screen, configure options associated with user activities.

1. 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.
2. Add the name of the default Genesys tenant to which new users will be added. The name of the tenant is case sensitive.
3. 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.

|-| 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.
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.
link=] The installer fails or gives the following error message: Caused by: java.security.AccessControlException: access denied ("javax.management.MBeanTrustPermission" "register")	To correct this error, go to the Java installation that is specified in the path included in the error message, or the Java installation defined as JAVA_HOME. To the java.policy file under jre/lib/security, add the following to the granted permissions: permission java.util.PropertyPermission "javax.management.MBeanTrustPermission", "register"