GroupsService

From OpenSimulator

Jump to: navigation, search

Contents

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

Formats

Group

This has the format 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AllowPublish>False</AllowPublish>
    <Charter>Group Charter</Charter>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <FounderUUI/>
    <GroupID>6ed52fa7-d910-4b6f-a2a6-8c121c0561dd</GroupID>
    <GroupName>group1</GroupName>
    <InsigniaID>00000000-0000-0000-0000-000000000000</InsigniaID>
    <MaturePublish>False</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <OwnerRoleID>97c9aecf-58c1-4a8d-a8b9-6eb0bedacd92</OwnerRoleID>
    <ServiceLocation/>
    <ShownInList>True</ShownInList>
    <MemberCount>2</MemberCount>
    <RoleCount>2</RoleCount>
  </RESULT>
</ServerResponse>

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <n-0 type="List">
      <GroupID>6ed52fa7-d910-4b6f-a2a6-8c121c0561dd</GroupID>
      <Name>abc1</Name>
      <NMembers>1</NMembers>
      <SearchOrder>0</SearchOrder>
    </n-0>
    <n-1 type="List">
      <GroupID>c5cd5ae2-6b06-4118-b0ed-41556c8c2fac</GroupID>
      <Name>fooabcbar</Name>
      <NMembers>1</NMembers>
      <SearchOrder>0</SearchOrder>
    </n-1>
  </RESULT>
</ServerResponse>

If no matching group is found, then you will receive 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No hits</REASON>
</ServerResponse>

Notes

If you want to find a specific group, use the GetGroup call instead.

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AllowPublish>False</AllowPublish>
    <Charter>Group Charter</Charter>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <FounderUUI/>
    <GroupID>6ed52fa7-d910-4b6f-a2a6-8c121c0561dd</GroupID>
    <GroupName>group1</GroupName>
    <InsigniaID>00000000-0000-0000-0000-000000000000</InsigniaID>
    <MaturePublish>False</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <OwnerRoleID>97c9aecf-58c1-4a8d-a8b9-6eb0bedacd92</OwnerRoleID>
    <ServiceLocation/>
    <ShownInList>True</ShownInList>
    <MemberCount>2</MemberCount>
    <RoleCount>2</RoleCount>
  </RESULT>
</ServerResponse>

If no group is found then the following is returned. 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>Group not found</REASON>
</ServerResponse>

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <m-0 type="List">
      <AcceptNotices>True</AcceptNotices>
      <AccessToken/>
      <AgentID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</AgentID>
      <AgentPowers>349644697632766</AgentPowers>
      <Contribution>0</Contribution>
      <IsOwner>False</IsOwner>
      <ListInProfile>True</ListInProfile>
      <OnlineStatus/>
      <Title>Owner of group1</Title>
    </m-0>
  </RESULT>
</ServerResponse>

If no matching group is found, then 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No members</REASON>
</ServerResponse>

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AcceptNotices>True</AcceptNotices>
    <AccessToken/>
    <Active>True</Active>
    <ActiveRole>28d962e4-81d4-4a3a-91a4-974b76c31a7d</ActiveRole>
    <AllowPublish>False</AllowPublish>
    <Charter>Group Charter</Charter>
    <Contribution>0</Contribution>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <GroupID>c5cd5ae2-6b06-4118-b0ed-41556c8c2fac</GroupID>
    <GroupName>group2</GroupName>
    <GroupPicture>00000000-0000-0000-0000-000000000000</GroupPicture>
    <GroupPowers>349644697632766</GroupPowers>
    <GroupTitle>Owner of group2</GroupTitle>
    <ListInProfile>True</ListInProfile>
    <MaturePublish>False</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <ShowInList>True</ShowInList>
  </RESULT>
</ServerResponse>

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

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No such membership</REASON>
</ServerResponse>

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

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>No such membership</REASON>
</ServerResponse>

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AllowPublish>True</AllowPublish>
    <Charter>Hello World,</Charter>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <FounderUUI/>
    <GroupID>620cf10c-e97d-4d40-8034-925a2dfd42d3</GroupID>
    <GroupName>great4</GroupName>
    <InsigniaID>00000000-0000-0000-0000-000000000000</InsigniaID>
    <MaturePublish>True</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <OwnerRoleID>9d468356-2fbe-4abc-bf4a-cca68b31f23b</OwnerRoleID>
    <ServiceLocation/>
    <ShownInList>True</ShownInList>
    <MemberCount>1</MemberCount>
    <RoleCount>2</RoleCount>
  </RESULT>
</ServerResponse>

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

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON>A group with that name already exists</REASON>
</ServerResponse>

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. 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AllowPublish>True</AllowPublish>
    <Charter>Moreover</Charter>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <FounderUUI/>
    <GroupID>620cf10c-e97d-4d40-8034-925a2dfd42d3</GroupID>
    <GroupName>great4</GroupName>
    <InsigniaID>00000000-0000-0000-0000-000000000000</InsigniaID>
    <MaturePublish>True</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <OwnerRoleID>9d468356-2fbe-4abc-bf4a-cca68b31f23b</OwnerRoleID>
    <ServiceLocation/>
    <ShownInList>True</ShownInList>
    <MemberCount>1</MemberCount>
    <RoleCount>2</RoleCount>
  </RESULT>
</ServerResponse>

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

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>NULL</RESULT>
  <REASON/>
</ServerResponse>

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT type="List">
    <AcceptNotices>True</AcceptNotices>
    <AccessToken/>
    <Active>True</Active>
    <ActiveRole>00000000-0000-0000-0000-000000000000</ActiveRole>
    <AllowPublish>True</AllowPublish>
    <Charter>Moreover</Charter>
    <Contribution>0</Contribution>
    <FounderID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</FounderID>
    <GroupID>620cf10c-e97d-4d40-8034-925a2dfd42d3</GroupID>
    <GroupName>great4</GroupName>
    <GroupPicture>00000000-0000-0000-0000-000000000000</GroupPicture>
    <GroupPowers>62672565501952</GroupPowers>
    <GroupTitle>Member of great4</GroupTitle>
    <ListInProfile>True</ListInProfile>
    <MaturePublish>True</MaturePublish>
    <MembershipFee>0</MembershipFee>
    <OpenEnrollment>True</OpenEnrollment>
    <ShowInList>True</ShowInList>
  </RESULT>
</ServerResponse>

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 

<?xml version="1.0"?>
<ServerResponse>
  <RESULT>true</RESULT>
</ServerResponse>

PUTROLE

REMOVEROLE

GETGROUPROLES

GETROLEMEMBERS

AGENTROLE

GETAGENTROLES

SETACTIVE

UPDATEMEMBERSHIP

INVITE

ADDNOTICE

GETNOTICES

Retrieved from "http://opensimulator.org/index.php?title=GroupsService&oldid=39561"
Personal tools
General
About This Wiki