By Frank Nimphius
My personal definition for chatbots is that they are front-end intelligent systems that use artificial intelligence and machine learning to understand what a user wants and to gather all information required to complete a task. For this, the bot needs to engage in a dialog with the user, for which Oracle Intelligent Bots uses built-in components to render bot responses and to request user input.
Where there is a front-end intelligent system, there must also be a back-end system that the bot calls to complete a task after the user intent is understood and all information is gathered or to query data for display. In Oracle Intelligent Bots, this remote data access is implemented through custom components you build with JavaScript and Node.js and that you declaratively add to a state in the bot dialog flow.
In this article, you will learn everything you need to know about custom components in Oracle Intelligent Bots. In the hands-on instructions, you are going to extend the pizza bot I explained how to build in the course of my three most recent Oracle Magazine articles, with a dynamic menu that reads its contents from a custom component.
Understanding how to build custom components is a must-have skill for Oracle Intelligent Bots bot designers implementing custom business and data logic. So let’s get started.
About Bot Custom Components
As Figure 1 illustrates, a custom component service in Oracle Intelligent Bots is a Node.js-based REST service that hosts one or many custom components and that exposes two HTTP methods: GET and POST.
Figure 1: Bot custom component service architecture
The GET method is invoked at design time by the bot when the custom component is registered with the Oracle Intelligent Bots instance. The POST method is invoked at runtime when the dialog flow navigates to a state that is associated with a custom component hosted by the component REST service.
When invoked, the custom component REST service receives the name of the custom component to invoke; looks up the custom component implementation JavaScript module; and dispatches the request, along with a reference to the custom component SDK.
A custom component is a Node module built with JavaScript that exposes two functions:
metadata. This function returns information about the custom component upon custom component service registration in the bot. The information includes the component name, the definition of the component input parameters (properties), and the action strings returned by the component to enable the bot designer to decide how to continue the dialog flow.
invoke. This function is called at runtime and executes the custom component business logic. The logic may access dependent resources such as Oracle Mobile Cloud connectors, platform services, and custom APIs.
The custom component SDK consists of four files and provides functions for reading the incoming bot message and sending a component response:
Registry. The registry.js file contains a mapping of custom component names and their physical JavaScript files.
Shell. The shell.js file contains the dispatcher logic that reads file locations from the registry.js file and loads the requested custom component implementation.
SDK. The sdk.js file is passed as a reference to the custom component’s invoke function.
MessageModel. The MessageModel.js file contains helper functions for the Oracle Intelligent Bots conversation message model and helps component developers build rich UI bot responses.
Hands-on Prerequisites
You develop custom components in JavaScript with Node.js. For this you need Node.js and the node package manager (npm) to have been installed on your local machine.
To test whether you have Node.js installed, open a command-line window and type the node -v command. If you have Node.js installed, a version number should appear. Try the same with the npm -v command to verify the installation of the node package manager (npm).
Note: You can download Node.js and npm from npmjs.com/get-npm.
A second prerequisite for building custom components is the Oracle Intelligent Bots custom component SDK. You can download the latest bot custom component SDK from Oracle Technology Network (OTN).
Note: For this article, the bot custom component SDK files are provided within the download for the hands-on instructions.
A last prerequisite is a JavaScript editor, which can be as simple as a text editor—commercial or free—such as Atom or Microsoft Visual Studio Code.
Getting Started
To follow the hands-on instructions in this article, you need to have access to Oracle Mobile Cloud Enterprise, which is available as a free trial.
The download for this article contains, in the starter-bot folder, a bot you need to import to your Oracle Intelligent Bots instance to complete the hands-on steps for this article. To import the bot, after downloading and unzipping the resources file for this article, do the following:
Figure 2: Oracle Mobile Cloud Enterprise with Oracle Intelligent Bots selected
Train and Test the Sample Pizza Bot
The hands-on instructions in this article continue using the pizza bot created in my last Oracle Magazine article. Note, however, that for this article, I did remove the dependency on translation services to make it easier to set up the bot, which means that this bot works only for English. To train and test the pizza bot, follow these instructions:
What You Are Going to Build
The sample pizza bot has a section defined in the dialog flow that writes the pizza menu card to a context variable. To see the menu definition, in the bot, select the Flows icon in the left toolbar () and explore the InitializeMenu state. As you can see, all items on the pizza menu are defined in this state.
Because it is very unrealistic for a pizza bot to have the pizza menu defined in the dialog flow, you are going to replace the menu definition with a custom component that would have the option to query the pizza menu contents from, for example, a remote web service.
Creating a New Custom Component Service in Oracle Mobile Cloud
Custom component services in Oracle Mobile Cloud are built as custom APIs. Let’s create a new custom component.
Figure 3: Creating a custom API menu item
What you just did: An Oracle Mobile Cloud custom API is a Node.js REST Express project. By using the mcebots.raml template to create the custom API, you created a custom component service base project with the GET and POST method signatures preconfigured. By disabling the login requirement for the custom API, you allowed anonymous user access, which will be used by the bot when registering the component. And finally, you downloaded the project so that, as explained in the next section, you can configure the component service with the custom component SDK and build the custom component.
Preparing the Component Service Project Structure
You downloaded the Oracle Mobile Cloud custom API project, so next you need to turn this into a custom component service project by adding and configuring the custom component SDK.
It’s my personal preference to organize the component service project with custom component SDK files located in their own folder and the custom components created in subfolders. You may come up with your own location strategy at some point, but for now, let’s use mine.
Figure 4: Custom component service project folder structure
What you did: You created a custom component service project structure and copied the bot custom component SDK provided in the download for this article into it. You then copied the pizzamenu.js file, a predefined custom component that holds the pizza menu for the sample bot, into the menu folder.
Editing the Component Service Project
Now it is time for you to open your favorite JavaScript editor and edit some JavaScript. I chose Atom.
const apiURL = '/mobile/custom/MenuService/components';
var shell = require('./shell')();and edit it to match the project structure created earlier:
var shell = require('./js/shell')();
What you just did: The custom component service code doesn’t differ much from one service to another. The only difference is in the REST endpoint URI. The mcebots.js file you copied the contents from is a generic template provided by Oracle in the samples on OTN that I included in the download for this article. And because the SDK files are saved in the component service js folder, you updated the reference in the value for the shell variable.
"dependencies": {"joi": "^9.2.0"},The file contents should now look like they do in Figure 5.
Figure 5: package.json file after editing
'say_hello': require('./examples/say_hello')to
'oramag.sample.pizzamenu': require('./components/menu/pizzamenu)
Figure 6: npm installation resu
What you just did: With the package.json file containing the reference to the joi Node.js module, you needed to install the module dependency. For this you used the npm install command. The zip file you created at the end now contains the whole component service project, with all its dependencies, ready for you to upload to Oracle Mobile Cloud.
What the pizzamenu.js invoke function does: The custom component you copied and configured in the component service uses its invoke method to write a JSON object to a context variable in the dialog flow. The name of the context variable will be passed by the bot designer in a component property (defined in the metadata function). The invoke function, when called at runtime, obtains a handle to the custom component SDK through the conversation argument. It uses this handle to read the name of the context variable and to write the JSON object to the variable. It then triggers the dialog flow to navigate to the next state in the bot conversation before closing the call. With only a few modifications, you could change the sample to read the pizza menu from a remote web service instead of holding the menu statically.
Uploading the Component Service
To make the custom component available to the bot, you need to upload the component service implementation (menuservice.zip) and expose the component service on a mobile back end.
What you just did: First, you imported the custom component service implementation to Oracle Mobile Cloud so it can be exposed to the bot. To expose a custom API in Oracle Mobile Cloud, a back end is required. The back end is what you created next. You then associated the custom component service API with the back end to make it accessible for the bot.
Configuring the Custom Component Service with the Bot
We're almost done. The two steps missing before the pizza menu can be read from the custom component are to register the component service with the bot and to replace the menu defined in the dialog flow with a reference to the custom component.
Next you need three types of information from the Oracle Mobile Cloud back end you left open in step 75.
<Base URL>/mobile/custom/MenuService/components
InitializeMenu: component: "oramag.sample.pizzamenu" properties: menuVariableName: "pizzaMenu" transitions: {}Note: It is important to get the indenting right, because otherwise validation in the dialog flow editor will fail. Each indent is exactly two spaces. The InitializeMenu string is indented two spaces from the left margin; the component, properties, and transitions strings are indented four spaces from the left margin; and the menuVariableName string is indented six spaces from the left margin.
What you just did: In this last section of the hands-on instructions, you configured the custom component service you created and deployed it to Oracle Mobile Cloud with the sample bot. You then replaced the existing menu definition with a reference to the custom component so that the next time the bot runs, the menu will be read from the cloud.
Conclusion
Custom components are an important part of the Oracle Intelligent Bots architecture. They enable you to add custom logic to and integrate back-end services into your bot conversations.
Building custom components and custom component services for Oracle Intelligent Bots is a developer-specific task. In a bot project, you may separate the team by having bot designers building the dialog flow and JavaScript developers providing the custom components.
Note that for this article, I simplified and shortcut the custom component service creation process with starter templates and files. (How to connect custom components with remote services is explained in one of the Oracle TechExchange articles linked to at the end of this article.) The main focus in this hands-on demo was on the configuration of the custom component service and less on the programming. Building custom components, however, is easy to do and actually fun too.
Next Steps
TRY Oracle Mobile Cloud Enterprise and Oracle Intelligent Bots.
LEARN more about
DOWNLOAD the resources for this article.
Illustration by Wes Rowell