article by Frank Nimphius, April 2021
This article explains how you can export and import entity event handler that you created in Oracle Digital Assistant for editing in an external IDE, debugging or to add custom or 3rd party Node.js modules.
About Entity Event Handler
Entity Event Handler is a new feature since Oracle Digital Assistant 21.02 that allows you to write custom component code that executes when a composite bag entity gets resolved at run time. Using entity event handler you no longer need to rely on Apache FreeMarker expressions for implementing custom bag item validation, or external dialog flow states for accessing REST services. Entity event handler soon will become a required skill for all Oracle Digital Assistant developers to have.
Entity event handlers can be developed using the Oracle Digital Assistant skill (browser-based editor) or externally using a JavaScript IDE such as Microsoft Visual Studio Code. In either way, I recommend you install the Oracle Bots Node SDK from GitHub (https://github.com/oracle/bots-node-sdk), which you do by issuing the following command (assuming you have Node.js and Node Package Manager (npm) installed
npm install -g @oracle/bots-node-sdk (Windows)
or
sudo npm install -g @oracle/bots-node-sdk (Mac)
Using the Oracle Bots Node SDK, you have the following additional options when working with Entity Event Handler:
- External code editing, allowing you to develop even while offline
- Runtime debugging of entity event handler code (we will create a separate article about this)
- Adding 3rd party Node modules and JS library files to your Entity Event Handler project
Note: You can learn about entity event handlers by watching the 50 minutes "Understanding Entity Event Handler Oracle Digital Assistant Design Camp" recording. The design camp recording briefly explains composite bag entities to then focus on what entity event handlers are, how you build them and what you can do with them.
Exporting Entity Event Handler Created For A Composite Bag Entity
Composite bag entities group related entities as well as items of type string, location or attachment to a business domain object that, when resolved at runtime, generates the conversation flow needed to collect information for a specific task from a user. If you are not yet familiar with composite bag entities, watch this Oracle Digital Assistant design camp recording about model drive design.
A composite bag entity can have a single entity event handler defined that registers JavaScript functions for entity and bag item events like validation and prompting users for input. The registered JavaScript functions are then called at runtime by the System.ResolveEntities or the System.CommonResponse component.
If you are new to entity event handlers, trying it yourself by following this beginner tutorial might help.
In brief: To start developing an entity event handler, you select a composite bag entity in you skill ("PizzaBag" in the image below) and press the + Event Handler button.
In the Create Event Handler dialog, you need to select or define a Service name. The service is a package that can hold one or many entity event handlers. Because event handler are bound to the composite bag entity they are developed for, my recommendation is to save all event handler you create for a skill in a single service package. The Handler Name you define is the name of the entity event handler program you will be editing for the selected composite bag entity.
With the event handler open in the browser editor, you can now use the + Event button to add event handler for bag items, the entity as a whole or custom events.
Event handler services are deployed as Oracle Function to the embedded Oracle Digital Assistant skill container. Optionally you can decide to do a remote deployment of entity event handlers, for which however the entity event handler service package must be developed externally (outside the cloud) or exported from the skill.
To export the entity event handler service, click the link with the name of the entity event handler service (in this sample the name was chosen as PizzaEEH) followed by a version number and the extension ".tgz". The download is a ZIP file that contains the event handler components and configuration files (package.json). The image below shows the downloaded ".tgz" file and the extracted folder you can use for editing the component externally.
To install the entity event handler Node dependencies, you need to navigate to the entity event handler service root folder and then issue the following command
npm install
With the Oracle Bots Node SDK installed, you can now issue
bots-node-sdk service
to start the integrated Node express server. The server is needed if you wanted to locally debug entity event handlers (note that to be able to debug entity event handlers, your development machine must be exposed on the Internet so that the local Node express server (port 3000) can be accessed from Oracle Digital Assistant in the Oracle Cloud. This step may require tunneling software like NGROK.
With the entity event handler service downloaded and the dependent node modules installed, you can now edit the package.json file to change the name of the deployment package you are going to create (e.g. from "custom-component-service" to "PizzaEEH"), add JavaScript library files or install dependent node modules. For example, the entity event handler can use the node-fetch module out of the box to access external REST services. If your preferred REST access would be through the Axios module instead, then you can install axios to the event handler using
npm install axios
Similar for other Node modules you want to integrate in you entity event handler.
Once done with editing, or installing dependent modules, you need to run bots-node-sdk pack from the command line (in the EEH service root folder). This command creates a new tgz file that you can then deploy to the Oracle Digital Assistant skill.
To re-deploy a deployment package into Oracle Digital Assistant, select the change link (see image below) of the entity event handler package and use the opened dialog to locate the package file (.tgz) you created.
Select the ".tgz" file and press open to deploy it.
Note: After you deployed your external ".tgz" file back into Oracle Digital Assistant skill, you can continue using the browser based editor to program your event handler functions. If you added Node modules, or JS libraries then you can reference those from your JavaScript code in the browser editor (don't forget the "require" command when referencing node modules).
Related Content
Entity Event Handler introduction tutorial
Entity Event Handler Development Using External IDE tutorial
Oracle Digital Assistant Design Camp video recording about EEH
TechExchange Quick-Tip: Setting Composite Bag Entity Item Values From A Custom Component
TechExchange: Building your first entity event handler for Oracle Digital Assistant
