GrooveSubscriptions.CreateAggregated2 Operation
Applies to: SharePoint Workspace 2010 | Visual Studio 2008
In this article
HTTP Post URL
Input Message Header
Input Message Parameters
Output Message Header
Return Value
The CreateAggregated2 operation activates a new aggregated subscription for events. The subscription covers all events of a particular event class from all sources that are present within a specified scope. The scope can be all workspaces for an identity or all tools within a workspace.
HTTP Post URL
The HTTP Post URL targets the service. This URI is a top-level HTTP Post URL that you supply directly; it is not returned as a value by another operation.
Input Message Header
GrooveRequestHeader specifies information common to all Groove Web Services, including the Groove Identity URL and the Groove Request key.
Input Message Parameters
<EventClass />
<Query />
<SourceURI />
<CallbackURI />
<TimeToLive />
Element |
Data type |
Description |
|---|---|---|
EventClass |
xs:string |
The event class of the events to be monitored. Each service that provides events has one or more associated event classes. See the Remarks section for a list of the event classes that can be specified in CreateAggregated2. |
Query |
xs:string |
Filters events of the specified event class to those meeting the criteria of the query string. Currently queries are defined for Forms tool events only. Specifically, the query allows you to filter events originating from a specified Forms tools design by setting the string to DesignName=targeted-design-name Omit this parameter to skip filtering. The parameter is ignored for all non-Forms tool event classes. |
SourceURI |
xs:anyURI |
A URI which identifies the scope of objects to be monitored for events. The scope can be either all objects belonging to an identity or all objects in a workspace:
|
CallbackURI |
xs:anyURI |
URI that identifies the client creating the subscription. The CallbackURI is an identifier beginning with dpp://localhost. Note that Groove only uses the CallbackURI as an identifier and does not try to resolve it to an actual internet address. Typically the last field of the identifier used in the Callback URI specifies the SOAP client, but it should also include a unique ID so that two instances of the SOAP client have separate event queues, such as "dpp://localhost/MyWebServicesApp_UniqueInstanceID". Note that if multiple subscriptions specify the same CallbackURI, a call to GrooveEvents.Read will read events from all these subscriptions. You should specify dpp://localhost in the CallbackURI even if the operation is used in a remote request. |
TimeToLive |
xs:int |
The number of hours that the subscription should remain active if not deleted or updated. At the end of this period the subscription is deleted. The maximum value for TimeToLive is 2160 hours (90 days). If a long subscription is specified, the application design should guarantee that events are removed from the event queue periodically to prevent excessive queue growth. |
Output Message Header
GrooveResponseHeader specifies the Response key.
Return Value
<CreateAggregated2Result />
Element |
Data type |
Description |
|---|---|---|
CreateAggregated2Result |
Contains information about the subscription created and any sources found in the scope. |
Remarks
You can aggregate the following kinds of events for all the workspaces owned by an identity:
Tools events
Members events
Calendar events
Files events
Forms events
You can aggregate the following kinds of events for all the tools in a single workspace:
Calendar events
Files events
Forms events
Optionally, a query string can be specified to further filter the events. Events from this subscription are placed into a queue identified by the CallbackURI.
This method allows you to efficiently monitor all events of a particular type that occur within a fairly broad scope. For example you can monition updates to any Forms tool belonging to an identity.
Once a subscription is created, it queues all subscribed events until it is terminated. The subscription can be terminated by explicitly calling Delete or when it expires. Expiration is set using the TimeToLive parameter.
The following table lists the values for the EventClass and SourceURI parameters for aggregated subscriptions.
Scope of subscription |
Kind of event |
Event class |
Source URI |
|---|---|---|---|
All workspaces owned by an identity |
Tool events |
urn:groove-net:Tool2Event |
Account2[n].Identity2[m].Spaces element returned by GrooveAccounts.Read2. |
Member events |
urn:groove-net:Member2Event |
||
Calendar events |
urn:groove-net:Calendar2Event |
||
Files events |
urn:groove-net:Files2Event |
||
Forms events |
urn:groove-net:Forms3Event |
||
All tools in a workspace |
Calendar events |
urn:groove-net:Calendar2Event |
Space[n].Tools element returned by GrooveSpaces.Read. |
Files events |
urn:groove-net:Files2Event |
||
Forms events |
urn:groove-net:Forms3Event |
You should call CreateAggregated2 only with the combinations of EventClass and SourceURI listed in the preceding table. Any other combination is illegal.
Note
If no objects are found, no URIs are returned, but the subscription is still created.
Note
The only difference between CreateAggregated2 and CreateAggregated is in the conditions under which new event sources are included in the subscription. If you create an aggregated subscription with CreateAggregated2, Groove monitors the specified scope for new event sources while the subscription is active. If Groove finds a new event source matching the subscription event class and query, it automatically includes the new source in the subscription. Typically new event sources occur when either a new tool is added to an existing workspace or when the user accepts an invitation to a new workspace. In contrast, if you create an aggregated subscription with CreateAggregated, Groove does not monitor the specified scope for new event sources. Groove checks for new event sources only when the subscription is renewed with the Update operation.
See Also
Reference
GrooveSubscriptions Web Service
GrooveSubscriptions.CreateAggregated Operation