WebIssues/Email Notifications

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

Required Changes

The following changes need to be done in the database:

• email field for each user
• table for user-to-folder relations

As mentioned in the [[../../Documentation/Protocol|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.

But specifying user's email is not necessary unless the user uses notifications and there's no need to display the email address to everyone. So we can treat email address as part of user preferences, not the actual user data. Users can only access and modify their own preferences (except for server administrators who are allowed to do everything).

Preferences

Current preferences can be accessed using the following command:

 LIST PREFERENCES userId

   F 'name' 'value'

A single field can be changed using:

 SET PREFERENCES userId 'name' foo@bar.com'

   OK

Fields are identified by name (for example 'email'). This allows adding new fields without breaking the protocol. Generally both name and value can be any string, but 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). The userId is used to allow administrator to view other user's preferences, but normally it will be the current user's id.

The client can check the server version to see which fields can be used and will ignore fields that it doesn't know. This allow to work with both newer and older server versions (as long as the protocol version is the same).

Besides the email address there can be more settings like:

• enabling/disabling notifications globally
• email frequency (immediate, daily summary, etc.)
• notification type (all changes, only new issues, only changes to issues created by me, etc.)

Further details are TBD.

Notifications

Current notifications can be accessed using the following command:

 LIST NOTIFICATIONS

   N folderId

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

 SET NOTIFICATION folderId status

   OK

The status field can be 0 or 1. There could also be individual notification type per each folder, in that case status can be a set of flags and will be returned in the list of notifications. This is TBD.

Sending Emails

The actual sending is done by PHP code on the server via the mail() function. It can be done during each change (in that case response time can be slower) or periodically in the background (in that case a cron job and an additional table is required). This is TBD.

Notifications are configured using the configuration file:

• enabled/disabled
• From field
• Subject field
• additional fields if needed
• path of the body template

The email template can be a simple text file by default located in a templates subdirectory of the server. It will have placeholders for user name, folder name, issue name etc.

Yes, I know we can use Smarty. It's just that the Smary code is several times bigger than the WI server itself :). Besides I don't think we will need much logic here. But this is TBD of course.

Note that since notifications can be disabled by server administrator, the client must have a way of checking if notifications are available. This can be done using a LIST SETTINGS command which would return a list of fields similar to LIST PREFERENCES.

User Interface

For regular user it's just a 'Change Preferences' dialog (accessible via Tools menu) and an 'Enable/Disable Notification' setting for each folder (perhaps with some additional options). Folders for which notifications are enabled can be marked with a small overlay icon just like for folder watches.

Administrator should be able to 'Change Preferences' for each individual user from the users list.