SN-Conversation Service Whitepaper V PDF

ServiceNow
Integration with IBM

Watson Conversation Service
Whitepaper
V1.0

Table of Contents

Overview ....................................................................................................................................................................... 3
Supported Versions ....................................................................................................................................................... 3
Disclaimer ...................................................................................................................................................................... 3
IBM Bluemix Account .................................................................................................................................................... 4
Create a Watson REST Message .................................................................................................................................... 5
Create a Bot User .......................................................................................................................................................... 7
Scoped App Design Considerations ............................................................................................................................... 8
Design #1 – Async Business Rule with Sync Outbound REST ..................................................................................... 8
Design #2 – Sync Business Rule with Async Outbound REST ................................................................................... 11
Connecting Watson Dialogs to ServiceNow Actions ................................................................................................... 14
Create an Action table ............................................................................................................................................. 14
Relate an Action to a Dialog node ........................................................................................................................... 14
Executing Actions ..................................................................................................................................................... 14
Other Concerns ........................................................................................................................................................... 16
Chat Message Destination ....................................................................................................................................... 16
Watson Conversation Context Management .......................................................................................................... 16
Chat Entry Point ....................................................................................................................................................... 17
Chat Bot Impersonation ........................................................................................................................................... 19
Appendix A .................................................................................................................................................................. 20
Code: Chat Entry Point ............................................................................................................................................. 20
PRB1066179: GlideLiveMessageBroadcaster is unavailable to scoped applications ............................................... 22

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

© 2017 ServiceNow, Inc. All rights reserved.
ServiceNow and the ServiceNow logo are trademarks of ServiceNow, Inc. All other brand and product names are trademarks or registered trademarks of their respective holders.

Overview

This paper provides recommendations to build Virtual Agent bots on the ServiceNow Platform that integrate with
the IBM Watson Conversation Service. All chat interactions will occur through the Connect chat client provided by
ServiceNow.
Throughout this document, callouts for advantages and disadvantages of each approach will be noted. It is up to
you to decide which approach makes sense for your organization given your specific needs and criteria for success.

Supported Versions

This whitepaper copyrighted @2017, supports the ServiceNow Platform for releases Jakarta, Istanbul and Helsinki.
The IBM Watson Conversation service is at version 2017-05-26. All versions beyond this should also be compatible.

Disclaimer

ServiceNow is changing the way people work. With a service-orientation toward the activities, tasks and processes
that make up day-to-day work life, we help the modern enterprise operate faster and be more scalable than ever
before. The content covered on this whitepaper
The updates in this document represent our integration specs and assumptions, only as of the date of this
whitepaper. We undertake no obligation, and do not intend to update the forward-looking changes, to review or
confirm expectations on installations completed. The integrations with IBM, the IBM logo, Watson,
Bluemix and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in
the United States, other countries, or both.
Further information on these and other factors that could affect our technical outcomes are not intended to be
included.


IBM Bluemix Account

In order to integrate with any IBM Watson services, you are required to register for an IBM Bluemix account. Once
your account is created, you are able to create a new Conversation Service and workspace.
Start by create a Bluemix account. For more information see Bluemix Information- Click Here
For help creating a Conversation service please see Conversation Service - Click Here
1. Find the Conversation Service under the Watson Services catalog. For more information about adding a
service to your application see: Adding a Service - Click Here
2. Choose a pricing plan and click Create.
a. ServiceNow does not recommend any particular plan; choose the one that is right for your needs.

3. Your new Conversation service is created and given a default name.
a. Click the Service credentials menu item to access the REST endpoint credentials generated for
your service. This information will be needed later in this document.
b. Click Launch tool to open the Conversation workspace tool.

4. You are presented with a list of Workspaces. There is a default example Workspace, but you should take this
time to create your new Virtual Agent workspace.
a. Once created, click the overflow menu icon to access the Workspace details. You will need the
Workspace ID later in this document.

5. That’s it! Click “Get started” to begin building your Watson Conversation Intents, Entities, and Dialogs!



