Extract values with Augmenters

Teneo Inquire stores and retrieves highly detailed transactional records from running conversational AI applications. Augmenters are used to extend the default log data by enriching or summarizing it in a format that can be accessed by standard queries. These have the benefit of both simplifying the subsequent querying and increasing performance. One use-case is to mark key flows of the solution, making it easier to get statistics on how many of these are completed or aborted.

In this page we will learn how to create the two types of augmenters, and how key flows can be annotated and counted:

• Adorners
• Aggregators

Prerequisites

Before you can use the dashboard you need to have the following:

A published solution with data

Conversations that you have with your bot in Try Out are not stored in your bot's data repository. Before you can use augmenters, it is recommended that your solution is published and data is generated by interacting with your bot online. Also make sure that your environment is running by either logging into Teneo Studio or the console.

Teneo Inquire URL

The Teneo Inquire URL looks like this:

You should replace [your team name] with the name of your team. You can find it in the top right corner when you log in to your environment in the browser.

Access Log Data Source

The first step is to access the Log Data Source where we can create our augmenters.

1. Inside Teneo Studio Desktop, click on the 'Log Data' tab. (Alternatively, if you have opened a solution, go into the solution backstage and navigate to the 'Optimization' tab, where you can select 'Log Data'.)
2. Click on 'Manage' next to the desired LDS, followed by 'Open'.
3. In the newly opened LDS window, click on the 'Log Data Source' tab, followed by 'Augmenters'.

Create an Adorner

Augmenters can be created with several different purposes. For this example, we will create an adorner for the Longberry Barista solution to extract when the key flows in the solution has been raised and dropped, and when a completion point was reached.

1. Start by locating the 'Augmenters' section.
2. You will now see a 'Log Data Source' navigating to 'None'. Click on it and select the relevant solution; in our case, this is the longberry_baristas_XXX solution.

Once a 'Log Data Source' has been selected, two new panels will show up: Adorners and Aggregators. The difference between these is explained here.

3. Go ahead and select 'Add' followed up with 'Groovy script Adorner' under the 'Adorner' section. There is also an option to create Teneo Query Language based Adorners. This is not relevant for our case.
4. Give the adorner a name, like Issue adorner
   .

Now it is time to add a Groovy script to access the valuable information located inside our solution.

5. Copy the following code and paste it under 'Groovy script'

1    def issuesStarted = [:]
2    def issuesCompleted = [] as HashSet
3    def issuesAborted = [] as HashSet
4
5    // List of flow ids that represent relevant flows
6    def flowIdsToTrack = ["INSERT_FIRST_FLOW_ID", "INSERT_SECOND_FLOW_ID"] as HashSet
7    // List of vertex ids that represent when above flow should be considered completed
8    def endFlowVertexIds = ["INSERT_FIRST_FLOW_VERTEX_ID", "INSERT_SECOND_FLOW_VERTEX_ID"] as HashSet
9
10    session.transactions.each { t ->
11        t.events.each { e ->
12            def flowInstanceId = e.getValue('flow-instance-id')
13            def flowId = e.getValue('fid')
14            def pathType = e.getValue('pathType')
15            def flowName = e.getValue('fname')
16
17            if (pathType == "raise-flow" && flowId in flowIdsToTrack) {
18                issuesStarted[flowInstanceId] = flowName
19                callback.adornTransaction(t.id, 't.a.s:issueStarted', flowName)
20            } else if (pathType == "drop-flow" && flowId in flowIdsToTrack) {
21                if (e.getValue('vid') in endFlowVertexIds) {
22                    issuesCompleted.add(flowInstanceId)
23                    callback.adornTransaction(t.id, 't.a.s:issueCompleted', flowName)
24                } else {
25                    callback.adornTransaction(t.id, 't.a.s:issueAborted', flowName)
26                    issuesAborted.add(flowInstanceId)
27                }
28            }
29        }
30    }
31
32    issuesStarted.entrySet().each { entry ->
33        def flowInstanceId = entry.key
34        def flowName = entry.value
35
36        if (issuesCompleted.contains(flowInstanceId)) {
37            // Issue was completed
38            callback.adornSession(session.id, 's.a.s:issueCompleted', flowName)
39        } else {
40            // Issue was aborted
41            callback.adornSession(session.id, 's.a.s:issueAborted', flowName)
42
43            // If the session ended before the flow was drop, we mark the last transactions as the aborting point
44            if(!issuesAborted.contains(flowInstanceId)) {
45                callback.adornTransaction(session.transactions.last(), 't.a.s:issueAborted', flowName)
46            }
47        }
48    }
49

