GroupsService

=Introduction=

OpenSimulator both has a core groups service which is not yet enabled by default and an external XmlRpc/Flotsam groups service. This page describes the service level interface to the core groups.

For information on actually configuring the V2 groups service, see the link above.

The API calls described here potentially allow an external caller to manipulate groups. At the moment, changes will not be seem by users that are online until they log back in. And those changes will not be explicitly notified to them.

For example PHP code that makes these calls, see https://github.com/justincc/opensimulator-tools/tree/master/integration/php/src/programs/groups

=API=

Group
This has the format

where


 * AllowPublish probably controls whether a group is listed in external search. This is not used by core OpenSimulator.  Must be one of "true", "True" or "False", "false".
 * Charter the charter (description) for the group.
 * FounderID the UUID or the user account that is the founder of the group.
 * FounderUUI used by Hypergrid.
 * GroupID the UUID of the group.
 * GroupName the name of the group.
 * InsigniaID the asset UUID of the texture used as the picture for the group. If set to UUID.Zero then no picture will be displayed (which might look somewhat ugly for some viewers).
 * MaturePublish probably controls whether a group is listed in external search only for users with the mature preference set in their viewer. This is not used by core openSimulator.  Must be one of "true", "True" or "False", "false".
 * MembershipFee the membership fee required to join the group.
 * OpenEnrollment controls whether a user can join the group at any time (after having paid any required enrollment fee) or whether they have to be explicitly invited. Must be one of "true", "True" or "False", "false".
 * OwnerRoleID the UUID of the role assigned to owners. Owners have permission to perform any operation on the group.
 * ServiceLocation used by the Hypergrid.
 * ShownInList controls whether the group can be returned by the FindGroups call and displayed to the user when they do an in-world search for groups matching a given string.
 * MembershipCount the number of members of this group.
 * RoleCount the number of distinct roles in this group. Every group will have at least 2, the default Everyone role and the Owner role.

Calls
WIP - Not all possible service calls are currently described.

FINDGROUPS
This returns summary information for groups that match a given pattern.

The POST field is a urlencoded string like so

RequestingAgentID=00000000-0000-0000-0000-000000000000&Query=abc&METHOD=FINDGROUPS

where


 * RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
 * Query is the pattern to match. The query string follows SQL LIKE formatting where % is always appended and prepended.  So "group" will match any string containing the string "group", such as "mygroupname" and "group1".  An empty string will return all groups.

If successful, you will see a server response such as

If no matching group is found, then you will receive

GETGROUP
This returns information about a given group. One can retrieve information by group UUID or name.

Hence, there are two forms of query, one which specifies the group name and one which specifies the group UUID. The POST field of the group name version looks as follows

RequestingAgentID=00000000-0000-0000-0000-000000000000&METHOD=GETGROUP&Name=group1

where


 * RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
 * Name is the name of the group.

The POST field of the group UUID version is

RequestingAgentID=00000000-0000-0000-0000-000000000000&METHOD=GETGROUP&GroupID=6ed52fa7-d910-4b6f-a2a6-8c121c0561dd


 * RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
 * GroupID is the UUID of the group.

If the query finds a group, then a result like the following is returned

If no group is found then the following is returned.

GETGROUPMEMBERS
This returns settings for users that belong to a given group. The POST field is a urlencoded string like so

RequestingAgentID=00000000-0000-0000-0000-000000000000&GroupID=6ed52fa7-d910-4b6f-a2a6-8c121c0561dd&METHOD=GETGROUPMEMBERS

where


 * RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
 * GroupID is a group UUID.

If successful, you will see a server response such as

If no matching group is found, then

GETMEMBERSHIP
This returns membership information for a given user for their active group, a specific group or all the groups to which they belong.

The POST field is a urlencoded string like so

 RequestingAgentID=00000000-0000-0000-0000-000000000000&AgentID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&GroupID=c5cd5ae2-6b06-4118-b0ed-41556c8c2fac&METHOD=GETMEMBERSHIP

where


 * RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls
 * AgentID is the user UUID for which we want to retreive membership information.
 * ALL (not shown) is an optional parameter which returns information about all the user's memberships. It will be active if it is present at all, whether blank or filled with any value.  It will override any GroupID given.
 * GroupID is the group UUID for which we want membership information. If this is 00000000-0000-0000-0000-000000000000 or not present then information about the user's membership of their active group is returned.

'''NOTE: Due to a bug in OpenSimulator 0.8.0.1 and before, all groups returned by ALL or with a specific group ID will have Active = true EVEN IF THIS GROUP IS NOT ACTIVE. To find the actual active group, use the form of this query with GroupID = 00000000-0000-0000-0000-000000000000. This bug will be addressed in the next release of OpenSimulator.'''

If the user is found and a was specified and found, you will see a server response such as

If the group was not found then you will see the response

If the user was not found you will also see the response

PUTGROUP
This call handles both adding new groups and updating existing ones.

ADD
The POST for adding a new group is a urlencoded string like so

 RequestingAgentID=00000000-0000-0000-0000-000000000000&GroupName=great4&AllowPublish=true&MaturePublish=true&OpenEnrollment=true&MembershipFee=0&Charter=Hello+World%2C&FounderID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&InsigniaID=00000000-0000-0000-0000-000000000000&ShownInList=true&ServiceLocation=+&METHOD=PUTGROUP&OP=ADD

