Index: openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml 11 Dec 2003 21:39:50 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml 18 Jun 2004 12:26:44 -0000 1.6 @@ -5,705 +5,705 @@ %myvars; ]> -Groups Requirements + Groups Requirements - -By Rafael H. Schloming, Mark Thomas - + + By Rafael H. Schloming, Mark Thomas + - -Introduction + + Introduction -Almost all database-backed websites have users, and need to model the -grouping of users. The OpenACS 4 Parties and Groups system is intended to provide -the flexibility needed to model complex real-world organizational structures, -particularly to support powerful subsite services; that is, where one OpenACS -installation can support what appears to the user as distinct web services -for different user communities. + Almost all database-backed websites have users, and need to model the + grouping of users. The OpenACS 4 Parties and Groups system is intended to provide + the flexibility needed to model complex real-world organizational structures, + particularly to support powerful subsite services; that is, where one OpenACS + installation can support what appears to the user as distinct web services + for different user communities. - + - -Vision Statement + + Vision Statement -A powerful web service that can meet the needs of large enterprises must -be able to model the the real world's very rich organizational structures -and many ways of decomposing the same organization. For example, a -corporation can be broken into structures (the corporation, its divisions, -and their departments) or regions (the Boston office, the LA office); a -person who is employed by (is a member of) a specific department is also a -member of the division and the corporation, and works at (is a member of, but -in a different sense) a particular office. OpenACS's Parties and Groups -system will support such complex relations faithfully. + A powerful web service that can meet the needs of large enterprises must + be able to model the the real world's very rich organizational structures + and many ways of decomposing the same organization. For example, a + corporation can be broken into structures (the corporation, its divisions, + and their departments) or regions (the Boston office, the LA office); a + person who is employed by (is a member of) a specific department is also a + member of the division and the corporation, and works at (is a member of, but + in a different sense) a particular office. OpenACS's Parties and Groups + system will support such complex relations faithfully. -Historical Motivations + Historical Motivations -The primary limitation of the OpenACS 3.x user group system is that it -restricts the application developer to representing a "flat group" -that contains only users: The user_groups table may contain the -group_id of a parent group, but parent-child relationship -support is limited because it only allows one kind of relationship between -groups to be represented. Moreover, the Oracle database's limited support -for tree-like structures makes the queries over these relationships -expensive. + The primary limitation of the OpenACS 3.x user group system is that it + restricts the application developer to representing a "flat group" + that contains only users: The user_groups table may contain the + group_id of a parent group, but parent-child relationship + support is limited because it only allows one kind of relationship between + groups to be represented. Moreover, the Oracle database's limited support + for tree-like structures makes the queries over these relationships + expensive. -In addition, the Module Scoping design in OpenACS 3.0 introduced a -party abstraction - a thing that is a person or a group of people - -though not in the form of an explicit table. Rather, the triple of -scope, user_id, and group_id columns -was used to identify the party. One disadvantage of this design convention is -that it increases a data model's complexity by requiring the programmer -to: + In addition, the Module Scoping design in OpenACS 3.0 introduced a + party abstraction - a thing that is a person or a group of people - + though not in the form of an explicit table. Rather, the triple of + scope, user_id, and group_id columns + was used to identify the party. One disadvantage of this design convention is + that it increases a data model's complexity by requiring the programmer + to: - -add these three columns to each "scoped" table + + add these three columns to each "scoped" table -define a multi-column check constraint to protect against data corruption -(e.g., a row with a scope value of "group" but a null -group_id) + define a multi-column check constraint to protect against data corruption + (e.g., a row with a scope value of "group" but a null + group_id) -perform extra checks in Tcl and PL/SQL -functions and procedures to check both the user_id and -group_id values - + perform extra checks in Tcl and PL/SQL + functions and procedures to check both the user_id and + group_id values + -In sum, the goal of the Parties and Groups system is to -provide OpenACS programmers and site administrators with simple tools that fully -describe the complex relationships that exist among groups in the real -world. + In sum, the goal of the Parties and Groups system is to + provide OpenACS programmers and site administrators with simple tools that fully + describe the complex relationships that exist among groups in the real + world. - + - -User Scenarios + + User Scenarios -Pat Developer has a client project and wants to model the company, its -offices, its divisions, and its departments as groups and the employees as -users. + Pat Developer has a client project and wants to model the company, its + offices, its divisions, and its departments as groups and the employees as + users. - + - -System Overview + + System Overview -We start with Groups, which contain members; the -member can be either a person or another group (i.e. a -member is a party). + We start with Groups, which contain members; the + member can be either a person or another group (i.e. a + member is a party). -In addition to membership, the party and groups system defines a -composition relationship that may exist between groups: A -group can be a component of another group. The child group -is called a component group; the parent group is called a -composite group. + In addition to membership, the party and groups system defines a + composition relationship that may exist between groups: A + group can be a component of another group. The child group + is called a component group; the parent group is called a + composite group. -A group Gc can be a member and/or a component -of another group Gp; the difference is in the way -the members of Gc are related to -Gp: + A group Gc can be a member and/or a component + of another group Gp; the difference is in the way + the members of Gc are related to + Gp: - -If a party P is a member (or a component) of -Gc and if Gc is a -component of Gp, then P is also -a member (or a component) of Gp + + If a party P is a member (or a component) of + Gc and if Gc is a + component of Gp, then P is also + a member (or a component) of Gp -If a party P is a member (or a component) of -Gc and if Gc is a -member of Gp, then no -relationship between P and -Gp exists as a result of the relationship between -Gp and Gp. - + If a party P is a member (or a component) of + Gc and if Gc is a + member of Gp, then no + relationship between P and + Gp exists as a result of the relationship between + Gp and Gp. + -Consider an example to make this less abstract: Pretend that the Sierra -Club is a member of Greenpeace. The Sierra Club has chapters; each -chapter is a component of the Sierra Club. If Eddie Environmentalist -is a member of the Massachusetts Chapter of the Sierra Club, Eddie is -automatically a member of the Sierra Club, but being a Sierra Club member -does not make Eddie a member of Greenpeace. + Consider an example to make this less abstract: Pretend that the Sierra + Club is a member of Greenpeace. The Sierra Club has chapters; each + chapter is a component of the Sierra Club. If Eddie Environmentalist + is a member of the Massachusetts Chapter of the Sierra Club, Eddie is + automatically a member of the Sierra Club, but being a Sierra Club member + does not make Eddie a member of Greenpeace. -In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be -modeled as groups, and Eddie would be a user. There would be a composition -relationship between each Sierra Club chapter and the Sierra Club. Membership -relationships would exist between Eddie and the Massachusetts Chapter, -between Eddie and the Sierra Club (due to Eddie's membership in the -Massachusetts chapter), and between the Sierra Club and Greenpeace. + In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be + modeled as groups, and Eddie would be a user. There would be a composition + relationship between each Sierra Club chapter and the Sierra Club. Membership + relationships would exist between Eddie and the Massachusetts Chapter, + between Eddie and the Sierra Club (due to Eddie's membership in the + Massachusetts chapter), and between the Sierra Club and Greenpeace. -Membership requirements can vary from group to group. The parties and -groups system must provide a base type that specifies the bare minimum -necessary to join a group. + Membership requirements can vary from group to group. The parties and + groups system must provide a base type that specifies the bare minimum + necessary to join a group. -The parties and groups system must support constraints between a composite -group GP and any of its component groups, -GC. For example, the system should be able to -enforce a rule like: Do not allow a party P to become a -member of GC unless P is already -a member of GP. + The parties and groups system must support constraints between a composite + group GP and any of its component groups, + GC. For example, the system should be able to + enforce a rule like: Do not allow a party P to become a + member of GC unless P is already + a member of GP. - + - -Related Links + + Related Links - - - + + + - + - -Requirements: Data Model + + Requirements: Data Model -The data model for the parties and groups system must provide support for -the following types of entities: + The data model for the parties and groups system must provide support for + the following types of entities: - - -10.0 Parties + + + 10.0 Parties - - - -A party is an entity used to represent either a -group or a person. + + + + A party is an entity used to represent either a + group or a person. -The data model should enforce these constraints: + The data model should enforce these constraints: -10.10 A party has an email address, which can be -empty. + 10.10 A party has an email address, which can be + empty. -10.20 A party may have multiple email addresses -associated with it. + 10.20 A party may have multiple email addresses + associated with it. -10.30 The email address of a party must be unique within -an OpenACS system. - - + 10.30 The email address of a party must be unique within + an OpenACS system. + + - -20.0 Groups + + 20.0 Groups - - - -A group is a collection of zero or more parties. + + + + A group is a collection of zero or more parties. -20.10 The data model should support the subclassing of -groups via OpenACS Objects. - - + 20.10 The data model should support the subclassing of + groups via OpenACS Objects. + + - -30.0 Persons + + 30.0 Persons - - - -A person represents an actual human being, past or -present. + + + + A person represents an actual human being, past or + present. -30.10. A person must have -an associated name. - - + 30.10. A person must have + an associated name. + + - -40.0 Users + + 40.0 Users - - - -A user is a person who has registered with an OpenACS site. A -user may have additional attributes, such as a screen name. + + + + A user is a person who has registered with an OpenACS site. A + user may have additional attributes, such as a screen name. -The data model should enforce these constraints: + The data model should enforce these constraints: -40.10 A user must have a non-empty email address. + 40.10 A user must have a non-empty email address. -40.20 Two different users may not have the same email -address on a single OpenACS installation; i.e., an email address identifies a -single user on the system. + 40.20 Two different users may not have the same email + address on a single OpenACS installation; i.e., an email address identifies a + single user on the system. -40.30 A user may have multiple email addresses; for -example, two or more email addresses may identify a single user. + 40.30 A user may have multiple email addresses; for + example, two or more email addresses may identify a single user. -40.40 A user must have password field which can be -empty. - - - + 40.40 A user must have password field which can be + empty. + + + -The data model for the parties and groups system must provide support for -the following types of relationships between entities: + The data model for the parties and groups system must provide support for + the following types of relationships between entities: - - -50.0 Membership + + + 50.0 Membership - - - -A party P is considered a member of a -group G + + + + A party P is considered a member of a + group G - -when a direct membership relationship exists between P -and G + + when a direct membership relationship exists between P + and G -or when there exists a direct membership relationship between -P and some group GC and -GC has a composition relationship (c.f., 60.0) with G. - - + or when there exists a direct membership relationship between + P and some group GC and + GC has a composition relationship (c.f., 60.0) with G. + + -50.10 A party may be a member of multiple groups. + 50.10 A party may be a member of multiple groups. -50.20 A party may be a member of the same group multiple -times only when all the memberships have different types; for example, Jane -may be a member of The Company by being both an Employee and an -Executive. + 50.20 A party may be a member of the same group multiple + times only when all the memberships have different types; for example, Jane + may be a member of The Company by being both an Employee and an + Executive. -50.30 A party as a member of itself is not supported. + 50.30 A party as a member of itself is not supported. -50.40 The data model must support membership -constraints. + 50.40 The data model must support membership + constraints. -50.50The data model should support the subclassing of -membership via OpenACS Relationships. - - - + 50.50The data model should support the subclassing of + membership via OpenACS Relationships. + + + - - - - -60.0 Composition - - - -A group GC is considered a -component of a second group -GP + + + + + 60.0 Composition + + + + A group GC is considered a + component of a second group + GP - -when a direct composition relationship exists between -GC and GP + + when a direct composition relationship exists between + GC and GP -or when there exists a direct composition relationship between -GC and some group Gi -and Gi has a composition relationship with -GP. - + or when there exists a direct composition relationship between + GC and some group Gi + and Gi has a composition relationship with + GP. + - + -60.10A group may be a component of multiple groups. + 60.10A group may be a component of multiple groups. -60.20A group as a component of itself is not -supported. + 60.20A group as a component of itself is not + supported. -60.30The data model must support component -constraints. + 60.30The data model must support component + constraints. -60.40The data model should support the subclassing of -composition via OpenACS Relationships. - - - + 60.40The data model should support the subclassing of + composition via OpenACS Relationships. + + + - + - -Requirements: API + + Requirements: API -The API should let programmers accomplish the following tasks: + The API should let programmers accomplish the following tasks: - - -70.10 Create a group + + + 70.10 Create a group - - - -The parties and groups system provides a well defined API call that -creates a new group by running the appropriate transactions on the parties -and groups system data model. This API is subject to the constraints laid out -in the data model. - - + + + + The parties and groups system provides a well defined API call that + creates a new group by running the appropriate transactions on the parties + and groups system data model. This API is subject to the constraints laid out + in the data model. + + - -70.20 Create a person + + 70.20 Create a person - - - -The parties and groups system provides a well defined API call that -creates a new person by running the appropriate transactions on the parties -and groups system data model. This API is subject to the constraints laid out -in the data model. - - + + + + The parties and groups system provides a well defined API call that + creates a new person by running the appropriate transactions on the parties + and groups system data model. This API is subject to the constraints laid out + in the data model. + + - -70.30 Create a user + + 70.30 Create a user - - - -The parties and groups system provides a well defined API call that -creates a new user by running the appropriate transactions on the parties and -groups system data model. This API is subject to the constraints laid out in -the data model. - - + + + + The parties and groups system provides a well defined API call that + creates a new user by running the appropriate transactions on the parties and + groups system data model. This API is subject to the constraints laid out in + the data model. + + - -80.10 Refine a person to a user + + 80.10 Refine a person to a user - - - -The parties and groups system provides a well defined API call that -creates a new user by running the appropriate transactions on an existing -person entity. This API is subject to the constraints laid out in the data -model. - - + + + + The parties and groups system provides a well defined API call that + creates a new user by running the appropriate transactions on an existing + person entity. This API is subject to the constraints laid out in the data + model. + + - -80.30 Demote a user to a person + + 80.30 Demote a user to a person - - - -The parties and groups system provides a well defined API call that -demotes an existing user entity to a person entity by running the appropriate -transactions on the existing user. This API is subject to the constraints -laid out in the data model. - - + + + + The parties and groups system provides a well defined API call that + demotes an existing user entity to a person entity by running the appropriate + transactions on the existing user. This API is subject to the constraints + laid out in the data model. + + - -90.10 Update a party + + 90.10 Update a party - - - -The programmer should be able to modify, add, and delete attributes on any -party. This API is subject to the constraints laid out in the data model. - - + + + + The programmer should be able to modify, add, and delete attributes on any + party. This API is subject to the constraints laid out in the data model. + + - -95.10 Get the attributes of a party + + 95.10 Get the attributes of a party - - - -The programmer should be able to view the attributes on any party. This -API is subject to the constraints laid out in the data model. - - + + + + The programmer should be able to view the attributes on any party. This + API is subject to the constraints laid out in the data model. + + - -100.10 Delete a party + + 100.10 Delete a party - - - -The system provides an API for deleting a party. This API is subject to -the constraints laid out in the data model. + + + + The system provides an API for deleting a party. This API is subject to + the constraints laid out in the data model. -100.30 The system may provide a single API call to remove -the party from all groups and then delete the party. + 100.30 The system may provide a single API call to remove + the party from all groups and then delete the party. -100.40 In the case of a group, the system may provide a -single API call to remove all parties from a group and then delete the -group. - - + 100.40 In the case of a group, the system may provide a + single API call to remove all parties from a group and then delete the + group. + + - -110.0 Add a party as a member of a group + + 110.0 Add a party as a member of a group - - - -The parties and groups system provides an API for adding a party as a -member of a group. This API is subject to the constraints laid out in the -data model. - - + + + + The parties and groups system provides an API for adding a party as a + member of a group. This API is subject to the constraints laid out in the + data model. + + - -115.0 Add a group as a component of a second group + + 115.0 Add a group as a component of a second group - - - -The parties and groups system provides an API for adding a group as a -component of a second group. This API is subject to the constraints laid out -in the data model. - - + + + + The parties and groups system provides an API for adding a group as a + component of a second group. This API is subject to the constraints laid out + in the data model. + + - -120.0 Remove a party as a member of a group + + 120.0 Remove a party as a member of a group - - - -The parties and groups system provides an API for deleting a party's -membership in a group. This API is subject to the constraints laid out in the -data model. - - + + + + The parties and groups system provides an API for deleting a party's + membership in a group. This API is subject to the constraints laid out in the + data model. + + - -125.0 Remove a group as a component of a second -group + + 125.0 Remove a group as a component of a second + group - - - -The parties and groups system provides an API for deleting a group's -composition in a second group. This API is subject to the constraints laid -out in the data model. - - + + + + The parties and groups system provides an API for deleting a group's + composition in a second group. This API is subject to the constraints laid + out in the data model. + + - -130.0 Membership check + + 130.0 Membership check - - - -The parties and groups system provides an API for answering the question: -"Is party P a member of group -G?" - - + + + + The parties and groups system provides an API for answering the question: + "Is party P a member of group + G?" + + - -135.0 Composition check + + 135.0 Composition check - - - -The parties and groups system provides an API for answering the question: -"Is group GC a component of group -GP?" - - + + + + The parties and groups system provides an API for answering the question: + "Is group GC a component of group + GP?" + + - -140.0 Get members query + + 140.0 Get members query - - - -The parties and groups system provides an API for answering the question: -"Which parties are members of group G?" - - + + + + The parties and groups system provides an API for answering the question: + "Which parties are members of group G?" + + - -145.0 Get components query + + 145.0 Get components query - - - -The parties and groups system provides an API for answering the question: -"Which groups are components of group G?" - - + + + + The parties and groups system provides an API for answering the question: + "Which groups are components of group G?" + + - -150.0 Member-of-groups query + + 150.0 Member-of-groups query - - - -The parties and groups system provides an API for answering the question: -"Of which groups is party P a member?" - - + + + + The parties and groups system provides an API for answering the question: + "Of which groups is party P a member?" + + - -155.0 Component-of-groups query + + 155.0 Component-of-groups query - - - -The parties and groups system provides an API for answering the question: -"Of which groups is group G a component?" - - + + + + The parties and groups system provides an API for answering the question: + "Of which groups is group G a component?" + + - -160.0 Allowed membership check + + 160.0 Allowed membership check - - - -The parties and groups system provides an API for answering the question: -"Is party P allowed to become a member of group -G?" - - + + + + The parties and groups system provides an API for answering the question: + "Is party P allowed to become a member of group + G?" + + - -165.0 Allowed composition check + + 165.0 Allowed composition check - - - -The parties and groups system provides an API for answering the question: -"Is group GC allowed to become a component -of group GP?" - - + + + + The parties and groups system provides an API for answering the question: + "Is group GC allowed to become a component + of group GP?" + + - -170.0 Efficiency + + 170.0 Efficiency - - - -Since many pages at a site may check membership in a group before serving -a page (e.g., as part of a general permissions check), the data model must -support the efficient storage and retrieval of party attributes and -membership. - - + + + + Since many pages at a site may check membership in a group before serving + a page (e.g., as part of a general permissions check), the data model must + support the efficient storage and retrieval of party attributes and + membership. + + - -180.0 Ease of Use + + 180.0 Ease of Use - - - -Since many SQL queries will check membership in a group as part of the -where clause, whatever mechanism is used to check membership in SQL -should be fairly small and simple. - - - + + + + Since many SQL queries will check membership in a group as part of the + where clause, whatever mechanism is used to check membership in SQL + should be fairly small and simple. + + + - + - -Requirements: User Interface + + Requirements: User Interface -The user interface is a set of HTML pages that are used to drive the -underlying API. The user interface may provide the following functions: + The user interface is a set of HTML pages that are used to drive the + underlying API. The user interface may provide the following functions: - -200.0 Create a party + + 200.0 Create a party -210.0 View the attributes of a party + 210.0 View the attributes of a party -220.0 Update the attributes of a party + 220.0 Update the attributes of a party -240.0 Delete a party + 240.0 Delete a party -250.0 Add a party to a group + 250.0 Add a party to a group -260.0 Remove a party from a group + 260.0 Remove a party from a group -270.0 Perform the membership and composition checks -outlined in 130.x to 165.x - + 270.0 Perform the membership and composition checks + outlined in 130.x to 165.x + - + - -Revision History + + Revision History - - - - - -Document Revision # -Action Taken, Notes -When? -By Whom? - + + + + + + Document Revision # + Action Taken, Notes + When? + By Whom? + - -0.1 -Creation -08/16/2000 -Rafael Schloming - + + 0.1 + Creation + 08/16/2000 + Rafael Schloming + - -0.2 -Initial revision -08/19/2000 -Mark Thomas - + + 0.2 + Initial revision + 08/19/2000 + Mark Thomas + - -0.3 -Edited and reviewed, conforms to requirements template -08/23/2000 -Kai Wu - + + 0.3 + Edited and reviewed, conforms to requirements template + 08/23/2000 + Kai Wu + - -0.4 -Further revised, added UI requirements -08/24/2000 -Mark Thomas - + + 0.4 + Further revised, added UI requirements + 08/24/2000 + Mark Thomas + - -0.5 -Final edits, pending freeze -08/24/2000 -Kai Wu - + + 0.5 + Final edits, pending freeze + 08/24/2000 + Kai Wu + - -0.6 -More revisions, added composition requirements -08/30/2000 -Mark Thomas - + + 0.6 + More revisions, added composition requirements + 08/30/2000 + Mark Thomas + - -0.7 -More revisions, added composition requirements -09/08/2000 -Mark Thomas - - + + 0.7 + More revisions, added composition requirements + 09/08/2000 + Mark Thomas + + - +