Forms Script: Send Instant Message
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!
