Introduction
For a while now it’s been popular to add chat-bots to websites with the purpose of providing quick and automatic answers to the visitors’ questions. So much so that SAP has got its own bot building platform with machine learning capabilities – SAP Conversational AI (CAI for short). Suppose you’re an active user of SAP Conversational AI and you developed a CAI chat-bot that’s able, for example, to interpret and answer users’ questions based on a FAQ using NLP. And now you’d like to add that chat-bot to your SharePoint site so it can swiftly assist your users. Since SharePoint is a part of the Microsoft’s ecosystem, a chat-bot built with CAI could be added with the tools of Microsoft Azure using its Bot Channels Registration resource. The downside of this approach is the requirement of having an Azure account and sometimes it can be a bit problematic.
Hence, this summer I ended up developing an alternative solution – a custom client-based SharePoint Online web part. It doesn’t require any intermediaries for embedding CAI chat-bots into a SharePoint page, as it attaches the chat-bot’s script directly to a page’s HTML body itself. This web part is developed as an open-source project and its code is available on Github as a SAP Sample. Therefore, the main focus of this blog post is to showcase this web part, describe its implementation step-by-step for any potential users, as well as to summarize it from the technical point of view for any SPO developers.
Quick Start
First, we’ll swiftly go over several prerequisite steps:
- Check your SPO permissions. You should check whether you’ve got the necessary rights in order to add and manage external web parts on your SharePoint site. You should be able to access the site’s app catalog located in
https://sharepoint.com/sites/<YOUR SITE ID>/AppCatalog
In case you can’t access it, contact your SharePoint administrator and request the access. The process of creating and working with an app catalog is outlined here, and you can read more about requesting the required permissions here. The webpage should look approximately like this:
- Create a primary connection channel for your chat-bot. Open your chat-bot’s repository on SAP Conversational AI and go to the “Connect” tab (see screenshot below). Choose a primary channel of your liking (the web part can connect via any primary channel), set its properties and theming in the dialog window and hit “Create”.
CAI then should generate the script for embedding (see example on the screenshot); copy it somewhere or just leave the tab open.
If these prerequisites are complete, you can now get the web part itself, add it to your SharePoint site and connect it to your CAI chat-bot by checking out the following steps:
- Download the web part. Go to the Releases page of the web part’s Github repository, find the latest version (the first one in the list) and download the cai-chatbot.sppkg file from the drop-down “Assets” menu.
- Load it to SharePoint. Once the file is saved, open your site’s app catalog, click the “Upload” button and browse to the .sppkg file (see screenshot). The “CAI Chatbot” web part should now be successfully loaded.
- Add it to a page. You can now go to your site’s page and add the loaded web part by clicking “Edit” and selecting “CAI Chatbot” from the list of web parts (note that as it’s a custom web part, it’s usually at the very end of the list) anywhere on the page. It should display the web part’s placeholder with the web part’s name and description, as well as the “Configure” button.
- Connect your CAI chat-bot. Hit the “Configure” button to open the configuration panel. It consists of a drop-down menu where you can select the chat-bot’s connection channel, and of several input fields for the chat-bot’s attributes (like token and channel ID). Specify the connection channel and then copy and paste the attributes’ values from the script for embedding (the one from step 2 of the prerequisites) to the respective input fields.
- Save the changes. Now you can close the panel and hit the “Publish” button. The CAI chat-bot should then appear in the bottom right corner of the page and it should also stay there while scrolling. You may now continue developing and customizing your chat-bot on the CAI platform – all changes will be applied to the SharePoint site automatically via the connection channel. You may also change the channel’s settings anytime by clicking “Edit” on the page and hitting the “Configure” button.
Feel free to check out this Demo GIF of going through steps 3-5 for both primary channels.
If you encountered any difficulties while following the aforementioned steps, please feel free to ask for assistance in the comments below.
Technical Overview
This web part is written in TypeScript using SharePoint framework (SPFx), as well as React class components. As of the time of writing, the latest Node.js version required by SPFx is LTS v14. Please refer to the SPFx requirements page to check the current latest supported version of Node.js. It’s worth mentioning that the project’s README addresses the possible workaround using Node Version Manager (nvm). The Gulp toolkit is also required in order to generate the SharePoint package file manually, but it’s already included in the project’s "package.json" file. In case you’d like to try it and tweak it for yourself, you are welcome to follow instructions provided in the repository’s README file. In this section I’m going to briefly summarize how this web part works, its current features, and talk about possible improvements.
As has already been mentioned in the Introduction section, it works by generating its own script tag with a chat-bot’s attributes and values and then appending the tag to the target page’s HTML body. That being said, our web part has two modes: the “edit” mode where the configuration panel pops out and a user sets the required attributes, and the “normal” mode where these attributes populate the attached script tag.
For the first mode we render the panel element using React, and we also make use of React’s states in order to populate the component with values if any of them were already set. As you could have noticed in the demo, we require user’s input only for the token and channel ID values (and the expander preferences one, when the channel’s set to “SAP Conversational AI Web Client”). That’s because the rest of the attributes can be derived automatically based on the channel. Here’s a code snippet of generating the panel:
/**
* Populate the channel drop-down menu with available channel options.
* @returns A Promise for the completion of parsing the options.
*/
private loadChannelOptions(): Promise<IPropertyPaneDropdownOption[]> {
return new Promise<IPropertyPaneDropdownOption[]>((resolve: (options: IPropertyPaneDropdownOption[]) => void) => {
resolve([
{
key: 'webchat',
text: constants.channelOptionsWebchat,
},
{
key: 'webClient',
text: constants.channelOptionsWebClient,
},
]);
});
}
/**
* Render the config panel as well as the web part's placeholder.
*/
private async showPanel(): Promise<void> {
const configPanel = await import('./components/chatbot');
const element: React.ReactElement<ChatbotPropsStorage> = React.createElement(configPanel.default, {
channel: this.properties.channel,
channelId: this.properties.channelId,
token: this.properties.token,
expanderPreferences: this.properties.expanderPreferences,
propPaneHandle: this.context.propertyPane,
key: 'pnp' + new Date().getTime(),
});
ReactDom.render(element, this.domElement);
}
/**
* Generate the configuration panel's layout.
* @returns A configuration object interface
* (see reference: https://docs.microsoft.com/en-us/javascript/api/sp-property-pane/ipropertypaneconfiguration).
*/
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
const options: IPropertyPaneField<object>[] = [
PropertyPaneDropdown('channel', {
label: strings.propertyPaneSelect,
options: this.channels,
selectedKey: 'webchat',
}),
PropertyPaneTextField('channelId', {
label: strings.propertyPaneChannelId,
value: this.properties.channelId,
}),
PropertyPaneTextField('token', {
label: strings.propertyPaneToken,
value: this.properties.token,
}),
];
// Add an extra option for the 'expanderPreferences' attribute
if (this.properties.channel === 'webClient') {
const epOption = PropertyPaneTextField('expanderPreferences', {
label: strings.propertyPaneEP,
value: this.properties.expanderPreferences,
});
options.push(epOption);
}
// Append the footer
options.push(new ChatbotPropertyPane());
return {
pages: [
{
header: {
description: strings.propertyPaneDescription,
},
groups: [
{
groupFields: options,
},
],
},
],
};
}As for the other mode, it’s pretty self-explanatory – we create a new script tag, populate it with a chat-bot’s attributes based on the channel name and append it to the body. Here’s another code snippet that illustrates that:
/**
* Add the chatbot itself on a page via a <script> tag.
* Use different attributes based on the selected channel.
*/
private embedChatbot(): void {
const scriptTag = document.createElement('script');
scriptTag.type = constants.sTagType;
if (this.properties.channel === 'webClient') {
// If the 'SAP CAI Web Client' channel is chosen
scriptTag.src = constants.sTagWebClientSrc;
scriptTag.id = constants.sTagWebClientId;
scriptTag.setAttribute(constants.sTagWebclientAttrChannelId, this.properties.channelId);
scriptTag.setAttribute(constants.sTagWebclientAttrToken, this.properties.token);
scriptTag.setAttribute(constants.sTagWebclientAttrEP, this.properties.expanderPreferences);
scriptTag.setAttribute(constants.sTagWebclientAttrET, constants.sTagWebClientET);
} else {
// If the 'Webchat' channel is chosen
scriptTag.src = constants.sTagWebchatSrc;
scriptTag.id = constants.sTagWebchatId;
scriptTag.setAttribute(constants.sTagWebchatAttrChannelId, this.properties.channelId);
scriptTag.setAttribute(constants.sTagWebchatAttrToken, this.properties.token);
}
document.body.appendChild(scriptTag);
}Because the attributes’ names are fixed, we can store it as constants. Also, here you can see that the channel-based attributes like the chat-bot’s source URL and the ID for CSS are also fixed and are loaded as constants, too.
After cloning the repository and installing the required packages you can test the web part locally by running
npm run servePlease note, however, that the integrated chat-bot doesn’t show up while running locally; this test is only for checking the behavior of the web part itself. It is worth mentioning that the web part has been fully localized both in English and in Russian – the Russian localization can be checked by running the "serve-ru" package command that passes the appropriate "--lang" flag:
npm run serve-ruLastly, there’s a single package script that automates Gulp’s build, bundle and package operations:
npm run releaseAfter running this command, the resulting package file named “cai-chatbot.sppkg” should be created inside the newly generated "sharepoint\solution\" folder.
This is a relatively simple and little project, but I still tried to document the entire code-base using JSDoc-like comments, so you’re very welcome to browse the code and suggest improvements. One possible improvement I’m thinking on is rewriting everything on React’s functional components in opposite to the class ones. Granted, it won’t really change the UI and UX, but it will update the code to the more modern React development standards. You might have noticed that CAI also generates an optional meta-tag for its chat-bot widgets in order to properly display it on the mobile devices’ screens. I didn’t include it in the web part, since we didn’t require such feature so far. It’s also worth mentioning that as I’m writing this post, SAP Conversational AI launches new primary channel specifically designed to bring its chat-bots to iOS – the SAP Conversational AI Mobile SDK channel. But if you’d like to have the option of activating the meta-tag in the web part (say, via a check mark), please consider sending a pull request or creating an issue.
In Conclusion
In this blog post I’ve shared an alternative solution for integrating SAP Conversational AI chat-bots with websites based on SharePoint Online. It has its share of pros and cons comparing to using Microsoft Azure. The main pro being the removal of Azure as a requirement, and the main con being spending a bit more time managing permissions and configuring the settings (it also requires you to have some basic knowledge of web parts). Hopefully, someone will find this method useful or at least will have a better picture regarding the SharePoint web parts.
Once again, this is an open-source project that's available on SAP Samples Github repository under the Apache Software License, version 2.0, and you’re welcome to contribute if you’ve got any ideas on how to improve it. Any comments, feedback and/or pull requests will be greatly appreciated!
- SAP Managed Tags:
2 Comments