Create a Watson REST Message

1. Create a REST Message v2 record
In your ServiceNow instance, browse to the Outbound -> REST Message table and create a new REST
Message record. Given the Workspace ID from your Watson service (from step 4a above) configure the
REST Message as such:

Take note of a few things in this screenshot.
1. ${workspaceId} parameter – The Workspace Id of your specific Watson Conversation workspace.
2. ${version} parameter – The version of the Watson API you want to use.
3. Content-Type – Let the Watson service know we are sending the payload as JSON.

NOTE: You may hardcode these parameters instead if you do not need them to be programmatic in
your scenario.



2. Watson Service REST Credentials

Under the Authentication tab, choose Basic authentication type and create a new Basic auth profile to
hold your Watson Service credentials as found in step 3a above.

3. HTTP Method

Create a new HTTP Method to handle the POST request to the Watson Conversation service. Most of the
parameters are inherited from the parent REST Message record, but you will need to specify the Content
field of the POST payload as required by the Watson Conversation Service API docs.

The ${message} and ${context} parameters will be provided at runtime via scripting code. Examples are
provided in the sections below.


Create a Bot User

1. Create a bot user
Create a sys_user table record to represent your bot. Here you can brand your bot with a name, image,
email, etc.
2. Add roles
a. You may choose to create a new role for your bot to assist with other access rights, e.g. a role
called “virtual_agent”.
3. Locked out
Lock out the bot user to prevent anyone from logging in as that user.



Scoped App Design Considerations

Each of the following designs have their own pros and cons. Determine which approach will work the best for your
instance given your needs.

A Bit About Semaphores
Semaphores control the number of user transactions that can be run in parallel per node in your ServiceNow
instance. The Platform manages semaphores, and they require no customer administration. To see the number of
semaphores per node that your instance supports visit /stats.do on your instance.

Design #1 – Async Business Rule with Sync Outbound REST
Using an asynchronous business rule to handle incoming Connect Chat messages has the advantage of releasing
semaphores before processing the outbound REST Message to Watson, but gives a slow perceived user
experience. Use this design when your instances must support a large number of concurrent users. Consult your
System Administrator for more information about the number of concurrent users on your instance.
How do Async Business Rules work?
On an incoming transaction which triggers your business rule conditions a new run once sys_trigger (Scheduled
Job) record is created and queued to run. Once that sys_trigger executes it will run the business rule script in the
background, effectively allowing the rest of your virtual agent code to run without holding on the main thread’s
transaction semaphore. This allows other users to continually use your instance without any slow down.
When using an async business rule the Priority field is displayed on the form. Setting the priority to a lower value
increases the likelihood that the background sys_trigger will run before other pending sys_trigger jobs. This is
highly dependent on the other configurations of the instance running the business rule.



High Level Architecture Diagram

Build your app
1. Business Rule
Start by creating an async insert business rule on the live_message table. This is the entry point for your
virtual agent application code. For best practices consider putting all of your application code in a Script
Include instead of directly in this business rule.
a. Set a low priority value here to get faster perceived experience for your users.
2. Sync Outbound REST call
Within your virtual agent application code, make an outbound REST call to the IBM Watson Conversation
service endpoint. See the following example code:



This code takes the existing REST Message object you created earlier, sets some parameters, and executes
the outbound REST call immediately via the r.execute() call. Your script is now blocked while it waits for
an HTTP response object. This send function also gives an example return object and one possible
method for handling REST errors.

3. Sending a response back to the Connect chat client
Once your application code has the Watson response and finished any other processing it can proceed to
forward a response message back to the end user. This is done by using the LiveFeedMessage script
include object and calling its postMessage(data) method.
4. Business Rule
When posting a Live Feed message back to the user from behind an async business rule an extra step is
required in order for that message to be relayed to the frontend user. Create another business rule using
the following configurations:
• Table: Live Feed Message [live_message]
• Active: true
• Advanced: true
• When: before
• Order: 25
• Insert: true
• Filter Conditions: Profile is <choose your bot user>
• Actions: Chat To true


