Tutorial 3: Browsing and Searching your CapacityDB Data in a Guided Conversation
CapacityDB is a Capacity-hosted database that can conveniently and seamlessly integrate with the full Capacity tech stack and our customers’ mission-critical applications. Through an engaging and intuitive interface, even novice users will be able to create, update, and take action on useful data sets.
If you have any questions, contact support@capacity.com.
Introduction
In the previous tutorials, you first created a CapacityDB schema, populated a table with data, and wrote queries to read from and write to it. In this article, you’ll create a Guided Conversation - the template and flow for your interactions with a concierge.
1. Set Up Your Conversation
First, navigate to your KB. At this point, you might have multiple knowledge bases, with several folders and files. If not, you’ll see an empty screen ready for new knowledge!
The first thing you’ll want to do is create a folder to house your widget work. So select “Add” in the top right corner, and add a folder. Name it “Widgets” and click “Create”.
Inside the Widgets folder, you can create more folders, dialogues, and even upload files like PDF spec sheets for your widgets.
Click “Add” and and then pick “Create Dialogue” to get started with your Guided Conversation.
We’ll be creating a conversation that will connect to your CapacityDB data to allow users to browse, search, and add widgets. So name the Dialogue “Manage Widgets”.
A dialogue can consist of several different exchanges, each with a triggering inquiry and response flow. Click “Add exchange” to get started.
You could create several exchanges: one for searching, another for browsing, and a third for creating a widget. In fact, that would give you an advantage to decipher more complex asks from the user with natural language processing.
However, for the purpose of keeping this tutorial short, we’re just going to have one exchange for managing widgets. Note that on the left side, you can create inquiry variants. These are sample phrases that will kick off the conversation.
Add one, and type “manage widgets”. This exact phrase will kick off the conversation. Similar phrases will, too, as a result of Capacity’s AI engine.
Add a couple more variants that are similar. For the purposes of this tutorial, you won’t need to worry about what they are. But in reality, you’d want to add many possible phrases to give Capacity’s AI engine more hints to the user’s intent when user enters a phrase in the concierge.
After you’ve created a few inquiry variants, select the response type “Conversation” and start from scratch.
2. Create a Conversation for Browsing Widgets
Begin to edit the conversation. Note that it begins with a Multiple Paths card.
That’s an acceptable way to start a conversation, but first let’s make our concierge polite and extend the user a greeting. Click the plus button above the card, and you’ll see all of the types of cards available to you in the editor. The ones that can’t logically or functionally work at this point are grayed out.
Pick “Simple Message” and add a greeting to explain what the conversation will be about. Then, in the Multiple Paths agreement, add a question that will prompt the user to pick one of several options. For now, click “Path 1” and rename it to “Browse Widgets” and rename “Path 2” to “Search Widgets”. The paths will be options.
Disable text input for this example. Later, if you’d like, you could handle the user inputting text into the chat window rather than picking a path.
Your first path will handle the case where the user just wants to browse a list of widgets and their information. For large data sets, this wouldn’t make sense. The user would get overwhelmed with content in a chat window. However, we just have a few data points, so this will be fine for now.
Add another card by clicking the plus button, and note that the “App Action” card is not available. A tooltip explains why: you need to add an app to this conversation first.
Click the plus button in the top left, under available apps. If you followed previous steps in the tutorial, you’ll see the “Delmar Widgets” app that we created in a list. This app brings with it the actions (APIs, in this case) that can be performed in a Guided Conversation. Select it.
If you don’t see the app, be sure you’ve both published it and installed it, steps from the previous tutorial.
After the app is added to your Available Apps list, try again to create an App Action card. This time, you should be able to. Select it to add it to the conversation editor.
Pick “Get All Widgets” from the list of actions. And you’ll see the card populate with the output variables.
If you don’t see “Get All Widgets”, you may have not activated your APIs. Review the previous tutorial.
The App Action card is using the API call to execute the stored query that returns all widgets. Recall that the output “Rows” is a collection of widgets, with all associated information.
So, the next step will be to reply to the user with details of all found widgets. Add a Simple Message card with the first line “Here are all your widgets:”. Then, using the lightning bolt button, you’re able to access the widgets, with their information.
Click on “Rows” and you’ll see that the widgets will be presented in a list. You’ll notice that within each widget (item) of the list, represented by a white box, you can use variables that are the attributes of a widget.
Populate the Simple Message card, inside the item box, with the following format and variables. Small changes like spacing are fine for readability, but you’ll want to use all of the attributes of each widget - it’ll utilize all data points in your CapacityDB table!
Note that this tutorial assumes that there won’t be any errors returned by the database call, and at least one widget will be returned as a search result. In reality, this isn’t the case. You’ll want to create branching paths after your App Action call that will handle situations where the database has issues, all of the data has been deleted from the database, and so on. A future tutorial will touch upon best practices.
So you’ve now created an exchange, with a greeting, a choice, a database action, and a message reporting the results. Seems ready, right? Click “Publish” and notice that something is wrong. Click the error button to see that you’ve got an “Edge” without a “to_node”. What this means is that you have a branching path in your Guided Conversation without anything in it.
Scroll up and remember that you created the path for browsing widgets, but not the one for searching them. Notice the error message.
So, you’ll want to build the “Search Widgets” path next!
3. Extend the Conversation to Searching Widgets
The first thing we’ll need to add is a Collect Info card, for storing the user’s search term. Add it, with a prompt, and store the user’s reply as a variable, called “widget_name”. What this allows you to do is reference that value in subsequent steps in the conversation.
Next, add an App Action card, and select “Get Widget by Name”. Notice that this time, there’s an input for “name”.
If you don’t see the “name” input, it may be set as an optional (i.e., not required) input. If that’s the case, click “Add Optional Field” and select name.
Next, click the insert variable button, that looks like a lightning bolt, and select “widget_name”. This will use the user’s entry as the input to the search API, which queries your table to find widgets with matching names.
Continue as you did in the Browse Widgets path, by adding a simple message that will format matching widget information.
This tutorial assumes that there won’t be any errors returned by the database call, and at least one widget will be returned as a search result. In reality, this isn’t the case. You’ll want to create branching paths after your App Action call that will handle situations where the database has issues, all of the data has been deleted from the database, and so on. A future tutorial will touch upon best practices.
When you’ve added the proper information, click Publish and you should see a green checkmark and success message!
4. Connect the Conversation to a Concierge
Now, at this point you have a Guided Conversation, which is very useful, but only if chat users can actually trigger it! You’ll need to make it visible to at least one Content Group and accessible to a concierge. So, navigate back to the inquiry, click the eyeball icon, and make your selection.
Note that your concierge will need to be one that you can test. If it’s not set to the console’s default concierge in your org Settings (see the following image), or deployed to another interface, such as a webpage or Teams, you won’t be able to test your conversation!
5. Test the Conversation
When you’re ready, click the concierge, and send the message “manage widgets” in the chat window. You should be given options to browse and search. If so, you’re on the right track!
First try the browse. Click that, and you should see all your widgets in a list.
You’ll notice that prices are not presented in a familiar way. You have a few options for improving it. You could remove the currency code and add the dollar sign as a number. You could change “per” to a “/”, and so on.
For an added challenge, add some more data to your CapacityDB table, and change some existing values. When you navigate back to the chat window, your changes should immediately take effect.
Now, type “manage widgets” again, and this time, select “Search Widgets”. Because you’ve added a Collect Info card, you’ll be prompted for a widget name with which to search. Enter “Bracket”.
Sending the message to the concierge should return all matches in your database.
If you try a different term, or you don’t have a widget named “Bracket” in your database, you’ll experience a blank result list. That’s because we didn’t include a path in our Guided Conversation to handle a situation where no results are returned.
Congratulations! In this tutorial, you were able to build a very small, basic Guided Conversation that returned data from your CapacityDB widget table. Any changes you make to that table will be reflected in real-time! So feel free to experiment by adding new widgets to your database.