Forum OpenACS Development: relational segments: how do you use them

As an example, if you have a group of a type unicycle_club, which is composed of a set of mini-groups of type uni_group, and possibly direct members as well. Each of these uni_groups has members with a membership_rel subtype of unicyclist_rel, parent_rel or coach_rel. (I had created these rel types as a subtype of membership_rel, but the mistake I made when adding new rels was to add using acs_rel__new, I think I need to use membership_rel__new, but set the rel_type to 'parent_rel', etc.)

Would a relational segment be useful, and how, in gathering togeather all the unicyclists, parents and coaches that are members of a unicycle_club group by virtue of the composition rel between the uni_group and the unicycle_club? Or how and why might you use a relational segment in this situation?

Once the uni_group is created and a membership_rel added of subtype parent_rel, I added this group via a composition_rel of subtype club_cyclist_rel to a group of type unicycle_club.

I then created a relational segment on the unicycle club group for rel_types of parent_rel. As I expected, the parent of the uni_group is now part of the relational segment for the unicycle club.

=# select * from party_approved_member_map where member_id = 823;
 party_id | member_id | tag
----------+-----------+------
     1185 |       823 | 1174
     1177 |       823 | 1174
     1169 |       823 | 1174
     1161 |       823 | 1174
       -1 |       823 |  824
      291 |       823 |  824
       -2 |       823 |  824
      823 |       823 |    0

The composition relationship has created the top two rows, 1177 due to the membership_rel now applying to the unicycle_club group, and 1185 due to the parent_rel now applying to the relational segment on the club group. So, adding one composition rel has resulted in the unicyclist being a member of the club, and their parent being a member of the parents rel segment for the club.

I think the answer is: create a relational segment on the "registered users" group for rel_type = membership_rel. Adding a member to this relational segment only involves creating an acs_rel through membership_rel__new between the user and the -2 group (registered users). Every subsite gets a similar relational segment:

v=# select * from rel_segments;
 segment_id |         segment_name         | group_id |     rel_type
------------+------------------------------+----------+------------------
        291 | Main Site Members            |       -2 | membership_rel
        649 | GTSubsite Members            |      646 | membership_rel
        798 | test Members                 |      795 | membership_rel
       1169 | Tommys Parents               |     1161 | parent_rel
       1185 | My Unicycle Club Parents     |     1177 | parent_rel
       1190 | My Unicycle Club Unicyclists |     1177 | club_cyclist_rel

Tom,
    This discussion is very timely. I've been studying essentially this same problem for a long time now. I really would like to create subsite sub-groups and then assign subsite-wide permissions to users depending on their membership in these groups, creating a multiple-role system consisting of administrators, service managers, users, and auditors.

    Were you successful in creating sub-groups and then assigning permissions based on sub-group membership? If so, would you mind sharing the code, tables and pl functions that you developed to implement your "role" system?

Thanks,

Randy

Anything this sublime needs more commentary, don't you think? This join, used in acs_permission__permission_p, combines The Holy Trinity of OpenACS Core: Objects, Parties, Privileges. The result, when the join succeeds, is One. Maybe everyone should meditate on this join as their first assignment to understanding OpenACS. :)

how long since you slept, tom ?

Shoot, I was hoping noone would notice! Actually I spent most of last week flat on my back and in severe pain from a back strain/sprain. The fog cleared at the moment I saw Don's little jewel of code.

"registered_users" is a group, not a relseg. The relseg I alluded to was "Main Site Members" which is related to this group. The call to membership_rel__new() (which is specific to the "membership_rel" relation type) creates a "relation" between the user and the group, as you say. Only indirectly does it make the user a *member* of the group and associated relsegs:

membership_rel__new() also inserts a row into the "membership_rels" table and there's an insert trigger on that table ("membership_rels_in_tr"). Among other things, this trigger calls party_approved_member__add() - if new.member_state is "approved", that is. party_approved_member__add() basically inserts into party_approved_member_map, both for the group in question and for any relational segment(s) that the relation type may be mapped to.

That is how the newly created user becomes a member of the "Registered Users" group and "Main Site Members" segment.

Evidently, although I havent looked for it, there must be a relational segment already defined in an earlier step in the default installation that goes under the name "Main Site Members", is associated with group -2 ("Registered Users"), and holds relations of the basic type "membership_rel".

