Actuate Bot Features within SharePoint Framework

Published: Jun 23, 2020

Table of Content

  1. What is a bot?
  2. About the Bot Framework
  3. Bot Framework SDKs and tools
  4. Create your bot
  5. Register Bot on Microsoft Bot Framework & Publish Bot in Azure Web App
  6. Enable Bot within SPFx
  7. Conclusion

What is a bot?

A bot is an app through which users collaborate in a conversational manner. Bots can colloquial communicate with text, cards or speech. A bot might be as basic as a fundamental example coordinating with a reaction, or it might be a modern weaving of artificial intelligence methods with complex chatty state following and reconciliation to existing business services.

About the Bot Framework

The Bot Framework is a platform for building, connecting, testing, and deploying powerful and intelligent bots.

This Framework empowers you to fabricate bots that help various sorts of interactivities with clients. You can plan discussions in your bot to be freestyle. Your bot can likewise have increasingly guided interactivities where it gives the client decisions or actions. The conversation can utilize straightforward text strings or progressively complex rich cards that contain text, pictures, and activity buttons. You can include natural language associations that let your users collaborate with your bots in a common and expressive manner.

Our Sharepoint development team presents an example of a bot that schedules salon appointments. The bot understands the user’s intent, presents appointment options using action buttons, displays the user’s selection when they tap an appointment, and then sends a thumbnail card that contains the appointment’s specifics.

salon bot example

In the digital experiences, the Bots are quickly turning into its fundamental part. They are becoming as essential as a website or a mobile experience for users to interact with a service or application.

Bot Framework SDKs and tools

The Bot Builder SDKs provide libraries, samples, and tools to help you build and debug bots. To get started building bots, we need to download the SDK for the platform we are using, C# on .NET

Get the Bot Builder SDK for .NET

The Bot Builder SDK for .NET leverages C# to provide a familiar way for .NET developers to write bots. It is a ground-breaking framework for building bots that can deal with both freestyle interactivities and progressively guided conversations where the user chooses from potential qualities.

For creating bots using Visual Studio and Windows, the Bot Builder SDK for .NET is a simple to-utilize framework.

Let’s walks through building a bot by using the Bot Application template and the Bot Builder SDK for .NET, and then testing it with the Bot Framework Emulator.

Prerequisites

  1. For Windows, install Visual Studio 2017.
  2. In Visual Studio, update all extensions to their most recent versions.
  3. Download the below mentioned zip files from the mentioned links in brackets:
  4. In your Visual Studio 2017 project templates directory, copy the Bot Application.zip to install the project template.
  5. In your Visual Studio 2017 item templates directory, copy the Bot Controller.zip and Bot Dialog.zip files to install the item templates.

The template directory is typically located at %USERPROFILE%\Documents\Visual Studio 2017\Templates\ItemTemplates\Visual C#\

Note: For Bot Framework v4 SDK Templates for Visual Studio, refer http://aka.ms/bf-bc-vstemplate link.

Create your bot

  1. Open Visual Studio with Run as Administrator option → create a new C# project.
  2. Pick the Bot Application template for the new project.
  3. You’re creating a project which contains all the required components for building a simple bot by including a reference to the Bot Builder SDK for .NET which is included in Microsoft.Bot.Builder NuGet package with consumption of the Bot Application template. You need to take care that the project references must be the most recent version of the SDK.
  4. From Solution Explorer → right-click the project name → select Manage NuGet Packages.
  5. On the Browse tab, type “Microsoft.Bot.Builder” into the search box.
  6. From the searched result, locate the Microsoft.Bot.Builder package and click the Update button for it.
  7. To acknowledge the changes and update the package, you are required to follow the screens.

Without writing an extra code, your project contains the entirety of the code which is inevitable for making a bot and all this is possible just because of the Bot Application template.

Explore the code

Initially, the user message is served by the Post method within Controllers\MessagesController.cs and this method summons the root dialog.

The received message is processed and its response is also generated by the root dialog. The Dialogs\RootDialog.cs → MessageReceivedAsync method sends an answer that echoes back a message in the specified format.

Echoed Message Format: You sent @@ which was $$ characters, where @@ signifies the user’s message and $$ represents the number of characters in the user’s message.

For Example:

User’s Message: Hello World

Echoed Message: You sent Hello World which was 11 characters

Test your bot

By utilizing the Bot Framework Emulator, test your bot in it and see its action. This desktop application allows to test and debug the bots via a tunnel either locally or remotely. You can chat with your bot and examine the sent & received messages through the emulator.

Download and install this emulator from link – https://github.com/Microsoft/BotFramework-Emulator/releases/tag/v3.5.31

