GroupsService

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(→‎API)
(Add group format info)
Line 10: Line 10:
  
 
=API=
 
=API=
 +
 +
==Formats==
 +
 +
===Group===
 +
 +
This has the format
 +
 +
<source lang='xml'>
 +
<?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>
 +
</source>
 +
 +
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==
 
==Calls==
  
−
'''WIP - Only a small number of possible service calls are currently described'''
+
'''WIP - Only a limited number of possible service calls are currently described'''
  
 
===FINDGROUPS===
 
===FINDGROUPS===

Revision as of 10:57, 31 July 2014

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 - Only a limited number of 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.

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.

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>

ADDAGENTTOGROUP

REMOVEAGENTFROMGROUP

PUTROLE

REMOVEROLE

GETGROUPROLES

GETROLEMEMBERS

AGENTROLE

GETAGENTROLES

SETACTIVE

UPDATEMEMBERSHIP

INVITE

ADDNOTICE

GETNOTICES

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