The ServiceNow and Kbot Live Chat integration allows users interacting with Kbot to log issues or requests in ServiceNow ITSM. This page describes how to set up the integration and explains its key points.

This document and associated described Snow Object is Konverso proprietary information. The source code shall under no circumstance be shared with any other parties without written consent from Konverso.

Prerequisites

The Snow Live Chat is in place.
The sys_id of the related Chat Queue is known and available.

Kbot setup

Make sure you Kbot configuration includes the following:

The Operator Talk intent is enabled and available.
The snow_chat_queue configuration variable is set to the sys_id of the related chat queue. For example:

snow_chat_queue = 423769e3db89bf00e48283840596197f

Snow object setup

See the list of objects that must be configured in ServiceNow to permit the Kbot and Snow Live Chat integration. The objects are described in a valid Creation or Import order.

To quickly implement these objects in your environment, you can ask Konverso for the XML exports of these objects.

Object Class	Object Class	Object Name	Purpose
Server Development / Script Include	Script Include (`sys_script_include`)	`KonversoMessage`	This object implements the base JS class to process send/get a message to/from Kbot
Inbound Integrations	Scripted REST API (`sys_ws_definition`)	`KonversoOperator`	The REST endpoint on ServiceNow side to join a queue, send a message, and close the queue. This endpoint is invoked from Kbot side. This is the container of the three next Scripted REST Resources.
Inbound Integrations	Scripted REST Resource (`sys_ws_operation`)	`KonversoOperator/Join`	Is called with key Kbot information user token `conversation_id` kbot hostname `sys_user`; `sys_id` We store this information inside the `live_group_profile` in the short description, and use it later.
Inbound Integrations	Scripted REST Resource (`sys_ws_operation`)	`KonversoOperator/Send`	Called on every message sent by the user to the agent.
Inbound Integrations	Scripted REST Resource (`sys_ws_operation`)	`KonversoOperator/Close`	Called when a user closes the live chat session.
Outboud Integration	HTTP Method	`PostMessage`	The actual REST request to Kbot to post a message in a Kbot Conversation
Outbout Integration	REST Message (`sys_rest_message`)	`KonversoBot`	To send a message from Snow to Kbot.
Server Development / Business Rule	Business Rule (`sys_script`)	`KonversoRule`	This rule is triggered when an operator types a message in the Live Chat. It sends a message to Kbot.
Server Development	Business Rule (`sys_script`)	`KonversoOperatorExit`	This rule is triggered when an operator closes a conversation on the ServiceNow side. A command is then sent to Kbot to have the conversation closed in Kbot as well.

Flows

This section describes the flows of the requests and data in various interactions between users and agents.

User asks to talk to an agent

The KonversoOperator/Join flow creates the live_group_profile object.

Key points

A Kbot user is asked to wait for an agent to answer the chat session.
A Kbot user can stop at any time by typing stop and return to chatting with the bot.
Once a session is accepted by an agent, any Kbot user input is sent to the Live Chat, and not processed by the bot.

The live_group_profile object stores the Kbot user and conversation information inside its short description. This information is required to send this Live Session activity back to the bot later.

User and agent chatting

Once a user and an operator are in the session, they can both exchange messages. The flow is quite different in the two directions:

An operator types something

The flow is: Trigger Scripted Rule KonversoRule => Konverso Message => Outbout REST Konverso Bot

Basically, a Snow trigger catches the new message, and it causes an API call to be made to Kbot. The call contains the Operator message details, such as : message, operator name, and avatar.

Note that the Kbot user token, stored in live_group_profile, is used to make this API all to Kbot.

A user types something

The flow is: Kbot calls the KonversoOperator/Send ServiceNow API.

Live Chat termination

An agent ends a conversation

Triggers the Scripted Rule KonversoOperatorExit => this calls the utility Javascript Include Konverso Message => which invokes the Outbout REST Konverso Bot => Kbot conversation End Point receives the requests and informs the user.

A user ends a conversation

A user can end a conversation either by typing stop or exit, or by clicking the Refresh or Clear buttons.

KonversoOperator/Close => Change the status of live_group_profile (user exit).

Troubleshooting

Accessing Kbot debug information

If you have SSH access you can enable the debug. To do so, run the following command:

bin/core.sh debug add operator 3

It allows you to view messages regarding any API calls made to and from ServiceNow, and to study error details.

Managing log information

To understand what is happening in Kbot, study the core.log file. To see the latest process log information:

In Kbot, go to DevOps > Errors > Process log.

Classic errors

Permission error on message sending

WARNING:Send:Problem with sending message to operator : 
   {"error":
       {"detail":"User does not have permission to add messages to this group",
        "message":"User does not have permission to add messages to this group"},
    "status":"failure"
   }

This error means that a ServiceNow user has no access to the specified queue (see the snow_chat_queue group that is configured in your kbot.conf). Provide an access to a user on the ServiceNow side and try again.

Missing API endpoint

You might get the error of the following kind:

DEBUG:_make_request:https://your_portal.service-now.com:443 "POST /api/veefr/koperator/join HTTP/1.1" 400 None
2020-09-18 13:43:22,820 - SNowOperator::__OnDutyError(94) - operator - ERROR - 139976004073216 - Cannot join to ServiceNow chat queue
ERROR:__OnDutyError:Cannot join to ServiceNow chat queue

This means that the Inbound REST API endpoints are not defined. Check that both are equal:

The API path (in the sample above it is /api/veefr/koperator/join) is same for the snow_chat_queue variable (stored in the kbot.conf file) and the ServiceNow script.

Accessing Snow debug information

To view the logs and see the details about all Kbot interactions, navigate to Script Log Statements.

Kbot for Snow - ITSM Setup