GrooveSubscriptions.CreateAggregated2 Operation

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=desired-design-name

Omit this parameter if you do not desire 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:

  • Identity scope: the subscription scope is all workspaces owned by the specified identity and all tools in these workspaces. To create a subscription with an identity scope, set this parameter to an Account2[n].Identity2[m].Spaces element returned by GrooveAccounts.Read2.

  • Workspace scope: the subscription scope is all tools within the specified workspace. To create a subscription with a workspace scope, set this parameter to a Space[n].Tools element returned by GrooveSpaces.Read.

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

AggregateData

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 -- such as updates to any Forms tool belonging to an identity, for instance.

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

GrooveEvents Web Service
GrooveSubscriptions Web Service
GrooveSubscriptions.CreateAggregated Operation
AggregateData Complex Type

Concepts

Handling Groove Web Services Events