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.

Audits are an important piece to the ongoing maintenance of your agent. The purpose of auditing is to take a look at how users are interacting with the agent, and identify ways to improve the experience. Any issues that you uncover in audits should be addressed in a regularly scheduled agent update window.

There are two types of audits—Query and Session.

Session audits answer the question “Was this session satisfactory to the user?“ and are best for evaluating the overall user experience. Did the user find the information he or she was looking for? Was the answer complete? Did the user express any frustration that was not appropriately addressed? As a client, do you feel that the interaction served your purpose in deploying the agent?

Query audits answer the question “Was the query answered by the correct topic?” and are ideal for fine-tuning the Natural Language comprehension and finding commonly unanswered queries.

Once your agent launches, it’s preferred that you audit every 2-3 days for the first two weeks and then once every 2 weeks for the remainder of the agent’s life. Of course, it is up to you to determine how often you audit your agent. If your agent has a ton of traffic, you might want to audit more often.

If you choose not to audit your agent, the agent will never improve and you will supply users with a poor experience. Auditing your agent will not only improve it, but improve your development style and guidelines for future agents.

Auditing Guidelines

Session Audit

Suggestions for how to score sessions in a session audit:

• Misunderstood: If the query is not recognized correctly and the user...
  • eventually gets the correct answer – Yes
  • would have gotten the right answer if he had continued another step (selected menu topic, typed more, etc) – Yes
  • doesn’t get the right answer  – No
• Content: If the query seemed to be understood reasonably well but the response...
  • clearly does not answer the question – Yes, but consider improving content
  • does not answer the question but includes a URL to a page that should logically answer the question – Yes, test the link, consider improving content if it does not
• Menu: If a query is answered with an appropriate menu...
  • but should have been answered directly to a topic on the menu – Yes, notify WLA Team of misunderstood query
  • but is beyond the scope of the agent (too specific, technical)  – Yes
  • but the user does not select any of the options – Yes
  • but the user does not select the correct option – Yes, consider  improving the menu if possible
• Long/multiple: If the query is long or contains multiple questions and...
  • hits “catch” or gives the correct answer  – Yes, bravo
  • user eventually gets the correct answer – Yes
  • user doesn’t eventually get the right answer – No
  • user gets the wrong answer and gives up – N/A
