Global Variables

Global Variables, as opposed to Flow Variables, are accessible by all Flows in a solution and have an unlimited validity, meaning that Global Variables can hold data that is persistent during the session and only expires when the session ends or times out.

This section covers the following topics:

• Concept
• How To
• UI
• Practical Examples

Concept

Global Variables can hold data that is persistent during the session and only expires when the session ends or times out. They are accessible for reading and writing from all Flows and global documents, such as Listeners, Contexts or Integrations, as well as from most script events in your solution, making it possible to assign and pass on dynamic information throughout an entire session. In that way, they differ from Flow Variables, which only exist during the processing of a Flow, and will be forgotten as soon as a Flow is dropped from the flow stack.

In a general context, variables are placeholders for changeable values and can be of any type that Groovy (and Java) supports, for example strings, booleans, maps, Integers, lists, and custom objects.

info

A Global Variable lives for the entire session, or until it is reset, whereas a Flow Variable is forgotten as soon as a Flow is dropped from the flow stack.

Data Scope

Variable changes are automatically logged whenever the variable reference is changed during a transaction. This allows support for deeper debugging and reporting on specific types of sessions.

The process of logging this data, however, is automatic. Therefore, there are a number of things which should be considered in the solution design to prevent excessive or sensitive data from being automatically recorded, such as:

• If the information is of sensitive nature, such as API keys, tokens, passwords etc., the best practice is to use Secrets instead.
• When data is the same for all sessions and doesn't change over time, use a static property in a class defined in Solution Loaded script instead.
• If the information is part of the dialog history, instead extract it only if and when it is actually needed.

Naming conventions

There are various naming conventions related to computer programming and variable names, for example, snake_case or camelCase, and it is common for a team to use a convention which makes the names easy to read and understand for everyone.

Within the Teneo Platform, the scripting language is Groovy, which makes use of camelCase; furthermore, Java describes the use of camel case in their Java Language Basics (see last bullet point).

For Teneo solutions, the following recommendation are the following:

• Variable names must be unique within the solution.
• Use lower camelCase.
• Use a short yet meaningful name that communicates the purpose of its use to the reader.

Examples of valid variable names include user, userName, userFirstName, companyName, month, hour.

Lifespan

By default, the value of a Global Variable lives for the entire session, or until it is reset. You can, however, make a Global Variable forget its value after a specified number of turns. The variable will then be cleared and get back its default value. In Teneo this is called 'setting the lifespan' of a variable. A common use case is to remember something the user says in one Flow, so that it can be used in another Flow.

If you have a Global Variable called topic, you would set its lifespan like so:

_.setSessVarLifespan('topic', 2)

You would typically set the value and its lifespan at the end of a Flow. In this example, the lifespan is set to two turns, but you are free to choose whatever value you see fit.

The lifespan includes the request/input that is currently being processed. Each subsequent request (or input or turn) will consume one of the lifespans and when the lifespan reaches 0, topic will be reset to the value that was used when it was initialized.

note

Any Flow can overwrite the value of the Global Variable at any time and give it a new lifespan.

How To

Create

Teneo Studio Desktop

To create a Global Variable, follow these steps:

1. Navigate to the Global Variables section in the backstage of Teneo Studio (Solution tab > Globals > Variables).
2. Click Add next to the text filter.
3. In the right side of the screen, write a Name and optionally a Description.
4. Next, provide the Value of the variable.
5. Click Save in the top to preserve the changes.

Teneo Studio Web

To create a new Global Variable, follow these steps:

1. First, either:
   • Click the Create button next to Variables in the Globals tile on the Solution dashboard, or
   • In the view of Global Variables, click on Create New Global Variable.

2. The Edit global variable opens, now give the Global Variable a Name and optionally write a description.
3. Write the Variable value in the last field.
4. Click Create.
5. Next, optionally write a comment and click Save again to confirm the addition of the new Global Variable.

Edit

Teneo Studio Desktop

To edit a Global Variable, follow these steps:

