oracle intelligent bots techexchange · oracle intelligent bots - techexchange 3 messagemodel.js...

OracleIntelligentBots–TechExchange

1

OracleIntelligentBots

TechExchange

Sample.

Running and Debugging Custom Components Locally Martin Deh, May 2018

With Oracle Intelligent Bots, each state in the dialog flow invokes a component to perform actions that range from basic interactions like taking user input or providing a bot response, to complex interactions that, for example, call out to remote services for backend integration.

For standard bot functionality like setting variables and handling user interaction, Oracle Intelligent Bots provides a set of built-in components. For anything that you don't find a built-in component for and for backend system integration you are required to write a custom component.

While the runtime of custom components is recommended to be in a container such as Oracle Mobile Cloud Enterprise (OMCe) for testing and production, the development experience when writing components in such environments is not as good as it could be. Debugging custom component code is one example that can be improved if development was outside these containers. In addition, any changes applied to the code when using OMCe during development require redeployment of the custom component, which is time consuming.

In this TechExchange article, I describe how to enable the OMCe Intelligent Bots samples to run locally in development. I will also show how debugging can be locally without losing any of the functionality provided by OMCe.

Sample Installation To get started with Oracle Mobile Cloud Enterprise bot samples, you need to download them from the Oracle Technology Network (OTN) (http://www.oracle.com/technetwork/topics/cloud/downloads/mobile-suite-3636471.html).

At the time of this writing, the most current version to download is 18.1.5.0. To download the samples, you first need to accept the license agreement on the OTN page.

OracleIntelligentBots-TechExchange 2

Then click either on the download link.

Once the zip file with the samples has been downloaded and extracted, the content should appear as follows:

The following are the files included in the sample:

Directory File Name Description

api_implementation

mcebots.js The main Javascript file. It implements the Bot Component REST API by delegating most of the functions to the shell.js object.


MessageModel.js The utility class for implementing UI in Bot

registry.js Lists the custom component that are managed by the Component Service

shell.js A utility object that is responsible for both finding and invoking the custom components

sdk.js Bot SDK v 1.1

mcebots.raml Sample file to create an API in OMCe

package.json This is the standard package.js file used by Node.js

sample_bots CrcPizzaBot.json Sample Bot that can be imported into IB Admin

FinancialBot.json Sample Bot that can be imported into IB Admin

package-bots_samples.zip

MobileBackend bots_samples v18.1.5 => APIImplementation BotsSampleService v18.1.5

README.md The instructions for the sample bots to run the custom components in the Node.js container provided by OMCe. This container makes connectors and OMCe platform APIs like analytics, storage, database and logging available to a custom component.

Once code development is completed in the localized version, you can follow the instructions here to deploy the completed code to OMCe.

Running the Samples Locally The first step is to enable the provided contents to “run” locally. If you review the dependencies in the package.json and in the node_modules directory, you will notice that “express” is already part of the included contents. In order to take advantage of using express, create a new file: index.js under the api_implementation directory. In the index.js, include the following code, replacing [PORT] with the port of your choice:

const express = require('express');

const bodyParser = require('body-parser');

const components = require('./mcebots');

const app = express();

app.use(bodyParser.json());

components(app);

app.listen(process.env.PORT || [port], () => {

console.log('Custom Components Server Ready');

});

Note: For example, if the server should listen to port 3000 you change the app.listen configuraton as shown below: app.listen(process.env.PORT || 3000, () => {


console.log('Custom Components Server Ready');

});

Next, open a command prompt at the api_implementation directory and type:

node index.js

followed by pressing the "enter-key". Your command window should look similar to this:

Creating the Custom Component Service With the express server ready and listening, the next step is for you to create a custom component service in the Oracle Intelligent Bots Admin user interfaces.

Note: Depending on where you are running the express server, in order for OMCe to connect to the instance, a (local) tunnel, such as ngrok most likely will be needed.

The FinancialBot is one of the sample Bots provided with Oracle Intelligent Bots. If you don't see this bot in your Oracle Intelligent Bots instance, then import the bot from the sample_bot folder of the omce-bots-samples-v18.1.5.0 download. Simply, in the Oracle Intelligent Bots dashboard, click the Import button and point it to the FinancialBot JSON file.

So, lets create a custom component services configuration for the Financial Bot. In the Oracle Intelligent Bots Admin UI, select the FinancialBot to open it.


In the opened bot, select the Components icon ( ) in the menu on the left hand side. Next click on the +Service button to create a new service. In the Create Service dialog, complete the necessary information:

Give the Service a Name.

Next, select the Other option and provide the Metadata URL.

The Metadata URL for the custom component service is made up of 3 parts: The host name, port and the endpoint URL. The endpoint URL is defined in the api_implementation/mcebots.js file: const apiURL = '/mobile/custom/bots_samples/components';


Note: As stated in the comments in the mcebots.js, the apiURL value can be changed. However for deployment to OMCe, the value must start with /mobile/custom and include the API name (e.g. bots_samples) before the customized endpoint name (e.g. components). Since we will be running the components locally, the format of the Metadata URL would be as follows:

http://[host][port]/mobile/custom/bots_samples/components Note: For example, if you are using ngrok, then replace [host] with the ngork provided url (ngrok takes care of the port). http://123abc.ngrok.io/mobile/custom/bots_samples/components

Note: Ngrok enables a connection to a ngrok cloud service. This service: accepts traffic on a public address, then relays that traffic through to the ngrok process running on your machine and then on to the local address you specified. To install and configure ngrok, please go to https://ngrok.com/product. Note: To use ngrok for the sample node server listening to port 3000, type ./ngrok http 3000 on a command line, assuming you installed ngrok with the global (-g) option. The User Name and Password can be any value.

Click the Create button to complete the configuration.

Upon a successful creation, the Component Service UI should show the Financial Bot’s custom components.

But how were these components found? Well, recall that the registry.js is responsible for declaring which custom components are contained in a custom component services so they can be invoked from a Bot. Below is the content of the registry of this sample module.exports = { components: { // FinancialBot 'BalanceRetrieval': require('./banking/balance_retrieval'), 'TransactionsRetrieval': require('./banking/transactions_retrieval'), 'TrackSpending': require('./banking/track_spending'), 'Payments': require('./banking/payments') } };

Testing the Sample Now that the server is running and can connect to the (local) Component Service, you can use the embedded bot tester to call e.g. the BalanceRetrieval custom component.


However, before you test the bot and the configured custom component services, you need to train the bot. For this click the Train link on the right to menu. Before pressing the Train menu item, you should see an exclamation mark in front of the link text. After training the bot, a checkmark icon should be displayed instead.

Next (optionally) review the custom component code in balance_retrieval.js file, If you look at the invoke method, you will see that the component responds the bot component request with the account id and the balance information:

conversation.reply({ text: 'The balance in your ' + accountType + ' account (' + account.id + ') is

$' + String(account.balance()) });

Start the bot tester by pressing the tester icon ( ) on the top right menu.

In the Bot tester Message filed, enter what’s my balance and press the Send button. Select one of the displayed accounts for the bot print the account balance queried from the custom component.

From reviewing the command window that started the server, the logs are also displayed.


Debugging the Sample The next step is to start the local node server so that the java script code can be debugged. This can be done by using the default inspect flag along with the node command. For example, here are the two options. Notice that the debug port defaults to 9229.

node –inspect index.js

Or by using nodemon.io, which will enable live reload of code that has been changed. To install nodemon.io, issue the following command on the command line

npm install -g nodemon

nodemon –inspect index.js

Now that the server is running in debug mode, use an IDE (which supports nodejs debugging) of your choice to attach the server. The example in the image below uses Visual Studio Code.

In the balance_retrieval.js, set a breakpoint anywhere (for example, line #24) in the invoke method.


Again, use the Bot tester In Oracle Intelligent Bots (e.g. what’s my balance, then choose an account) and once the custom component is called, the execution will stop at the set breakpoint:

oracle intelligent bots techexchange · oracle intelligent bots - techexchange 3 messagemodel.js...

Documents