Creating Subscriptions in Groove Web Services
Applies to: SharePoint Workspace 2010 | Visual Studio 2008
To monitor events, you need to create one or more subscriptions. Subscriptions are created to monitor events of a particular event class. They may be created to monitor an individual event source, or all sources within a wider entity such as a workspace or an account.
When you create a subscription, you specify a callback URL. This URL identifies the queue into which events are saved. While each subscription can have its own queue, it is frequently simplest to have all subscriptions share a single queue. As each event is queued, it is assigned a sequence number. The latest sequence number represents the queue's high water mark and is useful in reading and cleaning up the queue.
After a successful non-destructive read, use GrooveEvents.Delete to clean out the processed events. This operation can also be used to delete events without reading them. For example, you could delete events after calling ReadExtended and you determine that there are no events of interest.
To register as a listener and create a new subscription for events, specify the following in a call to the GrooveSubscriptions Create or CreateAggregated2 operation:
Event Class: specifies the class of the event, such as "urn:groove-net:Forms3Event". Typically, each Groove Web Service has one event class.
Query: filters Forms tool events. The query string allows you to specify a Forms tool design and thus limit Forms tool events only to those from a particular kind of Forms tool. This argument is available for aggregated subscriptions only.
Source URI: specifies the source of events for the subscription. The Source URI is typically either a URI returned by another Groove Web Service, such as the URI returned in the Data element by the GrooveToolsRead operation, or a URI identifying a top-level Web Service, such as "/GWS/Groove/2.0/Spaces/". Note that you should not prepend http://host to the Source URI.
If you are creating an aggregated subscription, the scope of the subscription can either be all tools in a workspace or all workspaces in an account.
For a non-aggregated subscription the source must belong to the event class. Thus for example, if the event class is "urn:groove-net:Files2Event", the source object would have to be a Files tool or a SharePoint Files tool.
Callback URI: specifies a locator beginning with dpp://localhost/ that identifies the event queue for the application. Typically the last section of the locator identifies the application, but it could also include a unique ID so that two instances of the application have separate event queues, such as "dpp://localhost/SPACEEVENT_test_client3982a83l".
Time to live: specifies the number of hours that the subscription will be active. The maximum is 2160 hours or ninety days.
The Create and CreateAggregated operations return a SubscriptionID string. The SubscriptionID is included in the events returned by the GrooveEventsRead operation, and it allows you to associate the events with the subscription. You also use the SubscriptionID in the GrooveSubscriptionsUpdate and Delete operations.
The following example shows you how to create a subscription to GrooveMembers events.
See Accessing Accounts and Identities for an example of how to get account information; this is where the accountData variable comes from.
// Set up the subscription call;
// cache the callback URI and subscription ID for later deletion.
// Need a unique identifier for callback URI.
eventCallbackURI = "dpp://localhost/event/" + new
System.Random().Next().ToString();
// Need a time in hours that the subscription should remain active if
// not deleted or updated.
int timeToLive = 1;
GrooveSubscriptions.GrooveSubscriptions subscriptSvc = new
GrooveSubscriptions.GrooveSubscriptions();
subscriptSvc.GrooveRequestHeaderValue = new
GrooveSubscriptions.GrooveRequestHeader();
subscriptSvc.GrooveRequestHeaderValue.GrooveIdentityURL =
accountData.identityURL;
subscriptSvc.GrooveRequestHeaderValue.GrooveRequestKey = ...
// (See example in Reading Groove Registry Keys.)
subscriptSvc.Url = hostPortAddress + "/GWS/Groove/2.0/Subscriptions/";
// Create the subscription.
string subscriptID = subscriptSvc.Create("urn:groove-net:Member2Event",
membersPostURI, strEventCallbackURI, timeToLive);
// Delete or renew subscription at some point.
See Also
Reference
GrooveSubscriptions Web Service