hughpyle : Forms 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.

Contacts to Outlook

hpyle — Fri, 09 Sep 2005 21:49:00 GMT

As you can probably tell, it's a Friday afternoon, and I still have a load more of this to get through before the weekend. On Tuesday, I'm presenting this story at PDC. But the story is hidden behind all the little bits of code right now. So let's cut the code, make room for more of the story soon.

We scanned Groove workspaces and tools, and loaded Groove Forms data into a DataGridView for display in a form. The final piece to that application is to drop the selected rows of data into Outlook's "Contacts".

I implemented this by an accessor method in my form class:

// Access to the currently-selected-contacts list

public ArrayList GetSelectedData()

{

// read the VCard for each selected contact,

// and add it to the VCardList.

ArrayList dataRows = new ArrayList();

foreach (DataGridViewRow dgvr in dataGridView1.SelectedRows)

{

dataRows.Add(((System.Data.DataRowView)dgvr.DataBoundItem).Row);

}

// Equivalent for DataView:

//int n = 0;

//foreach (System.Data.DataRow row in ((System.Data.DataTable)dataGridView1.DataSource).Rows)

//{

// if (dataView.IsSelected(n))

// {

// dataRows.Add(row);

// }

// n++;

//}

return dataRows;

}

And when the form is closed, the caller (my addin class) puts the selected rows into Outlook like this:

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 )

{

ArrayList rowList = selectionForm.GetSelectedData();

foreach (System.Data.DataRow row in rowList)

{

Microsoft.Office.Interop.Outlook.ContactItem contactItem;

contactItem = (Microsoft.Office.Interop.Outlook.ContactItem)applicationObject.CreateItem(Microsoft.Office.Interop.Outlook.OlItemType.olContactItem);

if (row.Table.Columns["FullName"] != null) contactItem.FullName = (string)row["FullName"];

if (row.Table.Columns["NickName"] != null) contactItem.NickName = (string)row["NickName"];

if (row.Table.Columns["FirstName"] != null) contactItem.FirstName = (string)row["FirstName"];

if (row.Table.Columns["LastName"] != null) contactItem.LastName = (string)row["LastName"];

if (row.Table.Columns["Suffix"] != null) contactItem.Suffix = (string)row["Suffix"];

if (row.Table.Columns["JobTitle"] != null) contactItem.JobTitle = (string)row["JobTitle"];

if (row.Table.Columns["CompanyName"] != null) contactItem.CompanyName = (string)row["CompanyName"];

// I think that's enough to start with. Now save it to Outlook.

contactItem.Close(Microsoft.Office.Interop.Outlook.OlInspectorClose.olSave);

}

catch( Exception e ) { /* stuff */ }

}

So it's only at this last stage that we need any knowledge of the fields in our data.

Anyone reading this: now would be a great time to ask questions ("hughpyle" at...)!

Reading Forms Data

hpyle — Fri, 09 Sep 2005 21:35:00 GMT

I think we can read Forms data now.

We already added event handlers to two of our three combo-boxes (IdentitiesCombo, WorkspacesCombo), so let's do the same for the ToolsCombo, which contains a list of tools in the selected workspace. When the selection changes, we should read data from the tool.

private void ToolsCombo_SelectedIndexChanged(object sender, EventArgs e)

{

// Each item in the combobox is a ToolInfo, containing a Groove Tool

ToolInfo t = (ToolInfo)ToolsCombo.SelectedItem;

ReadDataFromTool(t.tool);

}

To display the data, let's drop a DataGridView into the form, and make it read-only. (DataGridView is new with Visual Studio 2005; if you're using Visual Studio 2003, a DataGrid is just as good). Then, when we have some data, let's assume we also have a DataSet. The only magic piece here is that the data set will need a particular name ("RecordDataSet"), because that's the name we'll receive from Groove.

private void ReadDataFromTool(Tool t)

{

// Make a DataSet to contain the records

System.Data.DataSet recordDataSet = new System.Data.DataSet("RecordDataSet");

// ... Get some data ...

// Bind the dataset to the grid view

dataGridView1.ReadOnly = true;

dataGridView1.DataSource = recordDataSet.Tables[0];

}

Without further comment, let's just read data.

// The Tool has a web service URI for us to access its data via the GrooveForms service

string toolURI = t.Data;

GrooveForms formsService = new GrooveForms();

formsService.GrooveRequestHeaderValue = new GrooveFormsWebService.GrooveRequestHeader();

formsService.GrooveRequestHeaderValue.GrooveRequestKey = GWSUtil.GrooveLocalRequestKey;

formsService.GrooveRequestHeaderValue.GrooveIdentityURL = selectedIdentity.URI;

