Variable Management

Variables And Context Elements

In the Knovvu VA product, we keep various values belonging to the end user in a "memory" called context in order to manage the dialogue. In a scenario where money transfer is carried out with the IBAN information obtained from the user, the context ensures that the IBAN information is accessible and can be used.

If the user complete a main flow from start node to end node it counts as "turn". The context variables are cleared after each turn, except SentimentScore. This way, the user's experience between sessions can be distinguished.

Within the main flow, if user end an intent flow and comes back to main flow the variables related to the intent flow (like entites) are also cleared.

The variables in the context are categorized for ease of use and management. Each category of variables has different properties, which can be listed as key, value, and runtime value.

Key: It is the value that represents the variable in the user interface. It can be thought of as the name of the variable. In Figure 1, the keys for the highlighted context elements are companyId and Language, respectively.

Figure 1 Context List

Value: It corresponds to the value of the variable or the reference it holds. Here, the reference can be taken from an object held by a node output or an activity. When a static value is desired to be used, the variable value can only be a string. The Designer can set the values of dynamic type contexts.

Figure 2 Edit Dynamic Context Modal

Runtime value: The values that variables hold during a conversation. For example, the runtime value for phoneNumber dynamic context should be a phone number that we see during the conversation.

The runtime value holds the actual value that we see during the conversation while value holds a reference. It is important to keep this difference in mind when managing contexts.

1.1. Context Types

We can categorize variables in a context based on their usage, value type, and scope. These categories include static, dynamic, entity, and custom variables.

1.1.1. Dynamic Context

Dynamic context is used to hold key-value pairs which value might be an "activity object value" that has reference from activity object (see figure 5) or it can hold an array/string values defined by the user. In addition, the dynamic context variables can store HTTP Node outputs too.

Dynamic context is a type of variable in which the designer can manage the key and value pairs to shape the flow during the design phase. It is represented with a green color in the context panel. When using dynamic context, it is important to keep in mind the concepts of key, value, and runtime value mentioned in the previous section.

To create a new dynamic context, you can use the % icon next to an input field that allows context usage in the nodes of the flow. By clicking on the % and + icons in order, you can open the modal to create a new dynamic context.

Figure 3 Adding Context

Value mostly holds a reference to an object. When the values inside the node output that carries an object are set to the context values using dot notation, the context holds the reference to that object's value, not the value itself. This is because the expected value inside the object can change during the conversation based on the user inputs. Therefore, holding the reference of the object in the design phase ensures that the runtime value of the variable is up to date throughout the conversation.

Figure 4 Create Context Modal

When creating a dynamic context, value can also be referenced from the activity object which is used by Knovvu Orchestrator during service-to-service communication. When the "select element from activity" dropdown in Figure 5 is clicked, the content of the activity object is displayed. The key and value fields are automatically filled in with the selected key from the activity object.

Figure 5 Select context value from activity

Dynamic context can only hold static string values in addition to object references. The reason for this is that the value is not designed to hold a value that will be directly displayed in the chat. The value should be given in single quotes. Dynamic context should not be used if the aim is to perform operations on numeric values.

Figure 6 Dynamic context with constant value

If numeric value representation is intended in the chat, it can be given within a string and used in the context prompt.

Figure 7 Numeric value within a string

When operations are desired to be performed on numeric values, the result obtained through code or variable node should be assigned to dynamic context within the node. This context can be used at different points where it is needed.

Figure 8 Assigning numeric value to dynamic context

New values can be assigned to dynamic contexts that hold object references using code or variable nodes.

Figure 9 Assigning new value to dynamic context

The scope of a dynamic context created depends on the type of flow it belongs to. Dynamic contexts created in action flows can only be used within the scope of the flow they are created in. Variables created in the main flow or subflows of a project can be shared across all project flows. Additionally, they can be accessed from the action flows of virtual agents in the project.

Previously created dynamic contexts can be deleted if they are not used in the flow. To delete a context that is being used, it must first be removed from all the places it is being used. If we try to delete a context that is being used, an error toaster will appear indicating how many flows it is being used in.

1.1.2. Static Context

Static context is a type of context variable provided by the application, which cannot be deleted and is colored in navy blue. Its runtime value is set by the application, and attempting to change this value by assignment in the designer can have unintended consequences and is not recommended.

1.1.3. Entity Context

Entity context consists of orange-colored variables that have a key and a runtime value. In action flows, entity contexts that bear the names of the entities in their corresponding intents are automatically created. The value cannot be set by the designer and key is equal to entity name. Their runtime values are set by the application based on the results obtained from the NER service. Designer can set entity runtime value to undefined by using variable node to make ask missing slot question to be asked. They cannot be directly deleted and are removed from the context list if they are not used in the flow and their associated entity is deleted.

Figure 10 Assigning undefined to entity context

1.1.4. Custom Context

Custom context refers to the gray-colored variables in the application. It differs from the other three entity types in many ways. There are three ways to create a new custom context:

1. Using node output: After the node is executed, a custom variable with the name entered in the node output is created, and the output of the node is assigned to this variable.

2. Using Code node: Variables that are created and assigned a value within a Code node without using the const, let, var keywords are considered as custom context variables.

3. Using Variable node: Variables that are created and assigned a value within a Variable node are considered as custom context variables.

Custom context differs from the other three context types in two important ways:

1. Scope: Custom contexts can be accessed in all project-VA flows that are related to each other.
2. Clearing variable values: Since variables are created freely without using const, let, var keywords, managing/clearing their values is not possible. Therefore, their values are not cleared after the main flow loop is finished or the intent is fulfilled. This can cause errors in the next session.

1.1.5. Receiving Location From Whatsapp User

It is possible to receive location and use the related location in the flows.

You need to create 2 custom entities and use reference from activity object

For the latitude:

For the longitude:

After creating the variables you can use it in flows:

1.2. Usage of Context

The % icon is located on the right-hand side of the node input fields enables the use of context elements. Clicking on this icon provides access to the context list. The selected variable is added to the input field. As a more practical way, when % is typed in the input field and the variable name is started to be written, context options are presented in a list format. The selected context is added to the input field. The value of the added context dynamically changes during the conversation.

The usage of context in output fields is more limited. It can only be used to assign a value to the Rating static context in the ask node output. The prerequisite here is that one quick reply type of response has been added to the ask node. The selected quick reply button value is assigned as a value to the Rating static context.

Figure 11 Survey example

1.2.1. Usage of Code Node

It is important to handle operations related to context variables in the code node to prevent errors during the preparation of the context for the next turn. Variables created within the node should use the let, var, const keywords. When these keywords are not used, the variables become global, otherwise they remain within the node scope. It is recommended to use the keyword when creating variables and to take them out of the node using dynamic context.

Accessing the context in the code node is different from other nodes. Different types of variables under the context can be accessed using dot notation. Examples of this are: context.static.LastUserInput, context.dynamic.key, context.entity.entityName for static, dynamic, and entity, respectively.

There is no restriction on assigning values to variables, but it is not recommended to assign values to static and entity variables because they are managed by the application. To assign values to dynamic context, an assignment operation is performed: context.dynamic.key = value. Static and entity context values can be assigned to dynamic context if necessary.

Figure 12 Assign value to dynamic context using code node

To extract a variable/value used in the code node and to take it outside of the node, a dynamic context is created for the variable used. The value of this dynamic context variable should be null, otherwise the operations performed in code node may not be successful. Later, the variable/value to be extracted from the code node is assigned to the previously created dynamic context.