One of the most powerful parts of the BuddyScript platform is its extensible reporting suite.  This article will describe how to log data relating to what your agent is saying, in a form that can be displayed in the Usage Reporting tab of the web console.

Category and topic logging is something that has been used for agent projects developed "internally," but the code to do this was never exposed to partners in the libraries that ship with the platform.  This is likely to change in future releases, but in the meantime feel free to implement the code here.

A topicis a routine with user input, agent output.  For example, we may have a routine that associates matching for "how are you" to various outputs saying "I'm doing fine." This is a topic.

A category is a grouping of topics, often associated with a single DDL file. For example, we might have a category for all the topics that handle queries relating to the agent as a person, like "how are you", "where did you come from", etc.

When we associate a title to a topic, we can log that title and keep a tally of how many users hit that topic. When we associate a topic to a category, we can also tally how many times users hit that category. Thus, we will have data relating to where user queries are matching the most, at two levels of granularity.

To get this working, we need to:

1.    Define categories

2.    Assign topics to categories

3.    Log the topics and categories

Here is an example of how to do this:

Say we have a domain for English conversational routines, Topics/EN-US/Conversation.ddl.

At the top of the Topics/EN-US/Conversation.ddl, we add this:

{category="Conversation (English)" label="CategoryDefinition"}

+ _ignore_me

  do nothing

This defines a new category called “Conversation (English)”.  Next, we need to associate routines to this category.  Here is an existing routine:

{label="? Hi" uid="MyAgent-1195066867"}

? Hi

  - Hi! 

  - Hello there! 

  - Hi there.

  - Greetings!

  nop

  - How are you?

  - What's new with you?

  - How are things?

  insist

    - Good to know.<br/>

    - Interesting.<br/>

    - Glad I asked.<br/>

    - Really? <br/>

The key-value pairs between brackets ("label" and "uid") were automatically generated by the KMS as part of its tracking mechanism.  If they are not present, don't worry about it.

Add this (the order of key-value pairs doesn’t matter):

{category="Conversation (English)" title="Hi" label="? Hi" uid="MyAgent-1195066867"}

Still, we are just labeling the routine, and nothing will happen unless we log it.  The platform will automatically do some simple logging, but we should override that to use categories.  Look at this part of the libaries, in Required/ABProcs:

########################################

##

## ABPostQueryLog

##

## This procedure is called at the end of a user query

## and can be overriden to log specific information.

##

########################################

procedure ABPostQueryLog()

  SYS.Log.ScriptFile[SYS.History[0].Match.ScriptFile]++

processing ABPostQueryLog

   post-process

     call ABPostQueryLog()

So, if we just want to know what file is being hit, right now that is being logged as “ScriptFile”, which we could add to usage_config.xml and show in Usage Reporting in the console.  However, a better approach is to define categories for every ddl, and assign titles and categories for each topic in the ddl.  Then we can override the logging behavior like so:

### Logging

variable G_LAST_LOGGED_QR_RECEPTION_TIME=0

procedure LogCategory(CATEGORY)

  SYS.Log.Categories[CATEGORY]++

procedure LogTopic(TOPIC_TITLE)

  SYS.Log.Topics[TOPIC_TITLE]++

procedure PerformTopicLogging()

  if G_LAST_LOGGED_QR_RECEPTION_TIME == SYS.History[0].Execution.QRReceptionTime

    exit

  G_LAST_LOGGED_QR_RECEPTION_TIME = SYS.History[0].Execution.QRReceptionTime

  if SYS.History[0].Match.RoutineId == ""

    exit

  TOPIC_TO_LOG = ""

  CATEGORY_TO_LOG = ""

  ROUTINE_ID = SYS.History[0].Match.RoutineId 

  if !ROUTINE_ID

    exit

  TOPIC_KEYS = GetRoutineKeys(ROUTINE_ID)

  if Exist(TOPIC_KEYS["menu"])

    exit

  if !Exist(TOPIC_KEYS["title"])

    exit

  TOPIC_TO_LOG = TOPIC_KEYS["title"]

  if !Exist(TOPIC_KEYS["category"])

    CATEGORY_TO_LOG = "undefined"

  else

    CATEGORY_TO_LOG = TOPIC_KEYS["category"]

  call LogTopic(TOPIC_TO_LOG)

  call LogCategory(CATEGORY_TO_LOG)

procedure overrides ABPostQueryLog()

  call PerformTopicLogging()

Note that all we are really doing is piggy-backing on the existing logging mechanism, using it to write the values associated with the “title” and “category” keys for each routine the agent matches to.  These values are written to the SYS.Log variable, a special object used for logging.  Anything written to SYS.Log is fair game to show in the reporting console, but to do so, we also need to make alterations to the usage_config.xml file, to accommodate SYS.Log.Categories and SYS.Log.Topics and specify how the data should appear.  Editing the usage_config.xml file is beyond the scope of the article and will be covered later, so let the WLA team know if you need help setting it up.