Jump to: navigation, search

attach-session-statistics

Section: settings
Default Value: none
Valid Values: all, fired, none
Changes Take Effect: Immediately


Enables calculating various statistics and attaching them to the interaction's user data at the end of the chat session. Possible values are:

  • none: Do not attach anything.
  • all: Attach all possible statistics (both encountered and non-encountered).
  • fired: Attach only statistics that were encountered during the course of the chat session.

Note: Genesys recommends that you change the value of this option from the default value of "none" to "fired" if you deploy Historical Reporting for either Chat or Bot Gateway.

Example of JSON file for BGS reporting event

{               "cbs_endTime": "2018-05-03T08:27:42Z",
                "schema_info": {
                                "version": 1.0
                },
                "chatBot_info": {
                                "chatBot_name": "Translator 3000",
                                "chatBot_category": "Service",
                                "chatBot_function": "Agent advisory"
                },
                "session_info": {
                                "attr_itx_id": "itx0000081b",
                                "attr_itx_submitted_at": "2018-05-03T08:27:33Z"
                                "cbs_id": "0002EaCD00K80030",
                                "attr_itx_tenant_id": 101,
                                "attr_itx_media_type": "email",
                                "cbs_startTime": "2018-05-03T08:27:34Z",
                                "cbs_rejectedToStart": 0
                },
                "session_stats": {
                                "cbs_endedAbnormally": 0,
                                "cbs_duration": 8500,
                                "cbs_messagesSent": 15,
                                "cbs_messagesReceived": 10,
                                "cbs_endedBy": "CPB",
                                "cbs_endReason": "ALL_PARTICIPANTS_LEFT",
                                "cbs_endResult": "Success"
                },
                "attr_extension": {
                                "customAttributeName": "customAttributeValue"
                }
}

enable-chat

Section: agg-feature
Default Value: No default value
Valid Values: None. This option takes no values—its presence alone within the [agg-feature] section issues the described instructions to RAA.
Changes Take Effect: After restart of the aggregation process
Introduced: 8.5.003
Modified: 8.5.011.02, 8.5.011.04

Instructs RAA to enable the AGT_CHAT_STATS table. To have RAA exclude chat data, remove this option from this section.

enable-bgs

Section: agg-feature
Default Value: No default value
Valid Values: None. This option takes no values—its presence alone within the [agg-feature] section issues the described instructions to RAA.
Changes Take Effect: After restart of the aggregation process
Introduced: 8.5.003

Instructs RAA to enable the Bot Gateway Server (BGS) table: AGT_BGS_SESSION. To have RAA exclude BGS data, remove this option from this section.

g:topic:<topic-name>

Section: kafka-<cluster-name>
Default Value: No default value
Valid Values: Any Genesys Info Mart–defined <mapping-id>, as listed in the option description
Changes Take Effect: On the next ETL cycle
Dependencies: None
Introduced: 8.5.011.18

Specifies a Kafka topic to consume and how messages in this topic will be mapped. The <topic-name> in the option name identifies the topic Genesys Info Mart will look for in Kafka message headers and matches the topic name configured in the producer application. The option value identifies the ID in the CTL_XML_CONFIG table that Genesys Info Mart will use to map that topic into the database schema.

Configure a separate g:topic:<topic-name> option for each topic to which the Kafka producers publish reporting data. A particular kafka-<cluster-name> section might contain multiple g:topic:* options, some of which might have the same <mapping-id> value, depending on the data source.

Genesys Info Mart supports the following <mapping-id> values:

Producer application <mapping-id> Supported since Genesys Info Mart release
Bot Gateway Server (BGS) BGS_K 8.5.011.18
Genesys Co-browse (GCB) COBROWSE 8.5.011.18

bootstrap.servers

Section: kafka-<cluster-name>
Default Value: No default value
Valid Values: Any valid host:port combination that identifies a Kafka server in the cluster
Changes Take Effect: On the next ETL cycle
Dependencies: None
Introduced: 8.5.011.18