formsService.Url = GWSUtil.GrooveURL + toolURI;

// Query for all the records, no attachments

GrooveFormsWebService.RecordQuery recordQuery = new GrooveFormsWebService.RecordQuery();

recordQuery.FieldSchemaScopingElement = "";

recordQuery.FieldSchemaScopingFlag = "All";

recordQuery.FileAttachmentFormat = "Base64";

recordQuery.FormURI = "";

recordQuery.IncludeFileAttachmentContent = false;

recordQuery.QueryMetadataOnly = false;

recordQuery.UnreadRecordsOnly = false;

recordQuery.ViewURI = "";

recordQuery.WhereClause = "";

// Ask service to query records

FormsRecordDataSet fds = formsService.QueryRecords(recordQuery);

And we end up with a FormsRecordDataSet, which is a serialized set of Groove Forms data retrieved from the web service. In this case we called QueryRecords(), which is a very flexible way to retrieve some or all records in a tool; it can include a WhereClause with some SQL-like syntax: a conditional expression or a series of conditional expressions joined by AND and OR logical operators (and parentheses), with the usual comparison operators, "LIKE" and "NOT LIKE". (The full documentation for this is in the API reference in the Groove Web Services GDK). To read a known subset of the data, an alternative to QueryRecords() would be ReadRecords(), which takes a list of record URIs for specific records.

The FormsRecordDataSet arrived in a SOAP packet as a chunk of XML, and it turns out that the XML format for this is designed to be essentially the same as a System.Data.DataSet serialization; there's an array of schema nodes, and an array of data nodes. So we can push that XML into our DataSet quite easily:

// If schema exists, load it into the DataSet

if (fds.Schema is System.Array)

