Annotate user inputs

If you want to match on dynamic details in the user input that would be hard to maintain in a language object, you might want to use annotations.

Annotations in Teneo can be considered 'labels' that are attached to inputs. Some annotations are created automatically by Teneo, but you can also dynamically add them using scripts.

As an example, on this page, we will use annotations to 'label' promotion codes in a user input. These promotion codes are stored in a global variable and we are going to assume this variable is dynamically populated through an API or something similar.

The following 2 steps are needed to annotate the user input with the promotion codes:

1. Create a global variable and populate it with a list of promotion codes.
2. Create a global listener that will listen for all user inputs and a script that inspects each word in the user input. If the word is in the list of promotion codes, it should add the annotation VALID_PROMO_CODE.

Add a global variable

First, we need to create a global variable that we will assume has been populated dynamically with promotion codes for Longberry baristas:

1. Go to the solutions backstage by clicking on 'Solution' in the top right.
2. Click on 'Globals' and go to 'Variables'.
3. Add a new variable and give it the name validPromoCodes
   .
4. Then give it this value: ["mvkn","vuyo","2ppu","lqgp","ym5b","634q","g2gl"]
5. Hit 'Save'.

Add the annotation script to a global listener

Next, we need to set up a global pre listener so that we can annotate the user input before it is tested against flow triggers and transitions.

1. Click on the 'Solution' tab.
2. Click on 'Globals' and select 'Listeners'.
3. Click on the 'Add' button, to open the drop-down menu and select 'Pre listener' to add a new pre-listener.
4. Name it Find valid promotion codes
   . Then click the left arrow at the top.
5. Paste the kleene star *
   into the TLML Syntax field. This will match on everything since we want to inspect every input for valid promotion codes.
6. Add the following script in the 'Execution Script' field. (Details on the script can be found below):

   groovy

   1 def n = _.sentenceCount  // get the number of sentences
   2 // iterate through the sentences
   3 for (int si = 0; si < n; si++) {
   4     // iterate through each word in the sentence
   5     _.sentences[si].words.eachWithIndex { word, wordIndex ->
   6         if (validPromoCodes.contains(word.getOriginal().toString())) {
   7             // if lookup value is true then we annotate the 'range' that matched the list.
   8             _.inputAnnotations.add(_.createInputAnnotation("VALID_PROMO_CODE", si, [wordIndex] as HashSet, ["Promo code": word.getOriginal().toString()]))
   9         }
   10     }
   11 }
   12

7. Save using the 'Save' button in the top left of the editing window.

Give it a try and inspect the annotations

We are now annotating promotion codes using a global pre listener, which means language conditions can now use the custom annotation %$VALID_PROMO_CODE

to check if a user input contains a valid promotion code.

We can also inspect the annotation in the Advanced Tryout window:

1. In the main solution window, open the 'Advanced Tryout' window on the left-hand side.
2. Type mvkn
   into Tryout. This is a valid promo code and will be annotated accordingly.
3. In the 'Input' panel under 'Annotations' you can see what Teneo annotated, including your customized annotation %$VALID_PROMO_CODE.

If you hover over an annotation, you will get extra information (if there is any) from the annotation variables.

Explanation of the script

Let's have a detailed look at the script that we used:

1def n = _.sentenceCount  // get the number of sentences
2// iterate through the sentences
3for (int si = 0; si < n; si++) {
4    // iterate through each word in the sentence
5    _.sentences[si].words.eachWithIndex { word, wordIndex ->
6        if (validPromoCodes.contains(word.getOriginal().toString())) {
7            // if lookup value is true then we annotate the 'range' that matched the list.
8            _.inputAnnotations.add(_.createInputAnnotation("VALID_PROMO_CODE", si, [wordIndex] as HashSet, ["Promo code": word.getOriginal().toString()]))
9        }
10    }
11}
12

Here is what the script does:

1. First, we get the number of sentences in the input and iterate through the sentences. We do this because we need to provide the sentence number when we add an annotation.
2. For each sentence, we iterate through its words. We get the word and the words' index. This is done via the eachWithIndex iterator.
3. Next we check if the word exists in the global list. If so, we annotate the word in the sentence at wordIndex and create a annotation variable Promo code with the found promo code as a annotation value to Promo code, like so:

The script uses a number of Engine scripting API methods: