article by Frank Nimphius, April 2021
I mentioned it in a previous article that the trinity of Composite Bag Entities (CBE), Entity Event Handler (EEH), and the System.ResolveEntities (RE) component will soon become the standard (aka go-to technique) for building model-driven conversations in Oracle Digital Assistant.
Entity event handlers can be developed using an external IDE such as Microsoft Visual Studio Code or using the browser-based editor in Oracle Digital Assistant.
In both cases, EEH are deployed to the embedded node container in Oracle Digital Assistant skills.
However, there is also the option to deploy and configure EEH component services as a remote service which can then be used to debug EEH.
This article explains how to start your EEH development in the browser, then export the handler for debugging with an external IDE.
Note: To learn more about model driven conversations, see TechExchange: Model Driven Conversations in Oracle Digital Assistant – Build Better User Interfaces By Using Entities For Everything. This article describes the principle of model driven conversations for a time before EEH. With EEH, model driven design is even more compelling to adopt.
Getting Started
Below screen shot shows a sample expense report that derives the reimbursement currency from the user employee ID. So, lets assume you want to debug this step
First thing to do before you can debug the entity event handler is to export it to a local computer. By default, entity event handler are deployed as Oracle function to the embedded container in the Oracle Digital Assistant skill.
Click the link net to the Package File entry to download the deployed event handler. Once downloaded, unzip the tgz file and open the root level "package" folder in a command line window
Next issue the following command to install all Node dependencies (ensure you have access to the Internet: npm install
Ensure you have Bots Node SDK installed (https://github.com/oracle/bots-node-sdk). If you don't have it installed yet, issue the following command
npm install -g @oracle/bots-node-sdk (Windows)
sudo npm install -g @oracle/bots-node-sdk (Mac)
To verify the installation, issue the command shown in the image below
If this command returns a version (which might be different than the version shown in the image), then you can start a local Node server on port 3000 by issuing the following command
bots-node-sdk service
If you open a browser window and type http://localhost:3000/components then you see all the custom components and entity event handlers defined in the package. The last hurdle to cross now is to expose the URL to the Internet so it can be configured in Oracle Digital Assistant. One way to expose the URL is by using a tunneling software like NGROK (https://ngrok.com/) .
Note: Before using NGROK, make sure you read up on what it does so you are aware of the risk associated with exposing your computer to the Internet (https://ngrok.com/) . If the environment you are in blocks calls to NGROK, then you either need to find another tunneling software or another solution (maybe you have a machine that is exposed to the Internet that you can use for debugging)
The image below shows how NGROK exposes the URL (by the time you read this, the NGROK URL will no longer exist). To create the tunnel, you issue the following command using ngrok
./ngrok http 3000
The URL I highlighted in the image is the URL you use to reference the local entity event handler deployment from your Oracle Digital Assistant skill
Configuring Your Local Deployed EEH In a Skill
To use the event handler running on your local machine in Oracle Digital Assistant, you need to create a new component service registration. To be able to disable the existing service, you need to go to your composite bag entity and unregister the event handler as shown in the image below.
Next, navigate to the Skill component package registration page and select the EEH you want to disable. Then, switch the Service Enabled toggle so the existing event hander package is no longer used.
Press the + Service button and create a new External configuration. As the Metadata URL, use the URL of your tunnel (NGROK in my example) and append it with /components. Set the username and password to any value as there is no authentication enforced on the event handler service.
Go back to your composite bag entity and set the event handler (as shown in the image below), which now points to your remote deployed event hander service.
Debugging Your Event Handler
The images in this section are screen shots from the Microsoft Visual Studio Code IDE (https://code.visualstudio.com/). Note that you can use any IDE that supports Node.js debugging and that Visual Studio Code is not a mandatory use.
In Microsoft Visual Studio Code, open the packge root folder of the event hander service (the one you obtained from unzipping the downloaded tgz file) and select the Debug icon.
Click the create a launch.json file link under the Run and Debug option (shown in image above) and select Node.js (shown in image below).
When the file got created, click the Add Configuration button shown in the image below.
Choose Node.js: Attach to Process from the configuration options …
and rename the entry to Debug EEH as shown in the image below.
Open the event handler file to debug (Using the file menu icon on top of the left-side menu bar) and set break points in your EEH code. Then switch back to the debug icon in the left side menu and choose the Debug EEH entry from the drop-down list. Then press the green run icon to start the debugging process. After clicking the run icon, another drop down opens that shows local Node processes on your local computer. Select the process for the EEH service to start the debugging.
With the debugger started, open the conversation tester in Oracle Digital Assistant skill and start a conversation.
As soon as the conversation hits a break point, the Microsoft Visual Studio Code IDE is put into focus. You can now introspect and step through the code.
For example (shown in the image below) you can watch the variable values in the Variables panel. This not only shows you variables defined in the EEH file, but also the variables that are passed from the System.ResolveEntities component (event and context)
Note: Chances are that, after completing your debugging, the conversation tester in the skill shows an error. This is because the debugging may have exceeded the time the skill waits before timing out on the component request. In this case, just restart the conversation to see the changes you applied to your component service.
Important: To see the changes you applied during a debugging session, you need to save the event handler file you edited and restart the Node process serving the EEH. For this, go to the command line window in which you issued the bots-node-sdk service command, press ctrl+c to stop the service, and then re-issue bots-node-sdk service. For a next debugging session, you also need to restart the debugger and hook it up to the new Node server process.
When You Are Done
If your done with your debugging session, and if you changed the event handler code, then you need to package it up and redeploy it to Oracle Digital Assistant. For this, navigate to the package root folder of the EEH project and issue the following command: bots-node-sdk pack
The command (shown in the image above) creates a new tgz file that you can load into the Oracle Digital Assistant skill. For this, select the (yet disabled) EEH package you originally exported and use the link (in 21.04 it is a button) to upload (change) the deployed event handler package.
Don't forget to disable or delete the debug service and to re-enable the deployed service. For this you
- Go to the composite bag entity and release the event handler configuration (clear it as before)
- Navigate to the debug service in the component registration page and either disable it (toggle) or delete it (if you don't need it anymore)
- Go to the original event handler and enable it (toggle)
- Go back to the composite bag entity and associate it with the event handler function to use (now coming from the original package deployed to the embedded skill container)
Related Content
Tutorial: Developing entity event handler using the browser based editor in Oracle Digital Assistant
Tutorial; Developing entity event hander in an external IDE using the Oracle Bots Node SDK
TechExchange Quick-Tip: Using nodemon to automate re-starting custom component services after edit
TechExchange: Accessing Remote Rest Services from Custom Event Handler
