Skip to main content

Global Listeners

A Global Listener listens for user input anywhere in the solution; this type of Listener can be used when wanting to listen for certain user inputs regardless of the Flow or transition. Just like Flow Listeners, Global Listeners help your bot pick up relevant pieces of information from user inputs, even when these things have not been explicitly prompted for.

The sections on this page provide information about the various aspects of Global Listeners:

Concept​

A Global Listener listens for user input anywhere in the solution; this type of Listener can be used to listen for certain user inputs regardless of the Flow or transition. Just like Flow Listeners, Global Listeners help your bot pick up relevant pieces of information from user inputs, even when these things have not been explicitly prompted for.

Global Listeners are made up of the same parts as Flow Listeners: a TLML Syntax condition, which determines what patterns should be listened for, and an optional Execution Script, which defines what should happen when the TLML Syntax matches.

For example, you may have a Listener where:

  • The TLML Syntax is set to match the name of a city, e.g. %TO.FW.LEX >> %CITY.ENTITY^{destination = lob.city}
  • The Execution Script finds airports close to the city, e.g. nearbyAirports = AirportChecker.findAirports(destination)
OVERWRITING VARIABLES

Be careful not to accidentally overwrite variables with the use of Global Listeners. For example, creating a Global Listener that stores the name of a user in the variable 'userName' whenever a name is encountered is risky, as it might accidentally overwrite 'userName' if several names are mentioned in the input.

In general, it is best to use a Flow Listener for the Flow where you specifically anticipate receiving a particular detail and only use Global Listeners to listen for things that transcend flows.

Global Pre Listeners vs Global Post Listeners​

There are two types of Global Listeners, pre matching Listeners and post matching Listeners. The difference between the two is the execution order:

  • Global Pre Listeners are run before the user input is tested against triggers, so if the user input matches a Global Pre Listener, the Listener's Execution Script is executed immediately before any Flow is triggered.
  • Global Post Listeners are executed after a Flow is triggered.

Global Pre Listeners listen to inputs before Teneo tries to match the user input to a trigger or transition and are best suited when you want to do things that are important during matching. For example, you may want to add Annotations that can then influence if a particular trigger or transition should match.

USE CASE

A Global Pre Listener can first annotate a postal code in a user input and then use a TLML Syntax that says 'you should only match if a postal code is present in the input'. Because the annotation is added before Teneo tries to match the TLML Syntax, the annotation will be taken into account.

Global Post Listeners act on inputs directly after Teneo finds a matching trigger or a transition waiting for a new input. You can't use them during the matching process, because by the time the Post Listeners are executed, the matching process is already completed.

USE CASE

A Global Post Listener can check if the currently triggered Flow was stored in a particular folder, like the 'Flows' folder. If true, the Listener would then perform the task specified in the Listener's operation

This means that if you wish to perform an action before a Flow is triggered, you should use Global Pre Listeners, while Global Post Listeners should be used for those tasks which are performed after the user input has triggered a Flow.

Listener Ordering​

You can have multiple Listeners in a solution. The Listener Ordering allows the user to organize the order in which the Listeners are executed. Setting an execution order for the Listeners is crucial because it also dictates in which order the variables are populated.

For example, you may find the following ordering:

  1. In first position, a Listener that listens for a user's name and populates the value of the user name variable.
  2. In second position, a Listener that listens for a user's child's name and populates the value of the user's child name variable.