Start your bot

After installing the emulator, start your bot in Visual Studio by using a browser as the application host. This Visual Studio screenshot shows that the bot will launch in Google Chrome when the run button is clicked.

By hitting the run button, Visual Studio will execute the below processes step by step:

  1. Build the application
  2. Deploy the application
  3. To display the application’s default.htm page, it launches the web browser

For example, here’s the application’s default.htm page shown in Google Chrome:

Note: You can modify the default.htm file within your project to specify the name and description of your bot application.

Start the emulator and connect your bot

At this point, your bot is running locally. Now by starting the emulator, connect your bot in the emulator:

  1. Type below URL into the address bar
  2. For now, click Connect by leaving blank Microsoft App ID and Microsoft App Password as these two fields are not required to specify. You’ll get this information later when you register your bot.

Note: In the example shown above, the application is running on port number 3979, so the emulator address would be set to: http://localhost:3979/api/messages.

Test your bot

Currently, your bot is locally running and connected to the emulator. Thus, give a try by typing few messages in the emulator to test your bot.

You will observe that your bot provides responses to each of your messages and echoed back to your message.

Echoed Message Format: You sent @@ which was $$ characters, where @@ signifies the user’s message and $$ represents the number of characters in the user’s message.

For Example:

User’s Message: Hello World

Echoed Message: You sent Hello World which was 11 characters

Note: In the emulator, click on any speech bubble in your conversation. Details about the message will appear in the Details pane, in JSON format.

You’ve successfully created a bot by using the Bot Application template Bot Builder SDK for .NET.

Register Bot on Microsoft Bot Framework & Publish Bot in Azure Web App

The second step towards activating Bot features within SharePoint framework application is having a web application in Azure.

You must have a Microsoft Azure subscription before you can use the Azure Bot Service.

Setting up web app with the Azure Bot Service

The Azure Bot Service accelerates the process of developing a bot by providing an integrated environment that is purpose-built for bot development. This walks you through the process of creating and testing a bot by using the Azure Bot Service.

Azure Bot Service enables rapid intelligent bot development powered by Microsoft Bot Framework, and run in a server-less environment.

Create your web app

To create a web app by using the Azure, sign in to Azure and complete the following steps.

Create a new web app

  1. Select New in the menu blade.
  2. In the New blade, navigate to the Web + Mobile category, and select Create below Web App.
  3. Provide the required requested information in the Web App blade to create the web application.
    • Set your web app’s name as App name and this name will be consumed as the subdomain when your bot is deployed to the cloud (For example: tatvabot.azurewebsites.net).
    • Select the subscription to use.
    • Select the resource group and location.
    • Select Pin to dashboard and click Create.
  4. From the top edge of the Azure portal, click a bell icon – Notifications. The notification changes from Deployment started to Deployment succeeded that means the Web App has been deployed successfully.
Azure notification

Once the Web App is created, a tile will appear on your dashboard. Click it to access your application.

After clicking, you will be taken to the Overview of your Web App. Check whether the URL for the web app is working by running it in a different tab.

Hitting the URL of the Web App, below screen will be displayed. Note down the URL for web app.

So, the Web App URL for the message endpoint input will now be https://tatvabot.azurewebsites.net/api/messages

Note: Make sure you are using the secure URL link for your message endpoint i.e. https.

Register your Bot

To register your bot, simply go to https://dev.botframework.com/ and click on My bots and then Register.

Fill out the Bot Registration form and use your Web App URL https://tatvabot.azurewebsites.net/api/messages/ for the Messaging endpoint input under Configuration.

Create App ID and password

Create an app ID and password for your bot so, it will be able to authenticate with the Bot Framework.

  1. Click Create Microsoft App ID and password in Register your bot with Microsoft to generate a new App ID and password under Configuration.

    Copy the App ID.
  2. After copying the App ID, hit Generate an app password to continue button to generate App Password.
  3. Copy and securely store the password that is shown, and then click Ok.
    Note: This is the only time when password will be displayed. Please store it securely and paste it into your bot configuration file.
  4. Once App ID and Password have been generated, click Finish and go back to Bot Framework.
  5. Confirm that the App ID in Paste your app ID below to continue is same as the one you copied.
  6. Finally, check I agree to the Terms of Use, Privacy Statement, and Code of Conduct for the Microsoft Bot Framework (Preview) and click Register.

A dialog saying Bot created appears. Click OK. At this point, the bot has been created, registered with the Bot Framework, deployed to the cloud, and is fully functional.

