hughpyle : Forms Tips

Forms Script: Send Instant Message

hpyle — Thu, 28 Sep 2006 20:47:00 GMT

I want to take you line-by-line through this code, with maybe a few words of explanation for each piece.

// Find the contact
var pContact = GetContactFieldValue("Contact");

Groove contacts are a datatype unto themselves; the contact object contains a ContactURL (the main unique identifier for this person's Groove identity; this is an opaque string), their VCard (with name, address, telephone numbers, email, and so on), and some internal stuff which provides enough information to allow Groove communicate with this user: the URL of their relay server(s) and their public key.

To send an instant message to a contact, you actually just need their contact URL, but the contact must be "known" as well: in other words, although the API to send a message just wants the contact URL, it needs to look up that contact by URL in your account's database of known contacts, in order to send an encrypted message across the network to that user. This "contact store" is a whole other subject, which I'm happy to delve into sometime. But for now, the Contact field type gives us easy access to a known contact, and the contact's URL.

GetContactFieldValue() is one of the built-in script functions. In the Forms developer documentation (which is part of the SDK), you can find the full list of public script functions; alternatively you can dive right in to the PublicFunctions.js script file which is located in Program Files\Microsoft Office\OFFICE12\Groove\ToolData\groove.net\GrooveForms5.

if(!pContact)
{
GetApp().DisplayError("Please specify a contact.");
return;
}

GetContactFieldValue() returns the contact object (a IGrooveFormsToolContact) which is contained in the specified field. If no contact has been selected, the return value is null, so we display an error message and return.

To display the error message, I could have used "alert()", since the form page is just an Internet Explorer document. But you get a nicer dialog box by using the DisplayError function.

GetApp() returns the Forms tool's "UI delegate": the entrypoint into a collection of Groove-related functions and capabilities. In this case, DisplayError is just a method on the UI delegate itself. You can also access the other script interfaces and their functions by a syntax like, for example

GetApp().IGrooveFormsToolApplicationPreferences.DoesPreferenceExist("something")

For a full list of these other interfaces and functions, again, refer to the forms developer documentation in the SDK.

if(!pContact.IsGroovey)
{
GetApp().DisplayError("Please specify a Groove contact.");
return;
}

We know we have a IGrooveFormsToolContact object, and this is an extra safety check to ensure that the contact is "groovey": that the contact represents a Groove user, rather than just an email address or other contact who can't receive Groove instant messages. It's actually quite hard to create non-groovey contacts in Groove 2007, but you might come across them occasionally.

var enumContacts = CreateBSTREnumFromArray([pContact.ContactURL]);

The pContact.ContactURL gives us the URL of the selected contact (which is a string). Wrapping this in square brackets is JavaScript's syntax to create a single-element array. Then we convert the script array into a BSTREnum, because the SendInstantMessage method we want to call later takes a IGrooveBSTREnum as the list of recipients. A BSTREnum is an (unordered, strictly) enumeration of strings. CreateBSTREnumFromArray() is one of the public script functions.

// Get the message text
var sMessage = GetHTMLFieldValue("Message");

Reads the text contents of the Message field into a string. GetHTMLFieldValue() is another of the public script functions.

// Send message
GetApp().SendInstantMessage(enumContacts,sMessage);

Sends an instant message, with the message body specified in sMessage, to the list of contacts in enumContacts. The body is just plain text. There are some optional parameters to this method, which we're just ignoring here: whether to track the message delivery, and whether to save the sent message into your message history. There's also an interesting alternate method, SendInstantMessageWithLinks, which can embed Groove hyperlinks into the message.

And that's it. A simple form which sends instant messages when you press a button. Extensions of this technique can be used to send messages automatically when a form is saved or particular conditions are met. I hope this little walkthrough has covered a few of the not-completely-obvious ways in which Groove Forms script hangs together. Let me know other subjects you'd like to see given the same treatment!

Forms Script: Send Instant Message

hpyle — Thu, 28 Sep 2006 20:29:00 GMT

Sorry about the hiatus here. It's been a while.

Here's a little piece of script code for Groove Forms, which might be useful to a few people. It's also small enough to be a nice illustration of some of how script and forms work together.

The application itself is small enough to be nearly trivial: make a form with a button on it which sends an instant message to someone. So, let's start with a new forms tool; create a contact field called "Contact", and a multi-line text field called "Message", and a script button called "Send". In the designer, it looks like this:

In the fields list, double-click the "Send" button-field to modify its properties; under "OnClick", enter a line of script code which calls a function we'll write in a second:

SendIM()

And save. Then, "Create new script", and paste in this script code.

function SendIM()

{

// Find the contact

var pContact = GetContactFieldValue("Contact");

if(!pContact)

{

GetApp().DisplayError("Please specify a contact.");

return;

}

if(!pContact.IsGroovey)

{

GetApp().DisplayError("Please specify a Groove contact.");

return;

}

var enumContacts = CreateBSTREnumFromArray([pContact.ContactURL]);

// Get the message text

var sMessage = GetHTMLFieldValue("Message");

// Send message

GetApp().SendInstantMessage(enumContacts,sMessage);

}

Save. Create a view. Publish sandbox. New -> Form, and test it out. Everything should work: you can pick a contact in the contact field, write a message, and send the message to that contact.

Now let's look at how this all fits together.

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.