groupService

Provides the ability to manage user group accounts and group membership. Use this service to find, create, delete, and update user groups. You can also manage group membership and properties.

A user group account is a way to collect user accounts in order to more easily manage permissions for user accounts in the group. For example, you might have a group account for all of the people in the human resources department. You can assign the group account permission to view sensitive HR-related content. This saves you the trouble of assigning that permission individually for each user account in the group.

In addition to having user accounts as members, a user group can also have administrators. A user group's administrator(s) has access to administrative features (such as through the admin console) in order to add or remove group members, edit groups settings, and so on.

For more on user groups, be sure to read the administrator documentation.

Note this isn't the service for working with social groups. For that, see SocialGroupService .

Method	Description
addAdministratorToGroup	Makes the specified user an administrator of the specified group.
addMemberToGroup	Adds the specified user to the specified group.
createGroup	Creates a new user group.
deleteGroup	Deletes the group with the specified ID.
deleteProperty	Deletes an extended property from the specified group.
getAdministratorCount	Returns the count of administrators for the specified group.
getGroup	Returns a user group by its ID.
getGroupAdmins	Returns an array of IDs for all users that administer the specified group.
getGroupByName	Returns a user group by its name.
getGroupCount	Returns a count of all groups in the system.
getGroupMembers	Returns the user IDs for all members of the specified group.
getGroupNames	Returns the names for all the groups in the system.
getGroupNamesBounded	Returns names for groups beginning at startIndex and until the number results equals numResults.
getGroups	Returns the group IDs for all groups in the system.
getProperties	Returns the specified group's extended properties.
getUserGroupNames	Returns the names of groups that the specified user belongs to.
getUserGroups	Returns the IDs of groups that a user belongs to.
isReadOnly	Returns true if this GroupService is read-only.
removeAdministratorFromGroup	Removes the specified user as an administrator from the specified group.
removeMemberFromGroup	Removes the specified user from the specified group.
setProperty	Sets a new extended property on the specified group.
updateGroup	Updates the specified group.

addAdministratorToGroup

Makes the specified user an administrator of the specified group.

POST http://domain:port/application_context/rpc/rest/groupService/groupAdmins

Arguments

Name	Type	Description
userID	xs:long	ID of the user to add as a member to a group.
groupID	xs:long	ID of the group to make the user an administrator of.

Arguments Template

<addAdministratorToGroup> 
    <userID>xs:long</userID>
    <groupID>xs:long</groupID>
</addAdministratorToGroup>

Errors

Error	When Returned
UserNotFound
GroupNotFound
com.jivesoftware.base.GroupAlreadyExistsException
Unauthorized	If the caller is not a system or group administrator.

addMemberToGroup

Adds the specified user to the specified group.

POST http://domain:port/application_context/rpc/rest/groupService/groupMembers

Arguments

Name	Type	Description
userID	xs:long	ID of the user to add to a group.
groupID	xs:long	ID of the group to add a user to.

Arguments Template

<addMemberToGroup> 
    <userID>xs:long</userID>
    <groupID>xs:long</groupID>
</addMemberToGroup>

Errors

Error	When Returned
UserNotFound
GroupNotFound	If the specified group doesn't exist.
com.jivesoftware.base.GroupAlreadyExistsException
Unauthorized	If the caller is not a system or group administrator.

createGroup

Creates a new user group.

POST http://domain:port/application_context/rpc/rest/groupService/groups

Arguments

Name	Type	Description
name	xs:string	The name of the group to create.
description	xs:string	A short description of the group to create.
isFederated	xs:boolean	true if is the system of record for the group is outside jive, false if the group exists only in jive

Arguments Template

<createGroup> 
    <name>xs:string</name>
    <description>xs:string</description>
    <isFederated>xs:boolean</isFederated>
</createGroup>

Response

Type	Description
Group	The newly created group.

Response Template

<createGroupResponse> 
    <return>
        <!-- Contents of Group -->
    <return>
</createGroupResponse>

Errors

Error	When Returned
com.jivesoftware.base.GroupAlreadyExistsException	If a group with the specified name already exists.

deleteGroup

Deletes the group with the specified ID.

DELETE http://domain:port/application_context/rpc/rest/groupService/groups/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	ID of the group to delete.

Arguments Template

<deleteGroup> 
    <groupID>xs:long</groupID>
</deleteGroup>

Errors

Error	When Returned
GroupNotFound	If the group with the specified ID does not exist.
Unauthorized	If the caller is not a system administrator.

deleteProperty

Deletes an extended property from the specified group. Group properties are a kind of metadata about the group. See the administrator documentation for more information.

DELETE http://domain:port/application_context/rpc/rest/groupService/properties/{groupID}/{name}

Arguments

