APC Action Applications - Home Page

Frequently Asked Questions v2



Related FAQ items:

AA Alerts are designed to deliver new AA items to users by e-mail. Slice Administrators choose the design and which kind of items from which slices to include, creating Collections. Users subscribe for Collections and receive them optionally once a day, week or month.

A user interface allows users to change their subscriptions. Users are identified by e-mail and they must confirm their e-mail address by a confirmation code received by e-mail to make sure the address is working.

The admin interface allows AA admins to define new Collections, list users subscribed to Collections and list Collections subscribed by users.


Collections are created by Slice Administrators on the page Slice Admin / Alerts / Collections. They are based on Filters, which are defined in the Digest type of Views.

A Collection is an ordered list of Filters. Each Filter is associated with one Digest and filters items to be sent by using the search form conds[] and sort[]. Digests are views suiting Alerts needs (see below).

You may define Editorial for each Collection, which will be printed before Digests' texts. In the Editorial you can use these aliases:

Digests and Filters

Note: You create filters by typing their DESCRIPTION. You must type at least one description before you can create Collections.

Each view of type Alerts Digest has a set of Filters definitions. Create filters by typing their description. If you want to include all items in the filter, don't fill anything into the "conds[]" field. Otherwise you may fill any conds[] and sort[] definition in the URL shape, e.g.

conds[0][headline........]="human rights"&conds[1][fulltext........]=Bosna

is a filter sorting out items with "human rights" in headline and "Bosna" in fulltext. If you want to order the filtered items, use sort[] (see How to setup searchform in FAQ for details on conds[] and sort[]).

If you want to add more than 2 filters, use Update and than open the view definition again. Two new empty filter boxes will appear.

Sending e-mails

To send the alerts, you must have AA cron set on. Three entries are added to table cron by sql_update.php3, for daily, weekly and monthly sending. You can change the entries if you like. They define the time and date at which all mails are sent. You can't set individual sending times for collections.

E-mails are created so that in e-mail clients supporting HTML users see the HTML form and in clients supporting text only, users see text. The text form is created by deleting all HTML tags. Technically speaking, it is a MIME multi-part/alternative message with a text part and a HTML part.

E-mail headers From:, Reply-To:, Errors-To: and Sender: are configurable for each Collection. Also, you may set these fields for a fictive collection __default__, which is used whenever any of them is not filled for the active Collection. Another fictive collection __subscription__ sets e-mail headers which appear in e-mails sent on user subscription.

User interface

The login screen is shown by misc/alerts/index.php3, the main interface is in misc/alerts/user_filter.php3. It allows to input name and change password. In the other part there is a list of all subscribed collections. A user may change contents of any of the collections. Until she does so, the collection ID remains the same as in the Admin interface. This allows to propagate changes to users: If you do any change in the Admin interface, it will change to all users which didn't modify the collection. But when a user changes a collection, its contents is copied not to modify the common Collection storage. From the user point of view, she doesn't recognize it.

Creating subscription forms

Two scripts are here to simplify subscription forms creation. The first one is add_user_collection.php3, which uses the following required parameters:

and the following optional parameters

The standard error page shows an error description. The standard OK page shows information about where to change subscriptions or that the user should confirm her email address if she didn't yet.

The second script print_collections_select.php3 prints a select box to choose a collection by description. It is not necessary to use it, the script only simplifies the maintainance because it gets the collection descriptions from database. It has these optional parameters:

A simple subscription form may be:

<form name='f' method='post' action='http://www.ecn.cz/apc-aa/misc/alerts/add_user_collection.php3'>
<tr><td>E-mail:</td><td><input type=text name=email size=50></td></tr>
<tr><td>How often:</td><td><select name=howoften>

<option value=daily>Daily
<option value=weekly>Weekly
<option value=monthly>Monthly

<tr><td>Choose a collection:</td>
<td><!--#include virtual="/apc-aa/misc/alerts/print_collections_select.php3?c[]=7&c[]=11"--></td></tr>
<input type=submit value="Subscribe">

But mind the example address www.ecn.cz/aaa is not working, it is only an example.

User Subscription Flow

  1. Usually users subscribe on subscription forms in your pages
  2. They receive an email message telling them to click on the confirmation URL or copy it to a browser
  3. The confirmation URL contains a 4-letter confirmation code which identifies the user
  4. After clicking on the URL the login screen appears with the user email filled in and the confirmation code is deleted from the database
  5. When the user clicks once more on the URL, the code is not more valid: a subscription page appears
  6. If the user doesn't remember her password, she clicks on "Send confirmation", receives another confirmation email and her password is deleted
  7. You can use AA Admin E-mails to warn users and / or delete them when they didn't confirm their subscription for a number of days

Sending e-mails manually

You do not need to send e-mails manually, this part is useful for developers. AA cron runs alerts.php3 with two parameters:

For example


It will work on all items which appeared in Active bin from the last time this script was run. That includes items which were Pending and became Active (even if they are Expired at the moment of sending e-mail), items which were moved from Holding bin and new items added directly to Active bin. Look in the source alerts.php3 for the exact algorithm of selecting items (it's not as easy as described here).

The script itself does not check how often you run it, hence a user can receive a monthly digest every day if you are not careful.

You can use cron.php3 to run the script regularly.

Permissions in Control Panel

Superadmins may as usually access everything.

Slice Admins may access:

Tables structure

All tables concerned with Alerts have a name starting with alerts_.

User information is stored in alerts_user, collections description in alerts_collection. Filters belonging to collections are in alerts_collection_filter.

Filters are in alerts_digest_filter which is linked 1:n to table view (1 view has n filters). The fields last_xx in alerts_digest_filter include last time when the digest of items filtered by the particular filter was created and text_xx temporarily store the digest text.

Users subscriptions are in alerts_user_filter, each line of which has either a filterid or a collecetionid filled. It allows the users to choose simple filters instead of whole collections but this is not implemented.


Related Articles:

Alerts/Mailman Integration
How does a user retrieve a forgotten password from reader managment?

Last Edit: Aug 17 2011

<aafaq id=1688> ~ToDo: 1688 AA Alerts </aafaq> 

This FAQ interface was developed by Jason at Commons.ca

APC: Internet and ICTs for social justice and development APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC)
APC - Internet and ICTs for social justice and development