Groove Web Services Release Notes for Microsoft SharePoint Workspace 2010

The Help folder contains the documentation for the SDK. The Help folder contains the following file:

• GrvWSDevLib.chm — Contains the Groove Web Services Programmer's Guide and the Groove Web Services API Reference.

The Lib folder contains the Groove WSDL files that describe the Groove Web Services API and source files that make it easier to create projects to handle events. The Lib folder contains the following subfolders:

• DotNet\GrooveEvents — includes definitions for Groove Web Services events. Include the appropriate language file in your project to use the GrooveEvents operations.

• XMIs\2.0 — includes the .wsdl and .xsd files that describe the Groove Web Services API. Use the .wsdl files to set the Web References for Groove Web Service applications.

Visual Studio stores Web references to .wsdl files on the local file system as absolute file paths. The SDK samples assume that the .wsdl files are in the following location:

c:\GrooveWebServices\Groove Web Services SDK\Lib\XMIs\2.0\wsdl

If you do not extract the SDK to the default location, you will be able to compile and run the samples. However, you will be unable to update the Web references of the samples without updating the location of the WSDL file for each imported Web reference.

The Samples folder contains the following subfolders:

• GrooveRemoteExplorer
  This sample is provided in C# .NET. It shows how to use Groove Web Services to display the data about the accounts on the device, the workspaces for each identity, and the tools in each Groove 2007 workspace.

• GrooveFormsExplorer
  This sample is provided in C# .NET. It shows how to use the GrooveForms2 service to display data from Groove Forms V5.0 tools and InfoPath Forms V1.0 tools in Groove 2007 workspaces.

Each developer sample includes a readme file that provides a brief description, the software requirements, and the steps that you must follow to install and run the sample.

In SharePoint Workspace 2010, all web services keys are in the following location in the registry:

HKEY_CURRENT_USER\Software\Microsoft\Office\Groove\WebServices

These keys are as follows:

• GrooveHTTPDesiredPort

• GrooveHTTPPort

• GrooveLocalHTTPPort

• GrooveLocalHTTPServerPID

• LocalRequestKey

• LocalResponseKey

The meaning of these keys has not changed from Groove 2007. See Groove Web Services Registry Keys for more information.

In order to get the string values of the LocalRequestKey and LocalResponseKey keys, you should call the Unprotect(byte[], byte[], DataProtectionScope) method. For example:

Microsoft.Win32.RegistryKey grooveWebServicesRegKey =
  Microsoft.Win32.Registry.CurrentUser.OpenSubKey(
  "Software\\Microsoft\\Office\\Groove\\WebServices");
if (grooveWebServicesRegKey != null)
{
  Object keyValue = grooveWebServicesRegKey.GetValue("LocalRequestKey");
  if (keyValue != null)
  {
    byte[] unprotectedData = ProtectedData.Unprotect((byte[]) keyValue, null,
      DataProtectionScope.CurrentUser);
    string localRequestKey = Encoding.Unicode.GetString(unprotectedData);
    return localRequestKey;
  }
}  

In order to call the Unprotect(byte[], byte[], DataProtectionScope) method, you must add a reference to the .NET System.Security assembly in your C# project and add the following line to your C# file:

using System.Security.Cryptography;

This code fragment also uses the Getstring(byte[]) method.

You can use any GrooveSpaces operation with a Groove 2010 workspace. Although the GrooveSpaces.Read operation returns a URL for the GrooveTools service, you cannot perform any operations on a Groove 2010 workspace with the GrooveTools, GrooveCalendar, GrooveForms2, or GrooveFilesBase64 service. Groove 2010 Workspaces have a Space.Version major version number 20.

Note
If you call GrooveTools.ReadAvailableTools on a Groove 2010 workspace, it returns an empty list because there are no tools that you can add.

Note
The GrooveSpaces.Create operation creates a Groove 2007 compatible workspace. You can create either a Groove 2007 or a Groove 2010 workspace with the GrooveSpaces.CreateFromGSA or the GrooveSpaces.CreateFromGSAByRef operation. The created workspace will have the same version as the original workspace that was exported to the .GSA file.

There is no Groove Web Services access to SharePoint workspaces.

Access to Shared Folders is unchanged from the access available to Groove File Sharing workspaces in Groove 2007 SP1. Shared Folders currently have a Space.Version major version 18.

