In Teneo, all conversations with the bot are stored in the Log Data Source(LDS). These conversations can be accessed using queries written in Teneo Query Language TQL to extract useful information for dashboards and reports that describe conversational project properties relevant to business or project development. The data logs are a rich data source which can be used to extract facts and insights on bot performance.
Valuable information in the logs in Teneo are retrieved using queries which are written in Teneo Query Language (TQL). These queries can be improved with the use of Augmenters.
What Are Augmenters Used for?
Augmenters are used to enrich the data logs. They can be created in the Teneo Log Data Manager using either Teneo Query Language or Groovy. An advantage of using augmenters is that they can even be used to enhance logs from the past ; this is a handy feature especially when you need to make changes coping with additional business requirements, or simply adjusting mistakes in tracking logs from the past.
Two Types of Augmenters
Augmenters can be of two types: adorners and aggregators.
By creating adorners, you can add labels to the logged data and use them to query information from the sessions. In addition, you can design adorners that extend or add information to the logs. Aggregators create a numeric summary over time. You can apply adorners and aggregators at session, transaction, or event levels in the data logs. In our documentation we describe the specific pattern for naming an adorner and an aggregator key. Check out our detailed reference documentation on how to create adorners.
Augmenters are used to extend the data with information to help simplify query syntax since they act as labels that can be reused in different queries and improve performance because once the augmenters are applied, they are applied to all the data in the LDS no matter when the data has been logged.
Enhance Data Logs with Augmenters: Examples of Augmenters
Here you have some commonly usage of adorners and aggregators with example:
TQL Adorner: put commonly used TQL constraints in an adorner to optimize your query
Sometimes you may have several lines of TQL constraints which are usually used together. In this case, a TQL Adorner can convert them into one single adornment key which makes your query cleaner, for example the following TQL Adorner:
adorn s.a.b:snHit = true : t.e.pathType=="raise-flow", t.e.fid=="86cc7642-1bb0-4d06-be29-99b2cf4c714a"
This Adorner generates a boolean type adornment key s.a.b:snHit which is true when the constraints of t.e.pathType and t.e.fid are both met . It can be used in different queries such as the following one which counts all sessions containing SafetyNet hit:
ca s.id : s.a.b:snHit=="true"
Where fid stands for Flow ID and it can be found in the flow properties window as shown in this image below.
Groovy Adorner: build a query with constraint “A OR B”
You can use Groovy adorners to create OR type relations and store the results inside a single key for your TQL queries. For example, if you want to count all sessions starts before 9:00 or after 15:00, you need the following Groovy Adorner:
import java.text.SimpleDateFormat
SimpleDateFormat dt = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'")
SimpleDateFormat time = new SimpleDateFormat("HH:mm:ss")
def beginTime = time.format(dt.parse(session.getValue('beginTime')))
def start = "09:00"
def end = "15:00"
def outsideHours = beginTime < start || beginTime > end
callback.adorn(session, 's.a.b:outsideHours', outsideHours)
Please remember that if you need something like flow name is A or B, you can use the “in” operator instead of Groovy Adorner:
t.e.fname == in {“flow A”, “flow B”}
Groovy Adorner: generate information which requires calculation
Out of the box, TQL provides you with some calculation query types, such as, mean and sum. A Groovy Adorner can further enhance this and add information to the logs to perform the calculation you need for a specific project. Here is an example of how to get session duration in seconds through Groovy Adorner:
import java.text.SimpleDateFormat
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'")
def beginTime = sdf.parse(session.getValue('beginTime'))
def endTime = sdf.parse(session.getValue('endTime'))
def sessionDuration = (endTime.getTime() - beginTime.getTime())/1000
callback.adorn(session, 's.a.n:sessionTime', sessionDuration)
Groovy Adorner: extract information which requires iterate all transactions of one session
Groovy Adorner is very useful to extract information which you won’t know unless you iterate all transactions in the same session. For example, the following adorner will generate a Boolean type Adornment key ** t.a.b:isLastTransaction** to all transactions, in which only the last transaction of the session will get the value True:
int nLastTransactionIndex = session.transactions.size() - 1
boolean isLastTransaction = false
session.transactions.each{ t->
if (t.index == nLastTransactionIndex) {
isLastTransaction = true
} else {
sLastTransaction = false
}
callback.adornTransaction( t.getId(), 't.a.b:isLastTransaction' , isLastTransaction )
}
TQL Aggregator: aggregate an adorner
The most common use of Aggregators is to summarize your data in numeric results. The following is an example of TQL Aggregator called Triggered Flow which counts the number of each flow triggered in each session and saved in the key called s:triggeredFlows:
aggregate s:triggeredFlows = t.e.fname : t.e.pathType == "flow-trigger"
After creating this Aggregator and applying the change to your log data, you can use it in TQL queries like the following example:
d (a = “[Aggregator_Name]”) date, [Aggregator Key]
Fill in the Aggregator name and the Aggregator key in the query above to count how many times a certain flow has been triggered each day. This is how it looks like in Teneo Studio:
Conclusion
Chun-Lin Wang and Mary Yako created this article to shed the light on Augmenters in a Teneo-based solution describing their role and properties. We summarize a description of the two types of augmenters, namely, adorners and aggregators. In addition, we provide five practical examples of augmenters covering both types: adorners and aggregators.
What types of augmenters are you using in your queries? Would you like to see other examples of them? Tell us more in the comment section.