WebIssues/Email Notifications

This feature is included in version 0.8.4 of the WebIssues server. It allows to send email notifications when issues in selected folders are created or modified.

A similar feature is also planned for version 1.0, but it will be deeply redesigned in connection with the mechanism of filters and watches.

General Design

Users are be able to subscribe to selected folders and issues. They receive email notifications when an issue is added to a subscribed folder or when a subscribed issue is modified. Users can choose if they want to receive notifications immediately, daily (at given time) or weekly (at given day and time).

Notifications are sent in background using a cron job (on scheduled task on Windows), so they are sent only as often as the cron job runs. The changes are accumulated for each user until an email is sent, even if they are configured to be sent immediately. That helps avoid additional overhead and delays.

As notifications are implemented server side, the implementation is as simple as possible. There is no possibility to filter issues or types of changes. The emails don't contain detailed information about the changes, only the issue name, identifier, user name and date of modification.

Required Changes

As mentioned in the protocol specification only new commands can be added and the syntax and semantic of existing commands cannot be changed. It means we cannot modify the existing commands: LIST USERS, ADD USER etc.

In order to associate email address, frequency of notifications, etc., a new concept called preferences is introduced. It is designed in a universal way which allows extending it in the future.

Email notifications are optional and can be enabled or disabled by the administrator. This allows to install WebIssues in an environment where a SMTP service or a cron job is not available, or when the notifications should not be available for any other reasons. To let the client applications determine whether notifications are available, an new concept called feature is introduced.

Notifications are handled completely within the cron job, so no modifications to implementation of existing commands are necessary. Also no modifications of existing database tables are needed.

Cron job

There is a new script called cron.php which can be executed as a cron job (or scheduled task on Windows). This script is written in PHP and can be executed in stand-alone mode (it doesn't need to be executed via web server).

All invocations of the cron script can be logged to a new, dedicated log file.

In future versions this script may perform other operations.

Features

The available features can be obtained using the following command:

 LIST FEATURES

   F 'name'

The name of a feature is a string consisting of lowercase letters, digits and hyphens. If a feature is listed, it means that it is available and enabled. The client can safely ignore features that it doesn't understand. Features cannot affect the syntax or semantics or other commands, they can only add their own commands.

Features defined in version 0.8.4:

notify

enables the notify-frequency preference and the commands related to notifications.

Preferences

Current preferences can be accessed using the following command:

 LIST PREFERENCES userId

   P 'name' 'value'

A single field can be changed using:

 SET PREFERENCE userId 'name' 'value'

   OK

Fields are identified by name, which can consist of lowercase letters, digits and hyphens. This allows adding new fields in the future without breaking the protocol. The value can be a string of arbitrary length, containing all characters allowed by the WI protocol (including escaped new line character).

The server only allows using fields that it understands and validates the value depending on field type (for example if it's a valid email address). So basically the list of allowed fields and their values is a part of the protocol specification. As an exception, all fields starting with 'x-' are accepted by the sever and not validated. Fields starting with 'x-wi-' are reserved; other fields may be used by third-party applications (although they should use a unique prefix).

A server administrator is allowed to get and modify preferences of all users. Regular users are only allowed to get and modify their own preferences.

Fields defined in version 0.8.4:

email

address used for sending notifications; must be a valid email address

timezone

the timezone of the user; must consist of a + or - sign, two digits for hours and two digits for minutes, for example "+0000", "+0200" or "-7000".

notify-frequency

frequency and time of notifications (only available if the 'notify' feature is enabled)

The definition of notify-frequency must follow the same rules as attribute definitions, i.e. it consists of a type and zero or more metadata. The allowed types are:

IMMEDIATELY

notifications are sent as soon as possible

DAILY hour="hh:mm"

notifications are sent every day at given time

WEEKLY day=d hour="hh:mm"

notifications are sent weekly at given day (from 0 - Sunday to 6 - Saturday) and time

Note that the exact time when notifications are sent depend on how often the cron script runs, so it should generally run at least once an hour. In practice, in immediate mode, notifications are sent during each cron script run, as soon as there are pending changes), but not more often to a given that the minimum configured time span. In daily or weekly mode, the changes are sent during the first cron run at or after the configured time.

Time is specified in user's time zone. By default it is the same as the server's time zone. It can be explicitly set to a different time zone using the timezone field.

Notifications

Current notifications can be listed using the following command:

 LIST NOTIFICATIONS

   F folderId
   I issueid

Notification for a folder can be enabled or disabled using the following command:

 NOTIFY FOLDER folderId status

   OK

Notification for an issue can be set using an analogous command:

 NOTIFY ISSUE issueId status

   OK

The status can be 1 (enabled) or 0 (disabled).

Sending Emails

The actual sending is done using the selected mail engine. The default engine uses the the built-in mail() function. The SMTP engine uses the PHPMailer class which can communicate with any external SMTP server.

The template of the email is a simple text file located in a templates subdirectory. It has placeholders for user name, folder name, issue name etc., and sections for project summary, folder summary, issue details etc. There are two predefined templates for plain-text emails and HTML emails, which can be copied and modified by the administrator.

The configuration file specifies whether notifications are enabled, what engine is used, and additional options depending on the selected engine (sender address, SMTP server to use, etc.).

User Interface

There is a 'Change Preferences' dialog (accessible via Tools menu) which allows changing preferences of the current user. Administrators can open this dialog for any user from the Users window. The first page contains general settings - email address and time zone. The second page, only available if the notify feature is enabled, contains the frequency settings for notifications.

There is an 'Enable/Disable Notification' setting for each folder and issue. Folders and issues for which notifications are enabled can be marked with a small overlay icon with an envelope symbol.