Data model

Introduction

This section explains in more details how the data model is structured and the type of data that is generated and used and may help understanding how to perform Teneo Query Language (TQL) queries.

Log Data Sources

Querying in the Teneo Platform is scoped to a single Log Data Source (LDS) at a time. A Log Data Source is a configurable container in the data layer which stores and indexes all the logs that are generated by a particular conversational AI application during a specific timeframe, as well as other user-generated data.

Log Data Sources are created by the data manager, for more information please see the Data manager section.

The content of a Log Data Source is structured as shown in the figure below:

A Log Data Source consists of the following types of data:

• Engine generated data (i.e. the logs), which are organized around sessions, transactions, and events
• User-generated data
• Augmenters, which extend the default log data
• Solutions, which are used for Engine-matching queries
• Saved Results, which stores on-demand the results of queries performed by the user.

The different sorts of data are described in more details in the following sections.

Teneo Engine logs

Whenever a published conversational AI application is used, the conversation with the end-user is logged, storing not only the user inputs and the system outputs, but also information about the processing path performed by the application.

Log files consist of a set of sessions, which are made up of a series of transactions and events.

Thus, a session in the log file contains the full conversation between the end-user and the conversational AI application. Every dialogue turn in the conversation is represented in the log as a transaction, which starts upon a user request, and ends when the application returns a response.

Transactions consist of a set of events, which contain no only the user input and the system output, but also the information about the processing path performed by the application, namely the same information that can be obtained when using the Tryout panel in Teneo Studio.

Log properties

All data logged from sessions, transactions and events is modelled in the Teneo Platform as session, transaction or event properties. Examples of these properties are the beginning time of the session, the name of a traversed flow, or the value of a flow variable.

Certain properties, such as variables and metadata, are logged by the Teneo Engine every time their value is updated. Therefore, they appear in the logs several times, first with the value they are initialized to (i.e. their default value), then for any subsequent values they attain along the transaction path, and/or the conversation. For instance, if a variable without an initial value is modified during the session, it will appear on different transactions with two different values. These variables can hold a value of any type, e.g. a string, a number, or an array.

All property values are indexed and handled using the following data types:

• Analyzed string: a string that has been tokenized and normalized before indexing. As a result, a list of tokens represent the original string, e.g. user input
• Keyword: a string that has been indexed as-is (unmodified), e.g. flowname
• Data: a timestamp with the format yyyy-MM-ddTHH:mm:ssZ, e.g. session begin time. Note that all dates and times are stored in UTC time zone
• Long: an integer value, e.g. transaction duration
• Boolean: a Boolean value, e.g. annotation's variable typed Boolean
• Double: a Double value, e.g. annotation's variable type Double
• Object: an object with named attributes, in JSON format, e.g. collection of request parameters.

The list of log properties is given in details in the following subsections. Session and Transaction properties are always generated (except for the properties related to variables and metadata), while properties related to events are only logged if said event takes place. For information on the timeline of log properties, please see the Log Timeline section.

Additional properties, such as those generated by augmenters, will be explained in the section User-generated data.

Logging Session and Flow variables

Session and Flow variables are updated using scripts in Teneo. These variables are logged by the Teneo Engine every time a new value is assigned to the variable. Thus, when the variable contains an object, the object instance must be re-assigned in order to log any change. In contrast, when changing just the value of its content the variable update is not logged because it has not been assigned.

See the table below for some examples.

Thus, variables must be re-assigned with a new instance of the object in order to get the value to be logged.

Additional information about how these variables are imported and can be queried in Teneo Studio can be found in the Teneo Query Language manual.

Session properties

Session logs can have the following properties:

Transaction properties

Transactions can have the following properties:

Event properties

In the Teneo Platform, events are always nested under transactions and hold information that is not directly attached to sessions or transactions.

There are three types of events:

• Request events, they correspond to the inputs sent from the user to the Engine, namely user inputs
• Path events, they represent Engine's processing path between the reception of the request and the generation of the response, e.g. triggered flow, listeners, or scripts
• Response events, these are the responses coming from the Engine to the user, i.e. the answer of the conversational AI application.

Each transaction contains at least one Request event at the beginning, a Response event that ends the transaction, and one or more Path events for Engine's processes.

Common event properties

The following properties belong to all event types:

Request event specific properties

On top of the Common properties, Request events also have the following properties:

Path event specific properties

Path events capture the different actions taken on the Engine side. They are indicated by the string property pathType

and can be divided into three sub-types, corresponding to script actions, flow stack manipulation, and listener / flow execution.

