Skip to main content
Skip table of contents

Deployment Guide GC

Date & Time Synchronization

An important consideration is time synchronization between related components. Communication between EF Connector, client applications and Cisco Finesse carry timestamps. If the system dates and time are not synchronized the system can produce unpredictable results. Therefore, please make every effort to adhere to the following time synchronization guidelines:

EF Connector, client applications and Cisco Finesse should have their Time Zone and time configured properly according to the geographic region and synchronized. To configure the time zone, please see the instructions from the hardware or software manufacturer of NTP server. Client applications and EF Connector should be synchronized to the second. This synchronization should be maintained continuously and validated on a regular basis. For security reasons, Network Time Protocol (NTP) V 4.1+ is recommended.

Variable names and password requirements

All the variables include team name, agent id’s, passwords and call variables shouldn't contain the following special characters.

  1. ,
  2. #
  3. |

Supervisor agent requirement

Each of the Supervisor agents must be assigned at least one team.

Prerequisites for EF Connector

EF Connector consists of 2 independent components, (i) ActiveMQ Broker and (ii) Generic Connector. This section covers necessary prerequisites.

Hardware Requirements

For a simplex (single server) deployment, minimum and recommended hardware requirements are as following:



Minimum

Recommended

vCPU

2 Cores

4 Cores

vRAM

4 GB

8 GB

vDISK

20 GB

160 GB


For a redundant deployment, two servers of the same specifications (as mentioned above) are needed.

Software Prerequisites

Microsoft Windows Server 2012 standard Edition x64 R2

A windows Server 2012 R2 64-bit or above is recommended

Locale Settings

English (recommended)

Java Runtime (64 bit)

Java Runtime (JRE) 8 is required

Antivirus

Any of the antivirus as mentioned in Software License Requirements

WinRAR

A package extractor to modify embedded configuration properties

.Net Framework

.Net Framework 4.5.2 for Service Manager

Network Prerequisites

EF Connector requires communication with the following:

  • <Client Server>
  • Cisco Finesse
  • Remote monitoring server running web console monitoring of ActiveMQ on HTTP/S.
  • Secondary EF Connector - only needed for a redundant deployment
  • NTP Server, for time synchronization


Following ports should remain open on the Firewall. The local security policy and any antivirus should also allow open communication on the following ports.


Type

Source Host

Source Port

Destination Host

Destination Port

TCP

<Client Server>

any

EF Connector

61616

TCP

EF Connector (B)

any

EF Connector

61616

HTTP

For status monitoring from any machine

EF Connector

8161

XMPP

EF Connector

any

Cisco Finesse

5222, 5223, 7071, 7443

HTTP/S

EF Connector

any

Cisco Finesse

80, 8080, 443, 8443

NTP

EF Connector

any

NTP Server

123

DNS

EF Connector

any

DNS Server

53


  • <Client Server> is a machine running client application of EF Connector. For server-based applications like Siebel, it’s Siebel Communication Server. For desktop-based applications, it’s the machine address of the agent desktop running the desktop application.
  • In a redundant deployment, both EF Connector instances communicate with each other on the same TCP OpenWIre port 61616. In the table above, it’s mentioned as EF Connector (B) ⇒ EF Connector.
  • These are defaults set in EF Connector, but you can always change the default configuration.

If you need to file sharing and remote installation/configuration using RDP, you might need to open the following additional ports.

Type

Source Host

Source Port

Destination Host

Destination Port

RDP

For remote desktop connection

EF Connector

3389

TCP

For file-sharing

EF Connector

139,445

UDP

For file-sharing

EF Connector

137,138

Access & Privileges Requirements

  • Administrative access (LocalSystem account or domain administrator) on the Connector Server is required to do the installation and configuration.

Install Software

  1. Download EF Connector Installer from Google Drive
  2. Run the setup wizard GenericConnector3.4.1.02.exe to start the installation process
  3. 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.


  4. Select the folder for a shortcut in Start Menu


  5.  Review your selection and if all is okay, proceed with the installation.
  6. The installation wizard will copy all the files to the selected folder.

  7. Press Finish to close this setup wizard.

 Upon successful completion, EF Service Manager App is installed with a shortcut created on the Desktop.

Upgrade Software

Upgrade GenericConnector3.4.1.02 to GCPatch 3.4.1.03-latest

