OpenACS 4 Groups Requirements
by Rafael H. Schloming, Mark ThomasIntroductionAlmost 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 StatementA 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 4's Parties and Groups
system will support such complex relations faithfully.Historical MotivationsThe 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:add these three columns to each "scoped" tabledefine 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 valuesIn 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 ScenariosPat 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 OverviewWe 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.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 GpIf 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.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.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 LinksRequirements: Data ModelThe data model for the parties and groups system must provide support for
the following types of entities:10.0 PartiesA 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 GroupsA 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 PersonsA person represents an actual human being, past or
present.30.10. A person must have
an associated name.40.0 UsersA 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
empty.The data model for the parties and groups system must provide support for
the following types of relationships between entities:50.0 Membership
A party P is considered a member of a
group Gwhen a direct membership relationship exists between P
and Gor 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
membership via OpenACS Relationships.60.0 CompositionA group GC is considered a
component of a second group
GPwhen a direct composition relationship exists between
GC and GPor 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: APIThe API should let programmers accomplish the following tasks:70.10 Create a groupThe 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 personThe 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 userThe 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 userThe 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 personThe 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 partyThe 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 partyThe 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 partyThe 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
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 groupThe 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 groupThe 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 groupThe 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
groupThe 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 checkThe parties and groups system provides an API for answering the question:
"Is party P a member of group
G?"135.0 Composition checkThe parties and groups system provides an API for answering the question:
"Is group GC a component of group
GP?"140.0 Get members queryThe parties and groups system provides an API for answering the question:
"Which parties are members of group G?"145.0 Get components queryThe parties and groups system provides an API for answering the question:
"Which groups are components of group G?"150.0 Member-of-groups queryThe parties and groups system provides an API for answering the question:
"Of which groups is party P a member?"155.0 Component-of-groups queryThe parties and groups system provides an API for answering the question:
"Of which groups is group G a component?"160.0 Allowed membership checkThe 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 checkThe parties and groups system provides an API for answering the question:
"Is group GC allowed to become a component
of group GP?"170.0 EfficiencySince 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 UseSince 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 InterfaceThe 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 party210.0 View the attributes of a party220.0 Update the attributes of a party240.0 Delete a party250.0 Add a party to a group260.0 Remove a party from a group270.0 Perform the membership and composition checks
outlined in 130.x to 165.xRevision HistoryDocument Revision #Action Taken, NotesWhen?By Whom?0.1Creation08/16/2000Rafael Schloming0.2Initial revision08/19/2000Mark Thomas0.3Edited and reviewed, conforms to requirements template08/23/2000Kai Wu0.4Further revised, added UI requirements08/24/2000Mark Thomas0.5Final edits, pending freeze08/24/2000Kai Wu0.6More revisions, added composition requirements08/30/2000Mark Thomas0.7More revisions, added composition requirements09/08/2000Mark Thomas