Accessing Workspace Members

The GrooveMembers.Read operation provides information about the members in a workspace. The HTTP Post URL for the GrooveMembers service is provided by the GrooveSpaces.Read operation in the Space Members element.

There are three ways to invite new members to a workspace:

• Invite a new member with a Groove instant message without any local user interaction by calling the GrooveMembers.Create operation.

• Invite a new member with a Groove instant message by having the local user interact with the Groove invitation user interface by calling the GrooveLocal.SendInvitation operation.

• Create an invitation file that your application can email to the user to be invited by calling the GrooveSpaces.CreateInvitationFile operation.

In all cases, the user receiving the invitation only becomes a member of the workspace after they have accepted the invitation and have fetched the workspace.

The GrooveMembers.Create operation sends an invitation to the Groove user specified by IdentityURL. Typically, you can get a user's IdentityURL by calling the GrooveContacts.Read operation or by reading the members of another workspace. You can specify the member's role in the invitation, but you cannot set the invitation message text.

The GrooveLocal.SendInvitation operation opens the Groove send invitation window and allows the user to interactively select the new member from the contact list. The user can also specify the role in the invitation message. You can specify the workspace in the call to SendInvitation, but cannot specify the recipient or role.

The GrooveSpaces.CreateInvitationFile operation creates a file that you can attach to an email or send to the recipient via any mechanism. The HTTP Post URL for the CreateInvitationFile operation must specify the workspace in its service-specific data. The Space.URI element returned by GrooveSpacesRead or ReadSpace contains this service-specific data.

When you specify the member's role in the invitation, you specify it with one of the following strings:

• $Telespace.Manager—invites the new member as a workspace manager.

• $Telespace.Member—invites the new member as a participant.

• $Telespace.Guest—invites the new member as a guest.

Telespace is the Groove internal term for workspace.

If you want to uninvite members, use the GrooveMembers.Delete operation. You cannot change roles and permissions using the GrooveMembers service, but you can call the GrooveLocal.OpenSpaceProperties operation to open a local window and allow the user to do so. In order to call this operation, you must use an HTTP Target URL that was created using the GrooveSpaces.Read operation LocalURI return parameter.

Reading Members

The following example shows you how to get the members for a given workspace and test the role for each. See Reading Workspaces for an example of how to get workspace information, which includes the HTTP Post URL for the GrooveMembers service.

// Set up a new GrooveMembers service
GrooveMembers.GrooveMembers membersSvc = new
  GrooveMembers.GrooveMembers();
membersSvc.GrooveRequestHeaderValue = new
  GrooveMembers.GrooveRequestHeader();

// Get the Groove request key and host and port information
// from the registry. See Reading Groove Registry Keys
string requestKey = ...;
string HTTPAddressAndPort = ...;

// Get the Groove IdentityURL from your account information
// See example in Accessing Accounts and Identities
string identityURL = ...;

membersSvc.GrooveRequestHeaderValue.GrooveIdentityURL = identityURL;
membersSvc.GrooveRequestHeaderValue.GrooveRequestKey = requestKey;

// The GrooveSpaces.Space returned by GrooveSpaces.Read
// provides the HTTP Post URL for the GrooveMembers service.
GrooveSpaces.Space space = ...;
membersSvc.Url = HTTPAddressAndPort + space.Members;

GrooveMembers.Member[] Members = membersSvc.Read();

// look for managers 
foreach (GrooveMembers.Member Member in Members)
{
  if (Member.Role != null)
  {
    if (Member.Role == "$Telespace.Manager")
    {
      // send some request to the online manager
    }
  }
}

Awareness and GrooveMembers Subscriptions

Groove does not track awareness information for members of a workspace unless you create a subscription to GrooveMembers events. If there is no subscription to member events, the GrooveMembers.Read operation return null values for the Awareness, AwarenessState, ActiveInTool, and ActiveInSpace elements. After you subscribe to member events, the GrooveMembers.Read operation returns meaningful values for these elements.

Note

There is a performance cost to listening to GrooveMembers events. Consequently, you should avoid creating an aggregated subscription that listens to GrooveMembers events on all workspaces. An aggregated GrooveMembers subscription can generate many events and may cause a significant load on the system. This is especially true on a Groove Data Bridge system that has many workspaces.

See Also

Reference

GrooveLocal.SendInvitation Operation
GrooveMembers Web Service
GrooveSpaces.CreateInvitationFile Operation

Concepts

Accessing the Groove Web Services Hierarchy
Handling Groove Web Services Events