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.

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.

API

Calls

WIP - Only a small 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. If an empty string is given then all groups are returned.

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>

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>

GETGROUP

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

PUTGROUP

ADDAGENTTOGROUP

REMOVEAGENTFROMGROUP

PUTROLE

REMOVEROLE

GETGROUPROLES

GETROLEMEMBERS

AGENTROLE

GETAGENTROLES

SETACTIVE

UPDATEMEMBERSHIP

INVITE

ADDNOTICE

GETNOTICES