Windows Live Agents

Greetings,

Windows Live Agents Blog has been moved.

New location is: http://blogs.msdn.com/windowsliveagents/

Thank you,

Windows Live Agents Team.

PHI - Hosting Process

Partner Hosting Infrastructure, or PHI, is a tool that will allow developers to apply for Microsoft to host their Agent projects. Developers will be able to upload their code, manage projects, and be informed of the current state of their projects. This section will go over the tools that developers have available to them when developing a project, taking it live, and making changes to project files.

The following is a quick overview of the PHI process, followed by a detailed explanation of the hosting process.

• Initial project application – log in to PHI and click on “Apply for New Agent”. Fill in the application form.
• Apply for Hosting – after your application is filled in, you will be in the “Initial” state. Once you are satisfied with your application, click “Apply for Hosting”. Microsoft will then review your project application. Don’t forget to sign and submit the Hosting Agreement.
• Project check-in – once your project application has been approved and Microsoft has received your signed Hosting Agreement, you can check in your project. For details on how to do this, see Step 2 below.
• Hosting – Once the project is checked in, Microsoft will review your project files and get them hosted in the data center. You must provide a screen name for your Agent before being hosted. You will then be able to talk to your Agent online. You can edit your Agent at any time.
• Going Live – Once you are satisfied with your Agent’s content, click “Submit Project Details for Review”. This will trigger another review by Microsoft, after which your project will go live.

 

A more detailed description:

Step 1: Initial Project Application

 

1.     Let’s assume that you have already created a project called sampleProj and you now want it to be hosted and take it live.

2.     Go to http://phi.agents.live.com

3.     In the top right corner, click on the “Sign In” link and sign in with your WLID.

4.     In the “Agents Home” page, click on “Apply for New Agent”.

5.     Enter “sampleProj” as the Agent Name, and fill out the rest of the form.

6.     Ensure that you complete, sign, and send back the Hosting Agreement (if this is your first Agent) or the Statement of Work (if you have already completed a Hosting Agreement).

7.     Once you have filled out and sent back the appropriate documents, check the “I have signed and sent back the hosting agreement.” checkbox and then click “Save”. You will be taken back to the Agents Home page, and your project should be in the “Initial” state.

 

Step 2: Check in Code for a Project

 

To be able to check in your project code, you must first apply for hosting. To do this:

1.     Click the “Apply for Hosting” link next to your new project.

2.     Click the “Apply for Hosting” button

3.     You should be taken back to the landing page, and the project state should now be “Awaiting Initial Project Hosting Approval by Microsoft”.

At this point, you must wait for the reviewers at Microsoft to go over your application and approve it. You will know that a project has been approved when the state changes from “Awaiting Initial Project Hosting Approval by Microsoft” to “Waiting for Legal Documents from Developers”. The reviewers will need to ensure that they have received legal documents from you. If they have, they will update your project to the “Awaiting Initial Project Checkin by Developer” state.

Once your project is in this state, you can check in your code. To do so:

1.     Open up your project in the Visual Studio IDE.

2.     Go to Tools -> Windows Live Agents Tools ->Code Management -> Sign in to Windows Live

3.     Sign in using the same WLID that you applied for the project with in PHI

4.     Go to Tools -> Windows Live Agents Tools -> Code Management -> Check In Project

5.     Select the project. Make sure it has the SAME NAME as the project you applied for in PHI (in our case, sampleProj). Then click “Check In”.

6.     Note: This initial check in will be version 2. This is expected.

Your project is now checked in!

Step 3: Hosting and Testing Your Project

 

After checking in your code, the state of your project should be “Awaiting Critical File Review by Microsoft”. Microsoft will need to review your critical files (in this stage, the only critical file is the .connections file) before proceeding.

Once your code review is in progress, your project will be in the “Initial Critical Files Under Review by Microsoft” state.

If the files are approved, the state will change to “Pending Hosting in Data Center by Microsoft”. This means that you are waiting for the Operations team to move your files to the data center. Once this is complete, your project will be hosted, and the state will change to “Hosted”. At this point, your files are live in our data center.

From the Hosted state and going forward, files can be modified and checked in at any time. The only file modifications that will require review are checkins of the connections file. You can think of being in the Hosted state as being in a staging environment.

To talk to your agent on Messenger, you will need to add a staging screen name to your project. To do this, click on the “Manage Screen Names” link in the “Actions” column next to your project. Enter a WLID that you would like for your staging screen name. The WLID will be validated before being added to your project.

