Reader Management

Jakub Adámek

Econnect

$Id: reader.html 4824 2023-11-30 15:29:56Z honzam $

Revision History
Revision 1.7 5.4.2003
The part about Alerts moved to a separate document.
Revision 1.6 9.3.2003
Added the section Sending emails by wizard
Revision 1.5 8.3.2003
Updated Mailman section. Other minor changes.
Revision 1.4 6.3.2003
Updated Alerts specific as the menu is updated and Filters are renamed to Selections not to confuse them with Content Pooling Filters
Revision 1.3 3.3.2003
Enhanced and corrected the Mailman specific section to reflect the recent implementation, it is not yet complete.
Revision 1.2 16.2.2003
The part about Anonymous forms moved to a separate document. Enhanced and corrected the Alerts specific section to reflect the recent implementation.
Revision 1.1 11.2.2003
Added a remark about using several slices (second paragraph in "Central point: Slice"). Enhanced and corrected the Auth specific section to reflect the recent implementation.
Revision 1.0 5.2.2003

Table of Contents

Basic idea
Reader Management Slice
Sending emails by wizard
Editing Reader Info: Anonymous posting form
Module common behaviour
Module specific behaviour
Alerts
Auth
Apache module mod_auth_mysql
Auth feature
Mailman
Mailman: create list
Discussion - Why to use slice?

Note

This file was created from the DocBook XML source. Please do modifications in the source, not here.

Basic idea

See also the separate documents about Alerts and about Anonymous forms.

Readers are users with no AA admin access. I don't want to use the term “users” because of possible confusion with the AA users like Authors and more.

Several modules may be connected with readers:

  • Alerts, for sending new items by email
  • Authorization (Auth), for HTTP authorization via MySQL_Auth
  • Mailman, for e-mail discussions
  • AA permissions synchronization, which propagates username and password changes to the AA permission system

Readers are identified by email in Alerts and Mailman and by username in Auth.

Reader Management Slice

After a lot of discussing and unhappily also a lot of work to be thrown off, we have in Econnect decided the best approach to handle Reader management will be a slice. It is so simple: each item belongs to one person. The individual settings for Alerts, Auth etc. are added as fields to the item design.

Note this means not one slice but several slices, one for each web site which uses Alerts, Auth or Mailman. Readers of different web sites are in different slices and thus independent. Slice features like item feeding may be used when necessary.

The minimal slice template named Reader Management Minimal is now a part of the sql_update script and consists of:

Table 1. Fields in the Reader Management Minimal template

Username Used in the Authorization (Auth) module
Email Required for Alerts and Mailman modules. For each Reader Management slice either username or email should be flagged as required.
Password If the web uses Auth, this is the HTTP password. Otherwise this password must be filled in the anonymous form every time a reader wants to change his or her personal details.
First / Last name Not required, may be used to personalize emails.
Email Confirmed This box is automatically checked after the reader clicks on a link including the Access Code (see below). No reader receives any Alert email until it is checked.
Access Code This code is received in emails as a part of a URL. By clicking on this URL a reader confirms his or her email address. The URL points to reader personal details. On webs not using Auth this is the only way to edit personal details.
Remark Any remark may or may not be a part of the personal details shown to readers.
Start date Membership start, readers are disabled before this point for all related modules.
Expiry date Membership finish, readers are disabled after this point.

Slice administrators create new slice based on this template and may add any number of further fields, which is the main advantage of using a slice for Reader Management.

The Alerts module adds automatically its own fields, with special field IDs linking to the module, e.g. alerts1....4e4c7 for “how often” and Alerts Collection with ID 4e4c7.

One Reader management slice may be connected with several modules, usually belonging to the same web site. Suppose you create a site with HTTP restricted access. You may provide an Authorization module and two different Alerts Collections. They all link to the same reader group and thus use the same Reader management slice.

In the simplest cases, there will be one Reader management slice + one Alerts or Auth module. The Alerts or Auth module will always use (almost) directly the slice data.

Sending emails by wizard

On Reader Management slices there appears in the action select box a new item: “Send emails wizard”. If you select some items (readers) and choose this action, the window is divided in two frames with a wizard in the right one.

The wizard contains hints and links into AA pages. Its steps include creating or editing the email template, sending an example email to yourself and sending the email to all readers which you selected before running the wizard.

You can use any fields aliases like in any view (index, fulltext etc.)

Editing Reader Info: Anonymous posting form

As readers do not have access to the AA control panel, they must edit their personal details on the Anonymous posting form, described in another document.

Module common behaviour

Only readers in Active bin will receive Alerts, be allowed to pages guarded by Authorization etc.