Replace the flow ID

Now we need to replace the ID from the Groovy script above that is located in line 6. This is the placeholder for a flow ID. In this example, we will use the Longberry Baristas solution and locate the business-critical flows to track. Let us go through the steps to achieve this:

1. Open up your 'Longberry Baristas' solution that's included in your Teneo environment, and open up the 'User wants to order a coffee' flow.
2. While inside the flow, click on the 'Flow' button located in the top left corner to open up the flow backstage window.
3. Located at the bottom of the 'Properties' section is the ID. Copy it and replace INSERT_FIRST_FLOW_ID in line 6 with the ID you just copied.
4. Close the solution and open up the 'User wants to buy a coffee mug' and do the same thing, but this time replace INSERT_SECOND_FLOW_ID in line 6 with the ID you find there.

The 'Properties' tab and flow ID can be found here:

Replace the vertex ID

Now that we have replaced the flow IDs from line 6, it is time to replace the following IDs in line 8. This time we will need to access the node at the end of the flow to ensure a full happy path was taken without any interruptions. In order to achieve that, we need to do the following:

1. Open up the 'User wants to order a coffee' flow.
2. Locate down to the last output node named 'Summarize order' and right click followed up with 'Copy ID to clipboard'.
3. Now it is time to replace the INSERT_FIRST_FLOW_VERTEX_ID with the ID you just copied.
4. Do the same thing with 'User wants to buy a coffee mug' flow and replace the INSERT_SECOND_FLOW_VERTEX_ID with the vertex ID from 'I have reserved a coffee mug for you'.

Adornment Keys

We are in the last step of creating a working adorner. The last step is to create your own Adornment Keys to use as a shortcut when working inside your solution to retrieve information.

1. Paste in the following line s.a.s:issueCompleted, s.a.s:issueAborted, t.a.s:issueStarted, t.a.s:issueCompleted, t.a.s:issueAborted
2. Click on the 'Preview' button to try out your adorner. This will test your adorner and warn you if there are any issues.

If issues are found, please repeat the steps taken above.

3. Finally, go ahead and save your adorner.

Congratulations, you have now created your first adorner! Now, it is time to use this adorner and retrieve information in Inquire using Teneo Query Language.

Retrieve information from the logs

It is finally time to go back to our 'Longberry Baristas' solution and use the newly created adorner to retrieve som valuable information. In this specific section, we are intrested to know when the business critical flows are triggered and finished with a happy path, without any interruptions.

1. Open up your solution 'Longberry Barista' that comes together with a Teneo environment.
2. While inside the solution, select the 'SOLUTION' button located in the top left corner. This will take you to the solution backstage.
3. Select 'Optimization', followed by 'Log Data'.
4. Expand the 'Manage' button and open up the relevant 'Log Data Source'.

A brand new window will open up where the user is able to use Teneo Query Language in order to run queries and analyze the solution. We will now go ahead and see how often our business-critical flows were used thanks to the adorner we built.

5. Paste in the following query: la s.beginTime, s.a.s:issueCompleted
   . This lists all of the times one of the two flows we chose were triggered.

If we are interested in more specific data we can access when a business-critical flow was interrupted by a different flow together with the input that caused the business-critical flow to be interrupted.

6. Paste in the following query: la s.id as 'Session ID', t.time as 'Time', t.a.s:issueAborted as 'Aborted issue', t.e2.fname as 'Flow', t.e1.userInput as 'User input' : t.e2.pathType == "raise-flow", t.e1.type == "request"

To be able to retrieve information as per the steps above, don't forget to ensure the solution is published, data has been generated as a result of the bot being interacted with, and the Teneo server has been started (you can make sure it has been started by lodding into Teneo Studio).