Groove Web Services Release Notes for Microsoft SharePoint Workspace 2010

  • Article

Applies to: SharePoint Workspace 2010 | Visual Studio 2008

In this article
SDK Contents
What Is New in the Groove Web Services SDK for SharePoint Workspace 2010
Groove Web Services SDK for SharePoint Workspace 2010 Requirements
Groove Web Services SDK Installation
Groove Web Services SDK Release Issues

The Groove Web Services Software Development Kit (SDK) for Microsoft SharePoint Workspace 2010 contains documentation, developer samples, and tools to help with Groove Web Services development.

These release notes are valid for SharePoint Workspace 2010 with Groove Web Services Versions 2.0 and 2.1. Groove Web Services Version 2.1 is available in SharePoint Workspace 2010 with the August 2012 cumulative update.

SDK Contents

The SDK is provided as a self-extracting zip archive. When you install the Groove Web Services Software Development Kit (SDK), the Help, Library, and Sample folders are extracted to your hard disk. You can extract the files to any folder that is convenient. By default, the SDK is extracted to c:\GrooveWebServices

The SDK is copied into the following three folders:

Groove Web Services SDK\
  Help
  Lib
  Samples

Help Folder

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

  • SPW14GWSCon.chm — Contains the Groove Web Services Concepts, API Reference, and Release Notes.

Lib Folder

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.

SDK Samples Folders

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.

What Is New in the Groove Web Services SDK for SharePoint Workspace 2010

This section describes what is new in this SDK.

SharePoint Workspace 2010 provides Web services that are compatible with the Web services available in Groove 2007. There are four significant changes:

  • The Office Cumulative Update for August 2012 provides Groove Web Services Version 2.1. Groove Web Services Version 2.1 extends the capabilities of Groove Web Services and provides support for invisible Groove 2007-compatible workspaces.

  • The location of the keys in the registry has changed.

  • The LocalRequestKey and LocalResponseKey are encrypted by using DPAPI CurrentUser encryption.

  • There is no Web service access to tool data in 2010 workspaces. Access to Groove 2007-compatible workspaces is unchanged from the access available in Groove 2007.

What Is New in Groove Web Services Version 2.1

Groove Web Services Version 2.1 provides operations to enable applications to control the lifetime of a workspace and to minimize the need for users to interact with the Groove user interface.

Groove Web Services Version 2.1 contains the following new operations and events:

  • GrooveLocal.SetAlertLevel—enables or suppresses alerts for all accounts.

  • GrooveMembers.Create2—invites the specified member to the Groove 2007-compatible workspace providing options, such as requiring confirmation or using a silent invitation.

  • GrooveMembers.Update—updates the role of the specified member of a Groove 2007-compatible workspace.

  • GrooveMessages.AcceptInvitation—accepts an invitation to a Groove 2007-compatible workspace.

  • GrooveMessages.DeclineInvitation—declines an invitation to a Groove 2007-compatible workspace.

  • GrooveMessages.ConfirmInvitation—confirms an accepted invitation to a Groove 2007-compatible workspace.

  • GrooveMessages.DenyInvitation—denies an accepted invitation to a Groove 2007-compatible workspace.

  • GrooveMessages.ReadInvitations—reads the invitations and invitation responses for Groove 2007-compatible workspaces for the identity.

  • InvitationReceivedEventData—indicates that an invitation to a Groove 2007-compatible workspace was received.

  • InvitationResponseReceivedEventData—indicates that a response to an invitation to a Groove 2007-compatible workspace was received.

  • GrooveSpaces.Create2—creates a new empty Groove 2007-compatible workspace with advanced options that include workspace visibility and alert level.

  • GrooveSpaces.CreateFromGSA2 and GrooveSpaces.CreateFromGSAByRef2— create a new workspace from a Groove Space Archive for a Groove 2007-compatible workspace with advanced options that include workspace visibility and alert level.

  • GrooveSpaces.CreateGrooveFileSharingSpace2—creates a new Groove File Sharing workspace with advanced options that include workspace visibility and alert level.

  • GrooveSpaces.CreateInvitationFile2—creates an invitation file to a Groove 2007-compatible workspace by using advanced options that include silent invitations and specifying the application to handle the invitation.

  • GrooveSpaces.Update2—updates the Groove 2007-compatible workspace with advanced options that include workspace visibility and alert level.

  • GrooveSpaces.Read2—provides extended information about Groove 2007-compatible workspaces including invisible workspaces, which are not returned by Read.

  • GrooveSpaces.ReadSpace2— provides extended information about the targeted Groove 2007-compatible workspace.

  • SpaceDeliveryProgressEventData—indicates the progress of a Groove 2007-compatible workspace being sent to an invitee. This event is available on both the inviter's and invitee's systems.

  • GrooveSubscriptions.Create2—creates a subscription that, optionally, specifies a query that limits an invitation message subscription to invitations targeted to the specified application.

  • GrooveTools.ReadPermissions—reads the tool permissions or the available tool permissions for the specified role in a Groove 2007-compatible workspace.

  • GrooveTools.UpdatePermissions—updates the tool permissions for the specified role in a Groove 2007-compatible workspace.

Registry Key Changes

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.

To get the string values of the LocalRequestKey and LocalResponseKey keys, you should call the Unprotect([], [], 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;
  }
}

To call the Unprotect([], [], 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([]) method.

Web Services Access to Groove 2010 Workspaces

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.

Web Services Access to SharePoint Workspaces

There is no Groove Web Services access to SharePoint workspaces.

Web Services Access to Shared Folders

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.

Other Web Services Changes

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

Groove Web Services SDK for SharePoint Workspace 2010 Requirements

Your system must meet the following minimum requirements to install and use the Groove Web Services SDK for SharePoint Workspace 2010:

 Operating System

  • 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

 Hardware Requirements

  • 750 megahertz (MHz) processor, 900 MHz or faster recommended

  • 256 megabytes (MB) RAM, 380 MB or more recommended

  • 300 MB free disk space, 1 gigabytes recommended

  • Display resolution 1024x768 or higher resolution monitor

 Software Requirements

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

 Development Environment

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.

Groove Web Services SDK Installation

This section provides information about how to install the Groove Web Services Software Development Kit (SDK).

Remove previous versions of Groove Development Kits

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. To preserve any information from previous development kits, make a copy of the relevant files before you uninstall or delete the kit.

Install the SDK

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

Before uninstalling the SDK, you can copy any files to a backup folder. Then uninstall the SDK by deleting the folder where it is installed.

Groove Web Services SDK Release Issues

This section provides late-breaking information about Groove Web Services in SharePoint Workspace 2010.

SharePoint Workspace 2010 may return different SOAP exceptions

SharePoint Workspace 2010 may return different SOAP exceptions than Groove 2007 under the same conditions. For example, SharePoint Workspace 2010 returns the SOAP exception "Not enough privileges to update user role. " but, under the same conditions, Groove 2007 returns the SOAP exception "Access denied. "

ExportAsArchive Does Not Handle Parameter Errors

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.

GrooveForms2.QueryRecords May Encounter Errors Reading Unread Records Only

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.

GrooveTools Events Are Not Received for Aggregated Listeners

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.

Multiple Subscriptions for the Same Source Can Fail on x64 Systems

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 Handle Optional Parameters Correctly In Some Cases

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.

Multiple Events from Single Data Update

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.

Many Groove Web Services SOAP Exceptions Are Not Localized

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.