In special cases, when you want to stop web access for some reader (authorization) but don't want to stop him or her receiving Alerts, you must create a dummy authorization group and assign this group to him or her.

Module specific behaviour

Alerts

Alerts are described in a separate document.

Auth

Apache module mod_auth_mysql

The Auth feature (it is not a real module) is meant to be used by the mod_auth_mysql Apache module. You must install this module on your web server to appreciate the Auth feature. There are several versions of the module with different option names. Find the correct ones in your version. This is the info you will need:

Table 2. Tables maintained by the Auth feature

auth_user with the fields “username” and “passwd”
auth_group with the fields “username” and “groups”

Set up Apache and fill correct group info into the .htaccess files in folders which you want to protect. Note the groups you are using here are the groups separated by semicolon in the AA constants, see below.

Auth feature

The Auth administration includes creating membership types (meta-groups) and assigning (sub)groups to them. This may be achieved with the usage of AA constants, where the constant name is the membership type and the constant value are the subgroups assigned to individual folders, separated by semicolon.

For example, if you want to create Standard Membership and Privileged Membership, where the first is permitted to folders "main" and "search" and the second to "main", "search" and "privileged", you create these two constants:

Table 3. Membership Constants Example

Name Value
Standard Membership myreaders_main;myreaders_search
Privileged Membership myreaders_main;myreaders_search;myreaders_privileged

The user / membership type assignments are synchronized with tables auth_user and auth_group using event handlers for events like updating an item or moving the item into another bin. Also you should check “Propagate changes into current items” in the constant group because then if you change the subgroups, all user-group assignments for that metagroup are updated even in the auth_group table.

To avoid the conflict of another Reader Management slice using the same subgroup names, I recommend to use some pre- or postfix (like “myreaders_” in my example).

When you have created the constant group, create a field of type “Auth Group” and assign the constant group to it.

The Auth feature is set on and off using a new item in Slice Settings, named “Auth Group Field”, with the name of the field mentioned above. This setting is visible only in Reader Management slices created from the Reader Management Minimal template (exactly, only for slices of type ReaderManagement).

Only when “Auth Group Field” is filled, the slice is synchronized with the auth_user/group tables.

You may set to which bin new readers are put on subscription with the standard "Allow anonymous posting of items" setting.

Because readers are assigned to items, they may appear in Pending or Expired bin depending on Start date and Expiry date settings. You should run the script auth_maintain.php?maintain_auth=1 once a day by cron to automatically add or delete users moved to or from the Active bin.

Mailman

You can manage mailing lists with the Mailman feature. The idea is to use a directory accessible both to PHP and to mailman. AA maintain files with names being the mailing list names, each file contains a list of email addresses subscribed to the list, one on a row. Mailman reads these files regularly to synchronize the real mailing lists.

To use this feature, follow these steps:

  1. create the mailing lists using the mailman interface
  2. in config.php, set $MAILMAN_SYNCHRO_DIR to the directory accessible both to PHP and to mailman, described above
  3. create a new field of type “Mailing Lists” in the Reader Management slice
  4. create a new constant group for this field. The names and values of constants in the group are the names of the mailing lists
  5. set the field type, the default is multiple-checkboxes. You can arrange the checkboxes into a table with the parameter wizard
  6. in Slice Settings, select the field as Mailman Lists Field
  7. set mailman cron so that it regularly (e.g. every minute) updates the real mailing lists using a Unix shell-script like

    LISTSDIR="/var/www/html/maillists"
    MMDIR="/var/mailman"
    for LIST in `find $LISTSDIR/* -newer $MMDIR/data/.lastsync -printf "%f\n"`;
        do
            $MMDIR/bin/sync_members -f $LISTSDIR/$LIST -w=no -a=no $LIST
        done
    touch $MMDIR/data/.lastsync

Mailman: create list

Another convenience feature is the possibility to create new mailing lists from the AA interface. For Reader management slices with a field filled in Slice Settings - Mailman Lists Field there appears a new option in the menu, “Mailman: create list”. You fill the name of the new list, admin email and password. The list name is added to the constant group used by the Mailman Lists Field and a request row is added to the file .mailman in the $MAILMAN_SYNCHRO_DIR directory. You should run another Unix shell-script regularly which executes the requests.

Tip: If you enable users to subscribe to mailing lists in an anonymous form, you must add the new checkbox to that form.

Discussion - Why to use slice?

The main reason to use slice was that we need some reader management with the possibility to add any new fields. This is exactly what slice does. Also, we can use many other nice features already developed for slice. And last but not least if we need to improve the current slice interface to better support Reader management, this will be useful for all other slices as well. This is for example the case of Anonymous forms.