How to build custom components for use in Oracle Intelligent Bots

By Frank Nimphius

November/December 2018

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:

1. Open a browser, and access the Oracle Mobile Cloud Enterprise homepage.
2. Authenticate with the user credentials you defined when you provisioned the cloud service.
3. Click the hamburger icon at the upper left to open the Oracle Mobile Cloud Enterprise menu.
4. Click the Bots menu item (shown in Figure 2), which opens the Oracle Intelligent Bots dashboard in a separate browser window or tab.

   Figure 2: Oracle Mobile Cloud Enterprise with Oracle Intelligent Bots selected

5. Click Import Bot at the upper right of the dashboard.
6. In the opened dialog box, navigate to the location to which you extracted the downloaded zip file and open the starter-bot folder.
7. Select the OracleMagazineOnlinePizzaBot4.zip import file, and click Open.
   Note: You cannot import two bots with the same name. If you need to import the starter bot more than once or if you share an Oracle Intelligent Bots instance, rename any previous imports of the starter bot before importing the new bot. You can rename a bot by opening it, clicking the Settings icon (), renaming the bot, and exiting the bot.
8. Close the upload confirmation dialog box, by clicking the X at the right side.
9. Keep the browser window open.

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:

10. Open the browser window or tab with the Oracle Intelligent Bots dashboard in it.
11. If you already have existing bots defined in your environment, chances are good that you won’t immediately spot the downloaded bot. To find the bot, type OracleMagazine into the Filter field above the green New Bot + icon.
12. Click the OracleMagazineOnlinePizzaBot4 bot to open it.
13. Click Train (at the top right). Before you click it, Train should show an exclamation point, because the bot is not yet trained after the download and import. After you click Train, a dialog box appears that confirms that the bot has been trained. Training the model is required for the bot to understand free-form text input.
14. Run the embedded bot tester, by clicking the Test icon () at the upper right.
15. Type Hi into the Message field, and click Send.
16. Type Show me the menu into the Message field, and click Send.
17. Choose a pizza, and complete the order process.
18. Click the Reset button at the top right of the embedded bot tester.
19. Try the bot again, but this time type I like to order a pizza, and click Send.
20. Choose a pizza, and complete the order process.
21. Click Reset.

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.

22. In Oracle Mobile Cloud Enterprise, select the APIs menu item from the Mobile Apps menu category, as shown in Figure 3. To see this option, you may have to click the hamburger icon next to the Oracle Mobile Cloud Enterprise label.

    Figure 3: Creating a custom API menu item

23. Click the + New API button, and choose API from the menu.
24. In the New API dialog box, click the Upload a RAML document link.
25. In the file system, locate the directory where you unzipped the download for this article, open the raml-template folder, and select the mcebots.raml file.
26. Click Open.
27. Change the API Display Name field value from MceBots to MenuService.
28. In the Short Description field, add Oracle Magazine pizza bot menu.
29. Click Create.
30. Select the Security () icon from the left menu, and toggle the Login Required button off (so that it’s greyed out).
31. Click the Save button at the top right.
32. Select the Implementation () menu option at the left side.
33. On the implementation page, click the green JavaScript Scaffold button to download the Node.js starter project (zip file) for building the custom component service.
34. Keep the browser window open.

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.

35. Navigate to the folder to which you downloaded the Oracle Mobile Cloud custom API (in step 33).
36. Find and unzip the downloaded menuservice_1.0.zip file.

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.

37. Open the newly created menuservice folder, and create a new folder named js therein.
38. Open the js folder, and create a folder named components therein.
39. Open the components folder, and create a folder named menu therein.
40. Copy the shell.js, registry.js, MessageModel.js, and sdk.js files, located in the bot-component-sdk folder of the download for this article, and paste them into the js subfolder in the menuservice folder.
41. Copy the pizzamenu.js file, located in the menu-component folder in the download for this article, and paste it into the menu subfolder in the menuservice -> js -> components folder. Your overall project structure should look like what’s shown in Figure 4.

    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.

42. In Atom, select File -> Add Project Folder, select the menuservice folder, and click Open.
43. Open the menuservice.js file, shown in the project menu at the left side.
44. Take note of the REST URI /mobile/custom/MenuService/components, configured for service.post and service.get.
45. Replace all of the menuservice.js file contents with the contents of the mcebots.js file, located in the component-service-src folder in the download for this article.
46. Find the const apiURL variable declaration, and change it to

    const apiURL = '/mobile/custom/MenuService/components';
    

47. Next, find the code line

    var shell = require('./shell')();
    

    and edit it to match the project structure created earlier:

    var shell = require('./js/shell')();
    

48. Save the changes.

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.

