Versions Compared

Version Old Version 1 New Version 2
Changes made by

Ekaterina Menetil (Unlicensed)

Danil Chernovalov (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Table of Contents
Note

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

...

Prerequisites

Create a service account for Kbot. This account must have access to ticket statuses and categories. Make sure you grant proper permissions for API requests concerning the ticket state.

Kbot setup

General configuration

To process incidents and demands, make sure you Kbot configuration includes the following:

  • The Operator Talk intent is enabled and available.The snow_chat_queue ticket_url configuration variable is set to the sys_id of the related chat queueportal URL, starting with https://. For example:

Code Block
snowticket_chat_queueurl = 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.

Info

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

...

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:

Code Block
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:

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

...

Classic errors

Permission error on message sending

Code Block
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:

Code Block
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.

...

https://my-company.service-now.com

  • The ticket_user and ticket_password variables store the username and the corresponding password of your ServiceNow service account. To configure these variables, open the Kbot back office and go to Configuration > General > ITSM.

...

In this view, you can also provide other ITSM parameters. To learn more about it, see the built-in documentation.

...

Incidents

To process incidents, make sure you Kbot configuration includes the following:

  • The Incident intent is enabled and available.

The list of additional settings for access options of logging issues. You can add these settings into the kbot.conf file if you need to redefine default values.

Parameter

Description

Default

now_sys_class_name_to_ticket_id

Contains the mapping of sys classes to the related ticket ID prefixes. It is a comma separated list of <sys_class_name>:<ticket id prefix>. This is used to get sys class by ticket ID prefix.

incident:INC, sc_request:REQ

snow_incident_sys_class_names

Specify sys_class_names of your incident tables to manage incidents.

incident

snow_incident_filter

Specify sysparm_query filters you want to use for getting incidents from each incident sys_class_name
in the format: snow_<incident sys_class_name>_filter.

active=true^caller_id={user_sys_id}^state=1^ORstate=2^ORstate=3

Requests

To process requests, make sure you Kbot configuration includes the following:

  • The Search ServiceNow catalog intent is enabled and available.

The list of additional settings for access options of a service catalog. You can add these settings into the kbot.conf file.

Parameter

Description

Default

snow_catalog_sys_ids

A comma separated list of sys_ids. You can define the list of catalogs that you want to use.

snow_sys_class_name_to_page

Contains the mapping of sys classes to the related portal page. It is a comma separated list of <sys_class_name>:<portal page name>. This is used for building the catalog item URLS (or have the URLs point to the Portal)

now_sys_class_name_to_ticket_id

Contains the mapping of sys classes to the related ticket ID prefixes. It is a comma separated list of <sys_class_name>:<ticket id prefix>. This is used to get sys class by ticket ID prefix.

incident:INC, sc_request:REQ

snow_request_sys_class_names

Specify sys_class_names of your request tables to manage requests.

sc_request

snow_sc_request_filter

Specify sysparm_query filters you want to use for getting requests from each request sys_class_name
in the format: snow_<request sys_class_name>_filter.

active=true^requested_for={user_sys_id}

Testing

Healthcheck

Once the ITSM is configured, you can use the Test button to see whether the portal is available and whether the service account that you are using is valid.

...

Creating an incident/request

You can test the incidents or requests in the chat. Note that you must have a ServiceNow user with the access to the portal.

Incident

In the chat, click the Quick Ticket Management button, then select Submit an incident.

...

Request

To create a request, run the following command in the chat: #do Search ServiceNow catalog:: <requested item>.

Managing tickets

In the chat, click the Quick Ticket Management button, then select List my tickets. The bot displays the complete list of tickets (both incidents and requests) with the current status.

Troubleshooting

  • If the ITSM configuration is invalid, the Healthcheck displays an error. In this case, follow the recommendations given in the error message.

  • If the dialog in the chat seems strange and you do not get expected replies, you can turn on the debugging. To do so, run the following command: #debug on and repeat the scenario to see the details. When you have finished the debugging, you can turn off the debugging functionality by typing #debug off.

...