Name	Type	Description
name	xs:string	The name of the extended property to delete.
groupID	xs:long	ID of the group to delete an extended property from.

Arguments Template

<deleteProperty> 
    <name>xs:string</name>
    <groupID>xs:long</groupID>
</deleteProperty>

Errors

Error	When Returned
GroupNotFound	If the specified group doesn't exist.
com.jivesoftware.base.GroupAlreadyExistsException
Unauthorized	If the caller is not a system or group administrator.

getAdministratorCount

Returns the count of administrators for the specified group.

GET http://domain:port/application_context/rpc/rest/groupService/administratorCount/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	ID of the group to acquire the administrator count for.

Arguments Template

<getAdministratorCount> 
    <groupID>xs:long</groupID>
</getAdministratorCount>

Response

Type	Description
xs:int	The number of administrators in the group.

Response Template

<getAdministratorCountResponse> 
    <return>xs:int</return>
</getAdministratorCountResponse>

Errors

Error	When Returned
GroupNotFound	If the group with the specified ID does not exist.

getGroup

Returns a user group by its ID.

GET http://domain:port/application_context/rpc/rest/groupService/groupsByID/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	ID of the group to get.

Arguments Template

<getGroup> 
    <groupID>xs:long</groupID>
</getGroup>

Response

Type	Description
Group	The specified group.

Response Template

<getGroupResponse> 
    <return>
        <!-- Contents of Group -->
    <return>
</getGroupResponse>

Errors

Error	When Returned
GroupNotFound	If the group with the specified ID does not exist.

getGroupAdmins

Returns an array of IDs for all users that administer the specified group.

GET http://domain:port/application_context/rpc/rest/groupService/groupAdmins/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	The group ID for which to acquire administrator IDs.

Arguments Template

<getGroupAdmins> 
    <groupID>xs:long</groupID>
</getGroupAdmins>

Response

Type	Description
List of User	An array of IDs for all the users that administer this group.

Response Template

<getGroupAdminsResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getGroupAdminsResponse>

Errors

Error	When Returned
GroupNotFound	If the group with the specified ID does not exist.

getGroupByName

Returns a user group by its name. The name should be encoded using java.net.URLEncoder.encode(name, "UTF-8") or equivalent.

GET http://domain:port/application_context/rpc/rest/groupService/groups/{name}

Arguments

Name	Type	Description
name	xs:string	The UTF-8 encoded name of the group.

Arguments Template

<getGroupByName> 
    <name>xs:string</name>
</getGroupByName>

Response

Type	Description
Group	The group with the matching name.

Response Template

<getGroupByNameResponse> 
    <return>
        <!-- Contents of Group -->
    <return>
</getGroupByNameResponse>

Errors

Error	When Returned
GroupNotFound	If the group with the specified name does not exist.

getGroupCount

Returns a count of all groups in the system.

GET http://domain:port/application_context/rpc/rest/groupService/groupCount

Response

Type	Description
xs:int	A count of all groups in the system.

Response Template

<getGroupCountResponse> 
    <return>xs:int</return>
</getGroupCountResponse>

getGroupMembers

Returns the user IDs for all members of the specified group.

GET http://domain:port/application_context/rpc/rest/groupService/groupMembers/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	ID of the group to get members for.

Arguments Template

<getGroupMembers> 
    <groupID>xs:long</groupID>
</getGroupMembers>

Response

Type	Description
List of User	An array of the user IDs.

Response Template

<getGroupMembersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of User -->
    <return>
</getGroupMembersResponse>

Errors

Error	When Returned
GroupNotFound	If the group with the specified ID does not exist

getGroupNames

Returns the names for all the groups in the system.

GET http://domain:port/application_context/rpc/rest/groupService/groupNames

Response

Type	Description
List of	An array of names for all the groups in the system.

Response Template

<getGroupNamesResponse> 
    <!-- List of ... -->
    <return>xs:string</return>
</getGroupNamesResponse>

getGroupNamesBounded

Returns names for groups beginning at startIndex and until the number results equals numResults.

GET http://domain:port/application_context/rpc/rest/groupService/groupNamesBounded/{startIndex}/{numResults}

Arguments

Name	Type	Description
startIndex	xs:int	The index of the first group name to return.
numResults	xs:int	number of results to return.

Arguments Template

<getGroupNamesBounded> 
    <startIndex>xs:int</startIndex>
    <numResults>xs:int</numResults>
</getGroupNamesBounded>

Response

Type	Description
List of	An array of the group names, beginning at`startIndex` and ending at `numResults`.

Response Template

<getGroupNamesBoundedResponse> 
    <!-- List of ... -->
    <return>xs:string</return>
</getGroupNamesBoundedResponse>

getGroups

