article by Frank Nimphius, June 2021
In previous articles I promoted the trinity of Composite Bag Entities (CBE), Entity Event Handler (EEH), and the System.ResolveEntities (RE) component as the (new) go-to technique for building model-driven conversations in Oracle Digital Assistant. Entity event handlers are called in the context of resolving composite bag entities, which allows you to influence the flow of conversations, but also how entities extract information from user messages.
In this article, I provide a Expense Report Skill (ZIP) that uses two composite bag entities and two entity event handlers to help users submit an expense report with one or many expense items. I am sharing this sample to provide you with entity event handler sample code that you can use to learn from.
Note: I developed the skill reporting example for an Oracle Digital Assistant Design Camp session about Entity Event Handler. So, if you are new to the topic of entity event handler, please pause here and watch this video first.
Entity Event Handler Expense Report Sample In Action
Let's start with how the demo performs at runtime to highlight areas that you find coded in an Entity Event Handler. The sample application is a simple version of an expense skill that follows the old traditional way of creating an expense report first to then add expense items to it. Let's start with how the demo behaves at runtime to highlight areas that you can find coded in an entity event handler. The sample application is a simple version of an expense skill that follows the old traditional method of first creating an expense report and then adding expense lines.
So you start by typing "create new report" or similar. The first information you provide is a reason for the report. So provide whatever title you want to set for the report (note that at the end of filing the expense report, nothing will get submitted. The sample stops by printing a summary that could be sent to a backend system).
Once you provided a title, the system prompts you for providing an employee Id. This information could be accessed from the profile of an authenticated user in a production implementation. In this sample implementation the employee ID is a country code followed by a 1 – 6 number (see image below).
The composite bag entity validates the employee ID using a regular expression entity. If the regular expression validates positive, then another validation takes place using an entity event handler function, which is to check whether the country code exists. For this the event handler looks up a JavaScript module that contains country codes and their associated currencies.
As you see in the image below, a country code of "D" is not valid as it has to be "DE" for Germany. Providing a valid Employee ID does progress the conversation to a next step, which is to select the reimbursement type, which can be "per diem" (as in Germany) or "actual expense" (as it is in the US). Some countries even offer both.
What you don't see in the image below is that the entity event handler set the reimbursement currency to the currency used in the country the employee ID indicates. So in the image below, the currency code for the expense reimbursement is set to EUR.
Selecting Per Diem as in the image below enforces another rule in the entity event handler, which is that meals cannot be expensed.
After selecting the reimbursement type, the first composite bag entity is resolved. As a result, you can see the expenseReport variable values in the Oracle Digital Assistant embedded conversation tester. Notice that the ReportingDate is set to the current date (which means that the user is not prompted for the date) and that the ReimbursementCurrency is set to EUR. Both settings were handled by the associated Entity
Event Handler.
The individual expense items are added in another composite bag entity that could be iterated over as many times as needed or an expense report. In the following I will go through it just once.
Let's try and file an expense item for Meals. Remember that I selected "Per Diem" as the reimbursement type, which means that meals are not an option. The Entity Event Handler validates the selection against the other composite bag entity variable and reports an error (see image below). Note that an alternative – maybe better option – would be to not display the Meals option, which also could be done using an Entity Event Handler.
So, lets choose Airfare (see image below) as the expense type and assume we got a refund for luggage we paid for but did not bring to a flight. After providing the expense type, the conversation prompts for the date. Here I tried a date in the future. An Entity Event Handler function detected the date to be a future date and displayed a validation error (Image below)
Note: Notice the two buttons to cancel the current expense item or the expense report as a whole. Both buttons are created programmatically using the Entity Event Handler.
The image below shows the validation error displayed by the Event Handler because of the user entering a date in the future. Once providing a valid date in the past, the next prompt is for the reimbursement (refund) amount. Here I provided a negative value because I got a refund and did not pay for something. The Entity Event Handler logic validated the amount and detected the negative number.
Because a negative amount in an expense report means you actually pay money back to your employer, the system asks if the amount is correct. The prompt and the two buttons were generated dynamically using JavaScript code in the Entity Event Handler.
after confirming the amount to be correct, notice how the composite bag entity acknowledges the amount in the currency of the expense but also calculates the equivalent amount of the reimbursement currency. For this, the Entity Event Handler makes a REST call to a public currency converter service on the Internet. One of the great features of Entity Event Handler is the ability to call REST service in the context of resolving a composite bag entity.
Lastly, a receipt is needed for all expenses exceeding a specific amount (no matter if a negative amount or positive amount was entered). In the embedded tester you cannot upload the receipt but need to provide the URL to an image (you can look at pixabay.com for such a URL). Again its an Entity Event Handler that enforces the receipt policy.
In a next step, the skill summarizes the expense item for the user to add to the expense report or to dismiss the expense item.
…
With adding the expense item to the expense report, you can submit the expense report for approval or add another expense item (Image below)
Installing The Sample
The sample is provided as a single skill. Import the skill to your Oracle Digital Assistant instance and make sure you train the model.
The only configuration you need to do is to:
1. go to the skill Settings (the cone icon highlighted in the image below)
2. Press the Configuration tab
3. Edit the currencyConverterKey parameter by adding your own free license key of the https://free.currconv.com website.
Note: You can choose a different currency converter like https://fixer.io, but then need to change the Entity Event Handler code that queries the conversion quote
No other configuration is required,
To run the sample, open the embedded conversation tester and start with a message like "create new expense report".
Exploring the Entity Event Handler Code
The Entity Event Handler code is commented well so you will find it easy to understand where which function got implemented and how it was done. As shown in the image below, there are two composite bag entities of interest in the sample skill
Both composite bag entities have Entity Event Handler defined.
To see the entity event handler code, select the composite bag entity in the list and then press the pencil icon next to the entity event handler to open the browser based editor.
Related Videos
I recommend you to watch the Entity Event Handler recording of the Oracle Digital Assistant Design Camp to better understand the sample and how Entity Event Handler work.
Oracle Digital Assistant Design Camp session about Entity Event Handler
Download Sample Skill
Expense Report Skill (ZIP)
Related Content
TechExchange: Building your first entity event handler for Oracle Digital Assistant
TechExchange: Accessing Remote Rest Services from Custom Event Handler
TechExchange: How to Debug Entity Event Handler in Oracle Digital Assistant
TechExchange Quick-Tip: How to Intelligently Cancel Composite Bag Entity Driven User Dialog Flows
TechExchange Quick-Tip: Setting Composite Bag Entity Item Values From A Custom Component
Tutorials
Creating an Entity Event Handler
Creating an Entity Event Handler with the Bots Node SDK