Step 4: Going Live

 

Once you are satisfied that your project is ready to go live, you need to submit your project for review. To do this:

1.     Click the “Submit Project Details for Review” link in the “Actions” column next to your project.

2.     Click the “Submit Project Details for Review” button.

3.     The project state should now be “Hosted: Awaiting Go-Live Approval from Microsoft”.

Once the Microsoft reviewers have reviewed and are satisfied with your project, they will submit the project files to Ops for deployment in the data center. The state of your project will change to “Hosted: Pending Go-Live in Data Center by Microsoft”.

Once your project has been put in the data center, the project state will be updated to “Live”.

To add your live screen name and talk to your Agent via Messenger, you again use the “Manage Screen Names” link on your PHI landing page. Enter the WLID that you would like your Agent to have. The WLID will be validated before it is added to the project.

 

How to Modify Files

 

You have two options available to you when you would like to modify files in your project.

Using the Console

You can use the KMS Console at https://sampleProj.console.agents.live.com to modify the project. This will allow you to edit topics and responses fairly easily. For more control, however, you would want to use the IDE to make project changes.

Using the IDE

You can use the IDE to check in files in the same way that you checked in the project originally. Please note that using the IDE will check in an entire project, and does not allow you to check in just a single file.

To check out using the IDE, you must first sign in and then acquire the lock by clicking on Tools -> Windows Live Agents Tools -> Code Management -> Check Out Project. You can then edit whichever files you wish. While a project is checked out to you, no one will be able to edit any of the project files using the IDE or KMS.

To check in, click on Tools -> Windows Live Agents Tools -> Code Management -> Check In Project.

 

Checking In the Connections File

When you check in the connections file, it must be reviewed and approved before being hosted or going live in the data center. Check in the connections file as you would check in any other file (see directions above).

Checking in your project when the .connections file has not been modified will not trigger a review. Those changes should propagate immediately.

 

Adding Project Developers/Contributors

 

Besides the project owner, there are two other roles that you may have:

·         Developer – A developer is allowed to check out, modify, and check in a project

·         Consumer – A consumer is allowed to check out a project, but all project files will be read-only. They cannot check in any changes.

To add a developer or consumer to your project, click on the “Manage Developers” link in the “Actions” column next to your project name. Enter a valid Windows Live ID that your developer/consumer will be using to log in, and select the appropriate role.

 

Summary

 

Using PHI will allow you to apply for hosting and track your project online. It also allows you to upload your code using the Visual Studio SDK. The tools that are available in PHI make it much easier for developers to get projects hosted in the Microsoft data center.

 

If you are moving from the old Colloquis IDE to the Visual Studio-based Windows Live Agents SDK, and you've never used Visual Studio, you may be a little lost.  This post aims to collect simple hints and tricks for agent developers new to working with Visual Studio.  This is just a start -- if you have any hints, please do comment, and later on we'll post a sequel. 

 

Also, this is by no means much of a guide to Visual Studio as a whole, and is really meant to get you started and oriented for agent-development tasks.  Also, it's not a guide for creating agents.  The first resource for using the new SDK is the Windows Live Agents SDK documentation.  You should start there before doing anything.

 

Here are some common menu locations for agent-development tasks:

 

Edit -> Find and Replace   ... Lots of options for searching through single or multiple files.  Regular expressions work!

View -> Solution Explorer ... This is rougly equivalent to the Explorer feature in the old IDE, and lets you see the project files in a tree view.

View -> Class View          ... Lets you see all the project's domains and packages as a flat list of classes.

View -> Error list             ... Displays compile errors and warnings.

View -> Output                ... Similar to the "Misc Debug" pane of the old IDE, displays compiler messages.

View -> Other Windows -> Conversation Window            ... Where you compile and talk to the agent.

View -> Other Windows -> Comprehension Info Window  ... Displays match scoring information.

Project -> Add DLS Item                ... Add datasources and other DLS items.

Project -> ProjectName Properties  ... Specify compile parameters like buddy id, filter, and command-line options.

Tools -> Windows Live Agents Tools -> Code Management              ... The SDK's interface to the Partner Hosting Infrastructure.

Tools -> Windows Live Agents Tools -> Request License Certificate  ... Get a new license cert.

Tools -> Windows Live Agents Tools -> Management Console          ... Launches the web management console within Visual Studio.

Tools -> Windows Live Agents Tools -> Update connections file        ... Attempts to update the connections file based on the content of your project.

