(4.4.12) Deployment Guide Windows
- 1 Solution Prerequisites
- 2 Deployment Modes
- 3 Installation
- 3.1 Note
- 4 Upgrade Software
- 5 EF Service Manager
- 6 ActiveMQ Configuration (Redundant Deployment Only)
- 7 Generic Connector Configuration
Solution Prerequisites
Deployment Modes
Installation
Note that the screenshots in this guide may not be up-to-date and may show older version. Please make sure that the file you download is of the desired version, i.e. 4.0.
Download EF Connector Installer
Run the setup wizard GenericConnector 4.0.exe to start the installation process. The .exe file when runs may show an older version on the installer. You may ignore that but make sure that you use the latest version, i.e. 4.0.
Now, select a location to install the software. The default path is C:\Program Files\Generic Connector. The specified path is mentioned as <EF Connector Home> in the rest of the document.
Select the folder for shortcut in Start Menu
Review your selection and if all is okay, proceed with installation.
The installation wizard will copy all the files to the selected folder.
Press finish to close this setup wizard.
Upon successful completion, EF Service Manager app is installed with a shortcut created on the Desktop.
Note
Note that after installing Generic-Connector4.0.exe successfully, you must need to upgrade the Software to version 4.4
Upgrade Software
Click here to upgrade the software
EF Service Manager
EF Service Manager is a mini management console to:
Install / Uninstall Services
Start / Stop ActiveMQ
Start / Stop Generic Connector
Open ActiveMQ configuration file
Open Generic Connector configuration
Open ActiveMQ logs folder
Open Generic Connector logs folder
Proceed with installing the application as a service and do any necessary configuration using EF Service Manager.
Install Windows Services
Run EF Service Manager from the Desktop shortcut. The Service Manager shows the status of all of the Connector services. Click on “Install Service” to install both ActiveMQ and Generic Connector services. Once the services are installed, you will be able to configure and use these services.
After clicking on Install Service, if the services installed correctly, it will prompt a success message or display an error message in case of any issue.
The panel will look like the following after successful service creation.
Manage Services
Run Service Manager from the desktop (if it is not running). You can locate Service Manager from system tray
Run both Services, one after the other.
To validate if ActiveMQ is running, login to the web-console via http://broker-[x]-ip:[web-console-port] with the default credentials [admin/admin] or as per your configured credentials. Reference ActiveMQ Web Console Configuration
In the Queue section, you should find a Queue name Connector1 created.
You can also verify ActiveMQ and GenericConnector from their log files by clicking on the Logs button in both Sections.
ActiveMQ Configuration (Redundant Deployment Only)
ActiveMQ “Config” button opens the ActiveMQ configuration file %ACTIVEMQ%/conf/activemq.xml in your default text editor (e.g. notepad).
Configuring Network of Brokers
Settings for a network of brokers are mandatory for redundant deployment only. These configurations should however be done on one-side only.
ActiveMQ brokers should be configured to run as a network of brokers to communicate with each other both for Active-Active and Active-Passive deployment models.
In activemq.xml, the “Network of Broker” configuration (<networkConnectors>...</networkConnectors>) is commented. Uncomment this tag and specify URI of the other broker to connect to. There are 2 instances of <networkConnector> (i) for Queues, (ii) for topics, where you need to set the value of uri parameter specifying other broker’s (site-B) address.
Note: Make sure that the configurations are active only one one side. On the other side, it should remain commented out.
This commented tag looks like following in activemq.xml file:
The URI on site-A should point to site-B URI “static:(tcp://SITE-B:PORT)” to configure it in network bridge mode.
For more information about configuring a network of brokers, see this article.
ActiveMQ Web Console Setup
ActiveMQ web console runs on HTTPS port 8162 and is enabled by default. You can modify web console configurations in <EF Connector Home>\conf\jetty.xml.
See this article for more information about web console configurations. As shown here we can create our own keystore and certificates for SSL configuration of ActiveMQ console.
Web Console Passwords Configuration
To ensure the security , default passwords for ActiveMQ web console are encrypted. For user “admin” default password is changed to “@ctiveMQSecured1!”.
To generate your own secure password.
Open command prompt
Navigate to <EF Connector Home> through command prompt
Execute the following command
java -cp jetty-util-9.3.12.v20160915.jar org.eclipse.jetty.util.security.Password [<user>] <password>
It will generate the encrypted passwords with three different algorithms i.e. OBF, MD5,CRYPT
Copy the encrypted password along with its algorithm name e.g. CRYPT:adi0HK/rgc8DA and paste it to the <EF Connector Home>\conf\jetty-realm.properties in the sequence: username: password [,rolename]
Save jetty-realm.properties
See this article for more information about generating a secure password for a web console.
Setting up ActiveMQ with Jetty and Active Directory
ActiveMQ administration console can be integrated with Windows Active Directory. The sample Active Directory configurations are outlined in the ldap.config file which is placed here <EF Connector Home>\conf\>
Create Object of Type GroupOfUniqueNames
In Active Directory,
Create a new Object in Active Directory with a class of type ‘GroupOfUniqueNames’ in any group and give it any name. This name should match with the roles attribute of SecurityConstraint in the <EF Connector Home>\conf\jetty.xml, which is explained here. For illustration purposes, we have created an empty group with type ‘Container’ called AdminTestGroup. In this container we have created an object of type ‘GroupOfUniqueNames’ called AdminRoles.
In the next step, add the user you want to give access to as a unique member of AdminRoles. Here we have added the distinguished name of the user called djtest.
You can find a user’s distinguished name from User’s Properties > Attribute Editor > distinguishedName.After adding the members to the group you should be able to see them in the group
Jetty/ActiveMQ Configuration
In <EF Connector Home>\conf\jetty.xml,
Modify the securityConstraint bean in the jetty.xml file and change the value of the roles to the name that you provided to the group you created above with the type ‘GroupOfUniqueNames’ in our case this is AdminRoles.
Modify the securityHandler bean in jetty.xml and change the ref of property name ‘loginService’ to ‘ldapLoginService’ as shown below
Also uncomment the following property ‘identityService’ in securityHandler bean
You will find the ldap.config file on this path <EF Connector Home>\conf\ldap.config.
You will have to update this file according to your Active Directory settings.
Note: Please do not change this string “amqLdapLoginModule“
Description of configuration attributes for Active Directory
Hostname : The IP address of the Active Directory server. In the illustration above, we used 192.168.1.132
Port : The port on which the Active Directory server is running
bindDn : The distinguishedName of a User which is used for initial binding with the Active Directory
bindPassword : The password of the User whose distinguishedName we gave in the bindDn
userIdAttribute : The value of this attribute is the username with which we will login to the ActiveMQ web console.
userPasswordAttribute : The format in which the password is saved in the Active Directory.
userObjectClass : The class of the object which can login to the ActiveMQ console. For instance we have have created a user of class ‘User’
roleBaseDn : This gives the distinguishedName of the group where all the users who can access the ActiveMQ console are added to.
roleObjectClass : The class of the group which contains all the users that we want to give access to.
roleMemberAttribute : This is the type of the members that are added into the group, for instance we have created a group which has the class groupOfUniqueNames and contains members of type ‘uniqueMember’.
roleNameAttribute : Specifies the attribute type of the role entry that contains the name of the role
Setting up SSL to access ActiveMQ console
Caution : Run all of the commands in administrator mode on the command line.
Replace the <KEY_STORE_NAME> with the name of your choice. Also replace the <ALIAS> with the alias of your choice. Make sure that the same names are used when running the commands.
1) Using the keytool provided in the java jdk to run this command
keytool -keystore <KEY_STORE_NAME>.ks -alias <ALIAS>-keyalg RSA -keysize 2048 -sigalg SHA256withRSA -genkey
This will generate the keystore.
2) Now to generate the certificate request file run this command
keytool -certreq -alias< ALIAS> -keystore <KEY_STORE_NAME>.ks -file <CSR_FILE_NAME>.csr
This will generate the certificate request file
3) Now use this certificate request file to get the issuing authority to issue you the certificate
4) You should get two certificates which look like this
5) Now import these certificates using these commands
keytool -import -alias ALIAS -file CERTIFICATE.cer -keystore KEY_STORE_NAME.ks
keytool -import -alias ALIAS -file CERTIFICATE.p7b -keystore KEY_STORE_NAME.ks -trustcacerts
6) Place the certificate files and the keystore in the <EF Connector Home>\conf\
7) Open <EF Connector Home>\conf\jetty.xml . In the property name keystorePath change the value to be the name of your keystore file. Also change the property name keystorePassword’s value to be the password of the keystore. As shown here we can encrypt the password.
Note: Only the OBF algorithm passwords will work here. So the value of keyStorePassword property will look like this OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
ActiveMQ SSL Certificates Configuration
Default ActiveMQ installation includes key and trust stores that reference the dummy self signed certificates. To configure the client provided certificates, copy the follow the instructions below:
In the conf/activemq.xml, edit the attributes in the sslContext element.
Generic Connector Configuration
Generic Connector “Config” button in EF Service Manager will open the folder where Generic Connector is installed.
Open generic-connector.jar file using WinRAR or similar to modify the embedded configuration properties file Config/config.properties.
Open Config\config.properties with text editor
Make the desired changes and update the file in the same jar file
Connector Configuration Parameters
Parameter | Default Value | Description |
NUMBER_OF_LICENSES | 1000 | Number of concurrent agents, DO NOT TOUCH |
CUSTOMER_NAME | Haseeb | Customer Name, DO NOT TOUCH |
KEY | ASDFGHJKLZXCVBNM234RFGHUIOKJMNBFEWSDFGHNJMNBV | License key. Must be obtained from EF Team |
Finesse_1 | https://Finesse-X-DN/finesse/api/ | Primary Finesse URL for Site A |
Finesse_2 | https://Finesse-X-DN/finesse/api/ | Primary Finesse URL for Site B |
ACCESS_TOKEN_URL | https://192.168.1.104:1126/getaccesstoken | SSO get access token URL |
FINESSE_REQUEST_TIMEOUT | 3000 | Finesse requested a timeout (in mili-seconds) |
FINESSE_HEARTBEAT_SLEEP | 5 | Delay in ping to finesse servers (seconds) |
ByPass_SSL | ture | Bypass SSL Certificate if finesse url is https and self signed certificate is used, in case of false Import SSL certificate to JVM if needed |
ACTIVEMQ1 | localhost:61616 | ActiveMQ Primary URL |
ACTIVEMQ1 | localhost:61616 | ActiveMQ Secondary URL |
ACTIVEMQ_TIMEOUT | 30000 | ActiveMQ connection timeout (in milliseconds) |
GRC_CONSUMER_PRIORITY | 127 | Connector1 Queue consumer priority (Used for primary, secondary deployment of GC)(0-127) |
PRIORITY_BACKUP | true | To connect with its primary GC |
RANDOMIZE | false | for failover url |
PREFETCH_SIZE | 20000 | Prefect Size of the messages |
AGENT_STATES_PUBLISHER_DURATION | 5000 | Time after which, states of all agents would be published on topic (In Milliseconds) |
GC_HEARTBEAT_TIMEOUT | 10000 | GC heartbeat timeout |
AGENT_INACTIVITY_DURATION | 30 | Agent inactivity time (in seconds) |
GC_HEARTBEAT_SLEEP | 10000 | gc heartbeat thread sleep time |
AGENT_INACTIVITY_TIME_SWITCH | false | Agent inactivity switch |
DEFAULT_NOT_READY_REASON | 19 | default reason code for not ready (Must be defined in finesse) |
DEFAULT_LOGOUT_REASON | 70 | Default reason code for force logout |
AGENT_XMPP_SUBS_TIME | 10000 | Agent XMPP Subscription Time |
USE_ENCRYPTED_PASSWORDS | false | Use encrypted password |
CHANGE_STATE_ON_WRAPUP | true | Automatically change the state when wrap-up occurs |
LOGLEVEL | TRACE | Log Level |
GC_HEARTBEAT_TIMEOUT | 10000 | GC heartbeat timeout |
USE_ENCRYPTED_PASSWORDS | true | Use password encryption (3Des). (Must be same as in client.) |
CHANGE_STATE_ON_WRAPUP | true | Caller’s state change automatically on wrap-up |
MESSAGE_FORMAT | JSON | Message Format for communication. Expected formats DEFAULT, JSON, XML |
AGENT_LOGS_PATH | C:\\EFLogs\\Agents\\ | Agent Logs Storage path |
AGENT_LOGS_LEVEL | TRACE | Agent Logs Level |
AGENT_LOGS_MAX_FILES | 10 | Max No of Files per agent for logs |
AGENT_LOGS_FILE_SIZE | 10MB | Max file size for agent logs |
XMPP_PING_INTERVAL | 3 | Interval in seconds between XMPP server pings |
ADMIN_ID | Administrator | The username of the administrator account the would be used for phonebook and contact APIs |
ADMIN_PASSWORD | Expertflow464 | The password of the administrator account would be used for phonebook and contact APIs |
Supervisor_initiated_NotReadyReasonCode | 19 | Reason code for supervisor state change to Not_Ready |
Supervisor_initiated_LogOutReasonCode | 20 | Reason code for supervisor state change to Log_Out |
UCCX_SERVER_IP | 192.168.1.29 | For queue stats in case of UCCX |
UCCX_SERVER_USERNAME | Administrator | UCCX DB server UserName |
UCCX_SERVER_PASSWORD | Expertflow464 | UCCX DB server password |
UCCX_DB_USERNAME | uccxhruser | UCCX DB userName |
UCCX_DB_PASSWORD | 12345 | UCCX DB password |
UCCX_DB_RETRY_ATTEMPTS | 2 | UCCX DB retry attemps |
UCCX_DB_TIMEOUT_CONNECTION | 1800 | UCCX DB connection timeout |
COMMUNICATION_FORMAT | REST | JMS | Communication format |
REDIS_URL | redis-master.ef-cti.svc | Redis URL |
REDIS_PORT | 6379 | Redis port |
REDIS_PASSWORD | Expertflow123 | Redis password |
SQL_SERVER | 192.168.1.89 | SQL server IP (For Skill groups and supervisor list) |
DATABASE | uc12_awdb | SQL server database |
DATABASE_TABLE | Skill_Group | SQL server database table |
DATABASE_USER_NAME | sa | SQL server database userName |
DATABASE_USER_PASSWORD | Expertflow464 | SQL server database user password |
KEY_STORE_TYPE | PKCS12 | |
KEY_STORE | D:\\EF_Project\\GC4.4\\Generic Connector\\certs\\store\\clientkeystore.p12 | |
TRUST_STORE | D:\\EF_Project\\GC4.4\\Generic Connector\\certs\\store\\client.truststore | |
KEY_STORE_PASSWORD | changeit | |
TRUST_STORE_PASSWORD | changeit | |
PRIVATE_KEY_STRING | key_value | |
ISSUER | ef-chat | |
EXPIRY | 300 | |
PEP_BASE_PATH | http://192.168.50.31:8113 | |
AOP_CALLBACK | /ef-voice/fnb-cme/submit-gc-event/v1 | |
AXL_URL | https://192.168.1.26:8443/axl/ | |
AXL_USER | administrator | |
AXL_PASSWORD | Expertflow464 |
Setup Default Reason Code(s)
Create at least one reason code for not-ready and one reason code for logout in Cisco Finesse and specify the default reason code in the Generic Connector configuration file.
For default not-ready reason,
DEFAULT_NOT_READY_REASON | 1 | Default reason code to be passed by Generic Connector to Cisco Finesse |
DEFAULT_LOGOUT_REASON | 2 | Default reason code to be passed by Generic Connector to Cisco Finesse |
JMX Monitoring
GC now supports JMX monitoring. You can monitor the performance of GC via any of the monitoring tools such as JConsole and VisualVM. GC supports JMX Monitoring on port 9010.