This will set the “Chat” (chat_message) field to true; as this can not be set via the LiveFeedMessage API.
This will indicate to Connect to forward that chat message along to the frontend user.

Considerations
Advantages Disadvantages
Does not hold onto client thread

semaphores during the execution of the Potentially slower chat performance
virtual agent code
Better overall instance health and Potential negative virtual agent

perceived performance for all users experience

Design #2 – Sync Business Rule with Async Outbound REST
Using a synchronous insert Business Rule to handle incoming Connect Chat messages has the advantage of speed,
but will consume more of your instance’s semaphores. Use this design only when the maximum number of
concurrent users is relatively low. Consult your System Administrator for more information about the number of
concurrent users on your instance.
Geneva Support
Geneva does not support async outbound REST and as such this design choice is not an option.
High Level Architecture Diagram


Build your app
1. Business Rule
Start by creating an insert Business Rule on the live_message table. This is the entry point for your virtual
agent application code. For best practices consider putting all of your application code in a script include
instead of directly in this business rule.
2. Async Outbound REST call
Within your virtual agent application code, make an outbound REST call to the IBM Watson Conversation
service endpoint. See the following example code:

This code takes the existing REST Message object you created earlier, sets some parameters, and executes
the outbound REST call asynchronously via the r.executeAsync() call. This send function also gives an
example return object and one possible method for handling REST errors.

NOTE: A background job polls the ecc_queue table every 2 seconds (based on the property
glide.scheduler.sleeptime) for outbound REST jobs to execute. Depending on how many items
are in the queue your request might not execute immediately. This can add a delay in the chat
experience that your users can perceive as a slow response from the bot.

In order for your application to process the asynchronous Watson response you will need to wait for the
response to return by using response.waitForResponse(6). ServiceNow recommends 6s; adjust as needed
from your own testing.


3. Send a response back to the Connect chat client
Once your application code has the Watson response and has finished any other processing it can proceed
to forward a response message back to the end user. This is done by using the LiveFeedMessage script
include object and calling its postMessage(data) method.

Considerations
Advantages Disadvantages
Holds client thread semaphore for the

Fast chat performance
life of the transaction
Potential to make the instance run slow

Better virtual agent user experience or give perceived slow down across all
HTTP requests for all users.


Connecting Watson Dialogs to ServiceNow Actions

The following is the recommended approach to relate ServiceNow actions to your Watson Dialog tree nodes in
your conversation flows.
Create an Action table
Start by creating a new table to hold your bot action scripts. Here is a simple example:

This is how you can extend your bot’s functionality based on the current dialog node in the Watson conversation
flow.
Relate an Action to a Dialog node
Once you create a bot action, copy its sys_id, log into your IBM Bluemix account, and open the Conversation
workspace tool. Once you find the dialog node in the tree you wish to relate the action too, open the node’s JSON
response object and create a context variable referencing the action’s sys_id.
For example:

Executing Actions


When you make the REST call to Watson to process the client’s input message, it runs through its dialog tree and
stop on a matching dialog node. That node’s context is part of the returned response object of the resulting REST
call. This is where your virtual agent application code should parse the context response for action sys_ids, look up
those actions, and execute those scripts to perform those actions.

NOTE: This is only example code:


Other Concerns
Other items to consider when developing your virtual agent application.

Chat Message Destination
Special logic is needed to determine who is talking to the virtual agent and to keep the virtual agent from
answering its own messages. Use the following logic to help determine when your virtual agent should handle an
incoming chat message from your business rule.
NOTE: This is only example code.

In this example code, BOT.USER_ID is a constant referencing the sys_id of your bot’s sys_user. Feel free to
implement this however you like, but the take-away is that we do not want the bot to process messages coming
from itself.
Additionally, we do want the bot to respond to @mention annotations or only to messages in groups in which the
bot is actively participating.