If you have successfully installed Generic Connector now or If you have already installed a previous version of Generic Connector and just want to upgrade, you need to obtain patch GCPatch 3.4.1.03-latest from Google Drive and follow the following steps.

  1. Download and extract GCPatch 3.4.1.03-latest.rar
  2. Double click on GCPatchService.exe. It opens a dialog to proceed.
  3. Click Next. It will open a dialog for folder selection. Select Generic Connector installation path <EF Connector Home>.
  4. Click OK. It will upgrade the existing GC with old configurations. It will ask you to review the configuration file. You need to ensure that all the newly introduced parameters are available in GC Config. Click Yes to open the installation folder. See Generic Connector Configuration.
  5. You have up-to-date GC. Old GC will be available as a backup in the same folder. You can now start GC from EF Service Manager.

Note

After the patch upgrade, please make sure to add the property  MAKE_AGENT_READY =False / True, in the GC config file 


EF Service Manager

EF Service Manager is a mini management console to:

  1. Install / Uninstall Services
  2. Start / Stop ActiveMQ
  3. Start / Stop Generic Connector
  4. Open ActiveMQ configuration file
  5. Open Generic Connector configuration
  6. Open ActiveMQ logs folder
  7. 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 are 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

  1. Run Service Manager from the desktop (if it is not running). You can locate Service Manager from the system tray
  2. Run both Services, one after the other.
  3. 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
  4. In the Queue section, you should find a Queue name Connector1 created.
  5. You can also verify ActiveMQ and GenericConnector from their log files by clicking on Logs button in both Sections.

Generic Connector Configuration

The generic Connector “Config” button in EF Service Manager will open the folder where Generic Connector is installed.

  1. Open generic-connector.jar file using WinRAR or similar to modify the embedded configuration properties file Config/config.properties.'
  2. Open Config\config.properties with a text editor
  3. Make the desired changes and update the file in the same jar file

Connector Configuration Parameters

Parameter

Default Value

Description

ActiveMq_URL_1

Activemq-Broker-X-IP:[openwire-port]

Primary ActiveMQ URL with configured Openwire port

ActiveMq_URL_2

Activemq-Broker-X-IP:[openwire-port]

Secondary ActiveMQ URL with configured Openwire port

Finesse_1

http://Finesse-X-IP/finesse/api/

Primary Finesse URL for Site A

Finesse_2

http(s)://Finesse-X-DN/finesse/api/

Primary Finesse URL for Site B


SERVER_ADDRESS_1

Finesse-X-IP

Primary finesse URL for heartbeat   for Site A

SERVER_ADDRESS_2

Finess-X-IP

Secondary finesse URL for heartbeat   for Site A

ActiveMq_Timeout

10000

ActiveMQ connection timeout in milliseconds

AGENT_STATES_PUBLISHER_DURATION

5000

Time (ms) after which, states of all agents would be published on ‘AgentStates’ topic

FINESSE_HEARTBEAT_SLEEP

5

Interval in seconds  to send heartbeat message to finesse

FINESSE_REQUEST_TIMEOUT

300

Finesse Request timeout (milliseconds) used to check Finesse Heartbeat

CLIENT_HEARTBEAT_SLEEP

30

in seconds

LOGLEVEL

TRACE

Log Level

GC_HEARTBEAT_TIMEOUT

10000

GC heartbeat timeout


AGENT_INACTIVITY_DURATION

30

In Seconds

AGENT_INACTIVITY_TIME_SWITCH

false

 Agent inactivity switch

GC_HEARTBEAT_SLEEP

10000

GC heartbeat thread sleep time

DEFAULT_NOT_READY_REASON

1

default reason code for not ready

DEFAULT_LOGOUT_REASON

2

Default reason code for force logout

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

MAKE_AGENT_READY

True

Add true if you want to make agent ready right after login

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

Deployment Modes

Simplex Mode

In simplex deployment, the application is installed on a single server with no failover support of EF Connector. However, the same EF Connector can still communicate with primary and secondary Finesse servers.

Simplex mode is useful for lab tests and commercial deployments at a smaller scale. Figure 1.0 explains the simplex mode of Generic Connector.

Figure 1.0

Duplex Mode

In Duplex mode, there are two types of supported configurations.

Active-Passive

