The Microsoft Office Live Small Business Blog: Developers

The Microsoft Office Live Client Application Connection code sample

Wed, 28 Mar 2007 22:27:41 GMT

The Microsoft Office Live Developer Platform Team has created some sample code to show how you can use Microsoft Office Live Web services to connect your client-side application to Microsoft Office Live data.

This code sample takes advantage of the Microsoft Office Live Discovery Web service, Windows Live ID for client applications , and the authentication services provided in the Microsoft System.Net namespace. Once you know how to combine these services, you can provide access to data in an Office Live subscription from your application without requesting additional credential information.

As an example of accessing Microsoft Office Live data after authentication, the Client Application Connection sample includes code that connects to a Microsoft Office Live server with the user's Windows Live ID credentials to list all documents in one of the user's Microsoft Office Live document libraries.

Download the sample

Client Application Connection is provided as sample code. You can copy snippets of this code or duplicate them in your application to help you provide authenticated connections.

To download the .exe file, go to the Microsoft Download Center.

· Click the .exe file to install the Client Application Connection files to the following location:

C:\Microsoft Office Live Developer Resources\Client Application Connection Sample

Authenticate your Client Application Connection

With Windows Live ID for client applications, your application can access Windows Live ID sites and services, including Microsoft Office Live, using a customized authentication ticket. Let’s say that Dan Park signs in to his Microsoft Office Live account, and then opens your client application.

The following steps demonstrate how you can authenticate Dan from your client application to allow access to Microsoft Office Live data.

Step 1. Authenticate Dan’s Windows Live ID account.

This sample uses the IdentityManager class of Windows Live ID to create an Identity object for the current user and then uses the Authenticate method of this class to authenticate the user’s Windows Live ID account.

IdentityManager identityManager;

identityManager = IdentityManager.CreateInstance(applicationId,

applicationName);

Identity identity = identityManager.CreateIdentity();

if (!identity.Authenticate())

