Genesys White Paper

Deploying Genesys for Key Mixed Language Scenarios

Related Topics

• Management Framework Deployment Guide

This white paper describes some use cases that support UTF-8 data and that can be used within a single logical call center for large multinational customers.

Overview

While many Genesys applications are built using modern Unicode technology, most string handling in core Genesys servers has been based on language specific MBCS (Multi-Byte Character Set) C++ routines. Migration from this model is a complicated endeavor because of the multitude of existing deployments with current production data in this format.

However, Genesys recognizes the multi-language reality that exists within a single logical call center for large multi-national customers. So, Genesys is engaged in a carefully staged enhancement program. This consists of:

1. Validating use cases where UTF-8 character set can be supported in Genesys deployment without expectation of errors.
2. Supporting UTF-8 when building new products.
3. Carefully building optional migration paths of current MBCS based products to UTF-8 mode.

This white paper outlines some use cases which can be supported with UTF-8 data, where deployed, to take advantage of combinations of the above according to instructions and limitation notes.

Not all Genesys products are explicitly designed for support of mixed-language scenarios. Recent improvements combined with specific deployment settings enable the implementation of many key scenarios for mixed-language contact center environments. As the Genesys software suite continues to evolve, support for additional scenarios is expected in a more natural (and less restrictive) manner.

Recent Improvements

As part of point 3, two major improvements have already been made to the product suite and are critical to the use cases documented in this white paper.

1. Genesys Administrator, Genesys Configuration Server and the DB Server for Configuration Server can be deployed together in UTF-8 mode so all data stored is in UTF-8 format. It is important that only data validated in these scenarios be stored in actual mixed languages to avoid character set (encoding) issues by products using that data.
2. Interaction Routing Designer (IRD, part of Universal Routing Server) and eServices Knowledge Manager are enhanced to be compatible with Configuration Server in UTF-8 mode, both when reading and writing data. The IRD changes allow the user to configure routing logic in a single strategy using string constants in mixed languages and encoded in UTF-8. The change in Knowledge Manager allows supporting data to be written to Configuration Server in UTF-8.

Key Observations

There is significant support of UTF character encoding in much of the Genesys application layer (such as Contact Server, Orchestration, and Voice Platform). This is important, because the many scenarios that use these products can work with UTF-8 formatted data if the data is not likely to be compared (using wrong encoding) by the MBCS servers; the data just passes through the MBCS servers. This is what enables the first element of the improvement plan (point 1, above) of validating where UTF-8 multi-language support already exists.

Traditionally, the two main obstacles have been the Configuration Layer and Routing, because key data was stored in the Configuration Layer and used in Routing decisions. This meant that faulty string comparisons with the wrong encoding would occur in both places. The recent improvements to support UTF-8 mode in each of those products enable many more possibilities.

This white paper focuses on how these scenarios can be made to work in a very specific validated architecture. One key aspect of this is to maximize handling of data as UTF-8 across the suite. On Unix, the machine’s system locale can be set to UTF-8, which appears to C/C++ handling routines as just another MBCS encoding. The scenarios described in this white paper utilize this to get successful UTF-8 handling in servers that rely on the system locale to determine applicable encoding.

Sample Deployment

Deployment Architecture

Note: It is easier to use the local language of the machine on which IRD is running to set up those parts of the strategy that requires typing characters for one of the given languages, since such characters are readily available.

Participating Components

Component	Minimum Version	Notes
Multi-tenant Configuration Server	8.1.200.17
DB Server	8.1.200.06
Genesys Administrator	8.1.300.09
Solution Control Server (not shown)	8.1.200.13
Message Server	8.1.200.06
Real Time Metrics Engine	8.1.100.26
Universal Routing Server	8.1.300.14
Interaction Routing Designer	8.1.4
Universal Contact Server	8.1.200.03
Interaction Server	8.1.200.27
Web API Server and Samples	8.1.200.03	Samples must be modified for UTF-8 encoding from original files
Classification Server (not shown)	8.1.000.08
Email Server Java	8.1.201.05
Chat Server	8.1.000.26
Knowledge Manager	8.1.300.09	Using JRE 1.6 32-bit
Interaction Concentrator	8.1.100.25
Outbound Contact Server	8.1.000.08
Interaction Workspace	8.1.400.16

Deployment Settings

UNIX Host Settings

In the Unix host (such as AIX) Environment Settings, set:

LC_ALL=EN_US.UTF8
LANG=EN_US.UTF8
NLS_LANG=American_America.AL32UTF8

where NLS_LANG=American_America.AL32UTF8 is used by the Oracle client.

Oracle Database Settings (11gR2)

In nls_database_parameters, set:

NLS_CHARACTERSET=AL32UTF8
NLS_NCHAR_CHARACTERSET=UTF8

as shown in the following figure:

Configuration Server Settings