There are no separate Path events for junctions and integrations due to the way these are logged. Junctions are logged as (empty) script nodes while integrations are logged as sub-flows, which corresponds to how they are handled by the Engine.

Path events related to scripts

Session-script Path event properties

These include global session events.

Flow-script Path Event properties

It corresponds to the flow events onTop and onDrop.

Variable-change Path Event properties

It indicates a side-effect variable change.

Path Events related to flow stack manipulation

Raise-flow Path Event properties

This event takes place when a flow is added to the stack.

Pause-flow Path Event properties

This event takes place when a flow is "paused", i.e. another flow becomes the active flow.

Continue-flow Path Event properties

This event takes place when a transition is matching and therefore the flow stays on top.

Resume-flow Path Event properties

This event takes place when a flow is resumed after being paused.

Drop-flow Path Event properties

This event takes place when a flow is dropped from the stack.

Input-processor-results Path Event properties

This event takes place once the input processor has been executed and the results are available.

Path Events related to flow/listener execution

Flow-trigger Path Event properties

This event takes place when a flow trigger matched.

Listener Path Event properties

This event takes place when a listener was executed.

Output Path Event properties

This event takes place when an output node was traversed.

Transition Path Event properties

This event takes place when a transition was traversed.

Script Path Event properties

This event takes place when a script node was traversed.

Flow-node Path Event properties

This event takes place when a flow node was traversed.

Annotations

Annotations may be created in the processing paths of the following types of Path event: input-processor-results

, session-script

, or listeners

.

They have the following properties:

Response Event specific properties

User-generated data

A Log Data Source may also contain user-generated data such as Augmenters, solutions for Engine matching, or Saved Results from queries.

Augmenters

Augmenters are new property fields 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.

Augmenters can only be created in the Teneo Log Data Manager frontend, using either Teneo Query Language (TQL) or Groovy. And, once created, they can be edited, disabled, or deleted.

The following sections introduce adorners and aggregators, but for more information please see the Augmenter section.

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, in order to single out all sessions with at least one user input falling into the safetynet 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, in order to avoid dependencies between them; but they can be used within aggregators.

Once created, adorner data is stored along the rest of properties listed in the Teneo Engine Logs section above. Therefore, it is possible to combine log properties with adornments in a single same query.

Adorner properties name follow the following, specific 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 below table)
• name
  (following the colon) is the adorner name provided when it is created.

Thus, adorners generate new properties with the following characteristics:

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 imported.

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 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. However, they can be used in sub-queries, which may serve the same purpose.

Aggregator's counts are computed around dates and the keys indicated by the user when the aggregator is created. A single aggregator can contain more than one key, e.g. one key which contains the counts for each flow identifier, and another key which has the counts for each folder name. That way it is possible to group several summary counts in a single aggregator.

The aggregator keys 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.

Solutions for Engine matching

The Teneo Platform also supports Engine matching constraints; to use them, a Teneo solution needs to be uploaded to the Log Data Source in Teneo Studio. In the context of Log Data, please note that an Engine solution is a .war file generated by Teneo Studio via Publish, for more information please see the Queryable solutions section.

Uploaded solutions are always linked to a single Log Data Source; if the same solution is needed in different Log Data Sources, the user will need to upload it to each of the Log Data Sources. By circumscribing a solution to a Log Data Source, undesired solution updates that may affect other users are avoided.

On the other hand, it is possible to upload different revisions of the same solution by just naming them different revisions of the same solution by just naming them differently within the Log Data Source. That way it is possible to compare Engine matching results provided by the two solution revisions.

For more information regarding how to use solutions in Engine matching Teneo Query Language constraints, please refer to the Queryable solutions section.

Saved Results

The Teneo Platform allows saving query results so they can be reused in subsequent queries. Saved Results can be used for obtaining intermediate results that can then be used in later queries, or to save final results that can be pulled out by other applications, such as Business Intelligence tools, or just keep them for future reference.

Saved Results are not stored along the rest of the data properties. Thus, its content is neither updated nor removed when a Log Data Source is re-imported, or its configuration changed.

For more information on how to store, use and manage Saved results, please refer to the Log Data Manager section and the Teneo Query Language manual.

Appendix Log Timeline

Logs exist ONLY if the solution generates them. The log sequence described in this section is approximate and may vary depending on the solution.

Session

A session with inputs and responses contains one or more transactions, as shown in the following diagram:

Upon the reception of user input, the first request is generated, logging information regarding the beginning of the session and the first transaction. For each transaction, the system logs the beginning and the duration of said transaction. All transactions have the same structure, which will be explained in the following subsection.

