hughpyle : Web Services demo

Furthur!

hpyle — Fri, 09 Sep 2005 22:37:00 GMT

Here's a recap and subject-index of the story so far.

Getting started with Groove Forms; the component parts (Fields, Forms, Views); a digression about the available fieldtypes; and a real example. And a hint about scripting in Groove Forms.
Then a deep dive into some of Groove's synchronization internals.
Groove Web Services (GWS) overview. (You'll need the security stuff to actually use it)
A brief look at the Groove Enterprise Data Bridge, which is a scalable server for Groove Web Services.
Some GWS code in practice: an Outlook addin, which can enumerate Groove identities and workspaces, and tools within a workspace.
How to identify Forms tools, and how to differentiate your Forms tool from others.
Reading and writing Groove Forms data using the Web Services APIs.
The beginnings of a wider story, of how Groove Forms and Web Services can be used to deliver useful context to virtual workgroups in the field.

That's where we'll pick up, later. Meanwhile: have fun, and I hope to see you at PDC next week. My presentation is "OFF303: Groove: Building Enterprise Workgroup Applications", and it's on Tuesday, September 13 2:45 PM in room 406 AB. The session abstract, surprisingly enough, is just about the same as the material I've covered here to date. I'll be bringing lots of code, plenty of customer stories, and as open a mind as I can muster. Then we'll jump off from there.

This session covers the architecture and design of Groove applications connected to enterprise systems. We show how to use the Groove Forms tool to build collaborative applications with the Groove client, and take apart a custom C# application that uses the Groove Web Services to connect Groove workspaces and Groove Forms data into an enterprise process.

See you at PDC!

Now it begins

hpyle — Fri, 09 Sep 2005 22:19:00 GMT

We've created an application which can read and write Groove data.

Groove's web services APIs also expose a very wide range of other functionality. Let's outline some of the possibilities.

Create a new workspace, blank, or from an archive or template (GSA file). (See GrooveSpaces.CreateFromGSAByRef, GrooveSpaces.CreateGrooveFileSharingSpace). A template consists of a set of tools, and can include data (files, checklists, and so on).
Add new tools into an existing workspace (GrooveTools.Create).
Read data from another system and write it into the new workspace. And vice versa. Files, forms records, discussions, calendar entries.
Invite people to a workspace (GrooveMembers.Create); or create an "invitation file" which can be posted on a website or attached to an email (GrooveSpaces.CreateInvitationFile)
Save a workspace as an archive (GrooveSpaces.ExportAsArchive)

We've concentrated on the detail of reading and writing data, but the surrounding activities really make this thing fly. We call an application implementing these a "controller".

My full demo is almost useful. It's a standalone application which scans a WSS list ("Incidents") looking for new records. When there's a new incident, my code creates a new Groove workspace, and pulls in data from the incident record and from other lists on the SharePoint site, into Groove Forms tools in the workspace. Then it creates an invitation file, and attaches the invitation to the incident record on SharePoint. If there were an assigned responder in the incident record, it could also send an invitation proactively to that user. (All of that takes only a few seconds).

The result of that simple skeleton demo app is that an incident team can rapidly be "swarmed" to handle a new occurrence, and then work with the appropriate team to handle the incident -- without being tied to the WSS site (which might be behind the firewall) -- and can continue working together even when communications is interrupted. After all, the Groove workspace contains all the relevant contextual data right away, with no user intervention, and members of the workspace don't need any network access to work with that data - it can be read and updated offline.

In a real system, you'd probably have the controller write data, or summary extracts, back from the workspace into the back-end whenever it changes. You'd also run the controller on a Groove Enterprise Data Bridge server, behind the firewall, 24/7.

Extending the reach of back-end systems, into the messy ugliness of real-world virtual team environments.

GWS Security

hpyle — Mon, 15 Aug 2005 16:25:00 GMT

Access to a Groove workstation is controlled by the account passphrase; once the account is unlocked, you can create workspaces, and read and modify data within all your workspaces (according to the permissions you have in those workspaces). Similarly, the web services interface doesn't introduce any additional access control restrictions. The Groove Web Services APIs allow essentially unrestricted access to everything within an account.

The secret key to unlock GWS access, however, is not the account passphrase. (Your account passphrase is never stored on disk, and we don't want to send it over a TCP port either; it's not just secret, it's personal too). So the GWS designers needed to create something else for authentication -- authentication of an application (a process running on the local machine, usually) which wants access to your Groove data. (The account must also be logged in, by the user typing their passphrase, because the passphrase really does key the cryptographic stuff of the account. If a GWS application requests access to a workspace when the account is not logged in, Groove will pop up the login dialog).

The solution is implemented using a registry key in the HKCU hive. When Groove starts, it creates a strong random secret, and writes that to a "current user" registry location (HKCU\Software\Groove Networks, Inc.\Groove\WebServices\LocalRequestKey). Local web services requests must provide that key value, which they can obtain by reading the registry (ie. by having a certain level of access to the local system). The key value may change at any time.

To avoid man-in-the-middle attacks on web services accesses, Groove also provides a LocalResponseKey in its SOAP responses, which again can be validated against the local registry if you want. Groove also writes its process ID to HKCU\Software\Groove Networks, Inc.\Groove\GrooveLocalHTTPServerPID.

Remote access -- usually only deployed for EDB servers where an integration application is running on a separate server in the data center -- uses a slightly different method; there's a different registry key (HKCU\...\RemoteRequestKey), but this one can be set to any value and remain constant, if appropriate. Confidentiality of the remote key and the network traffic is not done by Groove, so for remote applications you probably want a dedicated LAN segment and IPSEC, or some other mechanism, to secure the SOAP access. (Remote access is also disabled by default, and you need policy settings to switch it on. WS-Security: not yet.)

The other missing piece from my first code was the GWS HTTP port (which defaults to 9080). Again, there's a local registry key (HKCU\Software\Groove Networks, Inc.\Groove\GrooveLocalHTTPPort) updated by Groove when it starts listening.

To write an application calling local Groove web services, then, we need a few helper routines to provide access to these values. Each SOAP request sent to Groove must include the request key in the SOAP header, and the call must be targeted at the appropriate TCP port.

Here's my (static) util class which implements this. (Note: there's no dependency on the Groove WSDL web references):

namespace GrooveContactsAddin

{

static class GWSUtil

{

static public string GrooveURL

{

get

{

string url;

Microsoft.Win32.RegistryKey HKCU_GrooveRegKey = Microsoft.Win32.Registry.CurrentUser.OpenSubKey(@"Software\Groove Networks, Inc.\Groove");

object DesiredGroovePort = HKCU_GrooveRegKey.GetValue("GrooveHTTPDesiredPort", null);

if (DesiredGroovePort != null)

{

url = "http://localhost:" + DesiredGroovePort;

}

else

{

object GroovePort = HKCU_GrooveRegKey.GetValue("GrooveLocalHTTPPort", "9080");

url = "http://localhost:" + GroovePort;

}

return url;

}

static public string GrooveLocalRequestKey

{

get

{

Microsoft.Win32.RegistryKey HKCU_GrooveWebServicesRegKey = Microsoft.Win32.Registry.CurrentUser.OpenSubKey(@"Software\Groove Networks, Inc.\Groove\WebServices");

string key = (string)HKCU_GrooveWebServicesRegKey.GetValue("LocalRequestKey");

return key;

}

static public string GrooveLocalResponseKey

{

get

{

Microsoft.Win32.RegistryKey HKCU_GrooveWebServicesRegKey = Microsoft.Win32.Registry.CurrentUser.OpenSubKey(@"Software\Groove Networks, Inc.\Groove\WebServices");

string key = (string)HKCU_GrooveWebServicesRegKey.GetValue("LocalResponseKey");

return key;

}

GWS Application: Part 2

hpyle — Tue, 26 Jul 2005 15:51:00 GMT

Let's ask Groove for a list of accounts, identities, and workspaces, and display them in our form.

A groove account contains one or more identities, which are alternate names for the same user. You can create multiple identities, to appear with different names in different workspaces. (This is one of Groove's very-little-used features; I don't know anyone who actually uses multiple identities regularly. But it means that your workspaces are each tied to the identity, not the account).

Having added the GWS web references to our project, it's quite easy to ask Groove for the list of accounts, which returns an array including the list of identities for each account:

// Create an instance of the GrooveAccounts web service proxy class to call Groove

GrooveAccounts accountsService = new GrooveAccounts();

accountsService.GrooveRequestHeaderValue = new GrooveAccountsWebService.GrooveRequestHeader();

accountsService.GrooveRequestHeaderValue.GrooveRequestKey = "SECRET KEY GOES HERE";

accountsService.Url = "http://localhost:9080/GWS/Groove/2.0/Accounts";

// Read the list of Groove accounts

Account[] accounts = accountsService.Read();

foreach( Account a in accounts )

{

foreach( Identity i in a.Identities )

{

// Do something with the identity (display it in a combobox, for example).

}

One of the properties on the Identity i is Spaces, which is a string: the URL of the Spaces web service, which we can call to read the list of workspaces for this identity (and to create new workspaces, rename, export spaces as archive, and so on).

Two problems with the code so far. First, there's a secret key we don't know about; second, that URL is hard-coded to port 9080, and that's not a safe assumption (the port may change). Now, I only want to do this once, but it'll take a whole post to cover properly. Up next.

GWS Application: Part 1

hpyle — Mon, 25 Jul 2005 22:09:00 GMT

Almost ready to write some code to call Groove Web Services now.

My aim is to create an Outlook addin, which reads data from the Groove Forms tool we made earlier; the tool is a contact directory, and we'll pull those records out of Groove, into a contact-picker UI, and drop them into Outlook as contacts. (Much later, we'll read and write the same Forms data to a server-based system, using EDB, but this is a good place to start).

First step is to create a generic Outlook addin. For this, I just followed Dan Crevier's instructions. Be sure to very carefully follow his instructions about PIAs and the GAC. (There's more documentation on MSDN, but Dan's code should get you all the way).

There's only one piece of Dan's code I would recommend to change: I'd been playing around trying to decide whether I want a button (msoControlButton) or a dropdown menu (msoControlPopup with added buttons) on the toolbar, and at one point had a bunch of stray buttons left on the toolbar; so my code is a bit more aggressive in cleanup:

// Create a toolbar button on the standard toolbar that calls ToolbarButton_Click when clicked

try

{

// Delete any existing buttons or popups with our "Add Groove Contact" label.

while( true )

{

CommandBarControl c = (CommandBarControl)commandBars["Standard"].Controls["Add Groove Contact"];

c.Delete(false);

}

catch( System.Exception )

{

}

// Create it

this.toolbarButton = (CommandBarButton)commandBars["Standard"].Controls.Add(Microsoft.Office.Core.MsoControlType.msoControlButton, System.Reflection.Missing.Value, System.Reflection.Missing.Value, System.Reflection.Missing.Value, System.Reflection.Missing.Value);

this.toolbarButton.Caption = "Add Groove Contact";

this.toolbarButton.Tag = "Add Groove Contact Button";

this.toolbarButton.OnAction = "!<MyAddin1.Connect>";

this.toolbarButton.Visible = true;

this.toolbarButton.Style = MsoButtonStyle.msoButtonCaption;

this.toolbarButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.OnToolbarButtonClick);

Also add a new Windows Form to the project; mine's called Form1, and when the toolbar button is clicked, the form is shown.

private void OnToolbarButtonClick(CommandBarButton cmdBarbutton,ref bool cancel)

{

try

{

// Display the contact picker form

Form1 selectionForm = new Form1();

if( selectionForm.ShowDialog() == System.Windows.Forms.DialogResult.OK )

{

// later

}

catch( Exception e )

{

string msg = e.Message + System.Environment.NewLine + System.Environment.NewLine + e.StackTrace;

System.Windows.Forms.MessageBox.Show( msg, "Error", System.Windows.Forms.MessageBoxButtons.OK, System.Windows.Forms.MessageBoxIcon.Error );

}

Final step for now: add Web references to the Groove WSDL files, so we'll be able to call Groove. Right-click on "Web References" in the solution explorer; select "Add Web Reference"; enter the path on disk to the GrooveAccounts.wsdl file (C:\Program Files\Groove Networks\Groove Web Services Development Kit\Lib\XMI\2.0\wsdl\GrooveAccounts.wsdl, for example), and add this with a web reference name of "GrooveAccountsWebService". Then repeat for all the other Groove WSDL files (or at least for the ones we'll use in this project: Accounts, Forms, Spaces, Tools).

Unfortunately, I don't believe there's a shortcut to adding each reference separately. But you only need to do this once :-)

Build. (Did that work? Run Outlook, press the button to see an empty form...)

Next up, a few lines of code to actually call Groove.

Groove Web Services

hpyle — Mon, 25 Jul 2005 18:02:00 GMT

A quick overview of Groove Web Services (GWS), before EDB, I think.

The primary programming interface to Groove nowadays, apart from writing script inside of the Forms tool, is to talk SOAP. (I've written about Groove web services in the past, but not for a while - all my old links are stale). To get started, you'll need Groove, and the Web Services Development Kit (2.6MB EXE).

When Groove is running on your PC, it's listening for SOAP requests -- usually on port 9080 (although if another application gets that port before Groove starts, it might be something else). Yes, Groove is a local web server, albeit a very specialized one. (Note that by default, Groove only listens for requests on localhost - it's possible to enable remote web services access, so other machines can call into your Groove device, but that turns out to be quite an unusual situation -- we'll cover some of the use cases when talking about EDB).

The web service lets you address various Groove facilities at URLs underneath the root. For example, the Accounts service is at http://localhost:9080//GWS/Groove/2.0/Accounts, the Spaces service at http://localhost:9080/GWS/Groove/2.0/Spaces, and so on. Each service has a unique URL endpoint, and the SOAPAction specifies the action you want to perform: create, read, update, delete and so on. This makes for a fairly REST-like and very "regular" development model; once you've used one service, it's very straightforward to see how to call the other services too.

The development kit consists of WSDL and XSD, several samples (in C# and perl), and documentation. It installs usually into Program Files\Groove Networks\Groove Web Services Development Kit\. If you're building an application using Visual Studio .NET, you can just add the WSDL to your solution as web references (from the local disk path). To build the samples, you should refresh each of the web references, just in case they moved. We don't currently have samples for Python or Java or other environments, but the interfaces are the same.

What can you do with the GWS APIs?

Create new Groove workspaces (empty, or from an existing template or archive); create an archive or template from an existing workspace; add tools to existing workspaces; create new entries within the Files, Calendar, Discussion and Forms tools;
Create (or forward, or reply to) Groove instant messages;
Create and send workspace invitations (or create invitation-files, which you can send by email or deliver via a Web page, for example);
Read: enumerate the Groove accounts, identities, contacts, messages, workspaces, tools, members, files, Discussion entries, Calendar entries, Forms records, including rich-text field content and attachments;
Update or delete most tool data;
Subscribe for events, so your application is notified when interesting things happen (when workspace members enter or leave a space or tool; when new members join a workspace; when a new workspace is created or deleted or renamed; when tools are added or removed; and when data changes in a tool);
Using the "local" web service: execute objects from a Files tool; navigate the Groove UI to a particular place; open various Groove dialogs, such as the Contact Properties, the Create New Workspace wizard, and so on.

So that's a reasonably complete set of actions against most of the interesting parts of Groove. There are a few restrictions you'll notice too; it's not possible to create a new Groove account programmatically, or to manipulate the design elements of a Forms tool (only the data). But the spectrum of possible applications is quite large. In nearly all the usage scenarios, Groove is running on a user's machine, and an external application running on the same machine (custom-built, or with GWS code as an addin to some existing application) reaches in to Groove's workspaces, to provide data integration, or to use Groove's synchronization facilities as a collaborative service layer in that application.

For large-scale data integration, you don't often want to run the integration application on each user's own machine. Which is where EDB comes in.