The standard reporting suite on the Knowledge Management Console covers the most important metrics -- Unique Users, Total Sessions, etc. However, you'll often want (or be asked) to provide additional reports based on the special needs of the customer and/or the particular tasks of the agent. This article won't cover all the details of configuring usage reports, but will hopefully demonstrate how to log a simple data point and have it show up on the console as a graph or table.

 

Before configuring usage, we should look briefly at how logging works. The agent's log is an object variable called SYS.Log -- anything written there is a candidate to show up in usage reports. This is completely separate from the User Profile: the agent may store the user's birthplace in a variable called G_USER.birthplace, but it won't show up in usage unless we also write it to, for example, SYS.Log.birthplace. It is also completely separate from the server component logs on the console.

 

So let's actually use birthplace as our example, and look at what we need to record and display that statistic.

 

Say we have a procedure called CollectBirthplaceFromUser() that takes care of collecting the user's birthplace and resolving it into a valid place name we can record.

 

 

WriteBirthplaceToProfile assigns the value of BIRTHPLACE to G_USER.birthplace. LogBirthplace writes the same value to the SYS.Log.birthplace variable.

 

 

Now that we're confident birthplaces are being collected and logged, let's move on to configuring Usage. We do this by editing a file at the root directory of the project, called usage_config.xml.

 

usage_config.xml controls the presentation of log data in the Usage Reports section of the console.  It's completely separate from the actual logging of data -- we can log something in the BuddyScript, for example, but not add the necessary sections in usage_config.xml for another month, at which point the data the agent has been logging for the last month will be displayed. However, the opposite is not true -- adding a section in usage_config.xml doesn't cause data to be collected.

 

There are two main parts: a "sections" element containing all the configuration options for the usage reports, and a "usagestats" element containing the variables and datapoints to be used in the sections element.

 

The sections element itself contains two subsections labeled "all_ids" and "individual_id", which correspond to views of usage statistics broken out by individual buddyid or all buddyid's combined, exposed as a drop-down list in the console. First we'll look at the all_ids section, which is somewhat simpler than the individual_id section.

 

The first section here is called Volume Summary, and contains a number of elements for reporting usage data. You can get a good idea of the syntax we'll be using later by examining this section.

 

 

The "name" identifier is the text displayed on the console, the "key" is the datapoint, "calc-type" can be normal or something else depending on whether we want to perform some math on the number before displaying it, "subkey" is the other datapoint to use when calc-type is not normal, "default-graph-state" toggles whether a particular element shows up on the graph, "graph-type" controls what kind of graph, if any, to display the data on. In this case, multiple elements are sharing a "barline" graph -- a combination bar graph and line graph where the user selects which data goes on the bar, and which goes on the line.

 

We could add our own section for birthplace, but it turns out there is already a section for demographics, so we'll just add an element within that section:

 

  <element name="Birthplace Distribution" key='[birthplace][%]' keyName="Birthplace" valueName="Sessions" calc-type="distribution" graph-type="pie" display-type="percentage"/>     

 

This will pull all the values of SYS.Log.birthplace and display them in a pie graph, distributed by the number of sessions they occur in, along with a key. ("name", "keyName", and "valueName" are all labels and have no effect on the display of the data.) [%] represents a wildcard, meaning "all values of birthplace" -- we could choose instead to report on only [birthplace]['New York'], for example. 

 

Since there are potentially a large number of birthplaces (depending on how smart CollectBirthplaceFromUser is), it probably makes sense to dispense with the graph, and just display a table:

 

  <element name="Birthplace Distribution" key='[birthplace][%]' keyName="Birthplace" valueName="Sessions" calc-type="distribution" display-type="percentage"/>     

 

That's all we need to do for the all_ids section. For the individual_ids section, because we'll be filtering by buddyid, we need to go to the bottom of the file and add a datapoint:

 

 

First we create a variable called userBirthplace, which is assigned the value of SYS.Log.birthplace. Then we create an hourly bucket for that data with a key for pulling the number of sessions within a particular buddyid where a particular birthplace was recorded. In the demographics section of the individual_id section, we'll add this:

 

 

This is similar to the element we created for the all_ids section, but birthplace (userBirthplace=%) and buddyid (buddyid=%var:buddyid%) are interpolated into their actual values, and we see only the number of sessions for a birthplace recorded for the buddyid currently selected. Now we can use the buddy dropdown on the console as a filter.

 