A primary/secondary configuration setup where one Connector works as a primary server while the other (secondary) is available as a stand-by server (from a Disaster Recovery site)

Active-Active

In this mode, both Connector instances are active and serving clients and one instance serves as the backup / secondary for the other.

Active-Passive (Primary / Secondary) Setup

To configure the Connector in Active-Passive mode, set the value of attribute “GRC_CONSUMER_PRIORITY” in Connector configuration. For the Primary Connector, set the value of this attribute to “127” without quotes. For the Secondary Connector, set the value of this attribute to “100” without quotes.

Figure 1.1

The active-Passive mode has the following configurations.

Configurations for Site-1

Primary-AMQ: broker-1, Secondary-AMQ: broker-2

Generic Connector Configuration should look like, For a detailed description of the GC please consult properties

Property

Value

ActiveMq_Timeout

10000

GRC_CONSUMER_PRIORITY

127

RANDOMIZE

false

PRIORITY_BACKUP

true

ActiveMq_URL_1

primary-url-of-amq:port

ActiveMq_URL_2

secondary-url-of-amq:port

Configurations for Site-2

Primary-AMQ: broker-1, Secondary-AMQ: broker-2, For a detailed description of the GC please consult properties.

Property

Value

ActiveMq_Timeout

10000

GRC_CONSUMER_PRIORITY

100

RANDOMIZE

false

PRIORITY_BACKUP


true

ActiveMq_URL_1

primary-url-of-amq:port

ActiveMq_URL_2

secondary-url-of-amq:port


 Active-Active Setup

For an Active-Active deployment, the Failover URL is set to use the local AMQ as primary and remote AMQ as secondary.


Figure 1.2

For GC-1, the configuration would look like this, For a detailed description of the GC please consult properties

Property

Value

ActiveMq_URL_1

[AMQ-1]:61616

ActiveMq_URL_2

[AMQ-2]:61616

GRC_CONSUMER_PRIORITY

127

PRIORITY_BACKUP

true

Finesse_1

http://Finesse-1/finesse/api/

SERVER_ADDRESS_1

Finesse-1

Finesse_2

http://Finesse-2/finesse/api/

SERVER_ADDRESS_2

Finesse-2

For GC-2, the configuration would look like, For detailed description of the GC please consult properties

Property

Value

ActiveMq_URL_1

[AMQ-2]:61616

ActiveMq_URL_2

[AMQ-1]:61616

GRC_CONSUMER_PRIORITY

100

PRIORITY_BACKUP

true

Finesse_1

http://Finesse-2/finesse/api/

SERVER_ADDRESS_1

Finesse-2

Finesse_2

http://Finesse-1/finesse/api/

SERVER_ADDRESS_2

Finesse-1


Where [AMQ-1] should be replaced with the IP / machine-name of ActiveMQ-1 and [AMQ-2] should be replaced with the IP / machine-name of ActiveMQ-2. Finesse-1 is the IP/name of Finesse-1 server and Finesse-2 is IP/name of the Finesse-2 server.

Both Connectors will have its local AMQ as primary brokers and both Connector instances will be serving agents requests in parallel. All client requests received by Connector-1 are handled by Connector-1 and all requests received by Connector-2 will be handled by Connector-2. In case of failure of any component at any Connector instance, the other Connector instance will take over and handle the request. 

We have achieved it using ActiveMQ configurable properties specifically Consumer priority,

Priority Backup, and building a Connector Sync mechanism in Generic Connector.

ActiveMQ Configuration

ActiveMQ “Config” button opens the ActiveMQ configuration file %ACTIVEMQ%/conf/activemq.xml in your default text editor (e.g. notepad).

Configuring Network of Brokers (Redundant Deployment Only)

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 another 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 side. On the other side, it should remain commented out.

This commented tag looks like following in the 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 the SSL configuration of the ActiveMQ console.

Web Console Passwords Configuration

To ensure security, default passwords for the ActiveMQ web console are encrypted. For user “admin” the 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 secure passwords for the web consoles.

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,

  1. Create a new Object in Active Directory with 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.
  2.  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.

  1. 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 security constraint 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 security handler bean in jetty.xml and change the ref of property name ‘login service to ‘ldapLoginService’ as shown below

 

Also, uncomment the following property ‘identityService’ in securityHandler bean


9) 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 Keystore passwords 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 Keystore password property will look like this OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.