Tools -> Windows Live Agents Tools -> Performance                       ... Various tools for measuring performance.

Tools -> Options ... Set things like tabs and syntax highlighting.

 

By default, the SDK will mount a filesystem in the Solution Explorer, which may affect performance if there are a lot of files, causing the editor to lag.  If this is the case, you can click "Show All Files" to remove the All Files view, and navigate to files through the Class View.  Editing will be a lot faster.  Set Show All Files to false by default at Tools -> Options -> Windows Live Agents SDK -> SDK Settings -> General -> "Show All Files on project open."

 

Keyboard Shorcuts 

As of right now, there isn't a keyboard shortcut for starting/stopping the agent in the Conversation Window.  However, here are some shorcuts you may find useful:

 

CTRL-K CTRL-C ... comment

CTRL-K CTRL-U ... uncomment

CTRL-ALT-L ... Solution Explorer

CTRL-TAB ... toggle through open windows

CTRL-Shift-<arrow key> ... move forward/backward by one word

 

Many other shortcuts are listed next to the menu items they correspond to.

 

One of the best things about Visual Studio is the flexibility it provides for laying out your environment.  Any window can be tabbed, docked, or floating, and you can drag everything around the way you like.  Right click a window title, or click the small arrow in the top of the pane, to see your options. 

 

This is a continuation on An Advanced Look at Web Services and DataSources.  The original entry is located here:   http://windowsliveagents.spaces.live.com/blog/cns!5BCD45E519E07634!711.entry

 

Now let’s take a look at the datasource itself.  The datasource essentially is a function itself, with arguments to pass, and variables to return. In the preprocess section, the POST_DATA variable where the XML SOAP request string was built is put into here.  In addition, the actual web service URL is stated here as well. 

 

In the preprocess section, there are also two built-in variables that can be used, LIMIT and OFFSET.  These two variables are used to ‘page’ results in a cursor.  In the example above, we look at LIMIT to populate a variable called MAXRESULTS. The MAXRESULTS variable is then used in the COUNT element (in this case 10) to bring back 10 results per request.  If the user needs more, then the datasource then starts at the next row and retrieves 10 more results.

 

The simple xml section is a hierarchical representation of the XML response from the SOAP API, to be flattened out into a 2-dimension look when the data is retrieved.  Indentation is used to signify a parent-child relationship. The {loop=content} statement acts as a loop within the XML, iterating through the XML.  The end nodes (highlighted in BOLD) are the fields that is used to capture information and passed back to the calling routine.  Note that fields can be skipped in the simple xml section if the user does not need it.

 

It should be noted here that by using simple xml to represent the XML response, there is no provision for providing a “dynamic” representation of the XML using simple xml.  So in essence, you would have to potentially write a different datasource function for each different search type in this case.  For generate an advanced datasource that could output differently depending on the search type would require outputting a datasource in Buddyscript. We’ll cover this in a different blog.

 

 

datasource LiveSearchAPI(SEARCH, CULTURE_INFO) => Title, Description, Url, Source, NewsYear, NewsMonth, NewsDay, NewsHour, NewsMinute, NewsSecond {expire="in 1 hour" continue_on_error="true" timeout="15" }

  preprocess

    if LIMIT>10 || LIMIT<=0

      MAXRESULTS = 10

    else

      MAXRESULTS = LIMIT

    FIELDLIST = "Title Description Url Source DateTime"

    POST_DATA = BuildSearchAPIPostData(SEARCH, "News", OFFSET, MAXRESULTS, CULTURE_INFO, FIELDLIST)

  http

    http://soap.search.msn.com:80/webservices.asmx

    header

      Accept: application/soap+xml

    postdata {encode=no}

      POST_DATA

  simple xml

    Envelope

      Body

        SearchResponse

          Response

            Responses

              SourceResponse

                Offset => RESULTOFFSET    // Where we're starting from.

                Total => TOTAL     // Total number of results.  

                Results

                  Result {loop=content}

                    Title

                    Description

                    Url

                    Source

                    DateTime

                      Year

                      Month

                      Day

                      Hour

                      Minute

                      Second

  postprocess

    INFO.Offset = RESULTOFFSET

    INFO.MaxCount = TOTAL

    return INFO

 

 