where


 * RequestingAgentID is always 00000000-0000-0000-0000-000000000000 for external calls.
 * GroupName is the name of the new group.
 * AllowPublish probably controls whether a group is listed in external search. This is not used by core OpenSimulator.  Must be one of "true", "True" or "False", "false".
 * MaturePublish probably controls whether a group is listed in external search only for users with the mature preference set in their viewer. This is not used by core openSimulator.  Must be one of "true", "True" or "False", "false".
 * OpenEnrollment controls whether a user can join the group at any time (after having paid any required enrollment fee) or whether they have to be explicitly invited. Must be one of "true", "True" or "False", "false".
 * MembershipFee controls the membership fee required to join the group. If you aren't using currency or don't have a currency module running then you will want to set this to zero.
 * Charter the charter (description) for the group.
 * FounderID the UUID or the user account that is the founder of the group.
 * InsigniaID the asset UUID of the texture used as the picture for the group. If set to UUID.Zero then no picture will be displayed (which might look somewhat ugly for some viewers).
 * ShownInList controls whether the group shows us in the FindGroups call. This is used to control which groups are displayed to the viewer, but it currently has the unfortunate side effect of hiding the group from external service calls as well.  You probably want to set this to true unless you have a good reason not to.  Must be one of "true", "True" or "False", "false".
 * OP=ADD used to signal that the operation is intended to add a new group. Must be present.

If the group is added successfully, data such as the following will be returned

If the add failed because a group with the same name already exists, then the following will be returned.

UPDATE
Unfortunately, currently with OpenSimulator (at least up until 0.8), all possible update fields have to be supplied in the update call. Unless these have been stored externally, one would need to do a GetGroup or similar call and then resupply those values, changing only the ones that need to change.

So the POST for updating an existing group is a urlencoded string like so

 RequestingAgentID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&GroupID=620cf10c-e97d-4d40-8034-925a2dfd42d3&AllowPublish=true&MaturePublish=true&OpenEnrollment=true&MembershipFee=0&Charter=Moreover&InsigniaID=00000000-0000-0000-0000-000000000000&ShownInList=true&ServiceLocation=+&METHOD=PUTGROUP&OP=UPDATE

where


 * RequestingAgentID must belong to a user account that has sufficient powers to update group details. One way to do this is to supply the FounderID of the group from the GetGroup call.  In the future, OpenSimulator needs to be changed so that this field is not required from external callers.
 * GroupID
 * AllowPublish probably controls whether a group is listed in external search. This is not used by core OpenSimulator.  Must be one of "true", "True" or "False", "false".
 * MaturePublish probably controls whether a group is listed in external search only for users with the mature preference set in their viewer. This is not used by core openSimulator.  Must be one of "true", "True" or "False", "false".
 * OpenEnrollment controls whether a user can join the group at any time (after having paid any required enrollment fee) or whether they have to be explicitly invited. Must be one of "true", "True" or "False", "false".
 * MembershipFee controls the membership fee required to join the group. If you aren't using currency or don't have a currency module running then you will want to set this to zero.
 * Charter the charter (description) for the group.
 * InsigniaID the asset UUID of the texture used as the picture for the group. If set to UUID.Zero then no picture will be displayed (which might look somewhat ugly for some viewers).
 * ShownInList controls whether the group shows us in the FindGroups call. This is used to control which groups are displayed to the viewer, but it currently has the unfortunate side effect of hiding the group from external service calls as well.  You probably want to set this to true unless you have a good reason not to.  Must be one of "true", "True" or "False", "false".
 * OP=UPDATE used to signal that the operation is intended to add a new group. Must be present.

Parameters that are not shown here (e.g. group name) cannot be changed after group creation.

If the update is successfully, a response like the following will be received.

If the group ID did not match any existing group, the following response will be given

ADDAGENTTOGROUP
This adds a user to an existing group. The POST field for this query is like so

 RequestingAgentID=00000000-0000-0000-0000-000000000000&GroupID=620cf10c-e97d-4d40-8034-925a2dfd42d3&AgentID=04c259b7-94bc-4822-b099-745191ffc247&RoleID=00000000-0000-0000-0000-000000000000&METHOD=ADDAGENTTOGROUP

where


 * RequestingAgentID can always be UUID.Zero in this case.
 * GroupID is the group UUID to which to add the user.
 * AgentID is the user account UUID to add to the group.
 * RoleID is the role to assign to this user on add. If this is UUID.Zero then they will only be added with the default Everyone role (other roles can be added or removed later).

If successful, this will return a response such as

REMOVEAGENTFROMGROUP
This removes a user from group. The POST field urlencoded query is like so

 postFields:RequestingAgentID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&GroupID=620cf10c-e97d-4d40-8034-925a2dfd42d3&AgentID=04c259b7-94bc-4822-b099-745191ffc247&METHOD=REMOVEAGENTFROMGROUP

where


 * RequestingAgentID must be a user with sufficient permissions to remove the user from the group. One such user will be the founder (as retreived via GetGroup).
 * GroupID is the group UUID from which to remove the user.
 * AgentID is the user to remove.

On success, you will receive the result