parties.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="parties" xreflabel="Parties in OpenACS">
<title>Parties in OpenACS</title>
<authorblurb>
<para>By <ulink url="http://planitia.org">Rafael H. Schloming</ulink></para>
</authorblurb>
<sect2 id="parties-intro">
<title>Introduction</title>
<para>While many applications must deal with individuals and many applications
must deal with groups, most applications must deal with individuals
<emphasis>or</emphasis> groups. It is often the case with such
applications that
both individuals and groups are treated identically. Modelling
individuals and groups as specializations of one supertype is a
practical way to manage both. This concept is
so mundane that there is
no need to invent special terminology. This
supertype is called a "party".</para>
<para>A classic example of the "party" supertype is evident
in address books. A typical address book might contain
the address of a doctor, grocery store, and friend. The
first field in an entry in the address book is not labeled a person or
company, but a "party".
</para>
</sect2>
<sect2 id="parties-data-model">
<title>The Data Model</title>
<para>The parties developer guide begins with
an introduction to the parties data model, since OpenACS
community applications likely require using it in some way.</para>
<para><emphasis role="strong">Parties</emphasis></para>
<para>The central table in the parties data model is the parties table itself.
Every party has exactly one row in this table. Every party has an optional
unique email address and an optional url. A party is an acs object, so
permissions may be granted and revoked on parties and auditing information is
stored in the acs objects table.</para>
<programlisting>
<computeroutput>
create table parties (
party_id not null
constraint parties_party_id_fk references
acs_objects (object_id)
constraint parties_party_id_pk primary key,
email varchar(100)
constraint parties_email_un unique,
url varchar(200)
);
</computeroutput>
</programlisting>
<para>The <computeroutput>persons</computeroutput> and
<computeroutput>groups</computeroutput> tables extend the
<computeroutput>parties</computeroutput> table. A row in the persons table represents the
most generic form of individual modeled. An individual need not be known to the system as a user. A
user is a further specialized form of an individual (discussed later). A
row in the groups table represents the most generic form of group
modeled, where a group is an aggregation of zero or more
individuals.</para>
<para><emphasis role="strong">Persons</emphasis></para>
<para>If a party is an individual then there will be a row in the persons table
containing <computeroutput>first_names</computeroutput> and
<computeroutput>last_name</computeroutput>
for that individual. The
primary key of the persons table (<computeroutput>person_id</computeroutput>) references the primary key of
the parties table (<computeroutput>party_id</computeroutput>), so that there is a corresponding row in the
parties table when there is a row in the persons table.
</para>
<programlisting>
<computeroutput>create table persons (
person_id not null
constraint persons_person_id_fk
references parties (party_id)
constraint persons_person_id_pk primary key,
first_names varchar(100) not null,
last_name varchar(100) not null
);
</computeroutput>
</programlisting>
<para><emphasis role="strong">Users</emphasis></para>
<para>The <computeroutput>users</computeroutput> table is a more
specialized form of <computeroutput>persons</computeroutput> table. A row
in <computeroutput>users</computeroutput> table represents an individual that has login access to the
system. The primary key of the users table references the primary
key of the persons table. This guarantees that if there is a row
in <computeroutput>users</computeroutput> table then there must be a
corresponding row in <computeroutput>persons</computeroutput>
and <computeroutput>parties</computeroutput> tables.</para>
<para>Decomposing all the information
associated with a user into the four tables (acs_objects, parties, persons,
users) has some immediate benefits. For instance, it is possible to remove access to a user from a live
system by removing his entry from the users table, while leaving the rest of
his information present (i.e. turning him from a user into a
person).</para>
<para>Wherever possible the OpenACS data model references the <computeroutput>persons</computeroutput> or
<computeroutput>parties</computeroutput> table, <emphasis role="strong">not</emphasis> the <computeroutput>users</computeroutput> table.
Developers should be careful to
only reference the users table in situations where it is clear that the
reference is to a user for all cases and not to any other individual
for any case.</para>
<programlisting>
<computeroutput>create table users (
user_id not null
constraint users_user_id_fk
references persons (person_id)
constraint users_user_id_pk primary key,
password varchar(100),
salt varchar(100),
screen_name varchar(100)
constraint users_screen_name_un
unique,
priv_name integer default 0 not null,
priv_email integer default 5 not null,
email_verified_p char(1) default 't'
constraint users_email_verified_p_ck
check (email_verified_p in ('t', 'f')),
email_bouncing_p char(1) default 'f' not null
constraint users_email_bouncing_p_ck
check (email_bouncing_p in ('t','f')),
last_visit date,
second_to_last_visit date,
n_sessions integer default 1 not null,
password_question varchar(1000),
password_answer varchar(1000)
);
</computeroutput>
</programlisting>
<para><emphasis role="strong">Groups</emphasis></para>
<para>The final piece of the parties data model is the groups data model. A
group is a specialization of a party that represents an aggregation of
zero or more other
parties. The only extra information directly associated with a group (beyond
that in the parties table) is the name of the group:</para>
<programlisting>
<computeroutput>create table groups (
group_id not null
constraint groups_group_id_fk
references parties (party_id)
constraint groups_group_id_pk primary key,
group_name varchar(100) not null
);
</computeroutput>
</programlisting>
<para>
There is another piece to the groups data model that records relations between
parties and groups.
</para>
<para><emphasis role="strong">Group Relations</emphasis></para>
<para>Two types of group relations are represented in the data model:
membership relations and composite relations.
The full range of sophisticated group structures that exist in the real
world can be modelled in OpenACS by these two relationship types.</para>
<para>Membership relations represent direct membership relation between parties and groups. A party may be
a "member" of a group. Direct membership relations are
common in administrative practices, and do not follow basic set
theory rules. If A is a member of B, and B is a member of C, A is
<emphasis role="strong">not</emphasis> a member of C. Membership relations are not transitive.
</para><para>Composition relation represents composite relation
between <emphasis>two groups</emphasis>. Composite relation is
transitive. That is, it works like
memberships in set theory. If A is a member of B, and B is a member of
C, then A is a member of C.
</para><para>
For example, consider the membership relations of Greenpeace, and
composite relations of a multinational corporation. Greenpeace, an
organization (i.e. group), can have both individuals and organizations
(other groups) as members. Hence the membership relation between
groups and <emphasis>parties</emphasis>. However, someone is not
a member of Greenpeace just because they are a member of a
group that is a member of Greenpeace. Now, consider a multinational
corporation (MC) that has a U.S. division and a Eurasian division. A member of either the
U.S. or Eurasian division is automatically a member of the MC. In this
situation the U.S. and Eurasian divisions are "components" of
the MC, i.e., membership <emphasis>is</emphasis> transitive with respect to
composition. Furthermore, a member of a European (or other) office of the MC
is automatically a member of the MC.
</para>
<para><emphasis role="strong">Group Membership</emphasis></para>
<para>Group memberships can be created and manipulated using the membership_rel
package. Only one membership object can be created for a given
group, party pair.
</para><para>
It is possible in some
circumstances to make someone a member of a group of which they are already a
member. That is because the model distinguishes between direct membership and
indirect membership (membership via some composite relationship).
For example, a person might be listed in a system as both an
individual (direct membership) and a
member of a household (indirect membership) at a video rental store.
</para>
<programlisting>
<computeroutput>
# SQL code
create or replace package membership_rel
as
function new (
rel_id in membership_rels.rel_id%TYPE default null,
rel_type in acs_rels.rel_type%TYPE default 'membership_rel',
object_id_one in acs_rels.object_id_one%TYPE,
object_id_two in acs_rels.object_id_two%TYPE,
member_state in membership_rels.member_state%TYPE default null,
creation_user in acs_objects.creation_user%TYPE default null,
creation_ip in acs_objects.creation_ip%TYPE default null
) return membership_rels.rel_id%TYPE;
procedure ban (
rel_id in membership_rels.rel_id%TYPE
);
procedure approve (
rel_id in membership_rels.rel_id%TYPE
);
procedure reject (
rel_id in membership_rels.rel_id%TYPE
);
procedure unapprove (
rel_id in membership_rels.rel_id%TYPE
);
procedure deleted (
rel_id in membership_rels.rel_id%TYPE
);
procedure delete (
rel_id in membership_rels.rel_id%TYPE
);
end membership_rel;
/
show errors
</computeroutput>
</programlisting>
<para><emphasis role="strong">Group Composition</emphasis></para>
<para>Composition relations can be created or destroyed using the
composition_rel package. The only restriction on compositions is that there
cannot be a reference loop, i.e., a group cannot be a component of itself either
directly or indirectly. This constraint is maintained for you by the API.
So users do not see some random PL/SQL error message,
do not give them the option to create a composition relation that
would result in a circular reference.</para>
<programlisting>
<computeroutput>
# SQL code
create or replace package composition_rel
as
function new (
rel_id in composition_rels.rel_id%TYPE default null,
rel_type in acs_rels.rel_type%TYPE default 'composition_rel',
object_id_one in acs_rels.object_id_one%TYPE,
object_id_two in acs_rels.object_id_two%TYPE,
creation_user in acs_objects.creation_user%TYPE default null,
creation_ip in acs_objects.creation_ip%TYPE default null
) return composition_rels.rel_id%TYPE;
procedure delete (
rel_id in composition_rels.rel_id%TYPE
);
end composition_rel;
/
show errors
</computeroutput>
</programlisting>
</sect2>
<sect2 id="parties-views">
<title>Views</title>
<para>The parties data model does a reasonable job of representing many
of the situations one is likely to encounter when modeling organizational
structures. We still need to be able to efficiently answer questions like
"what members are in this group and all of its components?", and
"of what groups is this party a member either directly or
indirectly?". Composition relations allow you to describe an arbitrary
Directed Acyclic Graph (DAG) between a group and its components. For these
reasons the party system provides a bunch of views that take advantage of the
internal representation of group relations to answer questions like these
very quickly.</para>
<para>The <computeroutput>group_component_map</computeroutput>
view returns all the subcomponents of a group including components of
sub components and so forth. The <computeroutput>container_id</computeroutput> column is the <computeroutput>group_id</computeroutput> of the
group in which <computeroutput>component_id</computeroutput> is directly contained. This allows you to easily
distinguish whether a component is a direct component or an indirect
component. If a component is a direct component then <computeroutput>group_id</computeroutput> will be equal
to <computeroutput>container_id</computeroutput>. You can think of this view as having a primary key of
<computeroutput>group_id</computeroutput>, <computeroutput>component_id</computeroutput>, and <computeroutput>container_id</computeroutput>. The <computeroutput>rel_id</computeroutput> column points to the row
in <computeroutput>acs_rels</computeroutput> table that contains the relation object that relates <computeroutput>component_id</computeroutput> to
<computeroutput>container_id</computeroutput>. The <computeroutput>rel_id</computeroutput> might be useful for retrieving or updating standard
auditing info for the relation.</para>
<programlisting>
<computeroutput>create or replace view group_component_map
as select group_id, component_id, container_id, rel_id
...
</computeroutput>
</programlisting>
<para>The <computeroutput>group_member_map</computeroutput> view is similar to <computeroutput>group_component_map</computeroutput> except for membership relations.
This view returns all membership relations regardless of membership state.</para>
<programlisting>
<computeroutput>create or replace view group_member_map
as select group_id, member_id, container_id, rel_id
...
</computeroutput>
</programlisting>
<para>The <computeroutput>group_approved_member_map</computeroutput>
view is the same as <computeroutput>group_member_map</computeroutput> except
it only returns entries that relate to approved members.</para>
<programlisting>
<computeroutput>create or replace view group_approved_member_map
as select group_id, member_id, container_id, rel_id
...
</computeroutput>
</programlisting>
<para>The <computeroutput>group_distinct_member_map</computeroutput>
view is a
useful view if you do not care about the distinction between
direct membership and indirect membership. It returns all members of a
group including members of components --the transitive closure.</para>
<programlisting>
<computeroutput>create or replace view group_distinct_member_map
as select group_id, member_id
...
</computeroutput>
</programlisting>
<para>The <computeroutput>party_member_map</computeroutput> view is the same as <computeroutput>group_distinct_member_map</computeroutput>, except it includes the
identity mapping. It maps from a party to the fully expanded
list of parties represented by that party including the party itself. So if a
party is an individual, this view will have exactly one mapping that is from
that party to itself. If a view is a group containing three individuals, this
view will have four rows for that party, one for each member, and one from
the party to itself.</para>
<programlisting>
<computeroutput>create or replace view party_member_map
as select party_id, member_id
...
</computeroutput>
</programlisting>
<para>The <computeroutput>party_approved_member_map</computeroutput> view is the same as <computeroutput>party_member_map</computeroutput> except that when it expands groups, it only
pays attention to approved members.</para>
<programlisting>
<computeroutput>create or replace view party_approved_member_map
as select party_id, member_id
...
</computeroutput>
</programlisting>
</sect2>
<sect2 id="parties-extending-data-model">
<title>Extending The Parties Data Model</title>
<para>The parties data model can represent some fairly sophisticated real
world situations. Still, it would be foolish to assume that this data
model is sufficiently efficient for every
application. This section describes some
of the more common ways to extend the parties data model.</para>
<para><emphasis role="strong">Specializing Users</emphasis></para>
<para>Some applications will want to collect more
detailed information for people using the system. If
there can be only one such piece of information per user, then it might make
sense to create another type of individual that is a further specialization
of a user. For example a Chess Club community web site might want to record
the most recent score
for each user. In a situation like this it would be appropriate to create a
subtype of users, say chess_club_users. This child table of the users table would
have a primary key that references the users table, thereby guaranteeing that
each row in the chess_club_users table has a corresponding row in each of the
users, persons, parties, and acs_objects tables. This child table could then
store any extra information relevant to the Chess Club community.</para>
<para><emphasis role="strong">Specializing Groups</emphasis></para>
<para>If one were to build an intranet application on top of the party
system, it is likely that one would want to take advantage of the systems
efficient representation of sophisticated organizational structures, but
there would be much more specialized information associated with each group.
In this case it would make sense to specialize the group party type into a
company party type in the same manner as Specializing Users.</para>
<para><emphasis role="strong">Specializing Membership Relations</emphasis></para>
<para>The final portion of the parties data model that is designed to be
extended is the membership relationship. Consider the intranet example again.
It is likely that a membership in a company would have more information
associated with it than a membership in an ordinary group. An obvious example
of this would be a salary. It is exactly this need to be able to extend
membership relations with mutable pieces of state that drove us to include a
single integer primary key in what could be thought of as a pure relation.
Because a membership relation is an ordinary acs object with <ulink url="object-identity.html">object identity</ulink>, it is as easy to extend the
membership relation to store extra information as it is to extend the users
table or the groups table.</para>
<para><phrase role="cvstag">($Id: parties.xml,v 1.10.2.2 2023/03/28 11:20:36 antoniop Exp $)</phrase></para>
</sect2>
</sect1>
