article by Frank Nimphius, December 2020
In In this article I explain how you can use the Apache FreeMarker Online Tester to debug and test expressions in Oracle Digital Assistant
About Apache FreeMarker in Oracle Digital Assistant
Apache FreeMarker is the expression engine used in Oracle Digital Assistant dialog flows, entities and skill and digital assistant settings.
An Apache FreeMarker expression is defined using the ${ … } construct or as directives like <#if …> <#else> … </#if>. You can read up on Apache FreeMarker expressions at
About the Online Template Tester
The Apache FreeMarker online tester is available as a project on GitHub and online.
On GitHub
You find the GitHub project at https://github.com/apache/freemarker-online-tester
Online Tester
To use the online tester, point your browser to https://try.freemarker.apache.org/
The image below shows the tester that displays in the browser.
The Template field takes the Apache FreeMarker construct or expression you want to test. The Data model field provides various options for you to model the data objects that are referenced by your expression.
The data model may simulate a variable state in Oracle Digital Assistant or the content of a system variable.
As a rule of thumb: Any data object reference in your FreeMarker script needs to be modeled.
The image below shows the options you have available to model the data objects. These could be simple variables like variableName = value and more complex objects that you model as JSON objects.
If your script references variableName.value then either you need to define a variable that has ".value" in the name, or you create a value object for a variable that has a key "value".
Testing Example
The image below shows BotML code that defines an object of pastas. Each pasta is defined as an object that is associated with an attribute (property) that matches the pasta name.
For example, to access "Fettucine Alfredo" in the menu variable, the expression you use in BotML is ${menu.value['Fettuccine Alredo']}.
So to access the "Fettuccine Alfredo" title information, you use ${menu.value['Fettuccine Alredo'].title}
If the menu is rendered as a carousel of cards in the System.CommonResponse component, then the cards are stamped using the iteratorVariable property of the System.CommonResponse component card response item.
In the image below, the names of the pastas is the menu are read from a value list entity. Value list entities are good for user input validation but can also be used in list of values.
The expression to access the name of an entity from a card in a carousel is ${enumValue}. To use the information (the pasta name) read from the entity to access the pasta menu title and description properties you use the following expressions (also shown in the image below)
${menu.value[enumValue].title}
${menu.value[enumValue].description}
Hope the sample is complex enough for a realistic test 😉
To test the expression, I first needed to model the data in the online tester. As you can see in the Data model field, I used JSON to define the menu structure. I then copy and pasted the expression to test into the Template field.
If you click the Evaluate button, either the result of the expression or, in the event of an error, an exception is displayed. I agree that "exception" sounds scary, but it gives you a clear reason why your expression isn't working.
A frequent problem with expressions is a missing parentheses or redundant opening or closing parentheses. All of this can be solved quite easily in the online tester.
You can also test directives like the <#if …> <#/if> condition (shown in the image below).
Or to test the case in which Pasta Alfredo is not chosen as a value …
Using the <#list …> … </#list> directive you can also test iterating over a list of objects.
Related Content
TechExchange Quick-Tip: Access And Read Objects In An Array By Their Index Position In The Array
TechExchange – QuickTip: How To Tell Which Value Or Synonym Actually Resolved An Entity
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
TechExchange Quick-Tip: How-to Test Apache FreeMarker Expressions in Oracle Digital Assistant
(a limited expression tester that runs as a skill in Oracle Digital Assistant)
