Collaborate

Help Teams Work Together With Web Services And Groove 2007

John C. Hancock

Code download available at: Groove 2007_05.exe(524 KB)

Contents

Building Solutions with Groove
Groove 2007 Architecture
Using Groove Forms to Collect Data
Accessing Groove Data from an Application
Using the Groove Web Services API
Registry Settings for Groove Web Services
Accounts and Identities
Getting a List of Workspaces and Tools
Fetching Data from Groove Forms
Loading Forms Data into a Database
Conclusion

In the real world, users often need to collect information while they are out of the office and unable to access their company networks. For example, a consumer research organization might send employees out to the field to ask people to fill in a paper survey, and then manually enter this data into a database. If you wanted to write a custom application that could be used in the field to automate this process, you would need to handle issues like managing a local data store and synchronizing it with a server database.

In this article, I show how the unique collaboration capabilities in Microsoft® Office Groove™ 2007 let you solve these problems as I integrate them into a custom Microsoft .NET Framework application. Groove provides the rich client for collaborative data gathering and secure synchronization of data between team members, and my custom .NET Framework application will be used to connect the data to a corporate database.

Groove is an environment for team collaboration that allows members to share data across organizational boundaries, regardless of the network they are connected to. In other words, participants don’t need to be part of the same network, making Groove a great collaboration tool when you need to include employees, partners, and customers without requiring the cooperation of IT departments. Groove is also excellent for mobile scenarios where users have to be able to go offline and still access and update the shared data, and also need to automatically synchronize data when they are back in connected mode.

Groove 2007 is part of the Ultimate and Enterprise editions of the 2007 Microsoft Office system, and can be purchased as a separate product. You can also install a free trial of Groove and download the Groove SDK from microsoft.com/downloads.

Building Solutions with Groove

You can build custom collaboration solutions using the out-of-the-box Groove features like file sharing and discussions just by creating workspaces with the relevant tools and then saving the workspace as a reusable template. If you need more flexibility, you can also build custom applications that take advantage of the secure collaboration facilities in Groove through the Web services-based API.

For the consumer research application solution I discuss here, the researchers who will use the application use Tablet PCs to fill in surveys while they are out in shopping malls. Ideally, the solution should work while the users are offline and then allow them to easily consolidate the information from the different researchers. In practice, it would be great if a researcher could simply walk into a café with a public Internet connection and have the solution automatically and securely synchronize the information with all participants.

The first step in designing the solution is for the research coordinator to create a new workspace in Groove. Every workspace can include multiple tools for particular requirements, such as a Files tool that allows participants to share documents with each other, and a Discussion tool so that people can ask and respond to questions from other participants.

Once the workspace is created, the research coordinator sends an invitation to all of the researchers to join the workspace. This invitation shows up as a notification to each participant, allowing them to download the workspace to their local machines. Everyone is now ready to collaborate—any change that a participant makes to his local copy of the workspace, such as adding a file or discussion topic, will be automatically and securely propagated to all the other participants when they are connected to a network.

Groove 2007 Architecture

Groove has an innovative architecture that is the source of its unique capabilities. First, Groove stores all the data on participants’ PCs rather than on a central server. This means that there is no need to devise a secure way for all participants to access a shared resource; whether the researchers are employees of the company or independent users, the research coordinator can easily create a shared workspace and invite them to participate.

Second, all of the data is always encrypted—both the local workspaces on disk and all network communications. One of the benefits of this is that researchers can synchronize their changes simply by connecting to through a public Internet connection. There is no need for all participants to have virtual private network (VPN) access to corporate resources, because the automatic synchronization is already encrypted.

Although most of Groove is client-based, there are also a few server components. Groove uses a relay server that acts as a store-and-forward service so that clients can communicate across firewalls using standard protocols; the relay server also stores temporary encrypted copies of workspace updates for offline users. In addition, there is a management server so that administrators can manage licenses and policy settings for all the users.

Standalone Groove users can create their own accounts when they install the client, which will automatically use relay servers hosted by Microsoft. Large companies with many Groove users might choose to deploy Office Groove Server 2007 as part of their own infrastructure so that they have more control over license management and can do things like integrate with Active Directory®. Small to mid-size enterprises can purchase a subscription to Office Groove Enterprise Services, which gives them access to a hosted version of the management tools for centralized control without requiring them to deploy their own infrastructure.

Using Groove Forms to Collect Data

For my solution, the workspace must include a survey form that the researchers can fill out for every consumer that they interview. Groove includes a Forms tool for designing custom forms that allows me to specify fields including data types, captions and other properties. Then the participants can add data to the workspace as shown in Figure 1.

Figure 1** Groove Workspace with Forms Tool **(Click the image for a larger view)

Forms can also include JavaScript or VBScript to extend their capabilities for building custom solutions. Also, there is some flexibility when it comes to UI styles and formatting because the forms use DHTML and CSS. If you are already using InfoPath® forms in your organization, you can use the Groove InfoPath Forms tool to import XML-based InfoPath forms definitions instead of using built-in forms in Groove.

