Metadata

When building a solution in Teneo, it is useful to think about how you will be keeping track of the bot's performance. One option is to use Metadata. With Metadata, you create the tags you need and use them to annotate the relevant parts of the solution. In this way, Metadata tags are flexible and can be applied to different solutions in different ways. Once you have applied Metadata tags to your solution, they can be used queried for in Teneo Query Language queries, making it easier to get the information you need from the solution logs after a bot has been published and used.

Note that Teneo starts logging metadata from the point in time when the solution (with metadata) is published. Augmenters, on the other hand, can also annotate logs that precede those Augmenters. Augmenters can be used as a instead of or in addition to Metadata; both have their own benefits and which one is best to use depends on the project and use cases.

Metadata Scopes

Metadata tags are placed inside a flow and can be created on one of three different scopes:

• Session
• Transaction
• Flow

This page explains the differences between the three levels and also what value types Metadata can have.

Session

A session can be described as a complete conversation between a user and a bot, from start to finish. Metadata stored on a session scope may not be assigned, evaluated, and logged until a session ends. This type of Metadata therefore only stores one single value, namely a boolean that is set to either 'true' or 'false' at the end of the session. This value can only be logged using the Auto-Log function inside the Metadata settings.

A common use case for Session level Metadata is logging information about the end user, given that this Metadata is logged at the end of a session (i.e. at the end of an end user's conversation with the bot).

You can read more about sessions here.

Transaction

Transaction level Metadata can store more values than a session scope. As the name suggests, it is possible to store one value per transaction. This is also logged with Auto-Logging.

Transaction Metadata can be summarized with the following:

• Logs one value per transaction, meaning for one boolean, the value can be stored as 'false' or 'true' multiple times.
• Can only be logged using Auto-Logging.
• Has different use cases, e.g. seeing the current page the user is on.

You can read more about transactions here.

Flow

Flow level Metadata can store, evaluate, assign, and log a value at different flow events. These represent when a flow is raised, dropped, assigned, and resumed.

Flow level Metadata can be summarized as follows:

• Values will be logged at each of the following flow events of a transaction:
  • Flow goes on top of the stack
  • Flow is paused to wait for user input
  • Flow is continued or resumed after user input was received
  • Flow is dropped off the stack
• One transaction can have multiple different values for this Metadata
• Auto-Logged or manually set
  • One example use case is shown inside Use Metadata, in which a flow level Metadata is used to count the number of sold coffees in a coffeeshop bot.

You can read more about events here.

Different value types

Values stored in a Metadata can later be added and extracted using Teneo Query Language to later examine the solution value. The user can elect to use one single value or combine multiple using a bundle.

The values can be of one of the following types:

Value type	Description
Boolean	Typical boolean where two options are shown, true or false.
String	A string value.
Tree	A tree value.
Number	Integer, example value: 1.
Bundle	Allows the user to combine multiple value types in a bundle.

Auto-Logging value

For session and transaction Metadata, and optionally also for flow Metadata, values are assigned through Auto-Logging. The Auto-Logging value is set when the Metadata tag is created, and that value is logged automatically at the corresponding time. For example, the Auto-Logging value for Session level Metadata is logged at the end of a Session.

For Flow level Metadata, the Auto-logging value is optional. If used, values are logged at every flow event. If it is not used, values are instead logged only at the points in the flow where the developer manually adds Metadata tags inside the solution.

Auto-Logging can also be used in conjunction with script strings, with which the user can log the value of a specific variable or information from Teneo engine inside Metadata. For example:

• The name of a flow: ${ _.getThisFlow().getName() }
  .
• Session Id: ${ _.getSessionId() }
  .
• Transaction Id: ${ _.getTransactionId() }
  .

For more examples, please see Engine Scripting API.

How to use Metadata

Metadata are currently supported in multiple levels throughout your Teneo Studio experience. Let us now proceed with how to Use Metadata and learn how to use them in practice in an example use case.