collective.topicitemsevent 1.0

Facilitate flexible scheduled notifications in Plone: Fire 'Topic Item Events' for items in a Topic

Introduction

This product is intended as a solution for the use case of sending notification e-mails for items which are about to expire (in, say, the next 24 hours).

The solution this product facilitates allows you to:

1. Select and preview the items for which to take action

2. Select different actions:

   1. send e-mail notification:

      1. configure message text

      2. configure recipients

   2. modify the workflow state

   3. move the item somewhere else

All this can be done by site administrators without programming skills, using Plone’s control panel.

Implementation

The facilitated solution requires these parts:

1. Items are selected in a Topic. Topics allow you to define a relative date, like “in the next week”. They also allow you to filter items on lots of other criteria.

2. We create a View which fires an Event for each item in the Topic when that is View is called. That is the scope of this product.

3. A Content Rule is added which is triggered by the fired Event. Content Rules may have different Actions: sending e-mail, changing workflow state, moving objects.

4. The View is called at regular intervals. You may use Cron4Plone or a cron job for this.

Getting started

1. Select items

Create a Topic which gathers all content you want some action taken for.

In the future, we might also use plone.app.collection’s new style Collections for this, however these currently don’t seem to support relative date criteria.

Example

If you want to send e-mails about content that was modified the previous day:

• go to the criteria tab

• “Add new search criteria” for field name “Modification date”

• set “Criteria type” to “Relative date” and click “Add criteria”

• in the “Modification Date” criteria:

  • for “Which day”, select “Now”

  • for “In the past or future”, select “In the past”

  • for “More or less”, select “Less than”

2. Install the @@fire-topicitems-events view

Install this product using buildout

In buildout.cfg:

eggs +=
    collective.topicitemsevent

Afterwards, install the product using the Plone “Add-on products” controlpanel.

Check that it works

Go to your newly created Topic and call the @@fire-topicitems-events view on it. You should have administrator permissions to do this. If all goes well, you should be redirected to the Topic’s default view, and you will see a status message that says “Firing TopicItemEvent for: “, followed by a list of item titles and their urls.

3. Configure Content Rule

Creating the Content Rule

1. Via Plone’s control panel, go to the “Content Rules Control Panel” (/@@rules-controlpanel).

2. Add a content rule. As the “Triggering event” select “Topic Item Event”. Give it a meaningful title. For now, we’ll use “Send e-mail notifications about modifications”.

3. The new rule will show up in the Rules Control Panel. Click it to add an action. Under the header “Perform the following actions”, you can select any Content Rule action.

4. For now, just select “Send email”, click “Add” and configure the email. (Use the ${title} and ${url} variables, so the people who get the mail know what it’s about.)

5. You might also want to add a “Notify user” action. This is handy when testing the content rule: You’ll see the status message(es) after using the @@fire-topicitems-events view.

Adding the Content Rule

1. Go to the root of the Plone Site, click “Rules” and add the rule for the site.

2. Afterwards, select the rule and click “Apply to subfolders”.

Testing the Content Rule

Now go to your Topic and call @@fire-topicitems-events again.

4. Call the View at intervals

We’ll assume you use Cron4Plone for this, but you might also use a cron job. You need to call the view as administrator, the Cron4Plone documentation will tell you how.

In the Cron4Plone configuraton screen, you should have a line like:

30 2 * * portal/test-topic/@@fire-topicitems-events

Where ‘test-topic’ refers to your Topic’s id. This will call the view each night at 02:30 AM.

Issues

1. This solution doesn’t keep track of which e-mails were sent. When changing the Topic’s date range, or the cron interval, notifications my be sent multiple times or not at all. This issue will likely never be resolved.

2. You can likely not have multiple contentrules listening on the “Topic Item Event. If you have multiple contentrules listening on the “Topic Item Event”, there’s no way of knowing which Topic the Content Rule’s Event was fired from.

   1. One way to workaround this is to activate the Content Rule on a specific Folder. You’d have to be careful though: this might get complicated very quickly.

   2. You could also protect your Content Rule with an extra filtering condition. For example, if you have a rule that makes expired content private, and you’re afraid that this rule will come into action as a result of a TopicItemEvent being fired from an unrelated Topic (which unfortunately lists an item that is not to be made private) , then you could add python: DateTime() > here.getExpirationDate() as a TALES expression condition. This will ensure the rule only comes into action if the item is expired.

Changelog

1.0 (2012-06-13)

• Stable release

0.1.1 (2011-11-28)

• Documentation update: How to use a TALES expression in a Plone Content Rule to check on dates (ExpirationDate, EffectiveDate).

0.1 (2011-11-21)

• package info changes (setup.py)

0.1dvl (2011-10-26)

• Initial release