Augmenters

The options and functionalities described in this page currently only apply toTeneo Studio Desktop

Introduction

Analyzing and accessing conversational log data produced by the conversational AI application can be done using the Teneo Query Language; the log data is stored in such a way that it easily can be queried for analysis. However, some queries can be demanding, especially when they need to combine several fields or when they need to use Engine to compute and fulfill conditions.

Augmenters are new property fields stored along the log data that is generated by pre-calculations on existing log data. Augmenters extend default log data by enriching or summarizing it in a format that can later be accessed by standard queries. There are two types of augmenters: adorners and aggregators. Both adorners and aggregators are created in the backstage of a Log Data Source and can either be created using TQL or Groovy scripts.

For an overview of the Augmenters in the Log Data Source (Log Data Source window > Log Data Manager tab > Augmenters), please see here; this page describes the creation, application and usage of adorners and aggregators.

Please note that as of Teneo 7.5, the interpretation of date restrictions in augmenters is changed

Basics

Import

To import augmenters, follow the below steps:

• Open the Log Data Source window and go to the Augmenters in the backstage (Log Data Source tab > Augmenters)
• Click the Import button in the upper, right side of the window
• Browse to the compressed .zip file
• Select the file and click Open.

Export

To export augmenters, follow the below steps:

• Open the Log Data Source window and go to the Augmenters in the backstage (Log Data Source tab > Augmenters)
• Click the Export button in the upper, right side of the window
• Browse to the location where the file should be saved
• Give the file a name and click Save.

Note that the Export button is only enabled when augmenters have been created in the Log Data Source.

Reload

The Reload button, in the upper, right side of the window, allows to refresh the view of the augmenters.

Add

Adorners and aggregators are created very similarly and therefore this process will here be described together; for a description per type please see the Adorners and/or Aggregators sections further below on this page.

To add a new augmenter, follow the below steps:

• Open the Log Data Source window and go to the Augmenters in the backstage (Log Data Source tab > Augmenters)
• In the header of Adorners or Aggregators, click the Add button
• Select if the augmenter should be of type TQL (Teneo Query Language) or Groovy script
• The new augmenter window opens; the properties available in the window vary a little depending if it is an augmenter of type TQL or Groovy, please see the following two sub-sections for more information
• When done, click Save to preserve the changes
• Remember to perform the changes in the Pending Actions for the augmenter to be applied.

TQL Augmenter

When creating a new TQL adorner or aggregator, the following properties should be provided:

• Name of the adorner/aggregator
• Solution Revision the augmenter is only applied to logs belonging to these versions of the solution
• Date Range the augmenter is only applied to logs belonging to these date ranges
• TQL the command in Teneo Query Language that creates the augmenter(s)
• The keys, selections and constraints of the adorner/aggregator are generated after clicking Preview or Save.

Note on keys:

• Keys are generated automatically based on the TQL command
• It is recommended to follow the naming conventions
• Keys need to be unique, otherwise the augmenter will not be created.

Learn more on how to create TQL adorners and aggregators in the Details section further below.

Groovy Augmenter

When creating a new Groovy script adorner or aggregator, the following properties should be provided:

• Name of the adorner/aggregator
• Solution Revision the augmenter is only applied to logs belonging to these versions of the solution
• Date Range the augmenter is only applied to logs belonging to these date ranges
• Groovy script the command in Groovy that creates the augmenter(s)
• Adorner/Aggregator Keys these cannot use the words: "count", "date", "week" or "version"
• Adorner/Aggregator Selections (optional)
• Adorner/Aggregator Constraints (optional)

Learn more on how to create Groovy adorners and aggregators in the Details section further below.

Edit

To edit an augmenter, follow the below steps:

• Open the Log Data Source window and go to the Augmenters in the backstage (Log Data Source tab > Augmenters)
• In the Augmenters page, locate the adorner or aggregator to edit
• Click the down-pointing arrow button and select Edit in the far right side of the augmenter
• The Edit augmenter window opens, now perform all the needed updates
• Click Save to preserve the changes
• Remember to perform the changes in the Pending Actions for the augmenter to be applied.

Disable/Enable

To either Disable or Enable an augmenter, follow the below steps:

• Open the Log Data Source window and go to the Augmenters in the backstage (Log Data Source tab > Augmenters)
• In the Augmenters page, locate the adorner or aggregator to disable/enable
• Click the down-pointing arrow button and select the Enable/Disable button in the far right side of the augmenter
• Remember to perform the changes in the Pending Actions for the augmenter to be applied.