In practice, displaying a list of arbitrary names of places is not going to be very useful because there are many thousands of place names the user can enter. We'd probably want to constrain the list to countries, states, or other large areas, depending on the mission of the agent. Still, this example will hopefully get you started experimenting with Usage, which is the best way to learn. Chances are, usage_config.xml probably already contains most of the necessary pieces for whatever report you need to create.

Hi All,

 

I know a lot of folks have been waiting diligently for the new version of the SDK.  We have finished the product and are in the midst of deploying the platform in our data center now.  Once we get the final approval from Operations, we'll publish a link to the SDK and you'll be on your way!

 

Thanks for you patience and we look forward to you using the SDK!

 

Windows Live Agents team

 

 

 

 

 

 

So, you think you know everything about Buddyscript?

 

Well, let’s see how much of such a statement is true. Try to answer this short quiz! If you score all of them it doesn’t mean you are an expert, but you could say you are getting there ;-)

 

1-    Let’s talk about matching. Say we want to match precisely on full URLs (and only full URLs) during a conversation, which one of the following cases would be the way to go:

a)    subpattern AFullUrl /^www`.`S+`.(com|fr|org|net)$/ {minlength=3, example=”www.microsoft.com”}

b)    subpattern AFullUrl + www =Anything (com|fr|org|net) {canskip=”no”, minlength=3}

c)    subpattern AFullUrl www.=Anything.(com|fr|org|net) {canskip=”no” minlength=3}

 

2-    Nl-bricks? Only one of the following affirmations is true:

a)  “NL- bricks” along with “regular subpatterns” are processed during the “patternization” process, but “NL-bricks” have precedence over “regular subpatterns”.

b)  “NL- bricks” are the minimum expression of a meaning unit, and are “patternized” into “regular subpatterns” at compile time.

c)  “NL-bricks” are “skippable”, as opposed to “regular subpatterns” that need to have the property {canskip=”yes”}

 

3-    Defining macros in Buddyscript, only one of the following statements is true:

a)    If the code contains any line breaks, it should be placed immediately below the first line of the statement. If you want your macro to contain an empty line, add a line containing only the character “\”. The first empty line defines the end of the macro.

b)    If you want your macro to contain an empty line, add a line containing the character “\” at the end of the line before. I will add an empty line right between this and the following line. The first empty line defines the end of the macro.

c)    Macro definitions can’t contain line breaks. The first empty line defines the end of the macro.

 

4-    Only one of the following statements is true:

a)    The “always match as” statement allows you to associate a variable name with a particular subpattern throughout a group of patterns only.

b)    The “always match as” statement allows you to associate a variable name with a particular subpattern throughout a group of patterns, a package, or an entire domain.

c)    The “always match as” statement allows you to associate a variable name with a particular subpattern in a routine, or in a multi-line of code.

 

5-    What do you know about composite subpatterns? Only one of the following is true!

a)    Composite sub-patterns let you assemble multiple static subpatterns together, so that a candidate string is filtered through the first subpattern, then the result of this filtering is passed to the second one, etc.

b)    The minimum number of compositions is one, but there’s not a limit on the maximum number of compositions you can add.

c)    The default values for the properties of a composite subpattern are those of the outer-most subpattern, since it's going to be evaluated last.

 

6-    Hum, have you ever tried to create datasources? Let’s see if you know which one of the following is true:

a)    The “postprocess-block“ of a datasource is a BuddyScript routine used to set the offset and the total count of rows when the “preprocess-block” didn't return any of those values, or if the value returned is not accurate.

b)    “Expire” is a common property to the different datasource kinds. This information allows the platform to remember (cache) the result for a certain time. By default, expire is set to “now” (information is not stored). If you want the information to be cached, set it to “never”, or when the information won't be valid anymore (in 5 minutes, in 2 days, etc.)

c)    Datasources are BuddyScript tools to access external data. The external data retrieved can be accessed through many methods, including gateway calls, SQL queries, SOAP methods, datatables, etc.

 

7-    How about rephrasing rules? We want to use the property “MACRO_BEST_ONLY” when:

a)    We need to make sure the rule it’s only applied when it matches best from all of the other rephrasing rules.

b)    We want the rule to be applied only when it matches best, and no other rule can be applied after.

c)    We want to avoid matching on rules scoring lower than 80.

 

Solutions: 1-a, 2-b, 3-a, 4-b, 5-b, 6-c, 7-a

 If you failed the quiz, and you want to know more about Buddyscript, besides this blog you can browse the Windows Live Agents forum in MSDN, and of course read the documentation shipped with the platform.