Watson Conversation Context Management
When interfacing with the Watson Conversation service your application will need to maintain the context of each
conversation. This context JSON object will need to be passed to the Watson Conversation service for each request
and then be updated by the resulting context object when the response returns from Watson. Your application
should persist the context JSON object in a table which can be related to the current Connect Chat conversation.



A simple table is needed to store the Watson JSON context and reference to the related live_group_profile
conversation. Add any additional fields, references, or structures needed by your app.
NOTE: Example data model

Column Data Type Length
Live Group Profile Reference [live_group_profile] n/a
Context String 4,000

NOTE: Only one human user can chat with one virtual agent within a specific chat room conversation.

Chat Entry Point
In order to make a full featured experience for your users you will need one click access to your virtual agent. The
following is some example code you can use to help launch a new (or reuse an existing) Connect chat conversation
for the currently logged in user with the virtual agent.

See Appendix A for a script include which can be used from any manner you see fit; e.g. UI Action, Service Portal
script, or any other UI widget you deem fit. With a simple function call this script include will:
• Create a new live_group_profile conversation record, if needed or reuse an existing one.
• Add the current user to the conversation.
• Add the virtual agent to the conversation.
• Open a Connect chat window on the user’s UI.

NOTE: See Appendix A for usable code.

Known Issue
Both of the below options are only available in Jakarta at this time. This is due to a known bug in Helsinki and
Istanbul that is slated to be fixed in a future patch.
PRB1066179: GlideLiveMessageBroadcaster is unavailable to scoped applications
See Appendix A for a workaround which may be included into your scoped app.



Option #1 – Opening a Connect chat floating window
This option allows you to open a floating Connect chat window over top the current UI of your instance. This can
be triggered from any mechanism you like, but we will demonstrate this from a UI Action.
NOTE: Example code


Option #2 – Opening the full screen Connect chat
If you prefer to open a new full screen window for your chat experience, then use the following script to do so. It
will perform the same steps as above but launch Connect chat in a new tab.

NOTE: Example code

Chat Bot Impersonation
When taking actions within your application those actions will be reflected as the originating chat user. Currently
there is no way for a scoped app to impersonate another user; e.g. execute the actions as the bot user.


Appendix A
Code: Chat Entry Point
The following script include code can be used to create a conversation and open a new chat window with the
current user and the virtual agent bot. Use this script include from any means needed from your application’s UI.
Overview
1. Creates a new group, or reuses an existing group from the live_group_profile table to be used for
this chat interaction
2. Adds the bot user to the group using the bot user’s sys_id
3. If using the connect chat window then set the frame_state to open for all live_group_members of
the live_group_profile used for the chat interaction. This flag determines if the connect window
will open automatically at the start of the interaction.
4. Send a welcome message from the bot to the user using the function
liveFeedMessage.postMessage. This function is also responsible for publishing the AMB message
that causes the connect chat window to open. *
5. If using the connect full screen chat page, then construct and return the redirect URL for page.

Known Issue
There is a known bug with Helsinki and Istanbul that prevent the chat bot from updating the connect window from
a scoped application, causing the chat to appear as if it has hanged. The LiveFeedMessage postMessage
function can insert the chat messages into the live_messages table, however it cannot update the AMB
queue, which is used by connect to determine when it should pull data and update the chat interface.
See the next Appendix A section for a workaround which may be included into your scoped app.

Script Include
var ClickToChatService = Class.create();
ClickToChatService.prototype = {
initialize: function() {
this.botUserSysId = null;
},
/**
* Get the Live Profile sys_id of the given user
* LiveGroups use live_profiles not user sys_ids
*
* @param String userSysId
*/
getLiveProfileId: function(userSysId) {
var gr = new GlideRecord('live_profile');
gr.addQuery('document', userSysId);
gr.query();
if(gr.next()) {
return gr.getUniqueValue();
}
return null;
},
/**
* Find the existing liveGroupMessage, or
* create a new one
*
* @param String botUserName the username of the bot sys_user record
* @return String lgpId - the Live Group Profile sysId


*/
getLiveGroupProfileId: function(botUserName) {
var gr = new GlideRecord('live_group_profile');
gr.addQuery('name', gs.getUserDisplayName() + ',' + botUserName);
gr.query();
var lgpId;
if(! gr.next()) {
// create group profile
var lgp = new GlideRecord('live_group_profile');
lgp.initialize();
lgp.name = gs.getUserDisplayName() + ',' + botUserName;
lgpId = lgp.insert();
} else {
lgpId = gr.getUniqueValue();
}
return lgpId;
},
/**
* Add a member to a live group if they are
* not already a member of the group
*
* @param String lgpId Live Group Profile ID
* @param String liveProfileId Live Profile ID of the user
* @return void
*/
createMemberInLGM: function(lgpId, liveProfileId){
var gr = new GlideRecord('live_group_member');
gr.addQuery('group', lgpId );
gr.addQuery('member', liveProfileId);
gr.query();
if(! gr.next()) {
// create live group member for end user
var user = new GlideRecord('live_group_member');
user.initialize();
user.group = lgpId;
user.member = liveProfileId;
user.state = 'Admin';
user.frame_state = 'open';
user.insert();
}
},
/**
* Sets the framestate as open for all users in the live group
*
* @param String groupId Live Group Profile sys_id
* @return void
*/
openFrameState: function(groupId){
var gr = new GlideRecord('live_group_member');
gr.addQuery('group', groupId);
gr.query();
while (gr.next()) {
gr.frame_state = 'open';
gr.update();
}
},
/**
* @param groupId
* @param message
* @param fromProfileId
* @return void
*/
sendMessage: function(groupId, message, fromProfileId){
var data = {
message : message,
group_id : groupId,
to_profile : null,
is_worknotes : 'false',
from_profile : fromProfileId
};


var liveFeedMessage = new global.LiveFeedMessage();

liveFeedMessage.postMessage(data);
},
/**
* Entry point to the script include
*
* @param botUserSysId
* @param redirect boolean true will return a redirect URL
* @return String or void
*/
execute: function(botUserSysId, redirect) {
this.botUserSysId = botUserSysId;
var useRedirect = false;

if( typeof redirect !== 'undefined')
if(redirect)
useRedirect = true;
var endUserProfileId = this.getLiveProfileId(gs.getUserID()); // Profile Id of

the end user
var botUserPofileId = this.getLiveProfileId(botUserSysId); // Profile Id of the
bot user
var userGR = new GlideRecord('sys_user');

var botUserName = "";
if(userGR.get(botUserSysId)) {
botUserName = userGR.getValue('first_name');
}
var lgpId = this.getLiveGroupProfileId(botUserName);
// create user in group(if not already there)

this.createMemberInLGM(lgpId, endUserProfileId);
// Create bot member in group (if not already there)

this.createMemberInLGM(lgpId, botUserPofileId);
// force open the frame state for the user

if(useRedirect)
this.openFrameState(lgpId);
// Send a welcome message to the user

var firstMessage = 'Hello ' + gs.getUserName() + ' How can I help you ? ';
this.sendMessage(lgpId , firstMessage, botUserPofileId);
if(useRedirect)
return gs.getProperty("glide.servlet.uri") + '$c.do#/chat/' + lgpId;
},
type: 'ClickToChatService'
};

You may choose to help customers work around this bug by creating a global script include to proxy your scoped
app messages to the broadcaster. This global script include can only be included into your scoped app if you are
NOT publishing it on the ServiceNow Store, but delivering it directly to your customers.
If you are publishing your scoped app to the ServiceNow Store then you will need to provide a different
mechanism to deliver this update to your customers which is external to your app. Please work with the store
certification team and your customers on providing this global update outside of the ServiceNow Store publication
process.



Global Script Include

<sys_script_include action="INSERT_OR_UPDATE">
<access>public</access>
<active>true</active>
<api_name>global.GlideLiveMessageBroadcasterWrapper</api_name>
<client_callable>false</client_callable>
<description/>
<name>GlideLiveMessageBroadcasterWrapper</name>
<script>
<![CDATA[
var GlideLiveMessageBroadcasterWrapper = Class.create();
GlideLiveMessageBroadcasterWrapper.prototype = { initialize: function() { },
broadcastFromRecord: function(messageGR) { new
GlideLiveMessageBroadcaster().broadcastFromRecord(messageGR); }, type:
'GlideLiveMessageBroadcasterWrapper' };
]]>
</script>
<sys_class_name>sys_script_include</sys_class_name>
<sys_created_by>admin</sys_created_by>
<sys_created_on>2017-06-02 21:33:27</sys_created_on>
<sys_id>0da5ff2260473200964fb10ba92a5552</sys_id>
<sys_mod_count>1</sys_mod_count>
<sys_name>GlideLiveMessageBroadcasterWrapper</sys_name>
<sys_package display_value="Global" source="global">global</sys_package>
<sys_policy/>
<sys_scope display_value="Global">global</sys_scope>
<sys_update_name>sys_script_include_0da5ff2260473200964fb10ba92a5552</sys_update_name>
<sys_updated_by>admin</sys_updated_by>
<sys_updated_on>2017-06-02 21:35:18</sys_updated_on>
</sys_script_include>

Usage
Use the following code to call the above script include. In the Chat Entry Point code, simply replace the
“sendMessage: function(groupId, message, fromProfileId)” function with this function:
sendMessage: function(groupId, message, fromProfileId) {
var msg = new GlideRecord('live_message');
msg.initialize();
msg.message = message;
msg.group = groupId;
msg.chat_message = true;
msg.profile = fromProfileId;
msg.insert();
new global.GlideLiveMessageBroadcasterWrapper().broadcastFromRecord(msg);
}



©2013 ServiceNow, Inc. All rights reserved.

ServiceNow believes information in this publication is accurate as of its publication date. This publication
could include technical inaccuracies or typographical errors. The information is subject to change without
notice. Changes are periodically added to the information herein; these changes will be incorporated in new
additions of the publication. ServiceNow may make improvements and/or changes in the product(s) and/or
the program(s) described in this publication at any time. Reproduction of this publication without prior
written permission is forbidden. The information in this publication is provided “as is”. ServiceNow makes no
representations or warranties of any kind, with respect to the information in this publication, and specifically
disclaims implied warranties of merchantability or fitness for a particular purpose.

ServiceNow is a trademark of ServiceNow, Inc. All other brands, products, service names, trademarks or
registered trademarks are used to identify the products or services of their respective owners.



SN-Conversation Service Whitepaper V PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SN-Conversation Service Whitepaper V PDF

Uploaded by

Copyright:

Available Formats

ServiceNow

Integration with IBM

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

IBM Bluemix Account

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Create a Watson REST Message

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Create a Bot User

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Scoped App Design Considerations

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

High Level Architecture Diagram

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Does not hold onto client thread

Better overall instance health and Potential negative virtual agent

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Holds client thread semaphore for the

Potential to make the instance run slow

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Connecting Watson Dialogs to ServiceNow Actions

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Column Data Type Length

Live Group Profile Reference [live_group_profile] n/a

Context String 4,000

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

var liveFeedMessage = new global.LiveFeedMessage();

var useRedirect = false;

var endUserProfileId = this.getLiveProfileId(gs.getUserID()); // Profile Id of

var userGR = new GlideRecord('sys_user');

var lgpId = this.getLiveGroupProfileId(botUserName);

// create user in group(if not already there)

// Create bot member in group (if not already there)

// force open the frame state for the user

// Send a welcome message to the user

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

Global Script Include

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

©2013 ServiceNow, Inc. All rights reserved.

ServiceNow Integration with IBM Watson Conversation Service-Whitepaper

You might also like