Delete

To delete an augmenter, follow the below steps:

• Open the Log Data Source window and go to the Augmenters in the backstage (Log Data Source tab > Augmenters)
• In the Augmenters page, locate the adorner or aggregator to delete
• Click the down-pointing arrow button and select the Delete button in the far right side of the augmenter
• Remember to perform the changes in the Pending Actions for the augmenter to be removed.

Pending Actions

When an augmenter (either of type adorner or aggregator) has been created, imported, edited or enabled/disabled, usually the changes are automatically applied to the augmenter configuration stored in Elasticsearch however, the data generated by the augmenters is not modified in the Log Data Source until it is manually updated in the Pending Actions section.

Therefore, after any changes to or creation of a new augmenter, it must be executed and then, those sessions that match the augmenter constraint are updated. In addition, when a solution revision and/or date range are provided in the augmenter definition, only those sessions that match these properties will be updated.

Once an augmenter is created and while it is enabled, any new session added to the Log Data Source is automatically augmented in the background without the need of any user intervention, regardless the new session is sent automatically from the conversational AI application or it is part of a synchronize action (i.e., sessions are reimported into a Log Data Source).

When an augmenter is disabled, a new Pending action appears, and on performing the action, the augmentation data is removed; i.e., adornments and aggregation data are removed.

Note that the Pending Actions panel is populated each time an augmenter is created or updated and hence it is possible to edit various different augmenters and wait till the end to apply them all at once, clicking Perform all.

Details

Interpretation of Date Restrictions

Teneo 7.5 comes with a change in the interpretation of date restrictions for augmenters; in previous Teneo versions, for augmenters with date restrictions, the "to" date was not applied to sessions on the "to" date, that is, the "to date" was excluded. As of Teneo 7.5, for newly created augmenters with date restrictions, the "to" date is applied to sessions on the "to" date, that is, the "to" date is included.

The augmenters with date restrictions created in previous Teneo versions will keep working with the excluded date restriction until a user edits and saves the augmenter in Teneo 7.5 after which the behavior of the augmenter with a "to" date will change to the new included behavior.

This changes means that once an augmenter with a date setting is saved by the user, the "to" date will be included, thus the behavior of an augmenter with a "to" date will change. This new behavior is persisted and also applies to augmenters newly exported and then imported. Note that augmenters imported from a file that was exported from a previous Teneo version will not change behavior, that is, if they have a "to" date it will still be exclusive. The user would need to edit and save such augmenter to achieve the new behavior.

Moreover, augmenters that were last saved before this release or imported from a file that was exported from a previous version, if they have a "from" date and were saved from Studio Desktop running in a time zone to the east of UTC+0 (GMT), when such augmenter is opened, the "from" date displayed will be the day before the originally saved date. So, the user must doublecheck the date settings of such old augmenters before saving them again. Once the augmenter is saved, the dates are correctly stored and retrieved.

So, in short, date restrictions on any "old" augmenter keep on behaving as in Teneo 7.4 (or previous versions) as long as the augmenter is not modified) i.e., edited and saved). Once the augmenter is saved again in Teneo 7.5, the date restriction will change as described above.

Adorners

As the name suggests, adorners allow to extend data by furnishing it with additional or more precise information in order to simplify a query syntax or speed up its performance. For instance, to single out all sessions with at least one user input falling into a Safetynet flow of a solution, an adorner can be created to add this property directly to the session level.

Adorners cannot be built on top of other adorners, to avoid dependencies between them, but they can be used within aggregators.

Once created, adorner data is stored along the rest of the stored log data (for a list of the specific log properties, see here). Therefore, it is possible to combine log properties with adornments in a single same query.

When creating adorners, the user should provide the adorner name and keys, where the name is just a user-friendly identifier, and keys are the names of the actual new properties stored along the rest of the log data. A single adorner can generate more than one adornment, each having their own key. In addition, the user can limit the creation of adornments to a data range and/or a solution revision range; see the Add section above for a step-by-step guide on how to add an augmenter.

Below please find examples of a TQL adorner and a Groovy script adorner.

TQL adorner

Adorners in Teneo Query Language (TQL) are created with the adorn

command.

In the below image, the adorner name is User correction, and the adorn TQL command creates two adornments: t.a.s:user_correction_target_flow

and t.a.s:user_correction_input

.

The query first finds all transactions (t1

) which fall into a safetynet