When the workspace with the custom form has been downloaded to the researchers’ tablet PCs, they can disconnect and still use the form to add records while they are in the field. When they connect back to the network, all of the records they have added will be securely synchronized with the other participants. The research coordinator will get a popup notification from Groove so that she knows that there is new unread data in the workspace.

Collecting the data from the researchers is only part of the story though. Once all the data from the individual surveys is synchronized, the research coordinator needs to load all the data into the company’s database so that it can be analyzed further. The company’s analysts will be using a SQL Server™ database, an Analysis Services cube, and Excel® business intelligence capabilities to understand the survey results and make some recommendations.

Accessing Groove Data from an Application

To get data out of the Groove workspace and into a corporate database, the research coordinator could manually export the data from the Groove forms tool in a format such as CSV (comma-separated values) and then import it into the database. However, this manual process would quickly become unmanageable if she needed to load the survey data into the database for analysis as it became available, rather than all at once.

A better solution would be to build a custom .NET Framework application that uses the Groove Web services-based API to read the data entered by the field researchers. Install this application on the research coordinator’s PC and she can access both the Groove workspace and the SQL Server database because she is connected to the corporate network as shown in Figure 2, unlike the researchers in the field who may only be connected to the public Internet.

Figure 2** Groove Workspace Users and SQL Server Database **(Click the image for a larger view)

This approach is similar to the way Groove is integrated with Windows® SharePoint® Services (WSS) 3.0. Teams can use a Groove workspace for collaborating on documents, and then publish the completed documents to a SharePoint document library so everyone in the company can take advantage of SharePoint’s capabilities such as search and workflow. The way this works is that someone with access to both Groove and the SharePoint site adds a SharePoint Files tool to the workspace and connects it to a SharePoint document library. All workspace participants now have copies of all the documents and can submit changes, which the connected user can then synchronize with the SharePoint document library when necessary.

Using the Groove Web Services API

Even though I am developing a client application, the programming model for Groove uses Web services rather than a managed API. It feels a little strange programming this way because the client application is calling Web services that are actually running on the same machine. These services will still be available even when the machine is disconnected from the network—the Groove client itself is answering the requests. For larger enterprise solutions, a server-based product called Groove Server Data Bridge with a similar programming model is available, but I am going with the client-side approach for this solution.

To create the client application shown in Figure 3, I start by adding Web references to my project for each of the Groove services that I want to access. The Groove SDK includes a WSDL file for each service, so I add the Web reference by specifying the path to the relevant .wsdl file, renaming the Web reference from the default "Web Reference" to something more useful and clicking the Add Reference button. In this application, I will be using the GrooveAccounts, GrooveForms2, GrooveSpaces, and GrooveTools services.

Figure 3** Load Groove Data into a SQL Server Database **(Click the image for a larger view)

Registry Settings for Groove Web Services

I will need to know the port that Groove is using before I can call the Web service—this defaults to 9080 but I should retrieve it from the GrooveLocalHTTPPort registry setting for the current user. I will also need to supply a value called a request key for every call, which the Web services use to authenticate the caller. I can retrieve this key from the LocalRequestKey registry setting, as shown in Figure 4. The request key is randomly regenerated every time Groove is restarted, so I should retrieve it from the registry before every call in case it has been regenerated since the last time I checked.

Figure 4 Registry Settings for Groove Web Services

using (RegistryKey grooveSettingsRegKey = Registry.CurrentUser.OpenSubKey(
    “Software\\Microsoft\\Office\\12.0\\Groove”))
{
    // Get the URL for web services including the port
    string grooveHost = string.Format(“https://localhost:{0}”, 
       grooveSettingsRegKey.GetValue(“GrooveLocalHTTPPort”, 9080));

    // Get the LocalRequestKey for authentication
    string localRequestKey = (string)grooveSettingsRegKey.OpenSubKey(
        “WebServices”).GetValue(“LocalRequestKey”);
    ...
}

The other registry setting that is used for Web service authentication is the response key. Every time I make a call to a Groove Web service, the response includes a key that I can check against the LocalResponseKey registry setting to make sure they match.

Accounts and Identities

Every Groove user has an account that is configured the first time he starts up Groove. The account is stored as a file on their computer (or on multiple computers), and includes information such as cryptographic keys and contact lists. Every account also has at least one identity that contains the contact information that is shared with other Groove users, such as an e-mail address and phone numbers. An account can also contain multiple identities if required so that, for example, a person can use one identity for business purposes and another for personal use such as sharing files with friends.

I can use the GrooveAccounts service to get the list of accounts and identities on the computer. After setting up the Web service call using the request key and port as shown in Figure 5, I can use the Read2 method of the GrooveAccounts service to return an array of Account2 objects. Each account has a collection of identities, so I can load up a list of identities to allow the user to select which one has the consumer research workspace as shown in Figure 3. (Most users only have one account with a single identity.)

Figure 5 List All Groove Accounts