This means that the user name Listener listens first, waits for the variable value to be found (in this case, the user's name mentioned in the user input) and assigns it to the user name variable. Only after that would the second Listener start listening for the user's child's name in the user input, which is eventually assigned to the user's child name variable.

How To​

Open​

To open a Global Listener from the backstage of Teneo Studio, simply double-click the Listener; alternatively click the Edit button available in the right-side top of the view.

Close​

To close a Global Listener, either:

  • Click the X in the top, right corner of the Global Listener window
  • Click the Close button available in the top ribbon
  • In the Global Listener's backstage, click Close in the left-side menu

If there are unsaved changes, Teneo Studio will prompt the user to Save or Close without saving.

Create​

To create a new Global Listener, follow these steps:

  1. In the Global Listeners view, click Add and select Pre-Listener or Post-Listener in the dropdown.
  2. The new Listener window opens.
    • Write a Name and optionally a Description.
    • Click the back-arrow in the top left corner when done.
  3. In the TLML Syntax field, write the syntax that will be used when testing user inputs.
  4. In the Execution Script field, write - in Groovy - what the Listener should do when the TLML syntax is matched.
  5. If required, the following properties can be modified below the Execution Script field:
    • Test sentence from: select either Last to first (default) or First to last
    • Limit unused words to: tick this option to set the number of accepted unused words
    • Stop after: select between First match, Current sentences tested (only Global Post-Listeners) and All sentences tested
  6. Remember to click Save in the top ribbon.

Edit​

To edit a Global Listener in Teneo Studio Desktop, follow these steps:

  1. Navigate to the backstage view by clicking the Solution tab.
  2. Select Globals; this will open a window with all your Global Pre Listeners and Post Listeners.
  3. Click on the Listener you wish to edit; an editing section will open on the right.
  4. Click Edit (or Go to if you previously opened the Listener) and edit the Listener.
  5. Remember to Save the Global Listener to preserve the changes.

Save​

To save a Global Listener with a comment follow these steps:

  1. Click Save in the top ribbon of the Global Listener.
  2. Optionally, write a comment in the dialogue box.
  3. Click OK.

To save directly and bypass the comment, press the Alt key while clicking the Save button.

Delete​

To delete a Global Listener, follow these steps:

  1. In the backstage of Teneo Studio (Solutions tab > Globals > Listeners) select the Listener(s) to delete.
  2. Click Delete in the top, right side of the list.
  3. Teneo Studio prompts the user to confirm the deletion of the selected Listener(s).
  4. Click Yes to continue.

Read more about deletion and usage check here.

If a Global Listener is deleted by mistake, it can be restored from the Recycle Bin.

Order​

Listener Ordering is handled at the bottom of the Global Listeners view in Teneo Studio Desktop:

  1. Select the listener you want to move up/down by clicking the blue arrows in the right side of the list of Global Listeners.
  2. Remember to Save ordering to preserve the changes.
  3. Click Continue in the save prompt or Cancel to omit the changes.

You can also view previous versions:

  1. Select the version in the History window to view it.
  2. Set the previous version as stable by selecting it and clicking Set Stable in the top right corner of the History window.
  3. Restore a previous version by clicking Restore in the top right corner of the History window.
ORDERING MISMATCH

It is not possible to drag/drop from Pre to Post nor from Post to Pre, only within the given Listener type.

ORDERING UNAVAILABLE

The option to drag/drop only appears when two or more Listeners of the same type are available.

Filter​

To filter your Listeners in Teneo Studio Desktop, follow these steps:

  1. In an open solution, navigate to the backstage view and select listeners.
  2. Find the Filter Listeners bar on the left side and perform the search.

UI​

Global Listeners Overview​

global listeners view

In this view, you will find:

  • Left side:
    • Text filter
    • Add button
    • List of existing Global Listeners in solution
    • Listener Ordering including buttons to edit, view history, and set/unset stable
  • Right side:
    • Ribbon options allowing to Edit, Delete, view History, set/unset Stable version, include/exclude in branching (Localization setup)
    • Details of the selected Listener providing a read-only summary
    • Global Listener's Id

Global Listener Window​

When clicking Add or Edit, the Global Listener window will open; the window consists of two tabs: Listener allowing to access the backstage of the window and the Home tab presenting the main view of the the Global Listener.

The Home tab of the Global Listener window contains the following:

Global Listener Window

Top ribbon

SectionItemDescriptionRelated Pages
ListenerCloseClose the Global Listener window.
SaveSave the Global Listener in the current state; clicking the lower part of the button allows the user to save the Flow with or without a comment.
ExecutionOpen With...Allows to open the script in an external script editor; when the button is clicked for the first time the user will be prompted to select the script editor.
EditUndo/RedoUndo/redo changes performed in the Global Listener
Stable VersionSet/unsetSet the current version of the Global Listener as stable or unset itVersion Flags
BranchingInclude/ExcludeInclude or Exclude the Global Listener from branching when working in a Localization setup.Localization setup

Listener editor

SectionItemDescriptionRelated Pages
TLML Syntax EditorTLML SyntaxDefines TLML Syntax Match.TLML Syntax Match
Teneo Linguistic Modeling Language (TLML)
Execution ScriptExecution ScriptAn optional Groovy script that will be executed if TLML Syntax matches.Groovy basics
Advanced settingsTest sentences fromSelects how sentences in input are tested. Select 'First to last' if Engine should start testing at the first sentence and work forward, or leave the default 'Last to first' if Engine should test the last sentence first and move backwards.
Limit unused words toSpecifies a maximum number of words which the user input may contain (beside those matching the TLML syntax) for the match to be satisfied. The Listener will only execute if the TLML Syntax has fewer unused words than the defined limit.
Stop after*Determines when TLML Syntax will stop evaluating.

*The Teneo Engine stops testing sentences and user inputs once a match is found, but the Stop after setting allows to modify this behavior providing the following options:

  • First match (Default): testing is stopped when a match is found
  • All sentences tested: the TLML Syntax of the Global Listener is tested against all the sentences in the user input creating an array of results
  • Current sentences tested (only Post-Listeners): the TLML Syntax of the Global Listener attempts to match against the most recent syntax (the previous trigger or input consuming transition).

The Listener tab opens a Properties window consisting of a left-side menu with the following options and information:

img

ItemDescriptionRelated pages
SaveSave the Global Listener in the current state.
PropertiesAllows to edit the name and description of the Global Listener; the Id of the Listener is available in the lower area of the window.
HistoryLists the history and versions created each time the Global Listener is saved, comments added at save are displayed here. Open a previous version by clicking the version number; restore a previous version by opening the specific version and clicking Restore in the top ribbon.Version Flags
History
CloseClose the Global Listener window.

Listener Ordering​

note

The Listener Ordering is only available in the Global Listeners Overview in Teneo Studio Desktop.

Global Listener Ordering

ItemDescriptionRelated pages
EditOpens Listener Ordering in edit mode.
HistoryLists the history and versions created each time the Listener Ordering is saved. Comments added at save are displayed here.History
Version Flags
Set/Unset StableSet the current version of the Global Listener Ordering as stable or unset it.
SET STABLE

It is compulsory to set a version of the Listener Ordering to stable when using the Version flag feature of Teneo Studio.

Practical Examples​

Sentiment Detection​

Listeners can be used in multiple ways in Teneo. For this example, we will demonstrate how we can detect sentiment in Teneo and react accordingly when bad sentiment is detected.

Before our changes, we would have a conversation like this:

User: You are so bad. Bot: Really? That's very sad. I will try to perform better in the future.

After our modifications, it will look like this:

User: You are so bad. Bot: We do not condone this type of behavior. I understand that you're upset, but please don't speak to me that way.

To achieve this, we need to do the following:

Create a Global Variable​

First, we will create a Global Variable to store the user input sentiment.

  1. Navigate to the Globals section in the Solution backstage.
  2. Select Variables and click Add to create a new Global Variable.
  3. Give the Global Variable the name isUserNegative, an optional description, and set the initial value to false. This will turn to true if the variable is detected in the next step.
  4. Save the Global Variable.

Create a Global Listener​

We will create a Global Listener to only react to negative inputs from the user.

  1. Navigate to the Globals tab in solution backstage and open the Listeners section.
  2. Click Add and create a new Pre Listener.
  3. Add the name Negative Sentiment Detector, and optionally, a description for the Listener.
  4. Use the arrow in the top left corner to move to the Listener tab and edit the Listener.
  5. In the TLML field, paste in the following: %SENTIMENT_NEGATIVE_HIGH_CONFIDENCE.INDICATOR.
  6. Below, in Execution Script, add the following Groovy code: isUserNegative = true.
  7. Save the Listener.
info

The Teneo Sentiment NL Analyzer categorizes sentiment into negative, neutral and positive categories with either high confidence (clear, specific statements) or low confidence (partial statements or keywords that can vary according to context).

Teneo can detect five levels of sentiment:

  1. Negative High
  2. Negative Low
  3. Neutral
  4. Positive Low
  5. Positive High

Split the Path​

The next step is create a new Flow that will trigger once bad sentiment is detected with our Global Variable 'isUserNegative' turning from false to true.

  1. Navigate to the Flows folder and create a new Flow called Negative Sentiment Detected. Reuse the same name for the trigger node.
  2. Name the trigger Negative Sentiment Detected and add some positive examples in User Intent, such as:
    • You are so bad
    • Go to hell
    • This is the worst thing that ever happened
  3. In the Match section, add a Match for a Global Variable, and select 'isUserNegative'.
  4. Enter true as the 'Evaluation script'. This will cause the following intent to only trigger when actual bad sentiment from the user is detected.

Modify the Output​

Now we need to finish the flow by adding a fitting answer when the user is using negative sentiment.

  1. Navigate to the output node and name it Bad sentiment detected.
  2. Click edit to add the following answer: We do not condone this type of behavior. I understand that you're upset, but please don't speak to me that way.

Reset Sentiment Detector​

  1. Within the Flow, select the 'Scripts' symbol on the left to add a new Flow Script.
  2. Enter the following script: isUserNegative = false in the 'On Drop' section.
  3. Save the Flow.

Try it out​

Let's go ahead and test the Flow:

User: You are so bad.

Bot: We do not condone this type of behavior. I understand that you're upset, but please don't speak to me that way.