TechExchange Quick-Tip: How-to Test Apache FreeMarker Expressions in Oracle Digital Assistant

article by Frank Nimphius (Oracle) and Bastiaan van der Kooij (CX Builders), April 2019

In Oracle Digital Assistant, you use Apache FreeMarker expressions in a skill dialog flow to

define conditional blocks
iterate arrays
perform string, date, number and arithmetic operations
do formatting

and many more.

Apache FreeMarker is a powerful "tool" that allows developers to add custom logic to an otherwise declarative and component based dialog design.

And though Apache FreeMarker is the programming language¹ in Oracle Digital Assistant, at current there is no declarative expression builder or tester available for you to develop expressions.

In this article we explain a simple technique to create a custom Apache Freemarker tester using a skill and the embedded conversation tester in Oracle Digital Assistant.

¹ Apache FreeMarker is used in the dialog flow only. The programming language for custom components is Node.js

Build An Custom Expression Tester Experience

To use with the custom expression tester (or debugger, if you prefer) you create a skill as explained further down below and run it in the Oracle Digital Assistant embedded conversation tester.

Then, in the Message field, start typing the expression you want to test or create. Press the enter-key on your keyboard to test the expression. In the example shown shown below the initial expression is ${.now?long}, which prints the current date in milliseconds.

In a following extension, the expression gets refined to print the date not in milliseconds but in a date format. For this, the expression is changed to ${.now?long?number_to_date}. Because this too is a valid Apache FreeMarker expression, the result gets printed in the tester.

Next, we want to customize the date format. For this we change the expression to ${.now?long?number_to_date?string('dd-MON-yyyy')}, which however causes an error indicating that the Apache FreeMarker expression is not correct.

From experience we know, that the provided date mask is not valid and correct it to 'dd-MMM-yyyy'. And this then prints the date in the format we wanted.

Building the The Expression Tester

The expression tester is simply built. As you see in the image below, the tester state DebugFreeMarker contains a System.CommonResponse component that uses an Apache FreeMarker expression in its text property to evaluate the provided expression. Until the Exit button is pressed, the tester redirects to itself for a next expression to test.

Displaying Verbose Error Messages

Knowing that an expression is not valid is often not enough. The printErrorsSetting state allows you to set the printErrors boolean variable to true or false. When set to true, the expression tester prints a verbose message that contains the exact problem with an expression as well as some help to fix it. If you set it back to false then the error behavior is as shown in the example above.

Let's test the verbose error message. This time the expression to test is ${'hello world'?upper_case}, which, as you see in the conversation tester, produces HELLO WORLD as a result. Trying then to convert this string into one with initial uppercase letters only, fails because ?init_cap is not a valid Apache FreeMarker expression. In line 7 of the error message you see that "init_cap" is not a valid built-in expression. The error message then displays a list of valid expressions for help (Note that the list is truncated in the screen shot below). One of the built-in expressions displayed is capitalize, which is the expression that made the example work.

…

Note: To switch between true and false for displaying error messages, you need to reset the tester for the change to be picked up. Use the Reset button on top of the tester for this.

Known Limitation

The tester requires the output to be convertible into a string. If, for example you want to test array expressions, then you need to change the output as shown in the screenshot below. Here the expression first created an array of colors to then reverse sort it. Using "join" the result is then printed as a comma separated string.

Download Apache FreeMarker Skill Tester

You can download the Apache FreeMarker tester skill from the link below. To use it, just import the skill to your Oracle Digital Assistant instance and open it. Then run the embedded conversation tester using the run icon in the left side menu. IN the opened tester window start typing the expression you want to test.