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