There are other datasource properties that should be considered to either increase performance and or deal with potential errors in accessing/retrieving information from the datasource.  The first one is the Timeout property.  You can specify this time in order to lengthen or shorten the time it takes before the datasource quits accessing the web service.  The default value is 10 seconds.  In our case, we have it at 15 seconds.  The next property is the continue_on_error property.  By changing this property to ‘yes’, execution will still continue and the datasource caller can retrieve the error message in the SYS.Data.Error variable.  This is only on those sources that call the ABErrorProc.  The final property is very important.  It is the Expire property.  This determines how long retrieved data should be valid, i.e. kept in cahsed memory.  The ability to cache retrieved data in memory will improve performance on retrieving information in the datasource.  You should consider these factors:

 

1) how often does the data change?

2) how often will the same retrieved data be asked again?

3) how large is the retrieved data set?

4) server memory cache size (N/A on hosted applications)

5) how fast does the web service perform?

 

All of these are considerations.  In our case, since news items change frequently, we’ll set it for a relatively short time period, say 1 hour. 

 

Examples of the Expire property:

 

Expire=”never” /* this is the default expiration for most non-Buddyscript datasources */

Expire=”in 1 hour”

Expire =”now”  /* no caching at all, same as “never” */

Expire=”tomorrow at 5am” /* Note that this time is the server time, not the client time.  In hosted applications, this is in GMT time */

 

The postprocess section is important for returning a range of information.  For datasources that do not handle the processing of data using offsets and limits (i.e. simple xml), if the postprocess section is missing, the processing QueryServer will process the data coming back from the datasource in its entirety. In cases where the output coming back is one entity or one row, or if the amount of data needed to be processed is small, the postprocess section is not needed.

 

  postprocess

    INFO.Offset = RESULTOFFSET

    INFO.MaxCount = TOTAL

    return INFO

 

Looking at the postprocess section, this section is used to set the offset and total count of rows in a variable.  This variable is then used by Buddyscript to control the display of output.

 

In this case, INFO is the name of an object variable. The names of the variables inside the object is Offset and MaxCount, and these values are populated from the datasource:

 

                Offset => RESULTOFFSET    // Where we're starting from.

                Total => TOTAL     // Total number of results.  

 

 

Finally, here is a crude routine to pass a request to the Live Search API, access the web service and display the contents of the data, using Buddyscript code to control the amount of data coming in.

 

? Tell me some news about STRING=Anything

  LOCALE="en-us"

  TITLE, DESCRIPTION, LINK, SOURCE, YEAR, MONTH, DAY, HOUR, MINUTE, SECOND = LiveSearchAPI(STRING, LOCALE) show 10

    * Here are the results:

    - TITLE, SOURCE

    * <blank/>

      <ifmore>Type "more" for more news.</ifmore>

  else

    - Sorry, no news sites were found for your input.  

 

In the input, you could ask a question such as “Tell me some news about Baron Davis” for example, and get back results that looks like this (notice that the output only contains 2 out of the 10 arguments returned, Title and Source):

 

Here are the results:

 

Baron Davis Going South, San Francisco Gate

The Baron Davis, Gilbert Arenas Switch-a-roo?, San Francisco Gate

Clippers set sights on Baron Davis, Los Angeles Times

Baron Davis on verge of signing with Clippers, Washington Post

NBA: Warriors trying to woo Brand, Newsday

Baron Davis becomes free agent, Chicago Sun-Times

Report: Davis to ditch Warriors for Clippers, FOXSports.com

Logo? Colors? History? Don't mean a thing if you ain't got that team, CBS Sportsline

Davis on verge of joining Clippers, CNN Sports Illustrated

Davis on verge of signing with Clippers, Salon

 

Type “more” for more news.

.

.

.

.

 

 

Notice that in the pattern routine, there is an option called SHOW 10.  This means to output 10 rows at a time.  Buddyscript will go to the output datasource to retrieve the information, which in this case happens to be exactly 10 rows, since the request was to buffer 10 rows per datasource request.  If the user were to type in “more”, another 10 rows will be retrieved from the datasource and 10 more rows will be displayed, and so on.  (Note that there is a Buddyscript variable named SYS.Presentation.Maxlength that also controls the number of characters that can be displayed on an IM client.  Depending on what this is set to, this number will also control the number of rows displayed back.)

 

With the SHOW command, this allows the user a quick and equivalent way of emulating a forward read-only cursor, i.e. displaying x number of rows of output at one time.  The other option would be to put the data into an object and loop through the object, displaying each row, which involved more coding. It’s very possible that for control purposes, the latter method is the right way to go, but for quick coding and display, SHOW is very powerful.

 

Hopefully you have gotten a chance to absorb the intricacies of using datasources by accessing a really powerful web service.  Thanks for your attention!