Returns the group IDs for all groups in the system.

GET http://domain:port/application_context/rpc/rest/groupService/groups

Response

Type	Description
List of Group	An array of group IDs for all the groups in the system.

Response Template

<getGroupsResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of Group -->
    <return>
</getGroupsResponse>

getProperties

Returns the specified group's extended properties. Group properties are a kind of metadata about the group. See the administrator documentation for more information.

GET http://domain:port/application_context/rpc/rest/groupService/properties/{groupID}

Arguments

Name	Type	Description
groupID	xs:long	ID of the group to acquire extended properties for.

Arguments Template

<getProperties> 
    <groupID>xs:long</groupID>
</getProperties>

Response

Type	Description
List of Property	An array of the group's extended properties.

Response Template

<getPropertiesResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of Property -->
    <return>
</getPropertiesResponse>

Errors

Error	When Returned
GroupNotFound	If the group with the specified ID does not exist.

getUserGroupNames

Returns the names of groups that the specified user belongs to.

GET http://domain:port/application_context/rpc/rest/groupService/userGroupNames/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user.

Arguments Template

<getUserGroupNames> 
    <userID>xs:long</userID>
</getUserGroupNames>

Response

Type	Description
List of	An array of group names that the user belongs to.

Response Template

<getUserGroupNamesResponse> 
    <!-- List of ... -->
    <return>xs:string</return>
</getUserGroupNamesResponse>

Errors

Error	When Returned
UserNotFound	If a user with the specified ID does not exist.

getUserGroups

Returns the IDs of groups that a user belongs to.

GET http://domain:port/application_context/rpc/rest/groupService/userGroups/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to acquire group IDs for.

Arguments Template

<getUserGroups> 
    <userID>xs:long</userID>
</getUserGroups>

Response

Type	Description
List of Group	An array IDs for groups that a user belongs too.

Response Template

<getUserGroupsResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of Group -->
    <return>
</getUserGroupsResponse>

Errors

Error	When Returned
UserNotFound	If a user with the specified ID does not exist.

isReadOnly

Returns true if this GroupService is read-only. When read-only, groups can not be created, deleted, or modified.

GET http://domain:port/application_context/rpc/rest/groupService/isReadOnly

Response

Type	Description
xs:boolean	true If the service is read-only.

Response Template

<isReadOnlyResponse> 
    <return>xs:boolean</return>
</isReadOnlyResponse>

removeAdministratorFromGroup

Removes the specified user as an administrator from the specified group.

DELETE http://domain:port/application_context/rpc/rest/groupService/groupAdmins/{groupID}/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to remove as an admin.
groupID	xs:long	ID of the group from which to remove the admin.

Arguments Template

<removeAdministratorFromGroup> 
    <userID>xs:long</userID>
    <groupID>xs:long</groupID>
</removeAdministratorFromGroup>

Errors

Error	When Returned
UserNotFound
GroupNotFound
com.jivesoftware.base.GroupAlreadyExistsException
Unauthorized	If the caller is not a system or group administrator.

removeMemberFromGroup

Removes the specified user from the specified group.

DELETE http://domain:port/application_context/rpc/rest/groupService/groupMembers/{groupID}/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user to remove from the group.
groupID	xs:long	ID of the group to remove the user from.

Arguments Template

<removeMemberFromGroup> 
    <userID>xs:long</userID>
    <groupID>xs:long</groupID>
</removeMemberFromGroup>

Errors

Error	When Returned
UserNotFound
GroupNotFound
com.jivesoftware.base.GroupAlreadyExistsException
Unauthorized	If the caller is not a system or group administrator.

setProperty

Sets a new extended property on the specified group. Group properties are a kind of metadata about the group. See the administrator documentation for more information.

POST http://domain:port/application_context/rpc/rest/groupService/properties

Arguments

Name	Type	Description
name	xs:string	The extended property's name.
value	xs:string	The extended property's value.
groupID	xs:long	ID of the group to set the extended property on.

Arguments Template

<setProperty> 
    <name>xs:string</name>
    <value>xs:string</value>
    <groupID>xs:long</groupID>
</setProperty>

Errors

Error	When Returned
GroupNotFound	If the specified group does not exist.
com.jivesoftware.base.GroupAlreadyExistsException	If this change represents an attempt to change the group's name to the name of another group.
Unauthorized	If the caller is not a system or group administrator.

updateGroup

Updates the specified group.

PUT http://domain:port/application_context/rpc/rest/groupService/groups

Errors

Error	When Returned
GroupNotFound	If the specified group does not exist.
com.jivesoftware.base.GroupAlreadyExistsException	If the group parameter represents an attempt to change the group's name to the name of another group.
Unauthorized	If the caller is not a system or group administrator.