{

// For Groove V3 it's safe to assume there is only one schema in the dataset (although this may change)

System.Xml.XmlNode[] schemaNodes = (System.Xml.XmlNode[])fds.Schema;

foreach (System.Xml.XmlNode schemaNode in schemaNodes)

{

System.IO.StringReader schemaReader = new System.IO.StringReader("<?xml version=\"1.0\"?>" + schemaNode.OuterXml);

recordDataSet.ReadXmlSchema(schemaReader);

}

// If data exists, load it into the DataSet

if (fds.Data is System.Array)

{

System.Xml.XmlNode[] dataNodes = (System.Xml.XmlNode[])fds.Data;

foreach (System.Xml.XmlNode dataNode in dataNodes)

{

System.Xml.XmlNodeReader dataReader = new System.Xml.XmlNodeReader(dataNode);

recordDataSet.ReadXml(dataReader, System.Data.XmlReadMode.Auto);

}

And we're done! Because the FormsRecordDataSet includes its own schema, and the DataSet knows how to parse a schema in XML format, there's no need to wrestle with individual columns and their datatypes; it just drops right in. Then when bound to the DataGridView, we see Groove data in the form.

Copy, paste, build, run. Outlook shows my menu-button, and when I click the button, here's the form:

Wasn't that easy?

Identifying Groove Forms Tools

hpyle — Fri, 09 Sep 2005 21:05:00 GMT

The various workspace tools each have a Type, which identifies the tool: Files, Discussion, Calendar, Forms, and so on.

The standard list of tool types in Groove V3 are:

urn:groove.net:platform.tools.Forms

urn:groove.net:platform.tools.Files

urn:groove.net:platform.tools.Discussion

urn:groove.net:platform.tools.Calendar

Within a Forms tool, the designer may also have specified a DesignName and DesignVersion; these are optional, but I'd strongly recommend you use them to label your tools. The design name is a URN. The design version is just a string, but I recommend choosing a "dotted numbers" format: at a minimum <majorversion>.<minorversion>. That way, it's easy to identify releases of the same tool with compatible schemas (same major-version) or incompatible schemas (different major-version), and to write code to handle your various versions appropriately.

I went back and added a nice long design-name, and a version number, to the Forms tool from earlier:

Now, our GWS application currently list all workspace tools in the tools combo-box. This can easily be reduced to only display Forms tools, by checking the tool's type:

Tool[] tools = toolsService.Read();

// Add the tools to the combobox (unselected).

foreach (Tool t in tools)

{

// Only add the tool to the list if it's a Forms tool

if (t.Type == "urn:groove.net:platform.tools.Forms")

{

ToolsCombo.Items.Add(new ToolInfo(t));

}

We want to further restrict this to only include Forms tools with the design-name we chose. Only those tools will have the correct schema, and the data-transfer portion of my little application will be hard-coded to only expect the fields I created in that forms tool. The code for this is slightly more involved, because DesignName isn't a property on the Tool; it's a property on a ToolProperties class, which requires one extra web-services call to Groove.

if (t.Type == "urn:groove.net:platform.tools.Forms")

{

// Query the forms tool to find its "design name"

// (property set by the forms designer).

// The contacts tool we can connect with has a known type (which we made up):

// urn:groove.net:pdc2005.demonstration.Contacts

// Only add these special tools to the tools combobox.

string toolURI = t.Data;

GrooveForms formsService = new GrooveForms();

formsService.GrooveRequestHeaderValue = new GrooveFormsWebService.GrooveRequestHeader();

formsService.GrooveRequestHeaderValue.GrooveRequestKey = GWSUtil.GrooveLocalRequestKey;

formsService.GrooveRequestHeaderValue.GrooveIdentityURL = selectedIdentity.URI;

formsService.Url = GWSUtil.GrooveURL + toolURI;

ToolProperties tp = formsService.ReadToolProperties();

if (tp.DesignTemplateName == "urn:groove.net:pdc2005.demonstration.Contacts")

{

ToolsCombo.Items.Add(new ToolInfo(t));

}

The behaviour of our application, once this code is added, isn't really optimal: you're presented with a list of workspaces, even those which don't contain any matching tools. Doing this "properly" is left as an exercise to the reader :-)

One more thing...

hpyle — Fri, 22 Jul 2005 20:49:00 GMT

The Rabbit is muttering to itself, "Oh dear! Oh dear! I shall be late!", so I must press on. So much to do. I have to write about the Groove EDB Server next, and then Web Services, and start showing some (C#) Real Code. I have a presentation the first week of August to cover the same ground I'm treading here and more, and this is thinking aloud.

But I can't leave Forms behind, at this early stage, without pointing toward the scripting features which make it a powerful application builder. (You can't (yet) integrate managed code in the Groove Forms tool user interface. But in case you're wondering, JavaScript is Real Code too, for all its faults).

Go back into the forms designer, to modify the Contact form. (Either select "Modify Form -> Contact", or "Open Design Sandbox" then select the form in the design objects tree).

Then "create new field..." and select "Script Button" field type.

Make three buttons. For the first, set the OnClick script to this:

alert( document.getElementById('FullName_Field').outerHTML );

There's a HTML input field on the form (in edit mode -- it's slightly different in preview mode) which is called "FullName_Field", because we have a field called "FullName"; this script reaches into the form's HTML and displays the contents of that piece of the form's structure. So, hey, the form is a web page. There are some helper functions (GetHTMLFieldValue etc) to get the current value out of an input field while in edit mode, and to set values directly into these fields; documentation in the Forms developer guide under "PublicScript Functions And Properties".

For the second, try this script:

alert( GetApp().CurrentAuthorName );

GetApp() is a helper function which gets you the Groove Forms UI Delegate (a COM component which implements IGrooveFormsToolUIDelegate) which has lots of really useful methods and properties. For example, here, to retrieve the name of the current user. Again, the developer guide (under GrooveFormsToolUIDelegate) has all the details.

For the third, this:

alert( GetFormRecord().OpenField("FullName") );

GetFormRecord() opens the current record (with a COM interface, IGrooveFormsToolRecord), from which you can read and write fields directly. Note: these are different from the values displayed in the form: if you make changes in the form, they aren't (usually) applied to the Record until you save changes. But the record's always accessible, so if you really really want to read and write its values, you can do that at any time.

If there's a hierarchy of records, for example in a discussion (with "main topics" and "responses"), you can also use the Record interface to walk up and down the hierarchy. For example, you might want to grab a field value from the topmost parent in a response hierarchy, to insert somewhere in the current form UI.

Enough rope to be dangerous. Two take-aways from this little segment, though.

One: the user interface of a form is HTML -- it's actually an embedded Internet Explorer control -- and you can use all your favourite DHTML techniques on the form. (There are lots of places to hook script into the form, and we'll cover them all in some detail, later...). Some of our custom applications have used really sophisticated DHTML: expanding sections, hover animation, dynamic tables, popup menus, and so on.

Two: There's a big difference between the DHTML form (the "front-end") and the record which actually holds the data (the "back-end"). When you start to edit an existing record, the front-end form has its field values populated from the back-end record; when you save, the front-end form pushes its values down into the back-end record; and in between, they are likely different.

Contact Form and View

hpyle — Fri, 22 Jul 2005 17:24:00 GMT

Back to work, then; let's make a Contact form, with some suitable fields on it.

In the last instalment, we were just about to add fields to a new form So let's do that; create a text field. (Select field type "text" and press the "Next>" button, or just double-click on "text"). The first field will be "full name", so let's make that the field's label. Note that you can edit a field's label anytime; the label can be plaintext, or even richtext if you want particular formatting.

The field name, in this case, is quite important too; A fieldname is the internal name used for the field, and never ever changes (and you can never ever have two fields with the same name). Field names can't contain spaces or special characters. I chose a selection of fields (FirstName, LastName, FullName, JobTitle, CompanyName) carefully - those field names happen to be the same as the properties of a contact in Outlook's object model, and I want to synchronize these contact forms with Outlook at some point. So, in the properties list select "Name", and enter FullName.

Then "finish" - let's see how this looks on the form:

OK, it's very plain; there's a "Style" dropdown above the form in the designer, so let's choose "LightSpirit", which looks nicer while still being fairly inoffensive. Now add the other fields too, remembering to enter the name carefully. (Use the "Save and Create Another" button to create lots of fields at once).

Finally, save the form -- the save button is way down the bottom right.

A Forms tool always needs at least one view, to display the records. So, if this is your first form, a helpful popup takes you into the view builder. Here I selected only a few of the fields, and gave the view a name ("Contacts"). Note the "move up" and "move down" buttons at the right, to change the order of columns in the view.

When you're done, save the view. Then press the "Save to Groove" button, which saves all our work from the "designer sandbox" and makes it available to everyone in the workspace. Finally we have a simple form to enter people's contact data, and a view showing our of contacts.

Forms, Fields, and Views

hpyle — Thu, 21 Jul 2005 22:57:00 GMT

The Groove Forms tool is a simple form designer. Sometimes it looks complex, but really the structure is quite straightforward. Let's begin at the beginning.

A Groove workspace contains tools, and members. You create a workspace, you're the only member. Then you invite another person; when they accept your invitation, a copy of the workspace is delivered to their PC, and they become a member too. If they're given appropriate permissions, the can also invite other people. So it grows. Everyone has a copy of the workspace and all its contents.

Most workspaces have several tools; tools can be added (and removed) by any member who has the appropriate permissions. There are several tools "in the box": files, calendar, sketchpad, discussion, and so on. (The most flexible of these is the Forms tool). Every Groove tool is "groovey": any action performed by any member of the workspace is automagically synchronized with all the other workspace members. (This isn't the time and place to explain how that happens. Another time).

The Files tool contains files. The sketchpad tool contains sketches. The forms tool contains, well... fields, forms, views, and records -- and these are user-defined; in other words, you can build your own forms, and make them behave the way you want, and create structured data the way you want to work with it.

When working in a forms tool, the display usually has two parts: at the top, a view (a list of records, displaying a selection of fields in columns); and below, a preview of the current record, which is displaying those and other fields on a form. (This terminology is Notes-like rather than InfoPath-like; that's the way it is, for now, and I hope there's no confusion). There are always multiple fields; there can be one or many forms; and there can be one or many views, each maybe selecting a different subset of the data records. The same field can be used on more than one form, if you want; there can't be two fields with the same fieldname.

To build a forms tool from scratch, you usually start with a blank form, and add fields onto it right away. (It's possible to have fields which aren't used on any form. I don't know a good reason you would want to do that). Then you create at least one view. Then you save, and all the members of your workspace can fill out your form to create records, which will be disseminated to everyone in the space.

Let's walk through building the skeleton of our contact-list tool, so you can see these pieces fit together. Pressing that "start here" button opens the Groove Forms Designer. (At this point, the faint-hearted will pass out. Don't be dismayed; it's easier than it looks). Now, I already know some of the fields I want to add to my contacts form: FirstName, LastName, FullName, JobTitle, CompanyName. So change the form name to "Contact", then click "Create New Field..." in the left-hand tree.

Next up: what the field types are, and we'll create those fields.

Getting Started with Forms

hpyle — Thu, 21 Jul 2005 22:41:00 GMT

Let's get coding.

I want to build a system which has Groove workspaces connected to a central system. This'll be a framework to show the various moving parts, and code to knit them together, and hopefully building something which has at least a nominal type of realistic use.

The scenario I'm working with is this: a Groove workspace with a contact list (and probably some other tools later - discussion, document libraries -- not sure what'll be needed yet). But the contact list helps focus on something simple and easily achievable. It's a nice place to start because there are two types of integration I'll try to demonstrate: one "local", connecting the contacts list with Outlook; one "central", connecting the contact list with either a SQLServer table or maybe a SharePoint site. (Yet to decide that one. I suspect probably SharePoint will be easy enough).

To begin, then: open Groove, create a new workspace. Give it a name; select "template" - "custom".

Then you're presented with a "More Tools" list; check "Forms" and press OK. The new workspace opens, with a nice splash screen saying "Start Here". This is the Groove Forms tool.

Now, before we start creating the forms, let's take a moment to walk through how Groove Forms is structured.