trigger, which are identified because they are stored in the Safetynet

folder. Then, from these, the query fiends the next transactions (t2

) that has a non-empty user input (t2.e1

) and checks that this user input did not go into another safetynet trigger (t2.e2

). The information stored in the adorner is: the name of the flow where t2

ended up, and the user input.

The adorn Teneo Query Language schematic syntax requires the following parameters:

1adorn key1 = selection1, key2 = selection2, .. : <TQL_condition>
2

Adornment keys must follow the below pattern:

1<LEVEL.a.TYPE:name>
2

where:

• LEVEL
  indicates if the property is stored at session s
  , transaction t
  , or event e
  level
• a
  stands for adorner
• TYPE
  indicates the data type (see table below): In the case of adorners of type array, the TYPE
  must following the pattern a:TYPE
  , where a:
  is the symbol for array and TYPE
  is the symbol describing the type of the element of the array
• name
  (following the colon) is the adornment property name which should be alphanumeric and cannot contain spaces nor punctuation marks.

Thus, adorners generate new properties with the following characteristics:

Groovy adorner

Adorners can also be created using a Groovy script without the need of using the Teneo Query Language. Groovy adorners are particularly useful when string processing or looping is required to obtain the intended adorner value.

Note that the adornment keys cannot be automatically calculated as in the case of TQL adorners, and needs to be filled in as well.

The key needs to follow the standard adornment key format, as explained in the TQL adorners section above.

1LEVEL.a.PREFIX:NAME
2

In this case, adorner selections and constraints are optional, but it is useful to indicate them for user friendliness.

The adorner code itself is written in the Groovy script box with the following generic syntax:

1def myVar
2session.getTransactions().each {
3	t -> t.getEvents().each {
4		e -> // do something to event, e.g.
5			// assign a value to myVar
6	}
7	callback.adornTransaction(t.getId(), "t.a.s:myKey", myVar)
8}
9

The Groovy code in the image below searched for events with the pathtype

"continue-flow" and stores the index and the flow name. Then, when it finds another event with pathType

"drop-flow", it checks if it is a subsequent event from the earlier one, in such case it is adorned if the flow name is the same as the previous one. The adornment key is at transaction level, named t.a.s:AbortedFlow

, and it stores the flow name of the second flow.

The following example creates a session adorner with the number of events per each session:

1def count = 0
2session.getTransactions().each {
3	t -> t.getEvents().each {
4		count++
5	}
6}
7callback.adornSession(session.getId(), "s.a.n:numberOfEvents", count)
8

Note the use of the adornSession

method to adorn transactions and the getTransactions

and getEvents

methods to retrieve transactions and events respectively. These are Teneo Platform specific methods provided to work with session log data. The table in the section Augmenter Groovy methods summarizes the list of available methods.

Query adorner

Adorners data (adornment keys) is stored along the standard log data, and can be queried like any other property in the query panel of the Log Data Source in Teneo Studio.

The following are examples of queries that retrieve the information stored with the adorners described in this section.

(1) la t.a.s:user_correction_target_flow,t.a.s:user_correction_input

(2) la t.e.userInput, t.a.s:AbortedFlow : t.a.s:AbortedFlow != "", t.e.type == "request"

(3) la s.id, s.a.n:numberOfEvents : s.a.n:numberOfEvents > 100

The following retrieves information from an adorner of type array of string (a:s

)

(4) la s.id, s.a.a:s:words : s.a.a:s:words == {“hi”, “hello”}

The following retrieves information from an adorner of type array of numbers (a:n

)

(5) la s.id, s.a.a:n:numbers : s.a.a:n:numbers ~~ {1, 2}

In addition, adorners definitions and the new property keys appear in the session viewer panel along the rest of the session properties:

Aggregators

Aggregators allow the construction of summaries over event, transaction, or session properties, including those generated by adorners. They simplify and speed up queries and post-query processing to obtain final counts. For example, an aggregator can be created at session level to store the number of inputs falling into the safetynet. These summary counts are automatically updated every time new data is added or imported into the Log Data Source.

Aggregators cannot be built on top of other aggregators in order to avoid dependencies among them. Once created, aggregated values are not stored along the rest of the regular log properties, but aside, as a detached division in the data structure. For this reason, they cannot be used directly as query constraints in regular queries. Instead, they can be used in sub-queries, which may serve the same purpose.

Aggregators counts are computed around dates

and keys

