In this tutorial, we’ll learn how to create an SAP Analytics Cloud chatbot with SAP Conversational AI, and SAP Analytics Cloud (SAC) Custom Widget.
The goal of this tutorial is to enable the users to interact and add the chatbot interface in SAP Analytics Cloud (SAC), Analytics Application. The bot will reply with the answer by updating the Analytics Application UI elements like a chart, widget, table, etc. For our case, we’ll design the bot to update the table based on the user’s question.
Here, figure 1 shows the bot architecture flow diagram.
The Custom Widget in SAC Analytics Application connects to the Bot server and gets the unique chat ID (or socket ID). The chat ID will be shown in the UI5 dialog box. A user will enter the chat ID in order to start the conversation. The chat ID is a unique identifier and acts like a password. If the user starts chatting without the chat ID, the Bot server will reply with “Please enter the chat ID”.
The Bot intents and entities are built with SAP Conversational AI. If the user says the intent that matches the question, it will call a WebHook (HTTP call to external service) to communicates with the Bot server. The Bot server will retrieve and parse the information from the WebHook body which provides the conversation states. If the information related to the questions is confirmed, the Bot server will reply to the user with “Here is the information”.
And then it sends the parsed data to Custom Widget via a Web Socket connection. The Custom Widget will listen to incoming data, process it, and triggers the custom event to update the table (or other UI elements) in SAC, Analytics Application via scripting.
There are four components we’ll build:
- Step 1 – SAP Analytics Cloud Custom Widget
- Step 2 – SAP Conversational AI Bot Building
We will build intents and entities and connect to the Bot server via a WebHook.
- Step 3 – Bot Server
The Bot server is written in NodeJS that exposed to SAP CONVERSATIONAL AI via a WebHook connection. It uses Socket.IO to have bi-directional communication between Bot server and Custom Widget.
- Step 4 – SAP Analytics Cloud, Analytics Application
We will create a simple table based on the Best Run Juice model and add scripting to listen to the custom event to update the UI element like a table, chart, etc.
Step 1 – SAP Analytics Cloud Custom Widget
The SAC Custom Widget comprises of the following files:
- SAP Conversational AI.json
The JSON file that defines the Custom Widget with id, name, web components, properties, methods, and events objects.
- SAP Conversational AI.js
Implements the custom element of the Custom Widget (Web Component).
- aps_SAP Conversational AI.js
Implements the custom element of the Styling Panel of the Custom Widget.
A Socket.IO client that always connected to the Bot server.
Socket client listens for a ‘connect’ and ‘disconnect’ event and it will update the SAPUI5 suite.ui.commons.MicroProcessFlow element with the chat ID information. If the connection is established, you will get the green icon with a random chat ID as shown below.
If the connection is broken, you will get the error message as shown below.
The below code shows the ‘connect’ and ‘disconnect’ event and calls the UI5() function to create the UI5 MicroProcessFlow dialog box above.
It also listens for the ‘req’ event to receive data from the Bot Server. The data consists of the parsed information from the user’s question. And then triggers the custom event onStart() to execute the SAC Analytics Application scripts.
The SAP Conversational AI Web Chat.
The SAP Conversational AI Web Chat creates the webchat dialog. The value of data-channel-id, data-token, data-expander-preferences for the Web Chat is obtained from the Styling Panel in SAC Analytics Application.
1.2 Styling Panel
The user can set property values of the custom widget in Custom Widget Additional Properties under the Styling tab of the Designer panel.
The custom widget properties in the Styling Panel lets you enter the following properties:
- Socket URL
The address of the Bot Server with port 3000: http://<BOT_SERVER_IP_ADDRESS>:3000.
- Channel ID
Channel ID uniquely identifies the channel your bot is connected to.
Token ID uniquely identifies the channel your bot is connected to.
Object containing some settings.
You can find Channel ID and Token ID when creating a webchat channel in the Bot Connector which we’ll discuss later.
The following code creates a template HTML element that lets the user enter the Socket URL, Channel ID, Token, and Preferences.
The setter functions place a text representation of the new value of the respective item (i.e., SocketURL) into the input field of the Styling Panel. The getter function returns the text of the input field of the respective item of the Styling Panel.
Step 2 – SAP Conversational AI Bot Development
We’ll start by building the intents and entities in SAP Conversational AI. Logon to https://cai.tools.sap/ and create a new bot.
2.1 Create Intents
Create intents called getstarted, uid and question.
Select @getstarted intent and add an expression “Start the conversation”. This intent lets the user start a conversation with the bot. An expression is a sentence that your bot can understand.
Select @question intent and add an expression as shown in the screenshot below. This intent lets the bot understand the user’s question.
2.2 Create Entities
An entity is a keyword that is extracted from an expression.
Create entities DATE, GETSTART, PRODUCTCATEGORY, PRODUCTNAME, SESSIONID, UID as shown below.
Select entity #DATE and add entity values as shown below.
Select entity #GETSTART and add value “start the conversation” as shown below.
Select entity #PRODUCTCATEGORY and add values “alcohol”, “carbonated drinks”, “energy drinks” and “juices” as shown below.
Select entity #PRODUCTNAME and add values “apple juice”, “dark beer”, “ginger ale”, “low-calorie beer”, “mango juice”, “mixed drinks”, “monster” and “orange crush” as shown below.
Select entity #SESSIONID and add random string values as shown below.
Select entity #UID and add value “chat id” as shown below.
2.3 Build Skill
Go to the Build tab and select greetings.
Select Triggers and add the trigger conditions as shown below.
Select Actions tab and click Add New Message Group. Set the condition for @uid, @question, @getstarted. For each condition, connect to a WebHook URL of the Bot server. You can use Ngrok or other HTTP calls for the WebHook.
If you are using Ngrok, type this command: ngrok http 3000 and copy the HTTPS Forwarding URL into the Webhook Configuration in SAP Conversational AI.
Select Connect tab and click SAP Conversational AI Web Client.
Click New SAP Conversational AI Web Client, fill in the information and click Create.
Make a note of the data-channel-id, data-token, and preferences. We will insert this information in the Styling Panel custom widget.
Step 3 – Bot Server
We will be using Socket.IO to facilitate real-time connection between Bot server and clients which are the custom widgets. Every time the widget (client) is connected to the Bot server, it receives the unique session ID, which is a unique identifier for the Bot server to differentiate each client.
Bot server is a chatbot engine that comprises of the following logics:
- It always checks for the user’s session ID or chat ID. The chat ID is like a password for the user to start the conversation. If there is no chat ID, the bot will reply with “Please enter the chat ID”.
- Once the bot server gets the chat ID from the client, it knows which client it is connected to and then saves the chat ID in its memory.
If the question intents are available and the Bot holds the memory of the client, it will parse the data from the intents and send the data to the respective client (Custom Widget) via a web socket connection.
We need to change the variables mentioned in the below screenshot. See below bullet items on how to get the information.
Click Settings and under Bot Settings click Tokens to get token from Developer token and botSlug from Your user slug. The botSlug is your bot’s name (for my case is SAP Conversational AI-3).
Run the Bot Server with command node server.js
Step 4 – SAP Analytics Cloud, Analytics Application
Now is time to write a script in Analytics Application to process the incoming data from the Custom Widget’s event and update the table.
- Create Analytics Application and add the Custom Widget that we had created earlier.
- Insert a table for the Best Run model.
Right-click on the Custom Widget. Insert the following code in onStart() function and save it.
Step 5 – Usage
We have built and set up all the required components and now it’s time to run and test the bot!
- Make sure you the Bot Server is up and running.
- Make sure you have configured the WebHook setting in SAP Conversational AI and it is connected to the Bot Server.
- Make sure you have deployed the Custom Widget and added the script in SAC Analytics Application.
- Fill in the properties of Socket URL, Channel ID, Token, and Preferences in the Styling Panel. Click Run Analytics Application.
- Check if the Custom Widget is connected to the Bot Server. The SAPUI5 icon status shows a green status with the chat ID. Copy that chat Id.
- Click “Click on me” and enter/paste the chat Id.
- Click Let’s get started.
Reply with the question:
“show me date 201309 with product category name Carbonated Drinks, product name Orange Crush, sales manager name Nancy Miller and state name California” or
“show me date 201307 with product category name Alcohol, product name Low Calorie Beer, sales manager name John Minker and state name California”.
If there is no error, the table will be updated with the relevant information as per the user’s question.
Congratulations, we’ve built a chatbot with SAP Conversational AI connected to SAP Analytics Cloud able to update the UI elements of the Analytics Application!
- Build a Custom Widget in SAP Analytics Cloud, Analytics Application