GrooveContacts.Fetch Operation

The Fetch operation gets the contacts from a Groove Manager or from Live Groove and ensures that the contacts are accessible.

HTTP Post URL

The HTTP Post URL targets the service for the account. This URI is returned by the GrooveAccounts.Read2 operation in the Contacts parameter.

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

<CallbackURI />
<TimeToLive />
<URIList>
  <!-- Array of -->  <URI />
</URIList>
<Directory />

Element	Data type	Description
CallbackURI	xs:anyURI	URI used to automatically create a subscription. This URI identifies the client creating the subscription. The CallbackURI is a locator 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 locator used in the CallbackURI identifies 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/Fetch_test_2.5_client3982a83l”. Note that if multiple subscriptions specify the same CallbackURI, a call to GrooveEvents.Read will read events from all these subscriptions.
TimeToLive	xs:int	Number of hours that the subscription should remain active if not deleted or updated.
URIList	Array of xs:anyURI	Specify the unique identifiers of directory entries. The operation fetches the contacts stored in these directory entries. These identifiers are supplied by the Search operation and are not the same as the contact's Identity URL.
Directory	xs:anyURI	Specifies the directory. This directory identifier is provided by the ReadAvailableDirectories operation in the ContactDirectoryID element. If you do not specify a directory, the operation uses Live Groove.

Output Message Header

GrooveResponseHeader specifies the Response key.

Return Value

<FetchResult />

Element	Data type	Description
FetchResult	xs:string	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.

Remarks

To gain access to contacts, you use ReadAvailableDirectories, Fetch, and GrooveContacts.Search. Search returns a directory entry identifier and summary information about the contact, such as the contact's FullName. Search does not by itself make the contacts accessible. The Fetch operation gets additional information from the directory and then makes the contact accessible for other operations, such as sending instant messages and adding the contact to the personal contact list. Fetch makes the contacts accessible only for a limited time. If you want them to be permanently accessible, you must use the Create operation to add the contacts to the personal contact list.

The Fetch operation returns its results indirectly by creating an event subscription and then returning the results in an event. This operation uses the event mechanism to return its events because the operation communicates with a server and time required to get the information can be dependent on network traffic. The subscription created for Fetch will receive a single event, which contains the results of the operation. After you call Fetch, you can access the subscription with GrooveEvents.Read and with GrooveSubscriptions.Delete and GrooveSubscriptions.Update.

The Fetch operation's event has an event class of urn:groove-net:ContactDirectoryEvent and an event type of ContactFetchResultsEventData. The Fetch return data consists of a Status and a ContactList. The status can be "Succeeded" or "Failed". If the status is "Succeeded", all requested contacts are returned in the ContactList. If the status is "Failed", the ContactList is not returned. See ContactFetchResultsEventData Event for the format of the returned event.

You should call GrooveEvents.Read for the subscription created by Fetch until you get the one event. After this point, there is no need to continue polling the queue. The contacts returned by the Fetch event are accessible as long as the subscription remains active. The contacts are no longer accessible after the subscription is deleted or expires. Consequently, you should delete the subscription after you have completed accessing the contacts. The CallbackURI specifies the event queue that will be used for these events. Since these operations return only a single event, you should not use the same queue for Search or Fetch that you use for a subscription that requires continuous polling. Reusing one of these queues provides little advantage and adds programming complexity.

Note

Some contacts may not be associated with a Groove user and may only contain descriptive information, such as name and email address. You cannot use an email-only contact to send an invitation or instant message. If you attempt to use an email-only contact to send a workspace invitation with the GrooveMembers.Create operation, the operation will fail.

See Also

Reference

GrooveContacts Web Service
ContactFetchResultsEventData Event
GrooveContacts.Search Operation
GrooveContacts.ReadAvailableDirectories Operation

Concepts

Handling Groove Web Services Events