{

throw new ApplicationException("Unable to authenticate the

user’s Windows Live ID account.");

}

Step 2. Get the Microsoft Office Live settings needed to generate a Windows Live ID authentication ticket.

The Client Application Connection code takes advantage of the Microsoft Office Live Discovery Web service to quickly discover the appropriate Live ID settings. First, it accesses the Discovery Web service.

Discovery discoSvc = new Discovery();

discoSvc.Url = "https://apis.officelive.com/discoverywebsvc/discovery.asmx";

Next, it gets the Windows Live ID settings for the Microsoft Office Live service.

LiveIDSettings settings = discoSvc.GetLiveIDSettings();

Step 3. Request Dan’s current Windows Live ID authentication ticket for the Microsoft Office Live service.

You can use Windows Live ID’s GetTicket method to get the user’s authentication ticket information for the Microsoft Office Live service.

string ticket = identity.GetTicket(settings.SiteName, settings.Policy, false);

Step 4. Authenticate Dan for Microsoft Office Live Web requests.

The class WindowsLiveAuthenticationModule, included in this sample code, handles Windows Live ID authentication for Microsoft Office Live Web requests. This module implements an IAuthenticationModule interface from the Microsoft System.Net namespace.

This sample code then creates and registers a new authentication module using the Register method of the AuthenticationManager class in the Microsoft System.Net namespace, passing the ticket obtained in step 3.

WindowsLiveAuthenticationModule authModule;

authModule = new WindowsLiveAuthenticationModule(ticket);

AuthenticationManager.Register(authModule);

Authenticate is the core method for the Client Application Connection sample custom authentication. The following are details of the actual process that triggers the Authenticate method:

1. When an Internet resource requests authentication, the System.Net WebRequest.GetResponse method calls the AuthenticationManager.Authenticate method.

2. The AuthenticationManager.Authenticate method calls each registered authentication module to find the first module that can respond to the authentication request.

3. When a module responds, an Authorization object is returned to the Web request.

This Authorization is the key you need to unlock Dan’s Microsoft Office Live data.

Access Microsoft Office Live data

The example in this code is designed to print the names of the documents in the user’s Microsoft Office Live document library if the user is authenticated.

You can use methods of the Discovery class in the Discovery Web service to determine the subscriptions that are associated with Dan Park and find a document library included in those subscriptions. The GetSubscriptions method allows you to identify a Microsoft Office Live subscription that Dan owns. The GetResources method returns a list of resources, including document libraries, in the subscription. The code in this example selects the first document library it finds.

The calls to the methods of the Discovery class invoke a WindowsLiveAuthenticationModule to authenticate this Microsoft Office Live Web request:

discoSvc.UserAgent = discoSvc.UserAgent + ";" + WindowsLiveAuthenticationModule.WindowsLiveClientHeader;

discoSvc.Credentials = new NetworkCredential();

To access Windows Live ID sites and services, including Microsoft Office Live, you must find the URL of the Web Service Description Language (WSDL) file that describes the service. The service being used in this example is the SharePoint Lists Web service. In addition to adding this service as a Web reference, the example constructs a URL for it.

string listServiceUrl = userDocumentLibraryUrl +

SharepointServicesPrefix + "Lists.asmx";

It then connects to the Lists Web service for Dan’s document library.

Lists listsWebService = new Lists();

listsWebService.Url = listServiceUrl;

Next, it invokes a WindowsLiveAuthenticationModule to authenticate this Microsoft Office Live Web request.

listsWebService.UserAgent = listsWebService.UserAgent + ";" +

WindowsLiveAuthenticationModule.WindowsLiveClientHeader;

listsWebService.Credentials = new NetworkCredential();

The example then uses the Lists Web service to access and print the titles of all documents contained in Dan’s document library.

Connect your client applications

The Web services provided by Microsoft Office Live, Windows Live ID for client applications, and the Microsoft System.Net namespace combine to provide easy access to the information you need in order to provide a connection between a client application and Microsoft Office Live data. You can use the code in this sample to help incorporate this functionality in your application.

The Office Live Developer Platform team

The Microsoft Office Live Time Card sample code

Thu, 22 Feb 2007 05:35:12 GMT

The Microsoft Office Live team has created another set of sample code to show off how you can use Microsoft Office Live Web services to extend the functionality of an Office Live business application. This newest sample, called Microsoft Office Live Time Card, extends Microsoft Office Live Project Manager (available with any Microsoft Office Live Premium or Microsoft Office Live Essentials subscription).

The Microsoft Office Live Time Card sample code shows a way to track time by project task. It uses Web services to look at a project you’ve already set up in Project Manager to populate a list of project tasks.

We created this sample to provide an example of how you can model your own calls to the Windows SharePoint Services Web services hosted by Microsoft Office Live. These services give you quick and easy access to the lists in the various Microsoft Office Live business applications, such as the Project Tasks list used in this example.

Look at the end result

The best way to understand the functionality is to install it on an Office Live business application. The download is an executable file that has everything you need, including a sample page containing a Page Viewer Web Part configured so that you can quickly see the results of the code. Here’s all you need to do to check it out:

1. To download the .exe file, go to the Microsoft Download Center.

2. Click the .exe file to install the Time Card files to the following location:

C:\Microsoft Office Live Developer Resources\Time Card Sample

3. Upload the files to a document library in a business application. For example, you can put the files in the Document Library of Document Manager.

4. In the Document Library, click samplepage.

5. In the TimeCard list creation dialog boxes, click OK.

This sample Web page opens with a Page Viewer Web Part configured to display our version of a time card. This time card allows the user to pick one project task and then Punch In to track the time he is currently spending on that task. The total time spent on each task is then stored, so that the next time he opens the time card the time tracked so far on any task appears in the Time spent on task field.

Web part configured as a time card

How it works

The tasktime and timecard JScript files provide the functions and methods needed to create and use our time card.

Build and manage the dropdown list of tasks

The getTasks function in timecard.js uses a Web service call to collect the tasks in the Project Tasks list of Project Manager, to populate the Project Tasks field.

The Time Card Project Tasks

We’ve already done the work of putting JScript functions together to package up the SOAP requests you need to talk to Office Live Web services. You can use these same functions from the common Jscript file (olsharedlibv1.js) to jump start your development work.

TaskTimer is the function defined in tasktime.js. If the user switches the task in the time card, the switchTask method of the TaskTimer function is called.

Capturing the duration of a task

The startTimer and stopTimer functions triggered by the Punch In button cause the timer to start and stop for the current task.

Storing and retrieving the recorded time

When you installed this sample code, an Office Live list named TimeCard was created to store time record items. Each time that an amount of time is recorded for a particular task, an item is added to this list. This time record item is created when the user clicks Punch in and modified when the user clicks Punch out. The duration is then calculated by taking the difference between the created and modified time of the list item. Finally, the total duration for a task is calculated by summing the duration of all list items associated with a particular task.

We wouldn’t generally allow an end user to see this list, as it’s a back end item. The list created by this sample code can be viewed in Project Manager. On the actions bar, click the arrow next to More, and then click TimeCard. The list is created and initialized by the createTimerList and initializeTimerList functions.

Your turn

This is just a quick example of the type of services you can add to your client’s Office Live Premium or Office Live Essentials subscription. The Web services provided by Windows SharePoint Services and the data stored in Office Live combine to provide functionality that can streamline your client’s day-to-day processes. The common JScript functions help you accomplish this with minimal effort.

To learn more about the Web services offered by Windows SharePoint Services, download the Windows SharePoint Services 3.0 SDK.

To learn more about which Windows SharePoint Services Web services are supported by Microsoft Office Live, read the Microsoft Office Live Developer’s Guide.

The Office Live Developer Platform team