Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 11 Dec 2010 23:36:32 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 31 Jul 2011 23:11:45 -0000 1.33 @@ -1,60 +1,60 @@ - -Groups Requirements

Groups Requirements

By Rafael H. Schloming, Mark Thomas

+ +Groups Requirements

Groups Requirements

By Rafael H. Schloming, Mark Thomas

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

Almost all database-backed websites have users, and need to model the +

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.

Vision Statement

A powerful web service that can meet the needs of large enterprises must + for different user communities.

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.

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 + system will support such complex relations faithfully.

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.

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 + 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

  • 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

In sum, the goal of the Parties and Groups system is to + to:

  • 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)

  • 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.

User Scenarios

Pat Developer has a client project and wants to model the company, its + world.

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.

System Overview

We start with Groups, which contain members; the - member can be either a person or another group (i.e. a + users.

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).

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 + 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:

  • 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.

Consider an example to make this less abstract: Pretend that the Sierra + 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:

  • 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.

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 @@ -67,158 +67,158 @@ 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.

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.

Requirements: Data Model

The data model for the parties and groups system must provide support for - the following types of entities:

10.0 Parties + 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.

Requirements: Data Model

The data model for the parties and groups system must provide support for + the following types of entities:

10.0 Parties -

A party is an entity used to represent either a - group or a person.

The data model should enforce these constraints:

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.30 The email address of a party must be unique within - an OpenACS system.

20.0 Groups +

A party is an entity used to represent either a + group or a person.

The data model should enforce these constraints:

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.30 The email address of a party must be unique within + an OpenACS system.

20.0 Groups -

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of - groups via OpenACS Objects.

30.0 Persons +

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of + groups via OpenACS Objects.

30.0 Persons -

A person represents an actual human being, past or - present.

30.10. A person must have - an associated name.

40.0 Users +

A person represents an actual human being, past or + present.

30.10. A person must have + an associated name.

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.

The data model should enforce these constraints:

40.10 A user must have a non-empty email address.

40.20 Two different users may not have the same email +

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:

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.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 + 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.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:

50.0 Membership + the following types of relationships between entities:

50.0 Membership

- A party P is considered a member of a - group 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.

50.10 A party may be a member of multiple groups.

50.20 A party may be a member of the same group multiple + A party P is considered a member of a + group 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.

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.30 A party as a member of itself is not supported.

50.40 The data model must support membership - constraints.

50.50The data model should support the subclassing of + Executive.

50.30 A party as a member of itself is not supported.

50.40 The data model must support membership + constraints.

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

  • 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.

60.10A group may be a component of multiple groups.

60.20A group as a component of itself is not - supported.

60.30The data model must support component - constraints.

60.40The data model should support the subclassing of - composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group + 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

  • 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.20A group as a component of itself is not + supported.

60.30The data model must support component + constraints.

60.40The data model should support the subclassing of + composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

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.

70.20 Create a person + in the data model.

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.

70.30 Create a user + in the data model.

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.

80.10 Refine a person to a user + the data model.

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.

80.30 Demote a user to a person + model.

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.

90.10 Update a party + laid out in the data model.

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.

95.10 Get the attributes of a party + party. This API is subject to the constraints laid out in the data model.

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.

100.10 Delete a party + API is subject to the constraints laid out in the data model.

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.

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 + 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.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 + 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.

115.0 Add a group as a component of a second group + data model.

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.

120.0 Remove a party as a member of a group + in the data model.

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.

125.0 Remove a group as a component of a second - group + data model.

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.

130.0 Membership check + out in the data model.

130.0 Membership check

The parties and groups system provides an API for answering the question: - "Is party P a member of group - G?"

135.0 Composition check + "Is party P a member of group + G?"

135.0 Composition check

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 + "Is group GC a component of group + GP?"

140.0 Get members query

The parties and groups system provides an API for answering the question: - "Which parties are members of group G?"

145.0 Get components query + "Which parties are members of group G?"

145.0 Get components query

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 + "Which groups are components of group G?"

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?"

155.0 Component-of-groups query + "Of which groups is party P a member?"

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?"

160.0 Allowed membership check + "Of which groups is group G a component?"

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?"

165.0 Allowed composition check + "Is party P allowed to become a member of group + G?"

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?"

170.0 Efficiency + "Is group GC allowed to become a component + of group GP?"

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.

180.0 Ease of Use + membership.

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.

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:

  • 200.0 Create a party

  • 210.0 View the attributes of a party

  • 220.0 Update the attributes of a party

  • 240.0 Delete a party

  • 250.0 Add a party to 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

Revision History

Document Revision #Action Taken, NotesWhen?By Whom?
0.1Creation08/16/2000Rafael Schloming
0.2Initial revision08/19/2000Mark Thomas
0.3Edited and reviewed, conforms to requirements template08/23/2000Kai Wu
0.4Further revised, added UI requirements08/24/2000Mark Thomas
0.5Final edits, pending freeze08/24/2000Kai Wu
0.6More revisions, added composition requirements08/30/2000Mark Thomas
0.7More revisions, added composition requirements09/08/2000Mark Thomas
View comments on this page at openacs.org
+ where clause, whatever mechanism is used to check membership in SQL + should be fairly small and simple.

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:

  • 200.0 Create a party

  • 210.0 View the attributes of a party

  • 220.0 Update the attributes of a party

  • 240.0 Delete a party

  • 250.0 Add a party to 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

Revision History

Document Revision #Action Taken, NotesWhen?By Whom?
0.1Creation08/16/2000Rafael Schloming
0.2Initial revision08/19/2000Mark Thomas
0.3Edited and reviewed, conforms to requirements template08/23/2000Kai Wu
0.4Further revised, added UI requirements08/24/2000Mark Thomas
0.5Final edits, pending freeze08/24/2000Kai Wu
0.6More revisions, added composition requirements08/30/2000Mark Thomas
0.7More revisions, added composition requirements09/08/2000Mark Thomas
View comments on this page at openacs.org