Specifies the location of the Kafka broker(s) in the cluster, in the form of host:port. If there are multiple servers, use a comma-separated list.

bootstrap.servers is a standard Kafka consumer option. The option is mandatory for Genesys Info Mart, as a Kafka consumer, to know where to connect for the initial connection to the Kafka cluster. In high availability (HA) deployments, Genesys recommends that you list all the brokers in the cluster.

For more information about the bootstrap.servers option, see the Apache Kafka documentation (https://kafka.apache.org/documentation#consumerapi).

kafka-topic-name

Section: channel-chatbot
Default Value: chat-bots-reporting
Valid Values: Any string
Changes Take Effect: Immediately


Specifies the name of Kafka topic to store the data.

kafka-zookeeper-nodes

Section: channel-chatbot
Default Value:
Valid Values: Any string
Changes Take Effect: Immediately


Specifies a set of Zookeeper nodes in form of host:port separated by semicolon or comma. This option is used only if kafka-cluster-brokers is not specified (in other words empty).

kafka-cluster-brokers

Section: channel-chatbot
Default Value:
Valid Values: Any string
Changes Take Effect: Immediately


Specifies a set of Kafka brokers in form of host:port separated by semicolon or comma.

Integrating BGS with Genesys Historical Reporting

For Bot Gateway Server (BGS), historical reporting on chat bot activity supplements the chat session reporting available in eServices premise deployments that include the Genesys Reporting & Analytics offering. Chat bot reporting is supported only for chat bots that are run by BGS.

This page describes the component and configuration requirements to enable historical reporting on BGS-managed chat bot activity in your deployment.

Overview: BGS reporting process

  1. After a BGS session is finished or when an attempt to launch a bot session is rejected, BGS produces a reporting event, which it publishes to Kafka. For more information about the reporting event attributes, see Reporting event attributes, below.
  2. The BGS reporting event is separate from the Interaction Server reporting event that is generated at the end of the Chat Server session. The chat session reporting event includes some bot-related statistics that are processed as part of chat session reporting (see Integrating Chat Server with Genesys Historical Reporting in the Chat Server Administrator's Guide).
  3. On a regular schedule, Genesys Info Mart extracts the BGS data from Kafka and transforms it into the BGS_SESSION_FACT table and supporting dimensions in the Info Mart dimensional model. For more information about the Info Mart database tables, see the Genesys Info Mart Physical Data Model for your RDBMS. For more information about managing the Genesys Info Mart ETL jobs, see the Genesys Info Mart Operations Guide.
  4. In deployments that include Reporting and Analytics Aggregates (RAA) and Genesys CX Insights (GCXI), RAA summarizes and organizes the Info Mart data in ways that enable GCXI to extract meaning. For more information about RAA data, see the RAA User's Guide.
  5. GCXI uses the aggregated data in the Info Mart database to produce a Bot Dashboard. For more information, see Chat reports in the GCXI User's Guide.

Enabling historical reporting on BGS activity

Prerequisites

The following table summarizes the minimum release requirements for the Genesys and third-party components that enable chat bot historical reporting.

Component Minimum release
Bot Gateway Server 9.0.004
Kafka 2.0
Chat Server 8.5.203.09
Genesys Info Mart 8.5.011.18
RAA 8.5.003
GCXI 9.0.005

Setting up historical reporting

  1. Ensure that your deployment has been configured as required for Genesys Info Mart to support chat session reporting.
    For more information, see Integrating Chat Server with Genesys Historical Reporting in the Chat Server Administrator's Guide. If you have not already done so, configure Interaction Concentrator (ICON) to store the user data KVPs listed below (see Chat Server reporting data).
  2. Configure BGS to report bot metrics.

    By default, BGS captures the minimum attributes required in the reporting event to enable historical reporting out-of-box. However, the default ESP methods do not populate all the parameters that are useful for reports.

    For meaningful reporting, Genesys strongly recommends that you populate the chatBot_category and chatBot_function attributes, in particular. There are two ways you can populate the category and function attributes:

    • Through the API (in BotCreationAttributes) during createChatBot
    • By specifying ChatBotCategory and ChatBotFunction in the parameters of the ESP StartBot method
    For more information about the available attributes, see ESP methods and BGS reporting event attributes, below.

  3. Enable the storage of BGS reporting metrics in Kafka.
    1. Deploy Kafka version 2.0.
    2. Configure BGS to output reporting data into Kafka by configuring the following options in the channel-chatbot configuration section:
  4. Configure Genesys Info Mart to extract the BGS reporting data from Kafka.
    1. On the Options tab of the Genesys Info Mart application object, create a new configuration section, kafka-<cluster-name>. The <cluster-name> can be any string you use to identify the cluster—for example, kafka-1.
    2. In the new section, add the following options:
      • bootstrap.servers—The value must match the value of the BGS kafka-cluster-brokers or kafka-zookeeper-nodes option (see step 3).
      • g:topic:<topic-name>—The <topic-name> must match the value of the BGS kafka-topic-name option—for example, g:topic:chat-bots-reporting. The value of the option must be BGS_K.
    3. (Optional, but recommended) Set an alarm on log message 55-20049, which identifies that a transformation job error has occurred because of a Kafka exception, such as a complete loss of connection to the cluster.
  5. Enable aggregation of bot-related data. (Required for GCXI reporting or other applications that use RAA aggregation.)
    In the [agg-feature] section on the Genesys Info Mart application object, specify the enable-bgs option. If you haven't already done so, also specify the enable-chat option.

Bot-related reporting data

There are two mechanisms by which Genesys Info Mart receives bot-related reporting data:

BGS application data

After a BGS session is terminated or rejected, BGS generates a reporting event for that session and stores the data in Kafka. There might be multiple BGS sessions within a single chat session.

JSON Example

The following is an example of a BGS reporting event serialized as a JSON file for Kafka storage. See BGS reporting event attributes for the meaning of the attributes.

Click to see example.

BGS reporting event attributes

The following table describes the attributes included in the BGS reporting event. The "Application data attribute" column, which includes the name of the section as well as the attribute itself, represents the XPath search term Genesys Info Mart uses to extract and map the data. The "Info Mart Database Target" column indicates the Info Mart database table and column to which the attribute is mapped.


Application data attribute Description Info Mart Database Target
Application data attribute Description Info Mart Database Target
/cbs_endTime
 The UTC-equivalent value of the date and time at which the BGS session ended or was rejected. BGS_SESSION_FACT.END_TS, BGS_SESSION_FACT.END_DATE_TIME_KEY
/chatBot_info/chatBot_category
 The generic category describing the type of function performed by the bot, such as Monitoring, Dialog, Notification, or Service.
Default value: "Unspecified" 		BGS_BOT_DIM.BOT_CATEGORY (referenced through BGS_SESSION_FACT.BGS_BOT_DIM_KEY)
/chatBot_info/chatBot_function
 The specific bot functionality, such as Translator, Advisor, Escalation, Recording, AI, or Questioner.
Default value: "Unspecified" 		BGS_BOT_DIM.BOT_FUNCTION (referenced through BGS_SESSION_FACT.BGS_BOT_DIM_KEY)
/chatBot_info/chatBot_name
 The identification of the bot represented by "ChatBotID-ChatBotName" pair, where:
  • ChatBotID (always presented) - The ID of the BGS bot plugin (this ID is hardcoded inside the bot and returned by getBotId()).
  • ChatBotName (may be empty) - The name of the "external" bot (for example, if the bot plugin implements a connector to other bot frameworks).
BGS_BOT_NAME_DIM.BOT_NAME (referenced through BGS_SESSION_FACT.BGS_BOT_NAME_DIM_KEY)
/session_info/attr_itx_id
 The interaction GUID, as reported by Interaction Server. This value is the ID of the chat session. BGS_SESSION_FACT.MEDIA_SERVER_IXN_GUID
/session_info/attr_itx_media_type
 The media type of the parent interaction. The default value of "NONE" means that BGS was unable to get information about the interaction.
Valid values: [Chat, Email, sms]
Default value: "NONE" 		MEDIA_TYPE.MEDIA_NAME_CODE (referenced through BGS_SESSION_FACT.MEDIA_TYPE_KEY)
/session_info/attr_itx_submitted_at
 The timestamp of the start of the interaction (in other words, the chat session) in Interaction Server. The default value is used when BGS is unable to get information about the interaction.
Default value: Current DateTime in ISO8601 date format as provided by Interaction Server 		BGS_SESSION_FACT.INTERACTION_SDT_KEY
/session_info/attr_itx_tenant_id
 The DBID of the Tenant. The default value is used when BGS is unable to get information about the Interaction.
Default value: -1 		BGS_SESSION_FACT.TENANT_KEY
/session_info/cbs_id
 The ID assigned by BGS to every bot instance or process connected to the chat session. BGS_SESSION_FACT.CBS_ID
/session_info/cbs_rejectedToStart
 Flags whether the session was rejected before it started. If the session was rejected (the value of the attribute is 1), the "session_stats" section of the reporting event is omitted.
Valid values: 0, 1 		BGS_SESSION_DIM.REJECTED_TO_START (referenced through BGS_SESSION_FACT.BGS_SESSION_DIM_KEY)
/session_info/cbs_startTime
 The UTC-equivalent value of the date and time at which the bot session was initiated in BGS, regardless of whether the session was accepted or rejected. BGS_SESSION_FACT.START_TS, BGS_SESSION_FACT.START_DATE_TIME_KEY
/session_stats/cbs_duration
 The duration, in milliseconds, of the BGS session. BGS_SESSION_FACT.DURATION
/session_stats/cbs_endedAbnormally
 Indicates whether the session ended abnormally for a technical reason (for example, a protocol or connection error resulted in disconnection of the bot from the session)
Valid values: 0, 1 		BGS_SESSION_DIM.ENDED_ABNORMALLY (referenced through BGS_SESSION_FACT.BGS_SESSION_DIM_KEY)
/session_stats/cbs_endedBy
 The type of participant that initiated termination of the BGS session.
Valid values:
  • SYSTEM—Denotes a Chat Server (for example, if Chat Server ended the chat session because of idle control or shutdown).
  • AGENT—Denotes an agent who participated in the chat session, regardless of whether that agent was visible to the customer.
  • BOT—Denotes the chat bot.
  • CBP—Denotes Bot Gateway Server (for example, if BGS ended the session because all participants left, or as a reaction to StopBotOnCustomerLeft if provided during bot startup, or during server shutdown, or because of a malfunction).
BGS_SESSION_DIM.ENDED_BY (referenced through BGS_SESSION_FACT.BGS_SESSION_DIM_KEY)
/session_stats/cbs_endReason
 The reason the BGS session was terminated.
Valid values:
  • ESP_REQUEST — Stopped by ESP request.
    Possible associated values for:
    • cbs_endedBy: SYSTEM
    • cbs_endedAbnormally: 1/0
  • AGENT_JOINED — Configured with StopBotOnAgentArrival, and agent joined.
    Possible associated values for:
    • cbs_endedBy: CBP
    • cbs_endedAbnormally: 1/0
  • ALL_CLIENTS_LEFT — Configured with StopBotOnCustomerLeft, and the last client (cusomer) left.
    Possible associated values for:
    • cbs_endedBy: CBP
    • cbs_endedAbnormally: 1/0
  • ALL_PARTICIPANTS_LEFT — All participants (except bots, external users, and system users) left the session.
    Possible associated values for:
    • cbs_endedBy: CBP
    • cbs_endedAbnormally: 1/0
  • RELEASED_BY_PARTY — A party release event was received, and the asker was not the current bot.
    Possible associated values for:
    • cbs_endedBy: AGENT or BOT
    • cbs_endedAbnormally: 1/0
  • RELEASED_BY_SELF — A party release event was sent by the bot (through leaveSession).
    Possible associated values for:
    • cbs_endedBy: BOT
    • cbs_endedAbnormally: 1/0
  • REMOVED_BY_SERVER — Chat Server removed a bot participant.
    Possible associated values for:
    • cbs_endedBy: SYSTEM
    • cbs_endedAbnormally: 1/0
  • IDLE_CONTROL — A bot participant was removed because the chat session was closed because of inactivity.
    Possible associated values for:
    • cbs_endedBy: SYSTEM
    • cbs_endedAbnormally: 1/0
  • DISCONNECTED — A protocol or connection error resulted in disconnection from the session.
    Possible associated values for:
    • cbs_endedBy: SYSTEM/CBP
    • cbs_endedAbnormally: 1
  • CBP_SHUTDOWN — CBP was shutting down.
    Possible associated values for:
    • cbs_endedBy: CBP
    • cbs_endedAbnormally: 1/0
    		• BGS_SESSION_DIM.END_REASON (referenced through BGS_SESSION_FACT.BGS_SESSION_DIM_KEY)
    /session_stats/cbs_endResult
    		 Not currently populated by BGS. In the future, this attribute might be populated with information provided by bots about the business result of the session: Success or Fail. BGS_SESSION_DIM.END_RESULT (referenced through BGS_SESSION_FACT.BGS_SESSION_DIM_KEY)
    /session_stats/cbs_messagesReceived
    		 The number of messages received by the bot in the BGS session. BGS_SESSION_FACT.MESSAGES_RECEIVED
    /session_stats/cbs_messagesSent
    		 The number of messages sent by the bot in the BGS session. BGS_SESSION_FACT.MESSAGES_SENT


    Chat Server reporting data

    When the chat session is finished, Chat Server attaches reporting statistics to the user data of the interaction in Interaction Server.

    The following table describes the bot-related reporting statistics that Chat Server includes in the user data if any BGS-managed chat bots participated in the chat session. The "Info Mart Database Target" column indicates the Info Mart database table and column to which the user data KVP is mapped. (For information about the rest of the chat session KVPs that Chat Server sends, see Chat Server reporting data in the Chat Server Administration Guide.)

    Important
    If the BGS session is rejected, no KVPs related to the rejected session are included in the user data that Chat Server attaches, regardless of the attach-session-statistics option value.

    KVP Description Info Mart Database Target
    KVP Description Info Mart Database Target
    csg_MessagesFromBotsCount
    		 The total number of messages visible to the customer that were sent by all bots that participated in the chat session. CHAT_SESSION_FACT.MSG_FROM_BOTS_COUNT
    csg_MessagesFromBotsSize
    		 The total character count (including spaces) of all messages sent by bots that participated in the chat session. CHAT_SESSION_FACT.MSG_FROM_BOTS_SIZE
    csg_PartiesAsBotCount
    		 The number of parties that participated in a chat session as bots. If the same bot (in other words, a bot with the same ID) connects multiple times, it is counted as a separate participant each time it joins. CHAT_SESSION_FACT.BOTS_COUNT
    csg_SessionUntilFirstBotTime
    		 The duration of the waiting period, or the period of time a customer waits until the first bot (visible to a customer) joined the chat session.

    Note: The 0 (zero) value has two alternative interpretations: No bots ever joined the session (if csg_PartiesAsBotCount=0) or a bot joined immediately when the chat session was started (if csg_PartiesAsBotCount > 0).

    		CHAT_SESSION_FACT.UNTIL_FIRST_BOT_DURATION
    This page was last edited on January 19, 2021, at 18:31.
    Comments or questions about this documentation? Contact us for support!