, which are defined by the user when the aggregator is created. A single aggregator can contain more than one key, e.g. one key contains the counts for each flow identifier, while another key has the counts for each folder name. That way it is possible to group several summary counts in a single aggregator, which in turn is identified by its name.

The aggregator name is a user-friendly id, while the aggregator keys

are used to store the data in the Log Data Source and hence must follow the below, specific pattern:

1<TYPE:NAME>
2

where:

• TYPE
  indicates the data type (see the above table for allowed values), and
• name
  (following the colon) is the key name provided when the aggregator is created.

Thus, aggregators data contain the following properties:

Note that as a result, date

, week

, version

and count

are reserved words that cannot be used as names in the aggregator keys.

Below please find examples of a TQL aggregator and a Groovy script aggregator.

TQL Aggregator

Teneo Query Language (TQL) aggregators are created with the aggregate command, and the TQL of an aggregator must follow the below schematic syntax:

1aggregate key1 = selection1, key2 = selection2 : <TQL_condition>
2

The example in the below image shows the creation of the aggregator "triggered Flows / Day" with the key s:triggeredFlowIdPerDay

(hence a session level count):

1aggregate s:triggeredFlowsIdPerDay = t.e.fid : t.e.pathType == "flow-trigger"
2

Groovy Aggregator

Aggregators can also be created using Groovy.

Aggregator Keys should be supplied manually as they cannot automatically be extracted from the Groovy code (as opposed to TQL)

Aggregator Selections and Aggregator Constraints are optional, but users are encouraged to provide these for user-friendliness.

The example in the following image creates an aggregator called "groovyagg" and generates the bucket counts s:flowIds

and s:id

. The Groovy code namely iterates over the list of events and aggregates those where pathType

is "flow-trigger".

The code in the image is also displayed in the following code piece:

1String sessionId = session.getValue("id")
2session.getTransactions().each {
3	it.getEvents().each {
4		String pathType = it.getValue("pathType")
5		if (pathType != null && pathType.equals("flow-trigger")) {
6			callback.aggregate(["s:flowIds":it.getValue("fid"),
7				"s:id":sessionId])
8		}
9	}
10}
11
12

Note the use of the getTransactions()

, getValue

and aggregate()

methods. These are Teneo methods to create the aggregations. the table in the Augmenters Groovy methods section summarizes the list of available methods.

Query Aggregator

The aggregated results are stored in separated namespaces. In order to query them, use the "a" command and provide the aggregator name. The syntax is the following:

1lu (a = "<aggregator name>") <aggregator key>
2

The examples below retrieve the data stored in the aggregators created in the previous section:

(1) lu (a = "groovyagg") s:flowIds, count

(2) lu (a = "groovyagg") s:id, count

(3) lu (a = "triggered Flows / Day") s:triggeredFlowsIdPerDay, count

In addition to the counts, aggregators store the session date

, week

, and version

, which can be also queried and used to further aggregate the results when combined with the distribute command.

See, for example, the difference among the following queries:

(1) d (a = "triggered Flows / Day") s:triggeredFlowsIdPerDay, count

(2) d (a = "triggered Flows / Day") week, s:triggeredFlowsIdPerDay, count

(3) d (a = "triggered Flows / Day") date, s:triggeredFlowsIdPerDay, count

(4) d (a = "triggered Flows / Day") version, s:triggeredFlowsIdPerDay, count

(5) d (a = "triggered Flows / Day") date, count

(6) d (a = "triggered Flows / Day") week, count

(7) d (a = "triggered Flows / Day") version, count

Export And Import of Augmenters

Augmenters definition can be moved between Log Data Sources. All augmenters in a specific Log Data Source can be exported to a zipped archive by clicking the Export button available in the top of the Augmenters page. Correspondingly, augmenters in an exported augmenter archive can be upload by clicking the Import button on the same page.

The zipped archive contains the augmenter definitions, where each augmenter is represented as a JSON file. The files in the archive can be modified or deleted, and therefore they can be modified before they are imported.

When augmenters are imported, they are stored but not automatically applied. However, the system will verify the correctness of the provided augmenters and invalid augmenters will not be imported.

Augmenter Groovy Methods

When writing Groovy augmenters, the user may need to explore and retrieve the data from the log store. Teneo Log Data provides the variable named session

that allows accessing the session data, and a collection of Groovy methods that allow exploring and retrieving its data content.

The following table summarizes these methods and where they can be used.

Teneo Log Data also provides some callback methods to fill in the adorner values and the aggregators. The following table summarizes these methods and their signatures: