Difference between revisions of "WebIssues/Email Notifications"

From MiMec
Jump to: navigation, search
(New page: 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 Ch...)
 
m
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
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.
+
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 ==
 
== Required Changes ==
  
−
The following changes need to be done in the database:
+
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: <tt>LIST USERS</tt>, <tt>ADD USER</tt> etc.
−
* email field for each user
+
 
−
* table for user-to-folder relations
+
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 <tt>cron.php</tt> 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'
  
−
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: <tt>LIST USERS</tt>, <tt>ADD USER</tt> etc.
+
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:
  
−
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).
+
;<tt>notify</tt>
 +
:enables the <tt>notify-frequency</tt> preference and the commands related to notifications.
  
 
=== Preferences ===
 
=== Preferences ===
Line 17: Line 50:
 
   LIST PREFERENCES userId
 
   LIST PREFERENCES userId
  
−
     F 'name' 'value'
+
     P 'name' 'value'
  
 
A single field can be changed using:
 
A single field can be changed using:
  
−
   SET PREFERENCES userId 'name' foo@bar.com'
+
   SET PREFERENCE userId 'name' 'value'
  
 
     OK
 
     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.
+
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:
 +
 
 +
;<tt>email</tt>
 +
:address used for sending notifications; must be a valid email address
 +
;<tt>timezone</tt>
 +
: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".
 +
;<tt>notify-frequency</tt>
 +
:frequency and time of notifications (only available if the 'notify' feature is enabled)
 +
 
 +
The definition of <tt>notify-frequency</tt> must follow the same rules as attribute definitions, i.e. it consists of a type and zero or more metadata. The allowed types are:
  
−
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).
+
;<tt>IMMEDIATELY</tt>
 +
:notifications are sent as soon as possible
 +
;<tt>DAILY hour="<i>hh</i>:<i>mm</i>"</tt>
 +
:notifications are sent every day at given time
 +
;<tt>WEEKLY day=<i>d</i> hour="<i>hh</i>:<i>mm</i>"</tt>
 +
:notifications are sent weekly at given day (from 0 - Sunday to 6 - Saturday) and time
  
−
Besides the email address there can be more settings like:
+
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.
−
* 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.
+
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 <tt>timezone</tt> field.
  
 
=== Notifications ===
 
=== Notifications ===
  
−
Current notifications can be accessed using the following command:
+
Current notifications can be listed using the following command:
  
 
   LIST NOTIFICATIONS
 
   LIST NOTIFICATIONS
  
−
     N folderId
+
     F folderId
 +
    I issueid
  
 
Notification for a folder can be enabled or disabled using the following command:
 
Notification for a folder can be enabled or disabled using the following command:
  
−
   SET NOTIFICATION folderId status
+
   NOTIFY FOLDER folderId status
  
 
     OK
 
     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.
+
Notification for an issue can be set using an analogous command:
  
−
== Sending Emails ==
+
  NOTIFY ISSUE issueId status
 +
 
 +
    OK
  
−
The actual sending is done by PHP code on the server via the [http://pl.php.net/manual/en/function.mail.php 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.
+
The status can be 1 (enabled) or 0 (disabled).
  
−
Notifications are configured using the configuration file:
+
== Sending Emails ==
−
* 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 <tt>templates</tt> subdirectory of the server. It will have placeholders for user name, folder name, issue name etc.
+
The actual sending is done using the selected mail engine. The default engine uses the the built-in [http://pl.php.net/manual/en/function.mail.php mail()] function. The SMTP engine uses the [http://phpmailer.codeworxtech.com/ PHPMailer] class which can communicate with any external SMTP server.
  
−
:''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.''
+
The template of the email is a simple text file located in a <tt>templates</tt> 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.
  
−
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 <tt>LIST SETTINGS</tt> command which would return a list of fields similar to <tt>LIST PREFERENCES</tt>.
+
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 ==
 
== 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.
+
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.
  
−
Administrator should be able to 'Change Preferences' for each individual user from the users list.
+
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.

Latest revision as of 20:52, 26 June 2010

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.

Retrieved from "https://wiki.mimec.org/index.php?title=WebIssues/Email_Notifications&oldid=229"