I've always wanted to start a series. And while I'm no Alexandre Dumas, I'm sure the topic will be no less exciting: Comparing SharePoint web services with Groove web services. OK, so maybe there's not as much intrigue but with the convergence of SharePoint and Groove its no less interesting and quite a bit more relevant.

My company produces Project Management software for both SharePoint and Groove. We just released our SharePoint product that uses web services and while we've been shipping a Groove tool for the past three years, we're making a transition to web services for Groove 12. Over the course of several web posts, I will share my experiences with both web service platforms and hope to draw a conclusion on where things are headed. As a teaser, I believe SharePoint and Groove will oneday converge since their models are very, very similar. I talk about this a little bit here.

Note: for brevity, I will refer to SharePoint Web Services as WSS, and Groove Web Services as GWS. Also, I will assume you can set up the web service proxies for both systems. There's plenty of help for WSS. For GWS, a good jumping off point is Hugh Pyle's blog. I'm here to help you get up and running. On to the story....

Everything has a beginning and when talking web services you have to start with authentication. If you're not authenticated, you won't get far. So how to authenticate?

For both systems, authentication information is bundled into each web service request. However, how they bundle the information is quite different.  With WSS, each web service request contains credential information. This is standard SOAP that works with the System.Net.CredentialCache. For example:

SharePointProxies.Lists l = new SharePointProxies.Lists();
l.Credentials = this.System.Net.CredentialCache.DefaultCredentials.

If your default credentials are not sufficient, you will need to create your own credentials, preferably with the credentials UI Microsoft provides. This is the standard Challenge/Response scenario common to Client/Server... oops, I mean Smart Client/Web Service computing.

That's about it for SharePoint since you can only log in as a single entity. Now that you have the proper credentials, you can access WSS for site information, member lists, tools and such. Just be sure to keep that credential handy.

Groove is a different beast, however. While it is a web service endpoint, it is in fact the world's smartest smart client. By this I mean you will most likely be accessing GWS via localhost on the same computer as your application. Because of this, GWS does not use System.Net.ICredentials, but instead creates a separate authentiaction requirement: windows registry lookups for key values.

What's happening is this: because Groove is a smart client most likely running on your local machine, it sets keys for access into the CURRENT_USER hive in your registry. Specifically:

// Read GrooveLocalHTTPPort
Microsoft.Win32.RegistryKey grooveRegKey =     Microsoft.Win32.Registry.CurrentUser.OpenSubKey( "Software\\Microsoft\\Office\\12.0\\Groove" );
string grooveHost= "http://localhost:" + grooveRegKey.GetValue(    "GrooveLocalHTTPPort" ).ToString();

// Read LocalRequestKey
Microsoft.Win32.RegistryKey grooveWebServicesRegKey  = Microsoft.Win32.Registry.CurrentUser.OpenSubKey( "Software\\Microsoft\\Office\\12.0\\Groove\\WebServices");
string grooveRequestKey = (string)grooveWebServicesRegKey.GetValue( "LocalRequestKey");

There is a third key for remote access, but it's left to the user to transport the key value from the computer running GWS to the machine that wants to talk to GWS. Because these keys are generated every time your start Groove, its a non-trivial challenge. The port is also generated by Groove in that 9080 is preferred, but it will bounce higher if another process has already grabbed 9080. So we perform the lookup on this as well.

Once you have the keys, you still must figure out who you want to be. This is done by accessing the GrooveAccounts. You can have multiple user accounts in Groove, much like multiple logins in Windows. Additionally, each account can have multiple identities. GWS wants to know exactly what Identity you want to be in order to work. Maybe you only have one Account with one Identity, in which case life is simple. But if you have multiple Accounts with multiple Identities, then you will need to settle on one. Here is how you can iterate through the choices:

// Create the GrooveAccounts service
GrooveProxies.Accounts accounts = new GrooveProxies.Accounts();
accounts.GrooveRequestHeaderValue = new GrooveProxies.GrooveRequestHeader();
accounts.GrooveRequestHeaderValue.GrooveRequestKey = grooveRequestKey;
accounts.Url = grooveHost + "/GWS/Groove/2.0/Accounts/";
 
// Read the accounts-- this is the actual Web Service Call
GrooveProxies.Account2 [] result = accounts.Read2();

// Display accounts and identities
foreach ( GrooveProxies.Account2 account in result) {

    System.Console.WriteLine( account.Name );

    foreach ( GrooveProxies.Identity2 identity in account.Identities) {

        System.Console.WriteLine( "\t" + identity.Name );

    }
   
}

Once you select your Identity, you have the GWS equivalent of the WSS System.Net.ICredential.

Did you notice the GrooveRequestHeader? This is how GWS extends basic SOAP packets to include its own keys and identity information. Whereas WSS uses a basic SOAP property

SharePointProxies.Lists.Credentials

GWS requires that you use:

GrooveRequestHeader

for authentication. And remember, those GWS key values will change every time the Groove process is restarted, so you can't cache keys. Instead, you should have a routine that does lookups for you when you start a series of operations. Also, unlike WSS, you cannot use the Microsoft credentials UI since GWS does not use System.Net.ICredentials. In fact, Groove has its own login UI that will challenge the user for a password. However, people (like me) often choose the 'Remember Password' option in Groove and rely on a successful Windows login for user validation. Once GWS is accessible, it will provide you the choice of Accounts and Identities you can use.

Wouldn't it be nice if Groove used the System.Net.ICredentials system as well? I suspect this will happen in the future.

Congratulations, you've just been cleared to talk WSS and GWS! But remember that this is a series. We will find out how to gather information about Sites and Workspaces in Part II.