The GrooveProperties.Read operation returns a major version number value of 14 for SharePoint Workspace 2010.

Groove 2007 SP2 provides additional Web Services operations as Groove Web Services Version 2.1. These additional operations are not available in SharePoint Workspace 2010.

• Windows XP with Service Pack 3 (SP3) or a later version 32-bit operating system

• Windows Server 2008 or a later version 64-bit operating system

• 750 MHz processor, 900 MHz or faster recommended

• 256 MB RAM, 380 MB or more recommended

• 300 MB free disk space, 1 GB recommended

• Display resolution 1024x768 or higher resolution monitor

In order to run the samples provided in this SDK, you should have the following installed on the system:

• SharePoint Workspace 2010

• Microsoft Visual Studio 2008 and the Microsoft .NET Framework Version 2

You can write SOAP clients for Groove Web Services in any Microsoft .NET CLR language or any development environment that supports SOAP. The sample project files that are provided in this SDK require Microsoft Visual Studio 2008. You cannot open these projects with earlier versions of Microsoft Visual Studio.

If any Groove development kits are installed on the system, they will not be automatically uninstalled when this SDK is installed. You should uninstall any previous Groove development kit that is installed on the system before you install this SDK. If you have installed Microsoft Office Groove 2007 SDK for Service Pack 2 (SP2), it does not have an uninstaller; you can delete it before you install this SDK. If you want to preserve any information from previous development kits, make a copy of the relevant files before you uninstall or delete the kit.

The SDK installer is a self-extracting zip archive. When you unzip this SDK, the default location is C:\GrooveWebServices\.

To uninstall this SDK, copy any files that you have altered and want to preserve and then delete the folder where you installed the SDK.

In SharePoint Workspace 2010, workspace archives must include the workspace data. Consequently, the ExportAsArchive operation should return an exception if the IncludeData parameter has a false value, but it does not. Instead, if IncludeData input parameter has a false value, the operation attempts to create an archive without workspace data. The resulting file contains a corrupted archive. If you attempt to instantiate a workspace from this corrupted archive, SharePoint Workspace 2010 displays an error message for 2010 workspaces but encounters a fatal error for 2007 workspaces.

The GrooveForms2.QueryRecords operation may encounter errors when it is trying to read unread records only. If a GrooveForms2.QueryRecords operation is passed a RecordQuery.UnreadRecordsOnly parameter equal to true, the query should return only unread records. In some cases, this operation encounters an error and returns a SOAP exception. As a workaround, set RecordQuery.UnreadRecordsOnly to false to read both read and unread records. After receiving the results, you can test the _UnreadFlag system field in the each record to determine whether the record is unread.

If you create an aggregated subscription for GrooveTools events using the GrooveSubscriptions.CreateAggregated2 operation, you will not receive events from workspaces created after the subscription is created. As a workaround, create individual tool subscriptions for each workspace. You can listen to GrooveSpaces events and create a new GrooveTools subscription when the SpaceAddEventData event is encountered for a new workspace.

If you create multiple subscriptions for the same event source on a 64-bit system, SharePoint Workspace 2010 may encounter errors processing the events. As a workaround, ensure that, at most, one subscription is active for a source at any time. This problem does not occur on systems with the 32-bit version of SharePoint Workspace 2010.

Groove Web Services do not process correctly any parameters that are specified after an omitted optional parameter. If there are no parameters specified after an omitted optional parameter, Groove Web Services handle the parameters correctly.

The workaround is to always specify optional parameters.

Some data changes produce multiple events even when there is a single data update. For example, adding a contact can produce three GrooveContacts events. These Web Services events are caused by events in the underlying Groove component. A single gesture by a Groove user can generate multiple events. Although this behavior can be surprising, it is as designed.

An exception to this behavior is how the GrooveForms2 service handles record update events. GrooveForms2 generates a single event for any update transaction in a Groove Forms or InfoPath Forms tool. The event shows the final state of the updated records.

Note that if an account has more than one identity that is a member of a workspace, an events subscription will receive duplicate events, one for each identity in the workspace.

The great majority of the SOAP exceptions that may be generated by Groove Web Services operations are not localized; that is, they are only provided in English and are not translated to the local language. Some of the exceptions may be localized.