adata-userdata-history
Section: callconcentrator
Default Value: none
Valid Values: none, first, last, all
Changes Take Effect: After restart
Specifies what changes to a key’s value must be recorded in IDB for a key that originates from the UserData reporting event attribute, but that is not included in the XML specification file specified by the adata-spec-name option value. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud.
This option applies to voice and multimedia interactions.
Valid Values:
- none - No value for a given key is recorded in IDB.
- first - Only the first value for a given key is recorded in IDB.
- last - Only the last value for a given key is recorded in IDB.
- all - Every change in value for a given key is recorded in IDB.
gud-cust-disp-groups
Section: callconcentrator
Default Value: 16
Valid Values: 0-255
Changes Take Effect: After restart
Specifies the maximum number of key groups that ICON can process. If you code more than the maximum number of groups in the XML file, ICON ignores the extra key groups and does not provide data to the active custom dispatcher.
Key names that you specify must be unique both within and across key groups. The maximum number of keys that you can specify for any particular key group is limited to 34 (17 key-value pairs for string values, and 17 for integer values).
A value of 0 indicates that ICON does not process any groups.
gud-cust-disp
Section: callconcentrator
Default Value: 0
Valid Values: 0, 1, 2
Changes Take Effect: Immediately
Specifies whether ICON calls a custom stored procedure to handle
attached data and store the information in custom tables.
ICON starts executing the new custom dispatcher as soon as the new configuration option value is set. Processing of interaction information stored in the persistent queue that was begun by the old custom dispatcher is handled in IDB by the old custom dispatcher.
Valid Values:
- 0 - ICON does not call a custom dispatcher.
- 1 - ICON calls the gudCustDisp1 stored procedure.
- 2 - ICON calls the gudCustDisp2 stored procedure.
Note: For more information, see Custom Dispatchers in the Interaction Concentrator User's Guide.
trim-broken-utf8
Section: callconcentrator
Default Value: 0
Valid Values: 0, 1
Changes Take Effect: Immediately
Introduced: 8.1.514.10
Modified: 8.1.514.56 (behavior modified); 8.1.514.23
When this option is enabled (trim-broken-utf8 = 1), ICON checks for and removes incomplete UTF-8 symbols from the end of truncated data strings. These incomplete UTF-8 symbols might occur when a long data string is truncated in the middle of a multi-byte UTF-8 character.
- In releases 8.1.514.10 through 8.1.514.20, this functionality applies to user data written to the following tables: G_USERDATA_HISTORY, G_CUSTOM_DATA_S, G_CUSTOM_DATA_P, GM_F_USERDATA, and GM_L_USERDATA.
- In releases 8.1.514.23 and higher, this functionality applies to data in all IDB tables.
- In releases earlier than 8.1.514.56, ICON incorrectly truncated one extra symbol of a long data ASCII string when the string exceeded the size of the database field.
Enable this option if you use long UTF-8 (non-ASCII) data strings and are encountering database error messages resembling the following, which is generated by the PostgreSQL RDBMS: invalid byte sequence for encoding 'utf-8'. Similar errors might occur on other RDBMSs.
suppress-user-data
Section: callconcentrator
Default Value: 1
Valid Values: Choose a value from the list
Changes Take Effect: After restart
Specifies whether ICON instructs T-Server to propagate attached
data only when the attached data changes. This optimizes processing
of attached data by reducing network traffic.
Note: This option can be set at the level of the Switch or the ICON application. ICON automatically detects the Switch-level option setting. If the Switch-level option is set to the value of 1 (unchanged attached data suppressed), T-Server TEvents are optimized for all ICON applications that connect to the T-Servers for that Switch. In this case, the Switch-level option setting overrides any ICON-level settings of 0 (unchanged attached data not suppressed). If the Switch-level option is set to -1 (the default), an ICON Application-level setting of 1 will override it.
max-userdata-length
Section: callconcentrator
Default Value: 255
Valid Values: Any integer between 255 - 1024
Changes Take Effect: Immediately
Introduced: 8.1.512.08
Modified: 8.1.514.06 (default value changed)
Specifies the maximum length of data stored in the following columns in IDB:
- The G_SUBJECT field in the GM_F_USERDATA table.
- The VALUE field in the G_USERDATA_HISTORY and G_SECURE_USERDATA_HISTORY tables.
If ICON receives userdata values longer than the specified value, they are truncated and ICON generates the Standard-level log message 09-25109.
cseq-adjustment
Section: callconcentrator
Default Value: 0
Valid Values: 0, 1, 2
Changes Take Effect: Immediately
Introduced: 8.1.000.37, 8.1.100.34
Improves sequence tracking for user data in the G_USERDATA_HISTORY table, which enables downstream reporting applications, such as Genesys Info Mart, to correctly associate user data with interaction activity when user data updates occur within the same second that the call is transferred or terminated.
To preserve compatibility with legacy behavior, cseq-adjustment enables you to control whether ICON implements improved behavior for populating the CSEQ field in the G_USERDATA_HISTORY table.
Valid Values:
- 0 - Compatibility mode. Preserves legacy behavior for pre-8.x Genesys Info Mart releases. See the extended description for a relevant known issue.
- 1 - Preserves legacy behavior, but corrects the known issue (see extended description). ICON stores correct values in the CSEQ field in the G_USERDATA_HISTORY table for all scenarios.
- 2 - Compatibility mode for Genesys Info Mart 8.x releases. ICON modifies the value of the CSEQ field in the G_USERDATA_HISTORY table to match the behavior that Genesys Info Mart 8.x expects.
adata-userdata-history
Section: callconcentrator
Default Value: none
Valid Values: none, first, last, all
Changes Take Effect: After restart
Specifies what changes to a key’s value must be recorded in IDB for a key that originates from the UserData reporting event attribute, but that is not included in the XML specification file specified by the adata-spec-name option value. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud.
This option applies to voice and multimedia interactions.
Valid Values:
- none - No value for a given key is recorded in IDB.
- first - Only the first value for a given key is recorded in IDB.
- last - Only the last value for a given key is recorded in IDB.
- all - Every change in value for a given key is recorded in IDB.
adata-spec-name
Section: callconcentrator
Default Value: ccon_adata_spec.xml
Valid Values: Any valid file name > any string
Changes Take Effect: Immediately
Indicates the name of the XML file that contains the attached data specification; optionally you can follow the file name with the > character and then a string specifying an update option, as explained in the extended description. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud.
For more information about the attached data specification, see Attached Data Specification File in the Interaction Concentrator Deployment Guide.
adata-reasons-history
Section: callconcentrator
Default Value: none
Valid Values: none, first, last, all
Changes Take Effect: After restart
Specifies what changes to a key’s value must be recorded in IDB for a key that originates from the Reasons TEvent attribute but that is not included in the XML specification file specified by the adata-spec-name option value. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud.
This option applies to voice interactions only.
Valid Values:
- none - No value for a given key is recorded in IDB.
- first - Only the first value for a given key is recorded in IDB.
- last - Only the last value for a given key is recorded in IDB.
- all - Every change in value for a given key is recorded in IDB.
adata-extensions-history
Section: callconcentrator
Default Value: none
Valid Values: none, first, last, all
Changes Take Effect: After restart
Specifies what changes to a key’s value must be recorded in IDB for a key that originates from the Extensions TEvent attribute but that is not included in the XML specification file denoted by the adata-spec-name option value. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud.
This option applies to voice and multimedia interactions.
Valid Values:
- none - No value for a given key is recorded in IDB.
- first - Only the first value for a given key is recorded in IDB.
- last - Only the last value for a given key is recorded in IDB.
- all - Every change in value for a given key is recorded in IDB.
adata-default-storage
Section: callconcentrator
Default Value: public
Valid Values: public, secure
Changes Take Effect: After restart
Specifies the default destination for storing attached data for keys not included in the XML specification file denoted by the
adata-spec-name option value. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud. This option applies to both voice and multimedia interactions.
Valid Values:
- public - Data is stored in the G_USERDATA_HISTORY table.
- secure - Data is stored in the G_SECURE_USERDATA_HISTORY table.
adata-spec-name
Section: callconcentrator
Default Value: ccon_adata_spec.xml
Valid Values: Any valid file name > any string
Changes Take Effect: Immediately
Indicates the name of the XML file that contains the attached data specification; optionally you can follow the file name with the > character and then a string specifying an update option, as explained in the extended description. ICON processes this option only if you enable attached data storage by setting the role option to either all or gud.
For more information about the attached data specification, see Attached Data Specification File in the Interaction Concentrator Deployment Guide.
role
Section: callconcentrator
Default Value: all
Valid Values: A comma-separated list of valid roles
Changes Take Effect: After restart
Specifies the type of data that this ICON instance processes and stores in IDB. The option value must be lowercase. If you use uppercase letters in the option setting, the role defaults to all.
Valid Values:
- all - Stores all types of data.
- cfg - Stores the initial configuration state and a history of configuration changes retrieved from Configuration Server.
- gcc - Stores interaction-related and party-related information; that is, T-Server and Interaction Server data that pertains to voice and multimedia interactions, and the parties associated with those interactions.
- gls - Stores T-Server and Interaction Server data that pertains to agent states and agent login sessions.
- gud - Stores T-Server and Interaction Server data that pertains to the attached data associated with calls.
- lrm - In an environment with License Reporting Manager, stores license reporting data.
- gos - In an environment with the Outbound Contact solution, stores OCS data that pertains to outbound calls and campaigns.
Prefixing an option value with a tilde (~) excludes that type of data from ICON processing, and includes all other types.
Configuring for Attached Data
Attached data refers to the interaction-related business data that is sent by T–Server or Interaction Server as key–value pairs (KVPs) in the UserData, Extensions, or Reasons attributes in TEvents.
Configuring Interaction Concentrator to store attached data in IDB is a two–part process:
- Specify the attached data key configuration file, which maps the key–value pairs (KVPs) in reporting event attributes to IDB tables and fields. For more information, see Attached Data Specification File.
- Specify the attached data configuration settings in the Genesys Configuration Layer.
- For more information about attached data in Interaction Concentrator, see Processing Attached Data.
- For information about configuring Interaction Concentrator to store user data from EventUserEvents that are distributed by T–Server or Interaction Server from other client applications (for example, from an agent desktop application), see Configuring for Agent State and Login Session Data.
To use attached data, follow the configuration instructions in the following sections:
- ICON Application Object
- Attached Data Specification File
- Parser Limitations
- Attribute Values
- IDB Fields
- Universal Routing Server Attached Data
ICON Application
This section describes the configuration settings that are available on the ICON Application object.
ICON Role Configuration Option
For every ICON instance that must store attached data, make sure that the role option on the Options tab of the ICON Application object includes gud in the list of values. If you deploy a single ICON instance for the entire contact center, you can keep the default value (all). For more information, see the description of the role configuration option.
Attached Data Specification File
The attached data specification file (named ccon_adata_spec.xml by default) maps the key-value pairs (KVPs) in reporting event attributes to IDB tables and fields.
The adata-spec-name configuration option] enables you to point ICON to your attached data specification file. In ICON versions prior to 8.1.5, you must restart ICON after making changes to the attached data specification file.
Starting in release 8.1.5, if you update the attached data specification file, ICON reads the changes dynamically. Each version of the attached data specification file is saved as a dictionary. By default, ICON can store up to twelve dictionaries.
Attached Data Configuration Options
The following ICON configuration options, enable you to specify what attached data ICON should store, and in what manner:
- adata-default-storage
- adata-extensions-history
- adata-reasons-history
- adata-spec-name
- adata-userdata-history
- cseq-adjustment
- max-userdata-length
- suppress-user-data
- trim-broken-utf8
Select the appropriate values for your environment, and make related configuration changes on the Options tab of the ICON Application object.
Custom Dispatcher Configuration Options
The following ICON configuration options enable you to specify how the custom dispatcher will process attached data:
Review the descriptions and values for the configuration options, select the appropriate values for your environment, and make related configuration changes on the Options tab of the ICON Application object.
Attached Data Specification File
If you require ICON to store attached data in IDB, create an attached data specification for ICON to use. The attached data specification is an XML file stored in the installation directory that you specify when you install the Interaction Concentrator application.
- For the XML schema definition for your attached data specification, see the Schema Definition tab on the Attached Data Specification File page. This page provides the following sample attached data specifications:
- Sample Basic Attached Data Specification
- Sample Specification for Multimedia Attached Data
- Sample Specification for Customized Attached Data
In this section, as in the rest of this document, italics indicate placeholder text.
Parser Limitations
The ICON XML parser imposes the following limitations:
- ICON ignores unknown attributes if they are present in the specification. When parsing the XML specification, ICON checks only for missing attributes.
- The ICON XML parser does not support namespaces.
Attribute Values
This section describes the attributes that are used in the XML schema definition.
History Types
The following values can be used as history types:
| none | No value for a given key is recorded in IDB. |
| first | Only the first value for a given key is recorded in IDB. |
| last | Only the last value for a given key is recorded in IDB. |
| all | Every change in value for a given key is recorded in IDB. This value applies only to keys that are configured to be stored in the history tables. |
Storage Types
The table below shows the IDB table in which each attribute is stored.
| Attribute Name | IDB Table Name |
|---|---|
| public | G_USERDATA_HISTORY |
| secure | G_SECURE_USERDATA_HISTORY |
| call | G_CALL_USERDATA |
| call-cust | G_CALL_USERDATA_CUST |
| call-cust1 | G_CALL_USERDATA_CUST1 |
| call-cust2 | G_CALL_USERDATA_CUST2 |
| mcr-f | GM_F_USERDATA |
| mcr-l | GM_L_USERDATA |
| user_supplied_name, such as cust-disp-group-n | Customer-defined name, as specified in the custom dispatcher. |
Data Source Types
The following table shows the TEvent attribute from which each attribute is derived.
| Attribute Name | TEvent Attribute Name |
|---|---|
| reasons | AttributeReasons |
| extensions | AttributeExtensions |
| userdata | AttributeUserData |
IDB Fields
The mapping between the field attribute (the logical key name) in the attached data specification and fields in the IDB tables is predefined. This section describes the predefined IDB fields for:
Predefined IDB Columns—Voice
For voice calls, the table below shows the predefined IDB field in which each attribute is stored in the G_CALL_USERDATA table.
| Attribute Name | G_CALL_USERDATA Field |
|---|---|
| customer-segment | G_CUSTOMER_SEGMENT |
| service-type | G_SERVICE_TYPE |
| service-subtype | G_SERVICE_SUBTYPE |
| business-result | G_BUSINESS_RESULT |
| customer-id | CUSTOMER_ID |
| transaction-id | TRANSACTION_ID |
| cause-id | CAUSE_ID |
| account-id | ACCOUNT_ID |
| destination-id | DESTINATION_ID |
| target-id | TARGET_ID |
Predefined IDB Columns—Multimedia
For eServices and 3rd Party Media interactions, the following table shows the predefined IDB fields in the GM_F_USERDATA and GM_L_USERDATA tables in which multimedia-specific attributes are stored. All the IDB fields listed in this table can be used for customer-defined keys.
- In this table, the Key Name and Field columns refer to Attached Data Specification attributes.
- For any field attributes marked with an asterisk (*), if it is not mapped to a customer-defined key in the attached data specification file, the IDB field will be populated with the value of the predefined key.
| Predefined Key Name | Key Name | Field | IDB Field |
|---|---|---|---|
| GM_F_USERDATA Table | |||
| FromPersonal | MyKeyName (customer-defined) | *mcr-from-name | G_FROM_NAME |
| MyKeyName (customer-defined) | mcr-called-back | G_CALLED_BACK | |
| Subject | MyKeyName (customer-defined) | *mcr-subject | G_SUBJECT |
| Origination_Source | MyKeyName (customer-defined) | *mcr-origin-source | G_ORIGIN_SOURCE |
| FromAddress | MyKeyName (customer-defined) | *mcr-from-address | G_FROM_ADDRESS |
| MyKeyName (customer-defined) | mcr-reserved-1 through mcr-reserved-4 | G_RESERVED1 through G_RESERVED4 | |
| GM_L_USERDATA Table | |||
| MyKeyName (customer-defined) | mcr-suggested-response | G_S_RESPONSE | |
| MyKeyName (customer-defined) | mcr-auto-response | G_A_RESPONSE | |
| MyKeyName (customer-defined) | mcr-auto-ack | G_A_ACK | |
| ContactId | MyKeyName (customer-defined) | *mcr-ucs-contact-id | G_UCS_CONTACT_ID |
Predefined IDB Columns—Custom Fields
ICON creates the IDB G_CALL_USERDATA_CUST* fields in the G_CALL_USERDATA_CUST* tables for the custom attributes that you might use in your attached data specification. You can use these fields for both voice and multimedia interactions.
The G_CALL_USERDATA_CUST* fields are named CUST_DATA_1, CUST_DATA_2, CUST_DATA_3, and so on to CUST_DATA_19. Use corresponding attribute names, as shown in the following table:
| Attribute Name | G_CALL_USERDATA_CUST* Field Name |
|---|---|
| CUST_DATA_1 | cust-data-1 |
| CUST_DATA_2 | cust-data-2 |
| CUST_DATA_3 | cust-data-3 |
| . . . |
. . . |
| CUST_DATA_19 | cust-data-19 |
Universal Routing Server Attached Data
Universal Routing Server (URS) distributes a standard set of attached data that usually exceeds reporting requirements for actual deployments.
Depending on whether you specify the URS keys in the public or secure sections of the attached data specification, the KVP data is stored in the KeyName, Value, and, if you also specify the id attribute, KEYID fields in the G_USERDATA_HISTORY or the G_SECURE_USERDATA_HISTORY table.
For an example of an attached data specification that includes URS attached data keys, see the Basic Sample tab on the Attached Data Specification File page.
Tables Showing How User Data is Stored in IDB
As a result of separate ICON processing, the values of the keys in Table 1 (below) are stored in the G_ROUTE_RESULT table by default. These keys come from userdata. You must nevertheless explicitly include these keys in the attached data specification file if you want the key values to be stored in the user data history tables.
| Table 1: source=“userdata” | ||
|---|---|---|
| RTargetRuleSelected | RTargetObjectSelected | RTargetTypeSelected |
| RTargetAgentSelected | RTargetPlaceSelected | RRequestedSkillCombination |
| RStrategyName | RTenant | RVQID |
| RVQDBID | ||
ICON masks the keys in the following three tables by default and does not store them in IDB. To store any of the userdata keys in Table 2, the reasons keys in Table 3, or the extensions keys in Table 4, you must explicitly specify the key in the attached data specification file.
| Table 2: source=“userdata” | ||
|---|---|---|
| CBR-Interaction_cost | CBR-IT-path_DBIDs | CBR-actual_volume |
| CBR-contract_DBIDs | RStrategyDBID | ServiceType |
| ServiceObjective | RVQID | RTargetObjSelDBID |
| RTargetRequested | RTargetAgentGroup | RTargetRuleSelected |
| RTargetObjectSelected | RTargetTypeSelected | RTargetAgentSelected |
| RTargetPlaceSelected | RStrategyName | RRequestedSkillCombination |
| RTenant | RTargetUsed/RTargetName | RTargetUsed/RTargetType |
| RTargetAgSelDBID | CustomerSegment | RTargetPlSelDBID |
| RRequestedSkills | RTargetPlaceGroup | RTargetCampaignGroup |
| RouterData70 | ||
| Table 3: source=“reasons” | ||
|---|---|---|
| RTR | CBR-Interaction_cost | CBR-IT-path_DBIDs |
| CBR-actual_volume | CBR-contract_DBIDs | RStrategyDBID |
| ServiceType | ServiceObjective | RVQID |
| RTargetObjSelDBID | RTargetRuleSelected | RTargetObjectSelected |
| RTargetTypeSelected | RTargetAgentSelected | RTargetPlaceSelected |
| RStrategyName | RRequestedSkillCombination | RTenant |
| RTargetUsed/RTargetName | RTargetUsed/RTargetType | RTargetAgSelDBID |
| CustomerSegment | RTargetPlSelDBID | RRequestedSkills |
| RTargetPlaceGroup | RTargetCampaignGroup | RouterData70 |
| Table 4: source=“extensions” | ||
|---|---|---|
| Reasons/RTR | Reasons/ServiceType | Reasons/ServiceObjective |
| Reasons/RVQID | Reasons/RTargetObjSelDBID | Reasons/RStrategyDBID |
| Reasons/RTargetRuleSelected | Reasons/RTargetObjectSelected | Reasons/RTargetTypeSelected |
| Reasons/RTargetAgentSelected | Reasons/RTargetPlaceSelected | Reasons/RTargetAgentGroup |
| Reasons/RTargetRequested | Reasons/RTargetUsed | Reasons/RTargetUsed/RTargetName |
| Reasons/RTargetUsed/RTargetType | Reasons/RStrategyName | Reasons/RRequestedSkillCombination |
| Reasons/RTenant | Reasons/RTargetAgSelDBID | Reasons/CustomerSegment |
| Reasons/RTargetPlSelDBID | Reasons/RRequestedSkills | Reasons/RTargetPlaceGroup |
| Reasons/RTargetCampaignGroup | Reasons/RouterData70 | ReportingEventSequenceNumber |
| Reasons | Reasons/CBR-IT-path_DBIDs | Reasons/CBR-Interaction_cost |
| Reasons/CBR-actual_volume | Reasons/CBR-contract_DBIDs | RTargetUsed |
| RTargetUsed/RTargetName | RTargetUsed/RTargetType | |