However, within the first transaction, transaction 0, there is an initialization header that may contain the logs of the following events (in order):

• session variables initialization: a single event that contains all session variables that are initialized with a default value. The following Teneo Query Language (TQL) example retrieves the initial value of a particular session variable named <NAME_1> which is assigned a string (s:
  ):

1listAll e.sv:s:<NAME_1> : e.pathType == "variable-change", e.change-type == "initialization" 
2

• begin dialog global script: this event reports the execution of the global begin dialog script if exists, along with any session variable change. The following TQL example retrieves the value of a particular session variable named <NAME_1> that has been updated within the begin dialog script, and has been assigned a string (s:
  ):

1listAll e.sv:s:<NAME_1> : e.pathType == "session-script", e.vname == "beginDialog"
2

• new session global script: this event reports the execution of the global new session script if exists, along with any session variable change. The following TQL example retrieves the value of a particular session variable named <NAME_1> that has been updated within the new session script and has been assigned a string (s:
  ):

1listAll e.sv:s:s<NAME_1> : e.pathType == "session-script", e.vname == "newSession"
2

Transactions

Transactions have the following phases:

Reception of the Request

When user input is received, a Request event is generated, and the transaction starts. Very roughly, a series of Path Events (i.e. the processing path) occur that lead to the evaluation of the triggers in the solution and the generation of a response. These path events vary depending on the input and how the solution is built.

The example below corresponds to a request followed by pre-processing and pre-matching session events, plus a global pre-listener, before trigger evaluation takes place.

Response

If no matches occur, or once the processing path has been completed because the transaction has consumed all user input, the system executes a last session script (named postProcessing) and, optionally, may modify one or more variables' values. The Response is generated, and the control is then returned to the user.

Processing path

The processing path varies slightly depending on the success of triggers, which depend on the input and the solution itself, or the estate of the flow stack. This section provides a few, non-exhaustive examples of typical processing paths that may occur in Teneo Studio.

If no triggers in the solution are matched, the system will proceed to finish the transaction, seeResponse section, and Path Event properties are logged ONLY if the event has occurred!

Basic flow processing when the flow stack is empty

If a condition is met, a flow is raised (which generates a path event of type raise-flow) and added to the flow stack. Then, the request begins to be processed, generating a log chain such as the one pictured below:

In general terms, this sequence of events takes place when processing a flow:

• The flow starts with:
  • a raise-flow path event
  • a session_script path event
  • a flow_script path event associated to raising the flow
• The flow is executed
• The flow terminates with:
  • a session_script path event associated to dropping the flow
  • a flow_script path event associated to dropping the flow
  • a drop-flow path event.

Sub-flows and Integrations

If a flow (flow A) contains a sub-flow or an integration (henceforth flow B), the parent flow begins the execution as usual until it is interrupted by flow B, generating the following set of events:

Where:

• Flow A is raised as described in the previous section
• when the sub-flow or integration kicks in, flow A is paused, and flow B is raised - note that the sequence of events when raising and dropping a sub-flow or integration is different from those taking place in a regular flow and are described below
• Flow A is resumed, being processed from the point where it was paused.

The execution of a sub-flow or integration, shown below, is slightly different from a regular flow:

In case of sub-flows or integrations, the following path events occur:

• a raise-flow path event
• a session-script path event (onTop)
• a script path event
• a session-script path event (onDrop)
• the execution of the sub-flow/integration
• a drop-flow path event.

As mentioned, Flow A is then resumed from the point where it was paused.

Order of listeners

Listeners are always active but only act (i.e. they execute an action, such as changing the value of a variable) when there is a match with the user input. There are several types of listeners, which work in this order:

• Global Pre-listener happens before any trigger matching
• Global Post-listener is evaluated right after a raise-flow event and right before any flow listener
• Flow listeners are evaluated after the trigger matching (raise-flow) and Global Post-listener, if any
• Trigger listener are evaluated after any transition through the flow.

In the following example, a request is received and, before any trigger is evaluated, the preProcessing and preMatching session scripts are executed. Then, the Global Pre-listener comes into action if its condition is matched before any flow-trigger matching happens.

A flow is triggered and raised, and then the rest of listeners act (of course, if their condition is matched). Finally, the flow execution carries on with the session and flow script path events, as explained in previous sections.

Output parameters and Response

The following example shows the events that happen when the conversational AI application generates an output - note that it may generate a response by traversing several output nodes separated by other transitions.

In this case, the execution of the flow results in the generation of outputs, then the flow is dropped.

Post-processing takes place and the Response is generated.

Related topics

Querying in the Log Data Source
Teneo Query Languages (TQL)