1. In the list of Global Variables, select the Variable to edit.
2. Click Edit (right side of the screen above the Variable's summary).
3. Now, update the Name, Description and/or Value as needed.
4. Remember to Save the changes when done, or alternatively click Cancel to discard the changes and exit the edit mode.

Below please find an overview of more editing options available in the ribbon when working with Global Variables.

Teneo Studio Web

To edit a Global Variable, follow these steps:

1. Go to the list of Global Variables (Solution dashboard > Globals tile > Variables).
2. In the list, select and click the Variable to edit.
3. Now, in the Edit Global Variable view, perform the needed modifications.
4. Remember to Save the Variable to preserve the changes.

Save

Teneo Studio Desktop

When a Global Variable is in edit mode, the Save button becomes available in the ribbon above the details of the Variable itself; click Save to save with comment or alternatively press Alt and click Save to bypass the comment.

Teneo Studio Web

To save a Global Variable in edit mode, follow these steps:

1. Click Save at the bottom of the Edit global variable view.
2. Optionally add a comment for the Version History.
3. Click Save again to confirm.

note

The Save button only becomes clickable in the Edit global variable view when changes are performed to an already existing Global Variable or if the Global Variable has not been saved earlier.

info

Successful save is confirmed with a "Document saved successfully!" message; by clicking elsewhere in the browser window the message is closed.

Close

Teneo Studio Desktop

In Teneo Studio Desktop, the view of a Global Variable in edit mode is closed by either clicking Cancel or Save to preserve any possible modifications.

Teneo Studio Web

To close a Global variable without modification simply click the x in the upper right side of the Edit Global Variable view; to close with modifications click Save.

Delete

Teneo Studio Desktop

To delete a Global Variable, follow these steps:

1. Select the variable(s) to be deleted. Multi-select is available by pressing Ctrl while selecting.
2. Click Delete in the top-area of the screen.
3. Note that the right side of the screen will now display a Variable delete pending view, which the user should either Cancel or Apply for each of the selected variables for the actual deletion to be performed.

warning

If Teneo Studio detects that the Global Variable is in use, the user is prompted to confirm a Force delete or to Cancel the deletion.

Teneo Studio Web

To delete a Global Variable in Teneo Studio Web, follow these steps:

1. Navigate to the list of Global Variables (Solution dashboard > Globals tile > Variables).
2. Hovering over the Variable in the list, an icon of a recycle bin appears in the right side of the browser window, click on it.
3. The user is prompt to confirm the deletion of the Global Variable:
   • Click Delete to perform usage check before deletion
   • Check Do not check usage and click Delete to delete without performing a usage check
   • Click Cancel to abort the deletion.

Read more about deletion and usage check here.

note

The deletion of a Global Listener currently cannot be undone in Teneo Studio Web. For this action, please refer to the Recycle Bin available in Teneo Studio Desktop.

Filter

Teneo Studio Desktop

A text filter is available at the top of the list of Global Variables. To filter on the available variable, simply write the desired letter combination to start filtering on the list.

Teneo Studio Web

A text filter is available in the top ribbon of Teneo Studio Web which allows to filter on the displayed list of documents. Simply write the desired letter combination to start filtering on the list.

The filter works on the following columns: Name, Description, Value, and Author.

Clicking the column headers allows to sort the list of documents alphabetically when clicking the Name, Description, Value, or Author header; when clicking Updated it is possible to sort by the date/time the documents were updated or created.

UI

View of Global Variables

Teneo Studio Desktop

The Global Variables are available in the backstage of Teneo Studio by clicking the Solution tab in the main window of Teneo Studio, then Globals and lastly Variables.

In this view, the user will find:

• Left side:
  • Text filter
  • List of existing Global Variables
• Right side:
  • Ribbon options; read more in the table below.
  • Details of the selected Variable providing a read-only summary
  • Global Variable's Id

Button	Description	Related pages
Edit	Allows to open the Global Variable in edit mode.
Search - Search by Variable Name	Allows to search through all places a variable can be used when referenced by name, for example, in scripts, Output Answers, etc.
Search - Search by Variable Reference	Allows to search through trigger/transition Match requirements and After Match actions, Flow Link and Integration transfer Variables
Delete	Provides the option to delete a Global Variable.	Delete Global Variable
History	Opens the History of the selected Global Variable; previous versions and revisions of the Global Variable are listed, comments added at save are also displayed here. Select any of the revisions to view its content.Set a previous version as stable by selecting it in the list and clicking Set Stable, restore a previous version by selecting it and clicking Restore.	Version Control
Set/unset stable	Set the current version of the selected Global Variable as stable or unset it.	Version Flags
Include/Exclude	Include or Exclude the selected Global Variable from branching when working in a Localization setup.	Localization setup

Teneo Studio Web

The Global Variables are available on the Solution dashboard in the Globals tile; clicking the right-pointing arrow takes you to the list of Global Variables.

In this view, you will find:

• The list of existing Global Variables (if any)
• Option to order the list per column header
• Create button allowing to create a new Global Variable
• Text filter available in the top ribbon

Global Variable Window

Teneo Studio Desktop

When adding or editing a Global Variable, a window will open on the right side:

Section	Description	Related pages
Name	Add a name for the variable.
Description	Add a description for the variable.
Initial Value	Set initial value of the variable; set as "" if empty.
Branching	Include or Exclude the selected Global Variable from branching when working in a Localization setup.	Localization setup

Teneo Studio Web

Section	Description
Name	Add a name for the variable.
Description	Add a description for the variable.
Variable Value	Set initial value of the variable; set as "" if empty.

Practical Examples

Share Information between Flows

Just as in human conversations, the user will assume your bot remembers what they recently have been talking about. Here you will learn how to make your bot remember information from one Flow to another.

Consider the following conversation:

User: Which coffee would you recommend? (Flow: User wants bot to suggest a coffee)

Bot: Easy choice, a flat white of course!

User: I'll go for one of those then. (Flow: User wants to order a coffee)

Bot: Ok, a flat white will be ready for pickup in 5 minutes.

This conversation combines two flows: 'User wants bot to suggest a coffee' and 'User wants to order a coffee'. In the first Flow, the bot recommends a 'flat white'. This coffee type is remembered. When the second Flow is triggered and the user asks for "one of those" the bot understands that a 'flat white' should be ordered. In other words, 'flat white' is mentioned in one Flow, and then used in another!

This logic can be applied to a variety of contexts.

To make sure a Global Variable works in two Flows, you should:

• Create a Global Variable.
• Make sure a Flow populates the Global Variable.
• Make sure another Flow retrieves the Global Variable and triggers on inputs.

Create a Global Variable

Teneo Studio Desktop

First we will create the Global Variable to hold the variable:

1. Create a Global Variable and give it a name. Assign it the value "". This Global Variable will be able to store any string value and be used by any Flows in the solution.
2. Return to the main solution view.
3. In the Tryout panel, a message to 'Reload now' appears. After clicking it, you will be able to use the Global Variable in your Flow.

We now have a Global Variable which we can use to store any string value and in which turn can be used by other Flows.

Teneo Studio Web

First we will create the Global Variable to hold the coffee type:

1. Create a Global Variable and give it a name. Assign it the value `"". This Global Variable will be able to store any string value and be used by any Flows in the solution.
2. In the Tryout window, a message to Reload now appears. After clicking it, you will be able to use the Global Variable in your Flow.

We now have a Global Variable which we can use to store any string and in which in turn can be used by other Flows.

Assign Flow Variable to Global Variable

Teneo Studio Desktop

To assign a Flow Variable value to a Global Variable, we will add a script in the Flow's 'On Drop' script event. Scripts in 'On Drop' are executed when the Flow has finished and is about to be dropped from the Flow stack.

In the script, we will first assign the Global Variable the value of the Flow Variable. However, we do not want the Global Variable to be remembered forever. Just like humans do not keep things in focus forever, your bot should not either. Once the variable is set, we will use a special method to specify that the value should be forgotten after a couple of turns (input-output turns). In Teneo that is called setting the lifespan of a variable.

note

This example assumes you have a Flow Variable which you want to turn into a Global Variable.

Let's update the Flow:

1. Open your Flow in edit mode.
2. Click on the FLOW tab.
3. Select Scripts, and then click On Drop.
4. Populate the script field with the following lines and your Flow Variable name and Global Variable name.

   // Save flow variable in global variable
   globalVariableName = flowVariableName
   
   // Set the lifespan of the global variable
   _.setSessVarLifespan('globalVariableName',2)
   

5. Hit Save and close the Flow.

Teneo Studio Web

To assign a Flow Variable value to a Global Variable, we will add a script in the Flow's 'On Drop' script event. Scripts in 'On Drop' are executed when the flow has finished and is about to be dropped from the flow stack.

In the script, we will first assign the Global Variable the value of the Flow Variable. However, we do not want the Global Variable to be remembered forever. Just like humans do not keep things in focus forever, your bot should not either. Once the variable is set, we will use a special method to specify that the value should be forgotten after a couple of turns (input-output turns). In Teneo that is called setting the lifespan of a variable.

note

This example assumes you have a Flow Variable which you want to turn into a Global Variable.

Let's update the Flow:

1. Open a Flow.
2. Click on the Scripts button.
3. Populate the script field with the following lines and your Flow Variable name and Global Variable name.

   // Save flow variable coffeeSuggestion in global variable coffeeTypeInFocus
   coffeeTypeInFocus = coffeeSuggestion
   
   // Set the lifespan of the global variable
   _.setSessVarLifespan('coffeeTypeInFocus',2)
   

4. Hit Confirm and save the Flow.

Ensure Flow Retrieves the Global Variable

Teneo Studio Desktop

Now we will move on to retrieve and use the variable within a Flow. First, we need to make sure that the Flow triggers on inputs referring to the variable, such as "I'll go for one of those then" (see conversation above). The new trigger will therefore include a context restriction stating that the Global Variable must carry a value for the trigger to be applied.

Let's create the trigger:

1. Open a Flow in edit mode.
2. Click on the Plus icon next to the trigger and add a new Intent Trigger. This will add an additional trigger to the Flow.
3. Name the trigger and add a few example intents.
4. Add a Match for TLML Syntax and define the inputs that should be linked to the Global Variable. This could look something like the following syntax, where references like "one of those" or "it" are linked to the Global Variable coffeeTypeInFocus:

   (
       (%I.FW.LEX &^ %WANT.VB.LEX &^ (one/%IT.FW.LEX))
       /
       (%I_WILL.PHR &^ %GO_FOR.VB.MUL &^ %IT.FW.SYN) 
   )^{ orderedCoffeeType = coffeeTypeInFocus }
   

5. Now we will add the context restriction. Click on Add in the Match section.
6. Select Global Variable and select the Global Variable that you created earlier.
7. Hit Save.

Teneo Studio Web

Now we will move on to retrieve and use the variable within a Flow. First, we need to make sure that the Flow triggers on inputs referring to the variable, such as "I'll go for one of those then" (see conversation above). The new trigger will therefore include a context restriction stating that the Global Variable must carry a value for the trigger to be applied.

1. Open a Flow.
2. Click on the Plus icon next to the trigger and select A trigger based on end user intent in the input.
3. Name the trigger and add a few example intents.
4. Beneath this new trigger, click on the Plus icon and add a Match for when a TLML Syntax rule matches the input. Define the inputs that should be linked to the Global Variable. This could look something like the following syntax, where references like "one of those" or "it" are linked to the Global Variable coffeeTypeInFocus:

   (
       (%I.FW.LEX &^ %WANT.VB.LEX &^ (one/%IT.FW.LEX))
       /
       (%I_WILL.PHR &^ %GO_FOR.VB.MUL &^ %IT.FW.SYN) 
   )^{ orderedCoffeeType = coffeeTypeInFocus }
   

5. Now we will add the context restriction. Click on the plus beneath the TLML Syntax field at the bottom of the new Match node.
6. Select a given Global Variable value matches a script condition and, in the dropdown, select the Global Variable that we created earlier.
7. Hit Save.

Populate the Flow Variable

We will now make sure that the Flow Variable is populated with the value stored in the Global Variable when the new trigger kicks in. You can do this in at least two different places: either you attach a script directly to the trigger's language condition, or you add a Flow Listener.

Here we will go for the former and attach a script snippet to the language condition.

An attached script is executed when the condition it is attached to has matched the input. The Flow Variable will therefore be set to the value of the Global Variable when the condition is evaluated to true and our new trigger kicks in. This way, we can skip the questions we already have answers to, such as "what coffee type do you want" (see the conversation above).