49. Open the package.json file, located in the project menu on the left side.
50. Create a new line after 'main'—'menuservice.js', and add the following:

    "dependencies": {"joi": "^9.2.0"},
    

    The file contents should now look like they do in Figure 5.

    Figure 5: package.json file after editing

51. Save the file.
52. Expand the js folder under the menuservice project root folder.
53. Open the registry.js file for editing.
54. Change the following line in the file from

    	'say_hello': require('./examples/say_hello')
    

    to

    'oramag.sample.pizzamenu': require('./components/menu/pizzamenu)
    

55. Save the file.

What you just did: The package.json file contains information about the Node project, such as the starter JavaScript file, but it also helps with tracking the project dependencies to other Node.js modules. The custom component SDK has a dependency on joi, a Node.js schema validator module, which needs to be listed in this file. The registry.js file tracks the name of custom components, along with their physical file locations. The existing file contents reference an example component that is not part of the project you are building and needed to be replaced with the name and the location of the pizzamenu.js file, located in the components/menu folder.

56. To understand where the name 'oramag.sample.pizzamenu' comes from, open the pizzamenu.js file, located in the /components/menu folder in Atom, which is also the relative path reference you added to the menu.js reference in the registry.js file (note that in Node.js, you don’t need to specify the .js file extension).
    The file contains two functions: metadata and invoke. The metadata function describes the custom component and also defines the component name, which, in this example, is 'oramag.sample.pizzamenu'. The invoke function then holds the code that is executed at runtime to display the menu.
57. Save all files.
58. Open a command-line window.
59. On the command line, navigate to the menuservice folder.
60. On the command line, type “npm install.” You should see a success result similar to that in Figure 6.

    Figure 6: npm installation resu

61. Close the command-line window.
62. In the file system, navigate to the menuservice folder and zip it to menuservice.zip.

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.

63. Go back to the browser window you left open in step 34.
64. Click the Upload an implementation archive link, and browse to the location in your file system where you saved the menuservice.zip file.
65. Select the file, and click Open.
66. Click the hamburger icon at the top left (next to the Oracle logo).
67. Select Mobile Apps and then Backends.
68. Click New Backend.
69. Provide the back-end name OraMagPizzaMenu. If you use Oracle Mobile Cloud Enterprise, set Application (under the Analytics label) to None.
70. Click Create.
71. Click the hamburger icon again to close the side menu.
72. In the OraMagPizzaMenu back-end editor, select the APIs () menu option at the left.
73. Click Select APIs.
74. Type MenuService into the search field, and click the plus icon on the MenuService card.
75. Click the OraMagPizzaMenu 1.0 link to return to the back-end editor.
76. Keep the window open.

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.

77. Go back to the browser window you left open in step 9. It’s the window with the sample bot.
78. Select the Components menu item () from the left-side menu to get to the custom component service registration page.
79. Click the + Service button.
80. Define the Name field value as PizzaMenuService.
81. Ensure that Mobile Cloud is selected.
82. Select the checkbox with the label use anonymous access.

Next you need three types of information from the Oracle Mobile Cloud back end you left open in step 75.

83. In the back-end editor, click the Settings menu option.
84. Copy the following values to a text file: Backend Id, Anonymous Key (you need to click the Show link to see the key), and Base URL.
85. Go back to the bot.
86. Copy Backend Id into the Backend Id field and Anonymous Key into the Anonymous Key field.
87. In the Metadata URL field, add the following value:

    <Base URL>/mobile/custom/MenuService/components
    

88. Click Create. If all went well, you should see a message such as “You successfully created the PizzaMenuService service.”
89. Expand the PizzaMenuService menu that now shows on the page, and click the "oramag.sample.pizzamenu" item.
90. Take note of the component name "oramag.sample.pizzamenu" and the name of the required property, MenuVariableName.
91. Click the Flows menu item ().
92. Find and delete the whole InitializeMenu state down to and including the transitions: {} line. Don’t touch the setCardsRangeStart state beneath.
93. Add the following code snippet above setCardsRangeStart:

      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.
94. Click the Validate link at the top right of the dialog flow editor.
95. If validation succeeded, click the Test icon ().
96. Type Hi into the Message field, and click Send.
97. Then type Show me the menu into the Message field, and click Send.
98. Choose a pizza, and complete the order process.
99. Click the Reset button at the top right of the embedded tester.
100. Try the bot again, but this time type I like to order a pizza.
101. Choose a pizza, and complete the order process.

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

• Oracle Mobile Cloud Enterprise and Oracle Intelligent Bots.
• building custom components (TechExchange article).
• back-end system integration (TechExchange article).
• building card layout bot responses from custom components (TechExchange article).

DOWNLOAD the resources for this article.

Illustration by Wes Rowell