It is the fact that there existed a relseg (which was associated with the group and relation type in question) in the first place, that made the user a (approved) member of the relseg, too, and not only of the group.

Does this make sense?

As a side note, there seems to be a rather ample supply of Tcl procs that handle these type/group/segment/relation issues. By using them we may avoid writing separate sets of Pl[Pg]SQL code for Oracle and PostgreSQL in our applications... (Now that we have a good support for APM Tcl callbacks, I mean.)

/Ola

It could be created when "Registered Users" is created, but I chose to delay it until acs-install because this is where the main site is created and mounted, and where "registered users" is transformed into an application group referencing the main subsite's package id.  Put all my kludges in one basket, so to speak.

I implemented this in 4.6.  Before the main subsite had its own membership group so registered users didn't belong to the main subsite, which is wrong.  aD had actually intended to copy registered users into the main subsite membership group: the 4.1->4.2 upgrade script did this but the registration code wasn't modified to track this change.  I decided it made more sense to just make registered users *be* the main site membership group.  Much simpler than copying users around willy-nilly.

The relational segment is in some sense redundant but doesn't cost anything as it's built on membership_rel as mentioned above - all the rows already exist for the relseg.  Having this relseg around should make it easier to write general API stuff built around relational segments (such as subsite admins or other "role"-implementing relsegs)

Without it in some cases code would need to check the subsite membership group, other cases various relsegs rather than just be oriented around interrogating relsegs.

This is infrastructure that's largely unused at the moment though Lars has been doing some admin UI work for 4.6.4 ...

And yes, please use the Tcl API in acs-subsite/tcl to manipulate groups, relsegments, etc.  If you need to do something that's not covered by the existing API and if that "something" is general enough, let's add it to the API so others can benefit.

And, Mr. Bob Phillips, I caught your code - your claims of being non-contagious while sputtering and coughing into our pitcher of beer notwithstanding!

However, what I'm really interested in is implementing a multi-role system (based on acs-subsite) where I can grant certain rights based on a member's role. I think that the tcl api is what I should use rather than reinventing this wheel. So, given this direction, I would like some help determining exactly what the implementation looks like... described by toolkit tcl calls. Unfortunately, I've searched through the source code (both the 4.6 cvs branch and dotlrn 1) and there are no working examples that I could find. Maybe I can start with what I assume is required to create a single role and grant permissions on the subsite to members in that role.

What I want to do...

Among other roles, I want to create a role called "Community Admin" and associate with it a Main Site registered user "u1" that will have permission to:

  # Create a rel_type
  set m_rel_type [rel_types::new
      -supertype "membership_rel"
      -role_one ?role_one?
      -role_two ?role_two?
      "adm_rel"                    # rel_type
      "Community Admin"            # pretty_name
      "Community Admins"           # pretty_plural
      ?object_type_one?
      ?min_n_rels_one?
      ?max_n_rels_one?
      ?object_type_two?
      ?min_n_rels_two?
      ?max_n_rels_two?

  # Create a rel_seg
  set m_rel_seg  [rel_segments_new
      -context_id ?context_id?
      -creation_user $user_id
      -creation_ip $peer_addr
      $subsite_app_grp_id          # group_id
      "adm_rel"                    # rel_type
      ?segment_name?

  # Grant permissions
  # How to do this?

Lars, thanks for the tcl translation of all the hooie I went through above. Wow, the tcl api makes things simple.

Randy, note that there are two relational segments created above, although Lars only included the Admin segment.

On creating the rel_type:

A relation type relates two objects. The type specifies which object_type each object must be in order to allow the relation to exist.

In the case of making a rel_type for use by a relational segment, the further requirement is that the object_type_one must be a group_type, and object_type_two must be a derivative of a party. If the party type for object_type_two is a person/user or derivative, then the supertype will be membership_rel, otherwise you need a composition_rel.

In your case, it looks like you want a membership_rel.

The role_one and role_two must be chosen from what is in acs_rel_roles, but the data is essentially meaningless, you can leave them blank if you want.

Max_* you can leave blank as well.

I'll post my code for the examples I have been using, maybe today or tomorrow.

Thanks again,

Randy

Can you file a bug in the bug-tracker, pls.

Finally, I wrote this up into a general Howto with example code and posted it as another thread: https://openacs.org/forums/message-view?message_id=116231

Have a look and let me know if you think it's useful.

Randy