• Dialogs: If a user engages agent in a dialog it cannot handle (responds to an answer with “I already tried that” or similar – Ignore that query
• Ambiguity: If the user hit an ambiguity and...
  • the correct topic is listed, but the query was specific enough that it should have been answered directly – Yes, notify WLA Team
  • neither option is correct – No
  • at least one of the options is incorrect/irrelevant –  Yes, notify WLA Team
• Entry message/empty session: If session only contains entry messages – N/A
• Looping: If topics are looping – No
• Nonsensical: When the user types nonsense, mark the query or session as N/A.             

Query Audit

* All internal query audits should use the option to "Only include queries relevant to natural language."

Suggestions for how to score queries in a query audit:

• Non-NL Queries: Despite selecting the option* above, the auditor may still need to manually discard non-natural-language queries
  • Menu selections: a # (followed by line of NL-comprehension code in parentheses) – N/A
  • Any dialogue queries such as: more, yes, no, show related topics – N/A
  • “?” – N/A
• Nonsensical: When the user types nonsense or question unrelated to products covered – N/A
• Beyond the scope of the agent: When the user asks a very technical or specific question and
  • gets a menu or somewhat related answer – Yes
  • doesn’t get an approximate answer – N/A
• Mismatched: Any reasonable query that
  • does not match an appropriate response in the agent – No
  • is known not to have an appropriate response in the agent and
    • doesn’t match anything at all relevant – No
    • matches something somewhat relevant – still Yes, but consider improving content
  • mismatched because the user tried to engage in a dialogue such as “I already tried that” – N/A
• Menu: If a query matches to an appropriate menu but was specific enough to have matched directly to a topic– No
• Long/multiple: If the query is long or contains multiple questions and...
  • gives the correct answer  – Yes, bravo
  • matches reasonably well – Yes
  • hits “catch” – Yes
  • mismatches – N/A
• Unanswered/Catch section: If the user makes a valid query (not nonsense) that will probably be asked again at some point – No
• Ambiguity: test each query in this section
  • the correct topic is listed, but the query was specific enough that it should have matched directly – No
  • neither option was correct – No
  • at least one of the options is incorrect/irrelevant – No

Ideally you start creating a new Agent using the WLATemplate! Detailed information on how to instantiate a new project [currently available languages are: English, Chinese (simplified), French, German, Italian, Japanese, and Spanish] from the WLATemplate: http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!446.entry

As you can imagine, this is only the beginning... In order to make your Agent a success and stand out in the crowd, you have to customize it to whatever you want your Agent to be, simple things like giving your Agent a personality and making "him" or "her" more natural. Here are a bunch of former blog posts that talk about exactly that:

Creating a Personality Spec - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!317.entry

Customizing Chat - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!230.entry

Welcome Messages and ABGreetingProc - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!408.entry

Changing PSM, Friendly Name, and Icon - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!315.entry

Best Practices for Developing a Windows Live Agent:

Part 1 [Use the WLATemplate Project as a Starting Point] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!149.entry

Part 2 [Create Good Subpatterns] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!150.entry

Part 3 [Use Dialogs] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!151.entry

Part 4 [Use Canonical Questions] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!152.entry

Part 5 [Remember User Information] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!156.entry

Part 6 [Create a Clear and Concise Welcome Message] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!160.entry

Part 7 [Be Careful When Using Public Variables] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!163.entry

Part 8 [Make Your Project Modular] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!164.entry

Part 9 [Make Your Agent Chatty] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!166.entry

Part 10 [Conclusion of Best Practices Series] - http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!176.entry

-----------------------------------------

Blog post contributor(s): Mirco

An important component in creating a good agent is to access and display rich content.  Often, this content comes from sources such as data feeds, flat files, SQL databases, or SOAP/RES methods.

There are two common components in Buddyscript that is needed to access, store and retrieve data.  They are datatables and datasources.

Datatables are two-dimensional arrays of data that is preloaded into memory.  For those of you familiar with SQL databases, these are tables that are pinned in memory.  The common sources where datatables are loaded from are from a hard coded list, tab-delimited flat files, SQL tables, or an external source that can return back an array of data.

The datatable statement looks like this:

datatable tablename [propertyoptions]

  load column1 [, column2...] from source

    retrievalmethod

For example, to load from a hard-coded list, the statement might look something like this:

datatable MovieGenreTable

  load GenreCode {index="exact"}, GenreName {index="exact"} from

    1, Action

    2, Adventure

    3, Comedy

This loads a datatable called MovieGenreTable with 3 rows of two columns, GenreCode and GenreName.  Both columns are indexed, using an 'exact' index.  From the BuddyScript documentation, the types of indexes you can use are as follows:

• exact: the two entries need to be exactly equal. => "exact" = "exact" but "Exact" != "exact"

• case-insensitive: the two entries can have different case => "exact" = "eXaCt" but "exact" != "exact?"

• thawed: the "thawed" version of the two entries need to be equal => "that's exact" = "$$ThaT %%

S&&ExAcT!!", "François" = "fRAncois". This is because the thawed version of both "That's exact!" and of "$$ThaT %% S&&ExAcT??" is "that s exact".

It's slightly faster to access a column indexed as exact, than a column indexed as case-insensitive. thawed indexed columns are the slowest.

To load from a tab-delimited file would look like this:

datatable CitiesMetaTiered

  load value*, score from file

    Data/CitiesMetaTiered.txt

This loads a datatable called CitiesMetaTiered into a two column table, the columns being value and score.  The file has two columns separated by a tab.  The table never expires from memory. The asterisk after the column (as in value*) is a shortcut for an index, with the property of exact.

Accessing the datatable

The way to access the datatable is as follows:

list of variables = get column1, [column2, ...] in datatableName [where

columnX is value [and columnY is value2...]] [limit startIndex, count]

Note that this syntax looks fairly similar to the SQL SELECT statement.

For example, using the above datatable definitions, to retrieve data from the datatable called CitiesMetaTiered, a typical statement might look like this:

SEARCHVAR = 'x'

V, S = get value, score in CitiesMetaTiered where value is SEARCHVAR limit 1

This will put into the variables V and S the value and score content in the CitiesMetaTiered datatable where the value is 'x'.  It will put into the variable the first row that it finds.

Datasources

Datasources are a way to define how data looks when retrieved from an external source. The most useful and common ways to use a datasource is to define a web data feed page, a datatable, or a SQL data table.

For example, to define a web datafeed page, an example might look like this:

datasource dsProductRecall() => ititle, idescription, ipubDate, ilink

  http

    http://www.cpsc.gov/cpscpub/prerel/prerelhousehold.xml

  simple xml

    channel

//      title

//      description

//      link

//      language

//      lastBuildDate

//      webMaster

      item {loop="content"}

        title

        description

        pubDate

        link

//      guid

This looks at an XML feed called http://www.cpsc.gov/cpscpub/prerel/prerelhousehold.xml. 

The XML has master information and item repeating information.  The datasource captures node information into the output variables.  The output variables are strictly positional based on what is captured from the feed.

The indentation in the datasource definition has to match the same parent-child level of the web page.  The  {loop="content"} indicates that the variable and all the children variables will repeat and the content put into an array.  The // are comment statements, in this particular case, some variables are commented out because the code has no use for the particular data.

In some instances, you would use a datasource instead of a datatable.  For example, if you only need part of a table in memory at any one time, it is much better to use a datasource than a datatable.

Here is an example of a datasource that loads from a datatable.

datasource DatGetAllCityInfo(ZIP) => city, state, region, country

   table

     get

       city, state, region, country

     in

       CombinedGeography

     where

       id is ZIP

This datasource takes in a parameter called ZIP, and will output 4 columns, city, state, region, and country.  It gets its output from a datatable, getting city, state, region, country from the datatable called CombinedGeography, and filters for those values in the id column where it is equal to the passed-in value called ZIP.

You can then access a datasource just like a function.  For example, using basic Buddyscript syntax:

? What products have been recalled lately?

TITLE, DESCRIPTION, PUBDATE, LINK = dsProductRecall()  show 5

     *  Here are the results for product recalls :

     -  TITLE, DESCRIPTION, PUBDATE, LINK

you can also access the datasource function with the OBJ <= datasourcename() statement.  This puts the data into an object. When there are multiple rows of data you can indent a block below the datasource call and the block will be looped on.  This will give you better display control over each line.

By Carl Moy

Language

·          Core

o    Rephrase Rules
This is a very powerful feature which predicts sentence variations based on syntactic structure, semantic context, and other linguistic and pragmatic cues.
e.g. "Can you please help me?" => "Can you help me?" => "Help me!"

o    Lexicon & Vocabulary
Includes lexicon files, i.e. for recognizing adjectives, nouns, verbs, etc. Also includes vocabulary files where most commonly used vocabulary is defined in categories, e.g. VocGeneral_xx, VocChat_xx, VocInternet_xx, etc. (_xx = language acronym) Definitions for synonyms are declared in vocabulary files as well.

o    Dates, Numbers, etc.

Handles recognition and display of strings for date, time, numbers, etc.

·         Extensions

o    Chat
Categories covering different chat topics such as Salutations_xx, Manners_xx, Comedy_xx, etc.

o    User Info
Handling different aspects of user's information such as birthday, gender, name.

o    Etc.

·         Utilities

A variety of different utilities to take advantage of. Scope of these utils is to make your Agent more unique, smarter, and to add features such as the activity window.

o    Math, Randomness...

o    Activity Window

o    Output processing & formatting...

o    Etc.

·          Run the script StartInstantiation.bat and follow its instructions. We'll assume you instantiated a project named YourProjectName. If you installed the SDK in the default directory, you can find it in "C:\Program Files\Colloquis\Colloquis SDK\Projects\WLATemplate\StartInstantiation.bat"

·          Open YourProjectName.dls

o    Remove sections for languages you don't need.

o    Replace references to English files to reference your language.

o    See #3 for an example for a DLS for a German speaking Agent.

·          Open YourProjectName.bfg and remove the sections for languages you don't need.

·          Delete the folders (languages) you don't need

·          Open Project in SDK, start compilation, and type "Hallo!"

·         Read README.txt to customize your project.

 This is part I of a two-part blog entry.

Introduction

This posting will go over various methods of inserting a Web Service call in Buddyscript code as a datasource. We will assume that you already have a working Web Service and Buddyscript project. For my example, I have a Web Service called Service1 running on my local machine.

Background Information

Our HelloWorld Function

Our very basic HelloWorld Web Service function simply takes an input parameter and outputs “you said <input>”.

Start Your Web Service

Before you begin, you must start your Web Service. Note the web address. My web service is running at http://localhost:54908/Service1.asmx.

GET Web Service Call

Step 1: Determine Web Service Call Format

To send requests to, and receive responses from, your Web Service, you need to figure out how to call it. We did this by going to our Web Service’s URL in a web browser. For the GET method, the Web Service XML code looks like this:

The following is a sample HTTP GET request and response. The placeholders shown need to be replaced with actual values.

Request:

Response:

Step 2: Create the Datasource in Buddyscript

The GET method is the easiest one to use in Buddyscript, and therefore is the recommended method of doing Web Service calls. To create the datasource that will call the HelloWorld function, the Buddyscript code looks like this:

// GET DataSource HelloWorld

datasource HelloWorldGet(INPUT) => HelloWorldResult

  http

    http://localhost:54908/Service1.asmx/HelloWorld?input=INPUT

  simple xml

    string

The result of this function is the string returned by the HelloWorld Web Service function call.

Step 3: Use the Datasource

To use the datasource we just created, we can do something like this:

? HelloWorldGet INPUT=Anything

  RESPONSE = HelloWorldGet(INPUT)

  - GET Web Service Response: "RESPONSE".

So if you type the query:

HelloWorldGet get test

The Agent would respond with:

GET Web Service Response: “you said get test”.

POST Web Service Call

Step 1: Determine Web Service Call Format

Once again, we went to the URL of our Web Service in a web browser to figure out the format of a POST call. The XML looks like this:

The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values.

Request:

Response:

Step 2: Create the Datasource in Buddyscript

Using the POST method to call a web service is not much more difficult than using a GET. To create the datasource, the Buddyscript code looks like this:

// POST DataSource HelloWorld

datasource HelloWorldPost(INPUT) => HelloWorldResult

  http

    http://localhost:54908/Service1.asmx/HelloWorld

    postdata

      input=INPUT

  simple xml

    string

Once again, the result of this function is the string returned by the HelloWorld Web Service function call.

Step 3: Use the Datasource

Using the POST HelloWorld datasource we just created is done in exactly the same way as using the GET HelloWorld datasource. So for the following routine:

? HelloWorldPost INPUT=Anything

  RESPONSE = HelloWorldPost(INPUT)

  - POST Web Service Response: "RESPONSE".

If we type the query:

HelloWorldPost post test

The Agent would respond with:

POST Web Service Response: “you said post test”.

For the Integrating Buddyscript and Web Services Part II, please click here.

POST /Service1.asmx HTTP/1.1

Host: localhost

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://tempuri.org/HelloWorld"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <HelloWorld xmlns="http://tempuri.org/">

      <input>string</input>

    </HelloWorld>

  </soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <HelloWorldResponse xmlns="http://tempuri.org/">

      <HelloWorldResult>string</HelloWorldResult>

    </HelloWorldResponse>

  </soap:Body>

</soap:Envelope>

1.       What is an Activity Window (AW) and how can it be used to enhance Agents?

The Activity Window is an area in the Messenger Client that allows Windows Live Agents developers to provide rich content to the user to make the Agents experience much more engaging than simply conversing through the conversation window. This can also greatly increase the interaction between the user and agent.

Activity Windows can be used to enhance Agents by providing rich content such as Animation, Games, Videos, Charts, Tables, etc… that are not possible to display in the Conversation Window. Activity Windows is also able to accept input (just like any web page can) through mouse or keyboard, and send this data to the Agent, which can respond in turn.

Note: AWs are a feature of Windows Live Messenger and has a lot more functionality to offer that are unrelated to Windows Live Agents. For more information about Activity Windows, please follow this link:  http://msdn2.microsoft.com/en-us/library/aa751014.aspx Activity Windows are a feature of Windows Live Messenger. This document only addresses how to use AW in the context of Windows Live Agents. For more information about Activity Windows, please follow this link:  http://msdn2.microsoft.com/en-us/library/aa751014.aspx

2.       What you need to implement  AWs for Windows Live Agents:

a.       Basic knowledge of the following technologies:

                                                               i.      HyperText Markup Language (HTML)

                                                             ii.      BuddyScript (scripting language used to add logic to Agents)

                                                            iii.      Javascript (JS) *

                                                           iv.      eXtensible Markup Language (XML) *

b.      Familiarity with the Messenger Activity API Process.

c.       A hosting site to host your Activity Window pages and JS code.

d.      An application provisioned for your specific Activity Window by Messenger. (please see section 7 for more information on this)

e.      Last but not the least, you need the user’s consent to display the AW. (The end  user needs to Accept the invitation from your agent to start an Activity Window).

* These are needed only if using the Data Interchange method of interacting with the AW. Currently this method is only available to internal Agents developers but should be available to external Agents developers in a future release.

3.       Basic Idea of how User à Agentà AW interaction works:

a.       First, anapplication ID is provisioned by Microsoft points to your specific Agent’s AW. This enables Windows Live Messenger to know which Activity it needs to call when the user accepts the invitation.

b.      When the user asks a question for which the Agent has an answer that can be displayed in the AW, the Agent will send the output data to the AW application (hosted in the hosting site that you provide) instead of the conversation window.

c.       Once the AW application receives the data, the code in the AW uses the data to display the content requested.

d.      In certain cases, it is also possible for the AW code to send data back to the Agent.                                                         

4.       AW Implementations used in Agents:

 There are several ways to achieve the functionality shown in the above diagram. The ones used by WL Agents team so far include the following:

a.       Page Drive

 Samples of Agents using this method include Encarta Instant Answers agent and MSN Music agent. 

b.       Data Interchange using Javascript Object Notation (JSON)  and XML*

       Samples of Agents using this method include College Football Guru agent.

               *As of this time, this method is still in Beta and available only to internal Agents developers. We expect to make this available to external Agents developers in a future release.

5.       The Page Drive method

Taking the example from MSN Music agent, it uses the AW to display Artist information when the user asks for it.

BuddyScript code is used to match on the user input, and if the user input is understood to be a request for Artist info, we search our list of Artist info.

Sample Code:

subpattern AnArtist

  <Your subpattern of an artist here>

? What do you know about ARTIST=AnArtist?

    ARTIST_ID = ArtistIDFromArtistName(ARTIST)

    If ARTIST_ID < 0

         - Sorry, I don’t have info about ARTIST :-(

         exit all

    -    Let me take you to the MSN Music page about ARTIST =>

   call PageDrive(StringConcat(“http://music.msn.com/artist/?artist=, ARTIST_ID, “#”))

                                                   BuddyScript code that calls the Page Drive procedure

In the above sample code, this is the handle that is executed when someone asks a question about an artist. The code will get an Artist ID and then call the PageDrive procedure which simply takes the URL string, starts up the AW process, and (assuming the user accepted the AW invitation), displays the page indicated by the URL in the AW.

The PageDrive  procedure is part of the WL Agents Activity Window Utilities API. This main package for handling AW functions in Agents is called WLMActivityUtilities.pkg and can be found under Modules\Shared\Utilities directory.

On the AW side, there is also JavaScript code that handles the request. Once the AW receives the request, the following JS code (embedded in an HTML file) is triggered.

Sample JS Code:

                                                 function Channel_OnDataReceived() {

                                                                var myData=window.external.Channel.Data;

                                                                DisplayDebugInfo("received data: " + myData);

                                                                if (myData=="READY") {

                                                                                Channel_OnRemoteAppLoaded();

                                                                                return;

                                                                }                                                                              

                                                                // Input sent by the BuddyScript code follows the format:

                                                                // param1=value1\nparam2=value2 ...

                                                                var myDataArray=myData.split("\n");

                                                                var destinationURL="";

                                                                for (var i=0; i < myDataArray.length; i++) {

                                                                                if (myDataArray[i].indexOf("url=")==0) {

                                                                                                destinationURL = myDataArray[i].substring(4);

                                                                                } else if (myDataArray[i].indexOf("debug=")==0) {

                                                                                                debugInfo = myDataArray[i].substring(6) * 1;             // * 1 to make sure we have a number

                                                                                }

                                                                }

                                                                                if (destinationURL!="") {

                                                                                // Go to the new location

                                                                                DisplayDebugInfo("URL=" + destinationURL);

                                                                                top.mainFrame.location.href = destinationURL;

                                                                }

                                                }

      Snippet of Javascript code that handles data from the Agent’s PageDrive procedure

To learn more about the different JS functions provided by the Window Live Messenger Activity API, please see their documentation.

6.       The Data Interchange method (a Sneak Peek)

Oftentimes it is not sufficient and certainly less interesting to simply use the AW to page drive to a URL. After all, AWs should be engaging and should provide rich content and functionality in order to increase user interaction time with your agent.

Windows Live Agents provides another way to implement AW in your Agent that allows for more complex AW displays. This is accomplished through data interchange using Javascript Object Notation (JSON) (please see http://www.json.org for more info) and eXtensible Markup Language (XML).

In a nutshell, here is how this works:

         

        Note: The Data Interchange method is currently not available for use as of this time by external Agents Developers because it is still in Beta. More detailed information will be posted on the Windows Live Agents Team blog as soon as this feature becomes available for external Agents developers.  

7.       All about the AW Application ID

The AW Application ID allows the MSN Messenger Client to determine which Activity it should load when the user accepts your Agent’s invitation to start an Activity Window session. This application ID can be obtained by contacting the Window Live Gallery team at http://gallery.live.com and submit a request.  Please click here to read a post for more information regarding this process.

The msgrp2p.xml file contains information that the Messenger client uses to load your AW application. It looks like this:

<?xml version="1.0"?>

 <Entry>

  <EntryID>99999999</EntryID> 

  <Error />

  <Locale>en-us</Locale>

  <Kids>1</Kids>

  <Page>1</Page>

  <Category>50</Category>

  <Sequence>10</Sequence>

  <Name>Windows Live Agents Sample Activity</Name>

  <Description>Windows Live Agents   SDK Activity Description</Description>

  <URL>http://localhost/activity.html</URL>

  <IconURL />

  <PassportSiteID>0</PassportSiteID>

  <Type>App</Type>

  <Height>498</Height>

  <Width>498</Width>

  <Location>side</Location>

  <MinUsers>2</MinUsers>

  <MaxUsers>2</MaxUsers>

  <PassportSiteID>0</PassportSiteID>

  <EnableIP>False</EnableIP>

  <ActiveX>False</ActiveX>

  <SendFile>False</SendFile>

  <SendIM>False</SendIM>

  <ReceiveIM>True</ReceiveIM>

  <ReplaceIM>False</ReplaceIM>

  <Windows>True</Windows>

  <MaxPacketRate>120</MaxPacketRate>

  <UserProperties>False</UserProperties> 

  <ClientVersion>6.0</ClientVersion>

  <AppType>0</AppType> 

  <Hidden>false</Hidden>

</Entry>

The elements to take note here are the ones bolded and displayed in red. The P4 Application ID that is provided to you by the Messenger team goes into the EntryID. The Name should be the name of the Activity that you are developing, and will appear in the Window Title of the AW. The Description is a description of the Activity, and the URL element specifies where the Messenger client will take the user once he accepts the invitation to start an AW.

Shown below is sample BuddyScript code that the Agent uses to get the Application Name and Application ID that will be passed to the AW in order to indicate which AW Application should be loaded.

function overrides MSNSLPGetAgentMainP4ApplicationName()

  return " Windows Live Agents Sample Activity "

function overrides MSNSLPGetAgentMainP4ApplicationId()

  return "99999999"

procedure MSNSLPSendInvitationToOpenP4Application(APP_ID, APP_NAME)

  if LogActivityUsage()

    call LogActivityInvitationMade()

  call IncrementIgnoredInvitationAttempts() // This invitation is ignored until an event accepts or rejects it

  SESSION_INVITE_STRING = StringConcat("msnslp invite session ", APP_ID, ";1;", APP_NAME)

  ABSendServiceEvent(SESSION_INVITE_STRING)

Note: For testing purposes, in order to see the Activity that you are developing even before you get it provision, you can put the EntryID value of 7, and provide correct values for Name, Description, and URL. Then, restart your Messenger client. When it starts up, you can talk to your agent, accept an invitation, and your Messenger client will automatically send you to the URL that you specified in the msgrp2p.xml.

                                For more information about this, please refer to Windows Live Messenger Activity SDK.

---------------------------------------------------------------------

Blog post contributor(s): Alan Chan

How do developers enable Multi-User conversation:

In the SDK, change the command line option in your BFG file for enabling Multi-User conversation (<multi-user> on|off <multi-user>), under MSM-MSN settings. This will allow an Agent to make use of the button on the Messenger Client chrome and “invite” another user to join the conversation.

How can developers integrate Windows Live Alerts:

Currently, this feature is only available for Agents that are built and hosted by Microsoft.   We’ll post a blog entry when this is made publically available.

How do we do more reporting on Activity Window (P4) usage:

The Agent Foundations team has this on their near term roadmap for external release. Developers will be able to grab statistics from AW use, including time spent on the window.  We’ll post a blog entry when this is made publically available.

When does a session time-out?

If a conversation has gone inactive for 15 minutes, the session will close and any new messages will constitute a new session.

How do developers bring in datasources:

http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!222.entry

How do developers detect which client version of Messenger is running?

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2550244&SiteID=1&mode=1

Does the Activity Window (P4) work on Mac Messenger?

Unfortunately, it does not at this time.  We’ll post something when we get more updates from that team.

Can Agents make use of Windows Live Calendar?

The APIs are not currently available. We’ll post a blog entry when developers can make use of them.

How do we update Dynamic Display Pictures, etc?

http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!178.entry

Is there support for LDAP access?

Not at this time.  No immediate plans to enable this now.

For the generic pointers about Agent testing:

http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!221.entry

http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!219.entry

Are there plans for VOIP integration?

The Agents team will be working with the Windows Live Messenger team to take advantage of their integration efforts. Please watch this blog for any future updates.

Skype integration for Agents?

We don’t have support or plans for that protocol at the moment.

Have trouble with the trial SDK?

After installing the SDK, if you have trouble instantiating a new project or viewing the contents of the solution explorer, please to the following:

1. Uninstall Windows Live Agents SDK

2. Reset settings using the following steps:

1.       Go to menu “Tools”

2.       “Import and Export Settings” (see figure 1)

3.       Select “Reset all settings” radial button

4.       Choose “Just reset settings, overwriting my current settings”

5.       Highlight “General Development Settings”

6.       Click “Finish”

Figure 1

3. Make sure to pick C# as the new default settings when Visual Studio is launched again

4. Close Visual Studio and install the Windows Live Agents SDK. The problem should now be solved, and are working on fixing this bug for the 5.0 release of our platform, which is the Beta release of the SDK.

http://cid-5bcd45e519e07634.skydrive.live.com/browse.aspx/London%20Training%20December%202007

Look for another blog posting soon with answers to all the questions from the training.