GrooveSubscriptions.Create Operation
The Create operation creates a new subscription to events originated by the specified event source. Event sources can be tools, workspaces, and other objects.
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 />
<SourceURI />
<CallbackURI />
<TimeToLive />
| Element | Data type | Description |
|---|---|---|
EventClass |
|
EventClass of the event source. See the Remarks section for a list of Event Classes that can be specified in this parameter and the SourceURI and Groove Web Service that is associated with each event class. |
SourceURI |
|
URI that allows access to the event source. See the Remarks section for the SourceURI and its associated Groove Web Service for each event class. |
CallbackURI |
|
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. |
TimeToLive |
|
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
<CreateResult/>
| Element | Data type | Description |
|---|---|---|
CreateResult |
|
Subscription ID used to identify events or to update or delete the subscription. When you read events with GrooveEvents.Read, it returns events from all subscriptions with the same CallbackURI. You can test the SubscriptionID in each event to identify the source of the event. |
Remarks
The EventClass specified must be one that is associated with the source object. The following table lists the possible values for the EventClass and SourceURI parameters in the Create operation.
| Kind of event | Event source | Event classes | Source URI |
|---|---|---|---|
Space events |
All workspaces owned by an identity |
urn:groove-net:Space2Event urn:groove-net:Space2Event2 |
Account2[n].Identity2[m].Spaces element returned by GrooveAccounts.Read2. |
Contact events |
Account contact list |
urn:groove-net:Contact2Event |
Account2[n].Contacts element returned by GrooveAccounts.Read2. |
Message events |
Account message list |
urn:groove-net:Messages2Event urn:groove-net:Messages2Event2 |
Account2[n].Messages element returned by GrooveAccounts.Read2. |
Tool events |
Workspace tool list |
urn:groove-net:Tool2Event |
Space[n].Tools element returned by GrooveSpaces.Read. |
Member events |
Workspace members |
urn:groove-net:Member2Event |
Space[n].Members element returned by GrooveSpaces.Read. |
Calendar tool events |
Calendar tool |
urn:groove-net:Calendar2Event |
Tool[n].Data element returned by GrooveTools.Read for a Calendar tool. |
Files tool events |
Files tool |
urn:groove-net:Files2Event |
Tool[n].Data element returned by GrooveTools.Read for a Files tool. |
Forms tool events |
Groove Forms tool or InfoPath Forms tool |
urn:groove-net:Forms3Event |
Tool[n].Data element returned by GrooveTools.Read for a Groove Forms or an InfoPath Forms tool. |
If the SourceURI is not associated with the EventClass, this operation generates an exception. To create a subscription that covers more than one object of a particular event class, use CreateAggregated2.
You should specify dpp://localhost in the CallbackURI even if the operation is used in a remote request on a Groove Data Bridge.
See Also
Reference
GrooveEvents Web Service
GrooveSubscriptions Web Service
GrooveSubscriptions.CreateAggregated2 Operation