Forum OpenACS Q&A: Groups API in 4.x

when I ported the acs-kernel module, I was curious about the usage of groups, so I embarked on a fruitless search for documentation.  Other than the basic creation of membership and composition relations, there doesn't seem to be any documentation.

I did however get some insights on how groups, relational segments, and relational constraints operate by playing around with the test code for acs-kernel.  Look in openacs-4/packages/acs-kernel/sql/postgresq/test.  The rel-constraints.sql file is especially instructive, once you get the hang of how things are supposed to work.

The main problem with figuring out the groups usage, is that terms like object_id_one, object_id_two and relational side one and relational side two are not very descriptive or intuitive.

The first thing you need to understand is the type hierarchy.  In acs 4.x, the type hierarchy is as follows:
<p>
<pre>
acs_object_type
  party
    group
    person
      user
</pre>
In the acs 4.x groups system, the relation to a group is represented by the party object regardless of whether the relation is between a group and a person or a group and another group.  The implication of this is that a person or another group can be a member in a group.
<p>
As far as relationships, composition or membership relations determine whether memberships are transitive.  If you have a membership relation with group A and group A has a composition relation with group B, then you are also considered to be a member of B.  Group A is like a sub-grouping of group B in this case.
<p>
On the other hand, if you have a memberhip relation with group A, and group A has a membership relation with group B, you are not then considered a member of B.  composition relations are transitive while membership relations are not.

Right. That is documented in the "Parties in ACS4" doc, which could use some improvements, but your description was nice.

Regarding composition and membership, I understood how they work, but what I haven't figured out yet (haven't looked hard enough) is how do I tell this:

Say a user is a member of group A, which is the "parent group" of B. How do I tell that he should have access to what group B owns (since A is a parent of B)?

This seems to be accomplished with the group_approved_member_map view, but I don't know which arguments I should put in the WHERE clause to get the answer to my question.

You are right Dan. I got my nomenclature wrong.

So I should say:

user X --- membership --> group A

group B -- composition --> group B

So in my world, user X would be able to access things "owned" by group B. But how do I find out that the user can do it?

Dang, another typo. Sorry about that.

But yes, you knocked it out! That's what I was looking for. Thanks.

I don't see group_element_map in the "Parties in ACS 4" doc. It should be there.

Roberto, there is no real documentation as far as I know. One general tip though: When you want to do something like create users or add users to groups, look at the way the stock ACS Tcl code does it, as it frequently is NOT as simple as calling what you would think are the correct PL/SQL functions. This sort of "learn by example" is the only reliable way to pick up this stuff, I think.

For example, from PL/SQL, the correct way to create a new ACS user is with acs.add_user() - NOT with acs_user.new()! (acs_user.new APPEARS to work, but does not quite do all the right things.) But the only way to realize this it to read the Tcl code.

For adding a user to a group, on the other hand, this:

v_rel_id := membership_rel.new(
   object_id_one => v_group_id
  ,object_id_two => v_person_id
);

does the right thing, as you might expect. But it sounds like you already figured all that out, despite the cryptic nature of object "one" vs. "two".

OK, Dave:

Since I have been swimming in this lately (to get it to work for a project I am doing), I wanted to see if I understood the problem.

To my dismay, it seems I cannot accomplish this with the GUI!@#$% My best approach was to try to make a Relationship Type for the assigned-to relation. The problem I had was that the GUI would only allow a relationship type which is a sub-type of Composition or Membership. I wanted to make a type that inherits from the supertype of these relations (I think this is group-type=group). The out-of-the-box UI only allows it the other way.

So I ended up with a sub-type of Membership as the assigned-to relation. I was able to make an instance (segment?) of it by creating some members. I have the impression that since this segment is in no way specialized when compared to Membership, that there is no value to this (sub-)type.

I have not done it yet, but I would guess that two possible approaches are (both not possible from the UI):

• add a contraint to this new segment (maybe this is the type) to make this different from Membership.
• create a new relationship type for the assigned-to relation and create the specific attributes you need at that time.

I have just figured out how to do the simple example of a making a subsite/group containing a sub-group of admins. This is also pathetically designed in terms of the current screens. I now know how to modify the current screens, code, and default settings to make this no harder than it needs to be.

My intent is to post the results of that work to this board.

Regards..

Thanks for the replies, Roger & Don.

Roger:  Thanks for the insight. I guess there's no silver bullet solution for me but at least I know I'm not missing something obvious...