- I OpenACS For Everyone
- I.1 High level information: What is OpenACS?
- I.1.1 Overview
- I.1.2 OpenACS Release Notes
- I.2 OpenACS: robust web development framework
- I.2.1 Introduction
- I.2.2 Basic infrastructure
- I.2.3 Advanced infrastructure
- I.2.4 Domain level tools
- I.1 High level information: What is OpenACS?
- II Administrator's Guide
- II.2 Installation Overview
- II.2.1 Basic Steps
- II.2.2 Prerequisite Software
- II.3 Complete Installation
- II.3.1 Install a Unix-like system and supporting software
- II.3.2 Install Oracle 10g XE on debian
- II.3.2.1 Install Oracle 8.1.7
- II.3.3 Install PostgreSQL
- II.3.4 Install AOLserver 4
- II.3.5 Quick Install of OpenACS
- II.3.5.1 Complex Install OpenACS 5.3
- II.3.6 OpenACS Installation Guide for Windows2000
- II.3.7 OpenACS Installation Guide for Mac OS X
- II.4 Configuring a new OpenACS Site
- II.4.1 Installing OpenACS packages
- II.4.2 Mounting OpenACS packages
- II.4.3 Configuring an OpenACS package
- II.4.4 Setting Permissions on an OpenACS package
- II.4.5 How Do I?
- II.4.6 Configure OpenACS look and feel with templates
- II.5 Upgrading
- II.5.1 Overview
- II.5.2 Upgrading 4.5 or higher to 4.6.3
- II.5.3 Upgrading OpenACS 4.6.3 to 5.0
- II.5.4 Upgrading an OpenACS 5.0.0 or greater installation
- II.5.5 Upgrading the OpenACS files
- II.5.6 Upgrading Platform components
- II.6 Production Environments
- II.6.1 Starting and Stopping an OpenACS instance.
- II.6.2 AOLserver keepalive with inittab
- II.6.3 Running multiple services on one machine
- II.6.4 High Availability/High Performance Configurations
- II.6.5 Staged Deployment for Production Networks
- II.6.6 Installing SSL Support for an OpenACS service
- II.6.7 Set up Log Analysis Reports
- II.6.8 External uptime validation
- II.6.9 Diagnosing Performance Problems
- II.7 Database Management
- II.7.1 Running a PostgreSQL database on another server
- II.7.2 Deleting a tablespace
- II.7.3 Vacuum Postgres nightly
- II.8 Backup and Recovery
- II.8.1 Backup Strategy
- II.8.2 Manual backup and recovery
- II.8.3 Automated Backup
- II.8.4 Using CVS for backup-recovery
- II.A Install Red Hat 8/9
- II.B Install additional supporting software
- II.B.1 Unpack the OpenACS tarball
- II.B.2 Initialize CVS (OPTIONAL)
- II.B.3 Add PSGML commands to emacs init file (OPTIONAL)
- II.B.4 Install Daemontools (OPTIONAL)
- II.B.5 Install qmail (OPTIONAL)
- II.B.6 Install Analog web file analyzer
- II.B.7 Install nspam
- II.B.8 Install Full Text Search
- II.B.9 Install Full Text Search using Tsearch2
- II.B.10 Install Full Text Search using OpenFTS (deprecated see tsearch2)
- II.B.11 Install nsopenssl
- II.B.12 Install tclwebtest.
- II.B.13 Install PHP for use in AOLserver
- II.B.14 Install Squirrelmail for use as a webmail system for OpenACS
- II.B.15 Install PAM Radius for use as external authentication
- II.B.16 Install LDAP for use as external authentication
- II.B.17 Install AOLserver 3.3oacs1
- II.C Credits
- II.C.1 Where did this document come from?
- II.C.2 Linux Install Guides
- II.C.3 Security Information
- II.C.4 Resources
- II.2 Installation Overview
- III For OpenACS Package Developers
- III.9 Development Tutorial
- III.9.1 Creating an Application Package
- III.9.2 Setting Up Database Objects
- III.9.3 Creating Web Pages
- III.9.4 Debugging and Automated Testing
- III.10 Advanced Topics
- III.10.1 Write the Requirements and Design Specs
- III.10.2 Add the new package to CVS
- III.10.3 OpenACS Edit This Page Templates
- III.10.4 Adding Comments
- III.10.5 Admin Pages
- III.10.6 Categories
- III.10.7 Profile your code
- III.10.8 Prepare the package for distribution.
- III.10.9 Distributing upgrades of your package
- III.10.10 Notifications
- III.10.11 Hierarchical data
- III.10.12 Using .vuh files for pretty urls
- III.10.13 Laying out a page with CSS instead of tables
- III.10.14 Sending HTML email from your application
- III.10.15 Basic Caching
- III.10.16 Scheduled Procedures
- III.10.17 Enabling WYSIWYG
- III.10.18 Adding in parameters for your package
- III.10.19 Writing upgrade scripts
- III.10.20 Connect to a second database
- III.10.21 Future Topics
- III.11 Development Reference
- III.11.1 OpenACS Packages
- III.11.2 OpenACS Data Models and the Object System
- III.11.3 The Request Processor
- III.11.4 The OpenACS Database Access API
- III.11.5 Using Templates in OpenACS
- III.11.6 Groups, Context, Permissions
- III.11.7 Writing OpenACS Application Pages
- III.11.8 Parties in OpenACS
- III.11.9 OpenACS Permissions Tediously Explained
- III.11.10 Object Identity
- III.11.11 Programming with AOLserver
- III.11.12 Using Form Builder: building html forms dynamically
- III.12 Engineering Standards
- III.12.1 OpenACS Style Guide
- III.12.2 Release Version Numbering
- III.12.3 Constraint naming standard
- III.12.4 ACS File Naming and Formatting Standards
- III.12.5 PL/SQL Standards
- III.12.6 Variables
- III.12.7 Automated Testing
- III.13 CVS Guidelines
- III.13.1 Using CVS with OpenACS
- III.13.2 OpenACS CVS Concepts
- III.13.3 Contributing code back to OpenACS
- III.13.4 Additional Resources for CVS
- III.14 Documentation Standards
- III.14.1 OpenACS Documentation Guide
- III.14.2 Using PSGML mode in Emacs
- III.14.3 Using nXML mode in Emacs
- III.14.4 Detailed Design Documentation Template
- III.14.5 System/Application Requirements Template
- III.15 TCLWebtest
- III.16 Internationalization
- III.16.1 Internationalization and Localization Overview
- III.16.2 How Internationalization/Localization works in OpenACS
- III.16.4 Design Notes
- III.16.5 Translator's Guide
- III.D Using CVS with an OpenACS Site
- III.9 Development Tutorial
- IV For OpenACS Platform Developers
- IV.17 Kernel Documentation
- IV.17.1 Overview
- IV.17.2 Object Model Requirements
- IV.17.3 Object Model Design
- IV.17.4 Permissions Requirements
- IV.17.5 Permissions Design
- IV.17.6 Groups Requirements
- IV.17.7 Groups Design
- IV.17.8 Subsites Requirements
- IV.17.9 Subsites Design Document
- IV.17.10 Package Manager Requirements
- IV.17.11 Package Manager Design
- IV.17.12 Database Access API
- IV.17.13 OpenACS Internationalization Requirements
- IV.17.14 Security Requirements
- IV.17.15 Security Design
- IV.17.16 Security Notes
- IV.17.17 Request Processor Requirements
- IV.17.18 Request Processor Design
- IV.17.19 Documenting Tcl Files: Page Contracts and Libraries
- IV.17.20 Bootstrapping OpenACS
- IV.17.21 External Authentication Requirements
- IV.18 Releasing OpenACS
- IV.18.1 OpenACS Core and .LRN
- IV.18.2 How to Update the OpenACS.org repository
- IV.18.3 How to package and release an OpenACS Package
- IV.18.4 How to Update the translations
- IV.17 Kernel Documentation
- V Tcl for Web Nerds
- V.1 Tcl for Web Nerds Introduction
- V.2 Basic String Operations
- V.3 List Operations
- V.4 Pattern matching
- V.5 Array Operations
- V.6 Numbers
- V.7 Control Structure
- V.8 Scope, Upvar and Uplevel
- V.9 File Operations
- V.10 Eval
- V.11 Exec
- V.12 Tcl for Web Use
- V.13 OpenACS conventions for TCL
- V.14 Solutions
- VI SQL for Web Nerds
- VI.1 SQL Tutorial
- VI.1.1 SQL Tutorial
- VI.1.2 Answers
- VI.2 SQL for Web Nerds Introduction
- VI.3 Data modeling
- VI.3.1 The Discussion Forum -- philg's personal odyssey
- VI.3.2 Data Types (Oracle)
- VI.3.4 Tables
- VI.3.5 Constraints
- VI.4 Simple queries
- VI.5 More complex queries
- VI.6 Transactions
- VI.7 Triggers
- VI.8 Views
- VI.9 Style
- VI.10 Escaping to the procedural world
- VI.11 Trees
- VI.1 SQL Tutorial
III.11.8 Parties in OpenACS
While many applications must deal with individuals and many applications must deal with groups, most applications must deal with individuals or 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".
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".
The parties developer guide begins with an introduction to the parties data model, since OpenACS community applications likely require using it in some way.
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.
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) );
groups tables extend the
parties 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.
If a party is an individual then there will be a row in the persons table containing
last_name for that individual. The primary key of the persons table (
person_id) references the primary key of the parties table (
party_id), so that there is a corresponding row in the parties table when there is a row in the persons table.
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 );
users table is a more specialized form of
persons table. A row in
users 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
users table then there must be a corresponding row in
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).
Wherever possible the OpenACS data model references the
parties table, not the
users 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.
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')), no_alerts_until date, last_visit date, second_to_last_visit date, n_sessions integer default 1 not null, password_question varchar(1000), password_answer varchar(1000) );
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:
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 );
There is another piece to the groups data model that records relations between parties and groups.
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.
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 not a member of C. Membership relations are not transitive.
Composition relation represents composite relation between two groups. 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.
For example, consider the membership relations of Greenpeace, and composite relations of a multinational corporation. Greenpeace, an organization (ie. group), can have both individuals and organizations (other groups) as members. Hence the membership relation between groups and parties. 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 is transitive with respect to composition. Furthermore, a member of a European (or other) office of the MC is automatically a member of the MC.
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.
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.
# 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
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.
# 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
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.
group_component_map view returns all the subcomponents of a group including components of sub components and so forth. The
container_id column is the
group_id of the group in which
component_id 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
group_id will be equal to
container_id. You can think of this view as having a primary key of
rel_id column points to the row in
acs_rels table that contains the relation object that relates
rel_id might be useful for retrieving or updating standard auditing info for the relation.
create or replace view group_component_map as select group_id, component_id, container_id, rel_id ...
group_member_map view is similar to
group_component_map except for membership relations. This view returns all membership relations regardless of membership state.
create or replace view group_member_map as select group_id, member_id, container_id, rel_id ...
group_approved_member_map view is the same as
group_member_map except it only returns entries that relate to approved members.
create or replace view group_approved_member_map as select group_id, member_id, container_id, rel_id ...
group_distinct_member_map 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.
create or replace view group_distinct_member_map as select group_id, member_id ...
party_member_map view is the same as
group_distinct_member_map, 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.
create or replace view party_member_map as select party_id, member_id ...
party_approved_member_map view is the same as
party_member_map except that when it expands groups, it only pays attention to approved members.
create or replace view party_approved_member_map as select party_id, member_id ...
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.
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.
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.
Specializing Membership Relations
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 object identity, 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.