// Set up the web service call for GrooveAccounts
GrooveAccounts.GrooveAccounts svc = new GrooveAccounts.GrooveAccounts();
svc.GrooveRequestHeaderValue = new GrooveAccounts.GrooveRequestHeader();
svc.GrooveRequestHeaderValue.GrooveRequestKey = localRequestKey;
svc.Url = grooveHost + “/GWS/Groove/2.0/Accounts/”;

// Get a list of all the accounts
GrooveAccounts.Account2[] accounts = svc.Read2();

// Display all identities
foreach (GrooveAccounts.Account2 account in accounts)
    foreach (GrooveAccounts.Identity2 identity in account.Identities)
        Console.WriteLine(account.Name + “, “ + identity.Name);

Getting a List of Workspaces and Tools

Once I know which identity I am working with, I have enough information to get a list of the user’s workspaces using the Read method of the GrooveSpaces service. The identity object has a URI property that is unique for this identity and can be used for most other Groove Web service calls as shown in Figure 6, and also a Spaces property that contains the URL for the user’s workspaces.

Figure 6 List All Groove Workspaces

private void LoadSpaces(GrooveAccounts.Identity2 identity)
{
    // Set up the web service call for GrooveSpaces
    GrooveSpaces.GrooveSpaces svc = new GrooveSpaces.GrooveSpaces();
    svc.GrooveRequestHeaderValue = 
        new GrooveSpaces.GrooveRequestHeader();
    svc.GrooveRequestHeaderValue.GrooveRequestKey =   
        GrooveSettings.RequestKey;
    svc.GrooveRequestHeaderValue.GrooveIdentityURL = identity.URI;
    svc.Url = GrooveSettings.GrooveHost + identity.Spaces;

    // Get the list of spaces
    _spaces = svc.Read(“”);

    // Load the list into a combobox
    comboWorkspaces.DisplayMember = “Name”;
    comboWorkspaces.DataSource = _spaces;
}

As you saw when I created the Groove workspace earlier, each workspace can contain multiple tools such as files, discussions and forms. When the user has selected the workspace in the client application, I can find the forms tool that contains the market research data using the Read method of the GrooveTools service. The workspace only has one forms tool so I can just look for a tool named "Forms", but if I wanted to get more sophisticated, I could display a list of all the tools of the right type and allow the user to pick the right one.

Fetching Data from Groove Forms

Now that I have written code to retrieve the Groove settings from the registry, and to get a list of accounts, identities, workspaces and tools, I am ready to tackle the original requirement of getting the data out of the Groove tool and into my SQL Server database for analysis. Fetching the data is actually pretty easy; I can just set up a query that describes what records I would like to fetch using a RecordQuery object and then pass it to the QueryRecords method of the GrooveForms2 service, as shown here:

// Query ALL records in the ALL view:
GrooveForms2.RecordQuery query = new GrooveForms2.RecordQuery();
query.ViewURI = “”;
query.UnreadRecordsOnly = false;
query.QueryMetadataOnly = false;
query.IncludeFileAttachmentContent = false;

// Issue the query
GrooveForms2.Forms2RecordDataSet recordDataSet = 
    svc.QueryRecords(query);

The fun starts when you take a look at the Forms2RecordDataSet object that is returned by QueryRecords. Forms2RecordDataSet contains both the schema and the data for the form in XML format, so I am going to have to do some further manipulation before I can use it effectively. The easiest way of working with forms data is to convert the Forms2RecordDataSet object into a more familiar .NET DataSet object.

The Groove SDK documentation has a whole section devoted to this topic, and the code is also included in the sample download for this article, so I will just give you a high-level overview here (especially since this is the type of code that you write once and then reuse all over the place). In principle, you create a new DataSet and use the ReadXmlSchema method to set up the tables and column definitions by creating a string reader for the schema and prepending the appropriate XML version declaration to the string. When the schema has been created, you can use the ReadXml method to load the actual data.

One minor issue that you have to take into account relates to date-time columns. Groove returns all date-time fields in the Forms2RecordDataSet as universal time, while the .NET DataSet has them as local time by default. I can avoid problems by looping through all the columns that are created in the DataSet from the ReadXmlSchema method, and setting their DateTimeMode to Utc before I load the data.

Loading Forms Data into a Database

I can now loop through the DataSet and add a new row to the SQL Server database for each new record from the Groove form. The user could run the process any number of times, so I need to have some mechanism to avoid loading duplicate records into the database.

Every record in a Groove form has a system-generated field called _RecordID that uniquely identifies that record. If I include this field when I load records into the database, I can use it to check whether a record has already been added to the database and if so, update the existing database row rather than inserting a duplicate row. This will ensure that any survey records that were modified since the last time the process was run are correctly reflected in the SQL Server database.

Conclusion

Groove is a great environment for building solutions for distributed teams that would be difficult and costly to develop from scratch. Whether you stick to the out-of-the-box features like file sharing and forms or build entirely new applications that build upon the API, Groove is a great addition to your arsenal.

John C. Hancock is a senior consultant for Microsoft, specializing in business intelligence and .NET Framework development. He is the coauthor of Practical Business Intelligence with SQL Server 2005 (Addison-Wesley Professional, 2006).