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.
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 following properties:
Name | Type | Comments and Value constraints |
---|---|---|
beginTime | date | Timestamp when the first transaction of this session began. |
botname | keyword | The name of the published solution that generated this session. |
endTime | date | Timestamp when the last transaction ended. |
eventCount | long | The number of events in this session. |
id | keyword | The session's unique ID. |
lv:NAME | keyword | A log variable assigned in this session. NAME is as set in Teneo Studio, e.g. lv:LAST_FLOW_SESSION . |
md:NAME | keyword | Metadata assigned to this session, on the session level. Queryable by name (e.g. md:COMMAND ). |
solutionRevision | keyword | The revision number of the solution that generated this session. |
studioVersion | keyword | The detailed information about the Teneo Studio version of the conversational AI application that generated this session (e.g. 3.1.1(16836): 7/4/14 4:01 PM). |
studioVersionNumber | keyword | The platform version of the conversational AI application that generated this session (e.g. 3.1.1). |
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. |
transactionCount | long | The number of transactions in this session. |
Transaction properties
Transactions can have the following properties:
Name | Type | Comments and Value constraints |
---|---|---|
duration | long | Time span of the transaction, i.e. the time required by Engine to process the user input and generate the answer, in milliseconds. |
id | keyword | The unique ID of the transaction. |
index | long | The transaction's index within the session (starts at 0). |
md:NAME | keyword | The metadata assigned to this transaction, queryable by metadata name. |
lv:NAME | keyword | A log variable assigned in this session. NAME is as set in Teneo Studio, e.g. lv: OUTPUT_NODE_IDS . |
time | date | Timestamp when the transaction began. In log data older than Teneo 3.2, it was the time stamp of the end of the transaction. |
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:
Name | Type | Comments and Value constraints |
---|---|---|
eventIndex | long | Any integer >= 0 |
fv:TYPE:NAME | keyword | A flow variable updated in this event. NAME is as set in Teneo Studio, e.g.: fv:s:sTripDestination . Logged every time it gets a new value. |
md:NAME | keyword | Metadata variable. NAME is as set in Teneo Studio. Logged every time its value is assigned. |
sv:TYPE:NAME | keyword | A 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. |
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 since it makes queries more efficient. |
Request event specific properties
On top of the Common 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.requestParameters.pageURL . |
userInput | keyword | The actual string sent to Teneo Engine. |
userInputWords | analyzed string | 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 since it makes queries more efficient.pathType can be any of these 15 types of path events, organized in 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) and related to flow/listener execution (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 |
---|---|---|
vname | keyword | The name of the script, limited to global script types in Studio beginDialog, newSession, onTop, onDrop, preProcessing, preMatching, postProcessing and timedOutSession . |
Flow-script Path Event properties
It corresponds to the flow events onTop and onDrop.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | The id of the flow that holds the script. |
flow-instance-id | keyword | The flow-instance-id of the flow that holds the script. |
fname | keyword | The name of the flow that holds the script. |
folder | keyword | The folder of the flow that holds the script. |
vname | keyword | The name of the script limited to flow script types in Studio onTop and onDrop . |
Variable-change Path Event properties
It indicates a side-effect variable change.
Name | Type | Comments and Value constraints |
---|---|---|
change-type | keyword | Value 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 | The id of the flow that is raised. |
flow-instance-id | keyword | The flow-instance-id of the flow that is raised. |
fname | keyword | The name of the flow that is raised. |
folder | keyword | The folder of the flow that is raised. |
vid | keyword | The id of the vertex where the flow is raised. |
vname | keyword | The 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 | The id of the flow that is paused. |
flow-instance-id | keyword | The flow-instance-id of the flow that is paused. |
fname | keyword | The name of the flow that is paused. |
folder | keyword | The folder of the flow that is paused. |
vid | keyword | The id of the vertex where the flow is paused. |
vname | keyword | The 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 | The id of the flow that is continued. |
flow-instance-id | keyword | The flow-instance-id of the flow that is continued. |
fname | keyword | The name of the flow that is continued. |
folder | keyword | The folder of the flow that is continued. |
vid | keyword | The id of the vertex where the flow is continued. |
vname | keyword | The 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 | The id of the flow that is resumed. |
flow-instance-id | keyword | The flow-instance-id of the flow that is resumed. |
fname | keyword | The name of the flow that is resumed. |
folder | keyword | The folder of the flow that is resumed. |
vid | keyword | The id of the vertex where the flow is resumed. |
vname | keyword | The 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 | The id of the flow that is dropped. |
flow-instance-id | keyword | The flow-instance-id of the flow that is dropped. |
fname | keyword | The name of the flow that is dropped. |
folder | keyword | The 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 | The id of the vertex where the flow is dropped. |
vname | keyword | The 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 | string | It contains the error message and the stack trace if the invocation of an input processor threw an exception. |
consistent | boolean | It is true if consistency-error is empty (that is, no error happened), otherwise it is false . |
Path Events related to flow/listener execution
Flow-trigger Path Event properties
This event takes place when a flow trigger matched.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | The id of the flow for this flow trigger. |
flow-instance-id | keyword | The flow-instance-id of the flow for this flow trigger. |
fname | keyword | The name of the flow for this flow trigger. |
folder | keyword | The folder of the flow for this flow trigger. |
vid | keyword | The id of this flow trigger. |
vname | keyword | The name of this flow trigger. |
triggerType | keyword | The type of this flow trigger. Valid values are intent-rule-trigger , intent-class-trigger , prompt-script-trigger |
used-words | keyword | Whitespace-separated list of words. |
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 | The folder of the flow for this listener. |
fid | keyword | The id of the flow for this listener. |
fname | keyword | The name of the flow for this listener. |
flow-instance-id | keyword | The flow-instance-id of the flow for this listener. |
listener-type | keyword | Valid values are global , flow , flow-trigger and transition . |
vid | keyword | The id of this listener. |
vname | keyword | The 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 | The emotion of this output node. |
fid | keyword | The id of the flow for this output node. |
flow-instance-id | keyword | The flow-instance-id of the flow for this output node. |
fname | keyword | The name of the flow for this output node. |
folder | keyword | The folder of the flow for this output node. |
max-revisits | long | Maximum number of times an output node can be used (since Teneo Platform 4.2 logs). |
output-id | keyword | The id of the selected output. |
output-text | keyword | The text of the output. |
revisits | long | Number of times an output node has been used along the session (since Teneo 4.2 logs). |
revisitable | keyword | Valid values are true and false . true if the output node is revisitable (up to Teneo Platform 4.1 logs). |
skipped | keyword | Valid values are true and false. true if the output node is skipped. |
vid | keyword | The id of this output node. |
vname | keyword | The name of this output node. |
url | keyword | Url the application navigates to, if logged. |
Transition Path Event properties
This event takes place when a transition was traversed.
Name | Type | Comments and Value constraints |
---|---|---|
fid | keyword | The id of the flow for this transition. |
flow-instance-id | keyword | The flow-instance-id of the flow for this transition. |
fname | keyword | The name of the flow for this transition. |
folder | keyword | The folder of the flow for this transition. |
input-consuming | keyword | Whether the transition is input consuming or not. Valid values are: true and false . |
used-words | keyword | Whitespace-separated list of words consumed during the transition. |
vid | keyword | The id of the transition vertex. |
vname | keyword | The 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 | The id of the flow for this script node. |
flow-instance-id | keyword | The flow-instance-id of the flow for this script node. |
fname | keyword | The name of the flow for this script node. |
folder | keyword | The folder of the flow for this script node. |
vid | keyword | The id of this script node. |
vname | keyword | The 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 | The id of the flow for this flow node. |
flow-instance-id | keyword | The flow-instance-id of the flow for this flow node. |
flow-node-type | keyword | Valid values are subflow and routing. |
fname | keyword | The name of the flow for this flow node. |
folder | keyword | The folder of the flow for this flow node. |
target-flow-id | keyword | The id of the flow where to hop on from the current flow. |
target-flow-name | keyword | The name of the flow where to hop on from the current flow. |
vid | keyword | The id of this script node. |
vname | keyword | The 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 | string | Valid values are added , removed or updated . |
name | string | Name of the annotation – either given by the input processor or by the user, depending on how the annotation is created. |
sentence-index | integer | 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 | array | 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 | The 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, 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:
tql
1<LEVEL.a.TYPE:name>
2
where:
LEVEL
indicates if the property is stored at sessions
, transactiont
, or evente
levela
stands for adornerTYPE
indicates the data type (see below table)name
(following the colon) is the adorner name provided when it is created.
Symbol | Type |
---|---|
b | Boolean |
bin | binary |
d | date |
gp | geo_point |
n | integer number (mapped as long) |
f | floating point number (mapped as double) |
s | string |
a | array |
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 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:
tql
1<TYPE:name>
2
where:
TYPE
indicates the data type (see the above table for allowed values), andname
(following the colon) is the key name provided when the aggregator is created.
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 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
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:
):
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 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:
):
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 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 Studio.
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.