If you sign in to the Bot Framework Portal, you’ll see that your bot is now listed under My bots. Congratulations! You’ve successfully created a bot by using the Azure Bot Service! You should be taken to a dashboard for your bot.

By having Bot IDMicrosoft App ID and Microsoft App Password, you can consume them inside your Bot application which was created earlier.

Linking your code to the Registered Bot

Now that your bot is running in the cloud, try it out by typing a few messages into the built-in chat control that’s located to the right on your dashboard. Hit Test. It should fail.

This happens because your code does not have the ID and Password Authentication codes.

Inside the Bot Application you created earlier, in your Web.config file, copy and paste your Bot Handle in the slot for BotIdApp ID into the value slot for MicrosoftAppId, and the same for the MicrosoftAppPassword you obtained when you registered your bot.

Publish you application to Azure. Select Publish after doing right click on the project.

On the Publish page, select Microsoft Azure App Service and choose Select Existing. Click Publish.

On the App Service page to host your web application in Azure, select your Azure web app service tatvabot and click OK.

Publish is succeeded and it will be redirected to https://tatvabot.azurewebsites.net.

This indicates that your Bot Application is successfully hosted in the Azure.

We need to consume this API within our Bot Framework. Again, try it out by typing a few messages into the built-in chat control that’s located to the right on your dashboard. Hit Test. Type some message and if we get a reply, we are sure that the web application is properly hosted and it works. If sending message fails, we have got some error while hosting the web app.

The Bot responds to each of your messages in below echoing message format.

Echoed Message Format: You sent @@ which was $$ characters, where @@ signifies the user’s message and $$ represents the number of characters in the user’s message.

For Example:

User’s Message: Hello World

Echoed Message: You sent Hello World which was 11 characters

From there, you can add multiple channels that your bot can communicate through. The Skype and Web Channels are turned on by default, so you can get started with those two first.

Here, you registered and published a simple bot by using the Azure Bot Service and verified the bot’s functionality by using the built-in chat control within Bot Framework Portal. You can also configure your bot to run on one or more channels and publish your bot, without ever leaving the Azure portal.

Enable Bot within SPFx

This is the final step towards enabling Bot features within SharePoint framework.

  1. Generate SharePoint framework application. In Windows Powershell, execute commands as shown below.
  • Select @microsoft\sharepoint
  • It will open SharePoint client-side Solution Generator and provide values as mentioned below:
  1. What is your solution name? = tatvabotApp
  2. Where do you want to place the files? = Create a subfolder with solution name
  3. Do you want to allow tenant admin……adding apps in sites? = Yes
  4. Which type of client-side component to create? = WebPart
  5. What is your WebPart name? = tatvaBot
  6. What is your WebPart description? = tatvaBot description
  7. Which framework would you like to use? = No Javascript framework
  • The solution is successfully created.
  • Open our newly generated web part in Visual Studio code.
  • To integrate Bot Framework web chat with SharePoint framework, perform below steps:
  • Open TatvaBotWebPart.ts file in Visual Studio code.
  • Under Connect to channelsEdit the Web Chat channel to fetch the secret key and iframe.
  • Under Default Site, Copy the code under Embed code.
  • Move to our SharePoint framework app and replace the code what we have by default in innerHTML with the iframe code we copied.
iframe code
  • To fetch the secret key, navigate to your Bot Framework app and under Default Site, click Show to view the secret key.
  • Copy the secret key.
  • Paste the secret key in our code where it has YOUR_SECRET_HERE and save the file.
  • In Windows PowerShell, navigate to the path where the web part is located and run gulp serve command.
  • It will open default SharePoint workbench where we develop our SharePoint framework applications.
  • Select tatvaBot web part which will be visible after clicking on the + symbol.
  • It will show the Web Chat we integrated and implemented in Azure.
  • Test your bot by typing a few messages in the chat and it will revert back to your messages in below message format.

Message Format: You sent @@ which was $$ characters, where @@ signifies the user’s message and $$ represents the number of characters in the user’s message.

  • To view the full chat, change the size of the iFrame and then you can see the full chat.

This is how we integrate our SharePoint framework with Bot framework.

Conclusion

Through this blog, you get the basic ideas about the integration of the Bot Framework into the SharePoint Framework. Create your own Bot Framework which serves your requirement. With use of the SharePoint Framework, place that Bot inside your SharePoint Office 365 to entertain the needs of your end-users.

Comments

  • Leave a message...

Related Articles

An Introduction to key aspects of Internet of Things (IoT)

Oct 21, 2020

TransactionScope in C#

Oct 9, 2020

Financial Information Exchange Protocol

Oct 6, 2020