Session Data model
This page explains how the session data model is structured and the type of data that is generated and used and may help understand how to perform Teneo Query Language (TQL) queries. For more details on how to query a Log Data Source in Teneo Studio, please visit the Log Data pages and the Teneo Query Language Manual.
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 this page.
The content of a Log Data Source is structured as shown in the figure below:
A Log Data Source can consist 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 store 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 not only the user input and the system output, but also information about the processing path performed by the application, namely the same information that can be obtained when using the Tryout 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 the 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 time, 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., flow name
- Date: a timestamp with the format yyyy-MM-ddTHH:mm:ssZ, e.g., a 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 typed Double
- Object: an object with named attributes, in JSON format, e.g., a 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, are 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 below table for some examples.
Variable change | Engine log | Comments |
---|---|---|
username=”John Doe” | Yes | Variable username is assigned with a new value |
date=new Date() | Yes | Variable date is assigned with a new Date object having the current time |
date.setTime(10000) | No | The value of the date object is updated but it is not logged because the date object is still the same. |
date=(new Date()).setTime(10000) | Yes | Variable date is logged because it is assigned a new instance of a Date |
itinerary=[ origin: ”BCN”, destination: ”STO”] | Yes | Variable itinerary is logged because it is assigned a new map object |
itinerary.origin=”LON” | No | Variable itinerary change is not logged because the object has not been re-assigned |
new_itinerary=itinerary.clone() new_itinerary.origin=”LON” itinerary=new_itinerary | Yes | Variable itinerary change is logged because it has been re-assigned with a new map object |
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 properties outlined in the below table.
Name | Type | Comments and Value constraints |
---|---|---|
beginTime | date | Timestamp, session's first transaction begin time |
botname | keyword | Name of the published solution which generated the data |
continuedFrom | keyword | Session continued from a previous session, session id of the previous session is displayed |
endTime | date | Timestamp, session's last transaction end time |
engineVersion | keyword | Teneo Engine version, e.g., 6.2.1, 7.0.3, 7.1.0 |
eventCount | long | Number of events in the session |
id | keyword | Unique ID of the session |
solutionRevision | keyword | Revision number of the solution |
solutionStatus | keyword | Available values latest, stable |
studioVersion | keyword | Teneo Studio version, e.g., 6.2.1, 7.0.3, 7.1.0 |
transactionCount | long | Number of transactions in the session |
lv:NAME | keyword | Log variable assigned in session, NAME is as set in Teneo Studio, e.g., lv:LAST_FLOW_SESSION |
md:NAME | keyword | Metadata assigned to the session at session level |
sv:TYPE:NAME | keyword | A session variable updated in this session, NAME is as set in Teneo Studio, e.g., sv:s:sCommand; logged every time it gets a new value |
Transaction properties
Transactions can have the following properties:
Name | Type | Comments and Value constraints |
---|---|---|
duration | long | Timespan of the transaction in milliseconds , i.e., time required by Engine to process the user input and generate the answer |
id | keyword | Unique id of the transaction |
index | long | The transaction's index within the session (starts at 0) |
time | date | Timestamp of transaction begin time |
md:NAME | keyword | Metadata assigned to this transaction, queryable by metadata name |
lv:NAME | keyword | Log variable assigned in this session; NAME is set as in Teneo Studio, e.g., lv:OUTPUT_NODE_IDS |
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 which correspond to the inputs sent from the user to the Engine, namely user inputs
- Path events which 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 which 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:
Name | Type | Comments and Value constraints |
---|---|---|
eventIndex | long | Any integer >= 0 |
type | keyword | Event type: request, event, path Specifying the event type may not always be strictly necessary but can nevertheless be done for performance reasons to make queries more efficient |
fv:TYPE:NAME | keyword | Flow variable updated in this event; NAME is set as in Teneo Studio, e.g., fv:s:sTripDestination Logged every time it gets a new value |
md:NAME | keyword | Metadata variable; NAME is set as in Teneo Studio Logged every time its value is assigned |
sv:TYPE:NAME | keyword | Session variable updated in this event; NAME is as set in Teneo Studio, e.g., sv:s:sTopic Logged every time it gets a new value |
Request event specific properties
On top of the Common event properties, Request events also have the following properties:
Name | Type | Comments and Value constraints |
---|---|---|
requestParameters | object | Contains a map with all the parameters passed to Teneo Engine along the user input Its contents are queryable by using the NAME of any attribute in the map, e.g., e.requestParameter.pageURL |
userInput | keyword | Actual string sent to Teneo Engine |
userInputWords | analyzed string | The same as userInput, but stored and indexed as an analyzed string |
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.
Name | Type | Comments and Value constraints |
---|---|---|
pathType | keyword | This property is not always strictly necessary but can nevertheless be done for performance reasons to make queries more efficient pathType can be any of these types of path evens, organized into 3 groups: Related to scripts (session-script, flow-script, variable-change) Related to flow stack manipulation (raise-flow, pause-flow, continue-flow, resume-flow, drop-flow, input-processor-results) Related to flow/listener execution (match-requirement, data-action, flow-trigger, listener, output, transition, script, flow-node) |
Path Events related to scripts
Session-script Path Event properties
These include global session events.
Name | Type | Comments and Value constraints |
---|---|---|
script-event | keyword | Valid values: beginDialog, newSession, onTop, onDrop, preProcessing, preMatching, postProcessing, timedOutSession |
script-id | keyword | Id of the script |
vname | keyword | Name of the script |
Flow-script Path Event properties
Corresponds to the flow events onTop and onDrop.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow that holds the script |
flow-instance-id | keyword | flow-instance-id of the flow that holds the script |
fname | keyword | Name of the flow that holds the script |
folder | keyword | Folder of the flow that holds the script |
vname | keyword | Name of the script limited to flow script types in Teneo Studio onTop and onDrop |
Variable-change Path Event properties
Indicates a side-effect variable change.
Name | Type | Comments and Value constraints |
---|---|---|
change-type | keyword | Values limited to initialization, change and reset |
Path Events related to flow stack manipulation
Raise-flow Path Event properties
This event takes place when a flow is added to the stack.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow that is raised |
flow-instance-id | keyword | flow-instance-id of the flow that is raised |
fname | keyword | Name of the flow that is raised |
folder | keyword | Folder of the flow that is raised |
vid | keyword | Id of the vertex where the flow is raised |
vname | keyword | Name of the vertex where the flow is raised |
Pause-flow Path Event properties
This event takes place when a flow is "paused", i.e., another flow becomes the active flow.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow that is paused |
flow-instance-id | keyword | flow-instance-id of the flow that is paused |
fname | keyword | Name of the flow that is paused |
folder | keyword | Folder of the flow that is paused |
vid | keyword | Id of the vertex where the flow is paused |
vname | keyword | Name of the vertex that is paused |
Continue-flow Path Event properties
This event takes place when a transition is matching and therefore the flow stays on top.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow that is continued |
flow-instance-id | keyword | flow-instance-id of the flow that is continued |
fname | keyword | Name of the flow that is continued |
folder | keyword | Folder of the flow that is continued |
vid | keyword | Id of the vertex where the flow is continued |
vname | keyword | Name of the vertex where the flow is continued |
Resume-flow Path Event Properties
This event takes place when a flow is resumed after being paused.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow that is resumed |
flow-instance-id | keyword | flow-instance-id of the flow that is resumed |
fname | keyword | Name of the flow that is resumed |
folder | keyword | Folder of the flow that is resumed |
vid | keyword | Id of the vertex where the flow is resumed |
vname | keyword | Name of the vertex where the flow is resumed |
Drop-flow Path Event properties
This event takes place when a flow is dropped from the stack.
Name | Type | Comments and Value constraints |
---|---|---|
aborted | keyword | Valid values are true and false; true if the flow is forcefully dropped via scripting |
fid | keyword | Id of the flow that is dropped |
flow-instance-id | keyword | flow-instance-id of the flow that is dropped |
fname | keyword | Name of the flow that is dropped |
folder | keyword | Folder of the flow that is dropped |
stuck | keyword | Valid values are true and false; true if the flow is dropped because it was stuck |
vid | keyword | Id of the vertex where the flow is dropped |
vname | keyword | Name of the vertex where the flow is dropped |
Input-processor-results Path Event properties
This event takes place once the input processor has been executed and the results are available.
Name | Type | Comments and Value constraints |
---|---|---|
consistency-error | keyword | Contains the error message and the stack trace if the invocation of an input processor threw an exception |
consistent | keyword | true if consistency-error is empty, that is, no error happened, otherwise false |
Path Events related to flow/listener execution
Match-requirement Path Event properties
This event takes place when a Match (requirement) was matched.
Name | Type | Comments and Value constraints |
---|---|---|
match-requirement-id | keyword | Id of the Match |
match-requirement-type | keyword | Match type, valid values are syntax, class, entity, languageObject, script, context |
parent-id | keyword | Id of the transition or trigger where the Match is defined |
parent-type | keyword | Valid values are transition, intent-trigger |
used-words | keyword | Whitespace-separated list of words |
vname | keyword | Name of this Match |
Data-action Path Event properties
This event takes place when an After Match is matched.
Name | Type | Comments and Value constraints |
---|---|---|
data-action-id | keyword | Id of the After Match |
data-action-type | keyword | After Match type, valid values are entity, languageObject, listener, script |
parent-id | keyword | Id of the transition or trigger where the After Match is defined |
parent-type | keyword | Valid values are transition, intent-trigger |
used-words | keyword | Whitespace-separated list of words |
vname | keyword | Name of this After Match |
Flow-trigger Path Event properties
This event takes place when a flow trigger matched.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow for this flow trigger |
flow-instance-id | keyword | flow-instance-id of the flow for this flow trigger |
fname | keyword | Name of the flow for this flow trigger |
folder | keyword | Folder of the flow for this flow trigger |
used-words | keyword | Whitespace-separated list of words |
vid | keyword | Id of this flow trigger |
vname | keyword | Name of this flow trigger |
triggerType | keyword | Type of flow trigger; valid values are intent-trigger, prompt-trigger |
Listener Path Event properties
This event takes place when a listener was executed.
Name | Type | Comments and Value constraints |
---|---|---|
execution-order | keyword | Valid values are pre and post |
folder | keyword | Folder of the flow for this listener |
fid | keyword | Id of the flow for this listener |
fname | keyword | Name of the flow for this listener |
flow-instance-id | keyword | flow-instance-id of the flow for this listener |
listener-type | keyword | Valid values are global, flow, flow-trigger and transition |
vid | keyword | Id of this listener |
vname | keyword | Name of this listener |
used-words | keyword | Whitespace-separated list of words |
Output Path Event properties
This event takes place when an output node was traversed.
Name | Type | Comments and Value constraints |
---|---|---|
emotion | keyword | Emotion of this output node |
fid | keyword | Id of the flow for this output node |
flow-instance-id | keyword | flow-instance-id of the flow for this output node |
fname | keyword | Name of the flow for this output node |
folder | keyword | Folder of the flow for this output node |
max-revisits | long | Maximum number of times an output node can be used |
output-id | keyword | Id of the selected output |
output-text | keyword | Text of the output |
output-parameters | keyword | Output parameters |
revisits | long | Number of times an output node has been used along the session |
revisitable | keyword | Valid values are true and false; true if the output node is revisitable (up to Teneo Platform 4.1 logs only) |
skipped | keyword | Valid values are true and false; true if the output node is skipped |
url | keyword | Url the application navigates to, if logged |
vid | keyword | Id of this output node. |
vname | keyword | Name of this output node. |
Transition Path Event properties
This event takes place when a transition is traversed.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow for this transition |
flow-instance-id | keyword | flow-instance-id of the flow for this transition |
fname | keyword | Name of the flow for this transition |
folder | keyword | Folder of the flow for this transition |
input-consuming | keyword | Whether the transition is input consuming or not; valid values are true and false |
vid | keyword | Id of the transition vertex |
vname | keyword | Name of the transition vertex |
Script Path Event properties
This event takes place when a script node was traversed.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow for this script node |
flow-instance-id | keyword | flow-instance-id of the flow for this script node |
fname | keyword | Name of the flow for this script node |
folder | keyword | Folder of the flow for this script node |
vid | keyword | Id of this script node |
vname | keyword | Name of this script node |
Flow-node Path Event properties
This event takes place when a flow node was traversed.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | Id of the flow for this flow node |
flow-instance-id | keyword | flow-instance-id of the flow for this flow node |
flow-node-type | keyword | Valid values are subflow and routing |
fname | keyword | Name of the flow for this flow node |
folder | keyword | Folder of the flow for this flow node |
target-flow-id | keyword | Id of the flow where to hop on from the current flow |
target-flow-name | keyword | Name of the flow where to hop on from the current flow |
vid | keyword | Id of this script node |
vname | keyword | Name of this script flow node |
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:
Name | Type | Comments and Value constraints |
---|---|---|
action | keyword | Valid values are added, removed or updated |
name | keyword | Name of the annotation either given by the input processor or by the user depending on how the annotation is created |
sentence-index | keyword | Assuming the user input is split in several sentences, it indicates which sentence the annotation belongs to; it is 0 if the user input contains a single sentence |
variables | Map<string,typedObject> | It provides additional information about the annotations, e.g., confidence score, sentence length, etc. Variables are logged every time they get a new value |
word-indices | long | Assuming the sentence can be split into several words or tokens, it contains which words hold the annotation |
Response event specific properties
Name | Type | Comments and Value constraints |
---|---|---|
answerText | keyword | Actual string returned by Teneo Engine |
answerTextWords | analyzed string | Same as answerText, but it is analyzed during indexing |
emotion | keyword | Name of the emotion returned by Teneo Engine |
viewVariables | object | Contains a map with all the response parameters returned by Teneo Engine along the system answer. Its content is queryable by using the NAME of any attribute in the map, e.g., e.viewVariables.url |
User-generated data
A Log Data Source may also contain user-generated data such as Augmenters, Saved Results from queries, etc.
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 suggest, adorners allow to extend the 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 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 with 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 property names follow the below, specific pattern:
tql
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 at creation.
Symbol | Type | Supported in... |
---|---|---|
b | Boolean | Adorners and aggregators |
bin | binary | Adorners and aggregators |
d | date | Adorners and aggregators |
gp | geo_point | Adorners and aggregators |
n | integer number (mapped as long) | Adorners and aggregators |
f | floating point number (mapped as double) | Adorners and aggregators |
s | string | Adorners and aggregators |
a | array | Adorners only |
Thus, adorners generate new properties with the following characteristics:
Name | Type | Value constraints |
---|---|---|
<LEVEL.a.TYPE:name> | Boolean, binary, date, geo_point, long, double, keyword, array | Integer numbers are indexed as Long, and Strings are indexed as keywords |
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 they 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:
tql
1<TYPE:name>
2
where:
- TYPE indicates the data type (see the above table for values), and
- name (following the colon) is the key name provided on creation of the aggregator
Thus, aggregators data contain the following properties:
Name | Type | Value constraints |
---|---|---|
count | long | Number of times that <PREFIX:name> matches its condition on <date>. |
date | date | The day for which the counts are calculated, formatted as yyyy-MM-dd. |
<PREFIX:name> | Boolean, binary, date, geo_point, long, double, keyword | Integer numbers are indexed as Long, and Strings are indexed as keywords. |
version | long | Version number of the aggregator. |
week | keyword | Week number within the year, formatted as ww-yyyy. |
Note that, as a result, date, week, version and count are reserved words that cannot be used as names in the aggregator key.
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 uses in later queries, or to save results that can be pulled out by other applications, such as Business Intelligence tools, or just to 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 Source window section and the Teneo Query Language manual.
Appendix Log Timeline
Session
A session with inputs and responses contains one or more transactions, as shown in the following diagram:
Upon reception of a 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 as a string (s:):
tql
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 it exists, along with any session variable change. The following TQL example retrieves the value of a particular session variable named <NAME_1> which has been updated within the begin dialog script and has been assigned a string (:s):
tql
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 it 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:):
tql
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.
Basic flow processing when the flow stack is empty
If a trigger's Match is matched, 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 listeners 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 TLML syntax 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 TLML syntax is matched). Finally, the flow execution carries on with the session and flow script path events, as explained in previous sections.
Output parameters and Responses
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.