Chat Server Administration

This page provides general recommendations for the administration of Chat Server. See also the following:

• Matching Contact Attributes
• Multilingual Processing

Limitations

The following table lists recommended limitations for a Genesys Chat solution running on a single host with two Intel Xeon 3.0GHz processors. Observe these limitations for optimum performace (meaning without significant delay).

Item	Maximum
Message size	4 KB (Genesys Desktop limitation; Chat Server does not have this restriction.)
Transcript size	54 KB (Genesys Desktop limitation; Chat Server does not have this restriction.)
Concurrent sessions (in a realistic simple scenario)	1000 per Chat Server
Messages per second	50 (rare temporary peaks up to 150)
Sessions opened and closed per second	10 (rare temporary peaks up to 30)

Chat Server also has a timeout that you can configure using the user-register-timeout option (default value 30 seconds). This is the maximum time between opening a socket and either of the following:

• Receiving a registration over the socket
  
• Receiving a flex packet over the socket
  

This timeout prevents keeping unused connections open.

Connection Delay with Antivirus

It may take some time (up to several minutes on some UNIX Platforms) for Chat Server to connect to an unopened port on a Windows host on which an antivirus program is running. For example, if Chat Server is running on Linux and is trying to connect to an inactive UCS instance, it could take up to three minutes for Chat Server to detect that the listening port is not open.

Chat HA

Deploying a high-availability Chat solution requires some special configuration.

Setting Load Limits

Starting in the 8.5.0 release of Chat Server, you can impose load limits on Chat Server: when Chat Server reaches the specified limit, it no longer creates new sessions or restores existing sessions.

You do this using the following configuration options (full descriptions are in the eServices Options Reference):

• Enable or disable the general functionality of load limitation using limits-control-enabled.
• Set the limits using
  • limit-for-flex-users—Maximum number of currently logged-in flex users.
  • limit-for-sessions—Maximum number of concurrent chat sessions.

  If any of these limits is reached, Chat Server stops creating and restoring sessions.

• If Chat Server is configured in primary/backup mode, you may want to stop it from reporting service unavailable to SCS when a limit is reached. You can do this using limits-reached-report-scs. Blocking the reports avoids a scenario in which Chat Server in primary/backup mode closes a chat session because (1) Chat Server detects disconnection from Interaction Server and/or UCS, (2) it sends a service unavailable notification to Solution Control Server, (3) SCS switches Chat Server to backup, which closes the chat session. (This scenario does not apply if Chat Server is in N+1 mode: multiple Chat Servers with no backup configured).
• Set the point at which Chat Server returns to full functionality using limits-restore-threshold. This value is a percentage of the limit set by the three limit-for-X options.

Example

If limit-for-flex-users is set to 400 and limits-restore-threshold is set to 80, then:

1. When the number of flex users reaches 400, Chat Server stops creating and restoring sessions, and rejects login attempts by flex users.
2. Then when the number of flex users falls to 320, Chat Server returns to full functionality.

Masking Sensitive Data

Chat Server logs and chat transcripts may contain sensitive data such as credit card numbers, phone numbers, Social Security numbers, and so on. You can omit this data from logs and mask it in transcripts.

In Logs

To omit sensitive data from logs, you must configure both UCS, as described elsewhere, and Chat Server, as follows:

• In the [settings] section, set message-log-print-size to 0. This means that logs do not show the messages sent between chat participants. Where a message occurs, the log shows [truncated from size=x], where x is the number of characters in the suppressed message.
• In the [log-filter-data] section,
  • Set StructuredText to hide so that logs will omit the transcript that UCS sends to Chat Server.
  • Set Transcript to hide so that logs will omit the transcript that Chat Server sends to UCS.

In Chat Transcripts

Chat Server can mask sensitive data in transcripts by using a regular expression (regex) to find and substitute the data with a configurable replacement character. This functionality consists of:

• Examining each chat session message with an ordered set of regex rules. Use the apply-config option to configure the source/location of regex rules that will be applied. Note: all options are located in the section [transcript-cleanup].
• Replacing any part of the message that matches a regex rule with a replacement character specified by the configuration. The default is specified by the default-repchar option.
• When replacing symbols you can choose to replace all symbols or only digits. When replacing digits, you can also leave the last few digits unmasked —see the default-spec option.

This functionality can be applied in the transcript messages of an ongoing chat session and/or a transcript saved in the contact history (UCS). This is specified by the apply-area option.

Important

Prior to the 8.5.103 release, Chat Server used different options from [settings] for this functionality. Click here to view the previous description.

.

If the apply-config option has a value of cfg or is set to mix and no UCS PII configuration has been provided for the given chat session, Chat Server uses the following default rules to find sensitive data:

	Name	Regular Expression
Credit card	GCTI_CreditCards	(?>^|(?<=[\s[:alpha:](),.:;?!"'`]))(?>4\d{3}|5[1-5]\d{2}|6011|622[1-9]|64[4-9]\d|65\d{2})[ -.]?\d{4}[ -.]?\d{4}[ -.]?\d{4}(?>$|(?=[\s[:alpha:](),.:;?!"'`]))
Social Security Number	GCTI_SSN	(?>^|(?<=[\s[:alpha:](),.:;?!"'`]))(?!000|666|9)\d{3}[- ]?(?!00)\d{2}[- ]?(?!0000)\d{4}(?>$|(?=[\s[:alpha:](),.:;?!"'`]))
Phone number using the North American Numbering Plan	GCTI_PhoneNANPA	(?>^|(?<=[\s[:alpha:](),.:;?!"'`]))(?:\+?1[-. ]?)?(?:\(?[2-9][0-9]{2}\)?[-. ]?)?[2-9][0-9]{2}[-. ]?[0-9]{4}(?>$|(?=[\s[:alpha:](),.:;?!"'`]))

Tip

As of release 8.5.103, in addition to the method of configuration described on this page, Chat Server also supports reading the regex rules from UCS. To do this,

• Set the apply-config option to mix or ucs.
• Use Privacy Manager, a plugin for Genesys Administrator Extension (GAX), to select and activate these rules.

In Typing Preview

Typing preview allows an agent to see text that a customer types before the text is submitted to the chat session. You can have Chat Server mask all digits in the typing preview by setting the typing-preview (called transcript-cleanup-typing before release 8.5.103) option to a value other than none. Chat Server then replaces all digits in the typing preview with the character specified by default-repchar (called transcript-cleanup-mask before release 8.5.103).

Inactivity Monitor

Inactivity monitoring control closes the chat session if there is no activity by chat participants after a certain length of time. To enable it, set the enabled option in the [inactivity-control] section to true. It works as follows:

• Chat Server carries out inactivity monitoring only if there is at least one customer and one agent participating in the chat session.
• If there is no activity during the time specified by timeout-alert, Chat Server issues a warning consisting of the text specified by message-alert. The default warning is "Chat session will be closed soon due to inactivity of chat participants."
• If there is no activity for another timeout-close seconds, Chat Server issues a notification consisting of the text specified by message-close and closes the chat session (thus removing all participants from it). The default notification is "Chat session closed due to inactivity of chat participants."
• If any activity occurs, Chat Server resets both of the timeouts. Activity here means any activity in the chat session that is visible to all participants—so, for example, coaching messages between agents do not count as activity in this sense.

KPI (Key Performance Indicator) counters

As of release 8.5.103, Chat Server includes KPI (Key Performance Indicator) counters that monitor activity within the server.

Accessing KPI counters

You can access the KPI counters through:

• Chat Server log by configuring options log-output-content, log-output-proviso, log-output-timeout in the [health-service] section.
• the web REST interface which you can configure by:
• adding a port with the ID=health to the ports of Chat Server.
• adjusting the soap-* options found in the [health-service] section.

Web interface

The web interface can be accessed through the following URL format: http://ServerName:ServerPort/Counters?<list of parameters> where:

• ServerName is the host name where Chat Server is running.
• ServerPort is the web service port, also specified as the health port of Chat Server.

Web interface parameters:

Name	Description	Valid Value	Default Value
metadata	Returns a list (in JSON format) with a description of all the supported counters.	true, yes false, no	false
content	Returns a list (in JSON format) with counters according to the provided parameter value.	all—returns all available counters new—returns only recently updated counters set —returns all initialized (non-zero) counters	all
reset	Resets all counters to zero.	true, yes false, no	false

If a parameter is omitted, or an invalid valid is used, then the default value will be taken. Parameters are processed according to the following rules:

• If reset is true, then all the counters will be reset and then the rest of the parameters will be processed.
• If metadata is true, then the content parameter will be ignored and the metadata will be sent.
  

Example URLs:

• http://hostname:7000/Counters?content=set
• http://hostname:7000/Counters?metadata=true&reset=true

How counter values are calculated

All counters, except the process memory counter, are cumulative. The value begins to accumulate the moment the application is launched or the counters are reset. In order to calculate the difference, the user must use two sample counters from different times and subtract the earlier sample from the later one. To find the counter's rate value, divide the difference by the number of elapsed seconds between the two samples.

Important

On some platforms, the time for processing internal activities may be reported as zero. This is not indicative of an issue with the counter. On the contrary, a rapidly growing value on the counter for internal activity indicates that the server is overloaded.

Deploying Chat Server with Cassandra HA

Required versions and supported platforms

As of version [to be announced] Chat Server supports Cassandra HA on Windows and Linux OS. Chat Server uses a C++ Cassandra driver version 1.0, which supports Apache Cassandra versions 1.2+ and DataStax Enterprise versions 3.2+.

Cassandra deployment and configuration

The following instructions work under the assumption that a Cassandra cluster, either Apache Cassandra version 1.2+ or DataStax Enterprise version 3.2+, is available. The document refers to IPv4 addresses in Cassandra configuration and deployment. When properly configured Cassandra and the Cassandra driver used in Chat Server support IPv6 addresses.

Important

Simple one node Cassandra installation for testing

For testing purposes download the Stable and Recommended version of DataStax Community Edition Apache Cassandra from http://www.planetcassandra.org/cassandra/. Once installed:

1. Modify the cassandra.yaml configuration file:
   1. change the options listen_address and rpc_address to the host IPv4 address.
   2. make sure the Cassandra ports specified in cassandra.yaml do not overlap with ports used by existing applications.
2. Start Cassandra node.

Following the steps below, use Cassandra CQL Shell to create a new keyspace and the tables required.

Keyspace

The example below shows the replication parameters suitable for a testing environment. In production, we recommend a replication_factor of at least 3. The replication strategy should be set according to the cluster and datacenter configuration.

CREATE KEYSPACE genesys_chat_server 
WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
USE genesys_chat_server;

Table transcripts

CREATE TABLE transcripts (
  id text,
  creatorid text,
  transcript text,
  PRIMARY KEY (id, creatorid) ) 
WITH CLUSTERING ORDER BY (creatorid ASC);

Table owner

CREATE TABLE owner (
  id text,
  ownership_start_time timeuuid,
  creatorid text,
  PRIMARY KEY (id, ownership_start_time) )
WITH CLUSTERING ORDER BY (ownership_start_time DESC);

Configuring and Deploying Chat Server for Cassandra HA mode

1. Configure Chat Server options to enable HA mode. See https://docs.genesys.com/Documentation/ES/latest/User/ChatHA.
2. Create and configure a Chat Server Cassandra RAP application object based on the template ChatServerCassandraRAP provided in the installation package. Refer to the Options Reference Guide or the contents of ChatServerCassandraRAP.xml.
3. Add a connection from each Chat Server application to the newly created Chat Server Cassandra RAP.
4. Restart Chat Server.

Configuring secure communication between Chat Server and Cassandra nodes

The SSL communication mode between Chat Server and Cassandra nodes is optional and can be configured in the [encryption] section of the Chat Server Cassandra RAP object. It is assumed that only one Chat Server Cassandra RAP is configured for all Chat Servers in the solution. Therefore, relative paths and certificates and keys should be the same on all Chat Server hosts. Should these paths be different, you can configure multiple Chat Server Cassandra RAP objects pointing to the same Cassandra cluster.

The following examples assume that:

1. The C* cluster consists of two nodes, node1 and node2, running on hosts with IP addresses 172.21.80.85 and 135.225.58.181.
2. All passwords in this example are "genesys".
3. The java keytool and openssl are available for certificate creation and manipulation.

Example of certificates creation

Cassandra nodes certificate creation

Create a keystore and generate a node1 certificate.

keytool -genkeypair -noprompt -keyalg RSA -keysize 2048 -validity 36500 -alias node1 -keystore keystore1.jks -storepass genesys -keypass genesys -dname "CN=172.21.80.85, O=Genesys, L=Daly City, ST=California, C=US"

Keystore and keystore1.jks should be accessible by node1 and configured in the corresponding cassandra.yaml file.

Create a keystore and generate a node2 certificate.

keytool -genkeypair -noprompt -keyalg RSA -keysize 2048 -validity 36500 -alias node2 -keystore keystore2.jks -storepass genesys -keypass genesys -dname "CN=135.225.58.181, O=Genesys, L=Daly City, ST=California, C=US"

Keystore and keystore2.jks should be accessible by node2 and configured in the corressponding cassandra.yaml file.

Creating Client Certificates

Generate a client certificate with a private key.

openssl req -x509 -days 365 -subj "/C=US/ST=California/L=Daly City/CN=chatclient" -newkey rsa:2048 -keyout chatclientkey.pem -out chatclient.pem

Copy both output files chatclientkey.pem and chatclient.pem into each Chat Server host and configure the client-private-key-file and client-certificate-file accordingly.

Exporting of Cassandra Node Certificates

Export node1 certificate:

keytool -exportcert -rfc -noprompt -alias node1 -keystore keystore1.jks -storepass genesys -file cassandra1.pem

Export node2 certificate:

keytool -exportcert -rfc -noprompt -alias node2 -keystore keystore2.jks -storepass genesys -file cassandra2.pem

Copy the exported node certificates, cassandra1.pem and cassandra2.pem, to each Chat Server host into the directory that is passed through each Chat Server "trusted-cert-dir" option.

Importing Client Certificates

Import the client certificate into the truststore of node1:

keytool -import -file chatclient.pem -alias chatclient -keystore truststore1.jks -storepass genesys

Import the client certificate of the truststore of node2:

keytool -import -file chatclient.pem -alias chatclient -keystore truststore2.jks -storepass genesys

Cassandra and Genesys configuration

Cassandra and Java with Cryptography Extension

C* nodes with client encryption enabled may fail to start unless Java is updated with the Java Cryptography Extension.

1. Download the Java Cryptography Extension (JCE) from Oracle's website.
2. Replace US_export_policy.jar and local_policy.jar in your JRE Java folder (found in: \jre7\lib\security for Windows or /jre/lib/security/ for Linux-like platforms).
3. Restart Cassandra.

Client encryption with different Cassandra nodes certificates and client authentication

In cassandra.yaml of node1:

client_encryption_options:
 enabled: true
 keystore: <path-to-keystore>/keystore1.jks
 keystore_password: genesys ## The password you used when generating the keystore.
 truststore: <path-to-truststore>/truststore1.jks
 truststore_password: genesys ## The password you used when generating the truststore. 
 require_client_auth: true

In cassandra.yaml of node2:

client_encryption_options:
 enabled: true
 keystore: <path-to-keystore>/keystore2.jks
 keystore_password: genesys ## The password you used when generating the keystore.
 truststore: <path-to-truststore>/truststore2.jks
 truststore_password: genesys ## The password you used when generating the truststore. 
 require_client_auth: true

Cassandra RAP, section encryption:

enbabled=true
trusted-cert-dir=<Path to directory containing cassandra1.pem and cassandra2.pem> 

client-private-key-file=chatclientkey.pem

password=genesys ## openssl will prompt for this password to be entered during the certificate creation

client-certificate-file=chatclient.pem

verify-peer-cert=true
verify-peer-identity=true

Using cqlsh with SSL encryption

Follow the DataStax instructions hyperlink DATA to configure the cqlshrc configuration file.The following examples assumes that all relevant .pem files are copied into the local C:\certs\ directory.

1. Copy cqlshrc.sample from the ~/conf directory to another location, for example C:\certs\ directory.
2. Rename the file to cqlshrc.conf.
3. Modify the following sections to be consistent with the encryption configuration shown above:

[authentication]
;username = fred
;password = !!bang!!$
;; We assumed no user name or password is set in the Cassandra example

[cql]
version = 3.2.0
;; it would not connect with lower version

[connection]
hostname = 172.21.80.85
;; this is node1 of our example
port = 9042
;; we assume the port is default
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
certfile = C:\certs\cassandra1.pem
;; the certificate of node 1
validate = true
;; assume that we want to validate the node, optional
userkey = C:\certs\chatclientkey.pem
;;if client auth is required on cassandra
usercert = C:\certs\chatclient.pem
;;if client auth is required on cassandra

[certfiles]
172.21.80.85 = C:\certs\cassandra1.pem
;; the cert for node1
135.225.58.181 = C:\certs\cassandra2.pem
;; the cert for node2

Start cqlsh with the following command:

cqlsh --ssl --cqlshrc=C:\certs\cqlshrc.conf

Cqlsh shell should connect to node1 using the configured SSL.

Client encryption with a single Cassandra node certificate and client authentication

In cassandra.yaml of node1:

client_encryption_options:
 enabled: true
 keystore: <path-to-keystore>/keystore1.jks
 keystore_password: genesys ## The password you used when generating the keystore.
 truststore: <path-to-truststore>/truststore1.jks
 truststore_password: genesys ## The password you used when generating the truststore. 
 require_client_auth: true

In cassandra.yaml of node2:

client_encryption_options:
 enabled: true
 keystore: <path-to-keystore>/keystore1.jks
 keystore_password: genesys ## The password you used when generating the keystore.
 truststore: <path-to-truststore>/truststore2.jks
 truststore_password: genesys ## The password you used when generating the truststore. 
 require_client_auth: true

Cassandra RAP, section encryption

enbabled=true
trusted-cert-dir=<Path to directory containing cassandra1.pem>
client-private-key-file=chatclientkey.pem
password=genesys ## openssl will prompt for this password to be entered during the certificate creation
client-certificate-file=chatclient.pem
verify-peer-cert=true
verify-peer-identity=false

Client encryption with a single Cassandra node certificate and no client authentication

In cassandra.yaml of node1:

client_encryption_options:
 enabled: true
 keystore: <path-to-keystore>/keystore1.jks
 keystore_password: genesys ## The password you used when generating the keystore.
 truststore: <path-to-truststore>/truststore1.jks
 truststore_password: genesys ## The password you used when generating the truststore. 
 require_client_auth: false

In cassandra.yaml of node2:

client_encryption_options:
 enabled: true
 keystore: <path-to-keystore>/keystore1.jks
 keystore_password: genesys ## The password you used when generating the keystore.
 truststore: <path-to-truststore>/truststore2.jks
 truststore_password: genesys ## The password you used when generating the truststore. 
 require_client_auth: false

Cassandra RAP, section encryption

enbabled=true
trusted-cert-dir=<Path to directory containing cassandra1.pem>
client-private-key-file=
password= ## empty
client-certificate-file=
verify-peer-cert=true
verify-peer-identity=false

ECDHE Cipher Suite Support

When the Java version used does not support ECDHE cipher suite, the cipher_suites option of the client_encryption_options section in cassandra.yaml file must be modified to exclude cipher suites prefixed with TLS_ECDHE_. For example:

cipher_suites: [TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA] #,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]