To prepare the database, run the init_multi_multilang_ora.sql script to initialize the Configuration Database. This script contains the following line:

INSERT INTO cfg_parameters(set_id,section,opt,val) VALUES(0,'database','multi-languages','true')

Note: If you are migrating an existing Configuration Database, use the Configuration Conversion Wizard.

In the confserv.conf configuration file, set configuration encoding, locale and multi-language support as follows:

[confserv]
port = 2820
management-port = 2821
server = dbserver
encryption = false
encoding = utf-8
locale = EN_US.UTF-8
multi-languages = true

Note: Testing with a UTF-8 Configuration Server is limited to the applications covered in this document. There are other Genesys applications which might not yet be set to properly work with a UTF-8 Configuration Server because of a failed encoding match check done at connection time. It is possible to bypass this check, allowing these applications to log in, using only ASCII English user credentials. However, this should be used cautiously so as not to introduce additional data into Configuration Server in an unexpected format. To bypass this check, add the following setting to the confserv.conf configuration file:

[confserv]
allow-mixed-encoding=true

Genesys Administrator Settings

In the web.config configuration file located in the Genesys Administrator installation directory, insert the following line:

<add key="PSDKEncoding" value ="UTF-8"/>

Interaction Workspace Settings

In the interactionworkspace.exe.config configuration file set the following to enable UTF-8 communication with the Configuration Server:

general.non-unicode-connection-encoding=UTF-8

In the Interaction Workspace Application object set the following to enable UTF-8 communication with other servers, such as Interaction Server:

general.non-unicode-connection-encoding=UTF-8

Web API Settings

In the Web API JSP application code for both Chat and Email:

• Set the page's contentType to use UTF-8, as follows:

  <%@ page contentType="text/html; charset=utf-8" %>

• Set the Response and Request class contentType to use UTF-8, as follows:

  <%
     response.setContentType("text/html; charset=utf-8");
     request.setCharacterEncoding ("utf-8");
  %>

• Do not use the i18nsupport class for retrieving parameters as currently shown in WebAPI Samples, just get the parameters directly:

  request.getParameter(“first_name”);

• For Email only, because the underlying protocol is different from Chat, also set the following:

  kvCollection.addString(Connection.STR_ATTR_ENCODING_NAME_KEY, "UTF-8");

Routing Settings

There is no special setup to make IRD or URS work properly with UTF-8 configuration. Encoding is detected by both protocols if Configuration Server is set to run in UTF-8 mode. However, some fonts do not support all characters that exist in the underlying encoding. It is recommended to use MS Sans Serif as the font set in Text Properties within Interaction Routing Designer.

Sample Usage Scenarios with Mixed Languages

Configuration Data

In many of the scenarios described in this section, key fields in the Configuration Database are stored in mixed language UTF-8 format. Setup cannot be done using Configuration Manager; it must be done using Genesys Administrator in UTF-8 mode. Although all data will be stored in UTF-8, only fields identified in the scenarios below should be stored in mixed (non-ASCII language) environments to avoid unpredictable results from products which may use this data and are outside the scope of these tests.

Examples of data that can be in mixed languages are Agent Names, Agent Group Names, Transaction contents and Knowledge Manager related data.

Example of a Chat Scenario

Chat contents already support mixed language contents.

Metadata fields validated to support mixed languages in UTF-8 include: First Name, Last Name and Subject.

Create a routing strategy in IRD. Routing logic can be designed using hardcoded strings in various languages that are compared against the values of the metadata fields to decide what step to take next (such as routing to an agent group with matching language skill). Note that Agent Group names can be configured in mixed languages for this purpose.

UData[‘Subject’]= ‘complaint’ direct to agent group ENGLISH
UData[‘Subject’]= ‘reclamation’ direct to agent group FRANÇAIS
UData[‘Subject’]= “怨言” direct to agent group 中国话的
…

As shown above, because one can directly compare values of the fields against hard-coded strings in mixed languages within the routing strategy, it is not necessary to collect and deliver the locale of the user’s client (browser). However, this might be beneficial in simplifying routing logic. The browser locale can be identified and delivered by the following methodology:

1. Make sure that the language is set in the browser (see Setting Locale in Browser).
2. Retrieve the browser locale in JavaScript code. For example:
   

   var lang = window.navigator.userLanguage || window.navigator.language;

3. Attach this information as an additional variable:
   

   userdata.addString("MyLocale", language);

Routing logic can also utilize mixed-language value text retrieved from a Transaction object stored in the Configuration Database (for example, ListGetDataCfg[‘Transaction’,’Korean’,’chatText’]) to respond in mixed languages based on a configuration such as:

Important

Section and option names were not tested for mixed language support at this time.

The following is an example of a routing strategy using the browser locale to select a Chat response from the transaction to return:

With Interaction Workspace configured as described above, the Chat Contents and subject and name fields are displayed properly when routed to the agent groups, as shown in the following Interaction Window window:

Example of an Email Scenario

Email contents already support mixed languages. Limitations in the past were related to classifications, categories and standard responses.

Supported fields for mixed languages are the same as with Chat. Email addresses should be restricted only to ASCII English.

Email works in same manner as Chat. In this example, the routing strategy chooses an agent group based on the language of the subject field. Note that the user locale is passed, but only for convenience because the decision can be made based on only the subject field.

The following is an example of using Genesys Administrator in UTF-8 mode to create Agent Groups as above with names in mixed languages:

The following is an example of Email in Interaction Workspace supporting mixed language subject and other attributes and contents, and of Interaction Workspace displaying mixed language standard responses and notes:

Screening Rules, Categories and Standard Responses

The main content associated with these items is stored in the Contact Server Database and is found to have good results in a mixed-language environment. The matching elements stored in the Configuration Database can also be in mixed languages.

Category names:

Screening Rules:

Standard Responses:

Example

The following are examples in Knowledge Manager of standard responses and screening rules for a given category.

Standard Response:

Screening Rule:

Contacts in UCS Scenario

All contact information is stored in Unicode format, and there are no limitations on this data being in mixed languages. The following is an example of Contacts in mixed languages as displayed by Interaction Workspace, along with the corresponding Interaction History.

Outbound Scenario

Custom fields in the Calling Lists may be stored in mixed language. Setup cannot use Outbound Contact Manager, and should be done using Genesys Administrator, as shown.

Interaction Concentrator Reporting

Properly deployed, ICON can handle mixed-language configuration data received from Configuration Server in UTF-8 format:

ICON was also found to be able to handle attached mixed-language data from earlier scenarios:

Setting Locale in Browser

Using the browser locale can simplify routing strategies. Below are examples of setting locale in various browsers:

Chrome

Firefox

Internet Explorer

Safari

Enabling Web API Sample Code

1. Modify all media to provide full support of Chat and Advanced Chat, by setting correct character sets (charsets) in all pages, as follows:
   1. Go to the SimpleSamples81x folder of the Web API server.
   2. Run the following commands to set correct charsets in all pages:

      find . -name "*.jsp" -exec sed -i "s/i18nsupport.GetSubmitParameter(request, /request.getParameter(/g" '{}' \;
      
      find . -name "*.jsp" -exec sed -i "s/ISO-8859-1/UTF-8/g" '{}' \;
      
      find . -name "*.jsp" -exec sed -i 's/charset=" + i18nsupport.GetCharSet()/charset=UTF-8"/g' '{}' \;
      
      find . -name "*.jsp" -exec sed -i 's/response.setContentType("text\/html; charset=UTF-8");%/response.setContentType("text\/html; charset=UTF-8");request.setCharacterEncoding ("utf-8");%/g' '{}' \;

   Now you can work successfully with Chat in a mixed-language environment.
2. Enable Email media for UTF-8 (both Simple and With Attachment), as follows:
   1. In the Email.jsp files, in both Email and EmailWithAttachment folders, replace:

      if (bUseTLS)
      {
      KeyValueCollection kvCollection = new KeyValueCollection();
      kvCollection.addInt(Connection.TLS_KEY, 1);
      KeyValueConfiguration kvconfiguration = new KeyValueConfiguration(kvCollection); email.configure(kvconfiguration);
      }

      With:

      KeyValueCollection kvCollection = new KeyValueCollection();
      kvCollection.addString(Connection.STR_ATTR_ENCODING_NAME_KEY, "UTF-8");
      if (bUseTLS)
      {
      kvCollection.addInt(Connection.TLS_KEY, 1);
      }
      KeyValueConfiguration kvconfiguration = new KeyValueConfiguration(kvCollection);
      email.configure(kvconfiguration);

   2. In the Email.jsp file in the EmailWithAttachment folder, replace:

      String fieldValue = item.getString(i18nsupport.GetCodePage());

      With:

      String fieldValue = item.getString("UTF-8");

3. Enable Interaction Submit for UTF-8 through Interaction Server. In the ItxSubmit.jsp file in the ItxSubmit folder, replace:

   if (bUseTLS)
   {
   KeyValueCollection kvCollection = new KeyValueCollection();
   kvCollection.addInt(Connection.TLS_KEY, 1);
   KeyValueConfiguration kvconfiguration = new KeyValueConfiguration (kvCollection);
   itxProtocol.configure(kvconfiguration);
   }

   With:

   KeyValueCollection kvCollection = new KeyValueCollection();
   kvCollection.addString(Connection.STR_ATTR_ENCODING_NAME_KEY, "UTF-8");
   if (bUseTLS)
   {
   kvCollection.addInt(Connection.TLS_KEY, 1);
   }
   KeyValueConfiguration kvconfiguration = new KeyValueConfiguration(kvCollection);
   itxProtocol.configure(kvconfiguration);