Notifications
Swarm can be configured to provide generic notifications of committed changes in the Helix Versioning Engine, taking the role of a review daemon.
Notifications configuration is expressed with a
notifications
block in the
file, similar to
the following example:
SWARM_ROOT
/data/config.php
<?php
// this block should be a peer of 'p4'
'notifications' => array(
'honor_p4_reviews' => false, // defaults to false
'opt_in_review_path' => '//depot/swarm', // optional; defaults to ''
'disable_change_emails' => false, // optional; defaults to false
),
- honor_p4_reviews
-
When set to true, Swarm sends notification emails for every committed change to all users where the change matches one of their
Reviews:
paths. - opt_in_review_path
-
Optional item. This item specifies a special depot path, which typically would not exist in the Helix Versioning Engine. When a path is specified, users must include this path (or a path that contains it) in the
Reviews:
field of their user spec to cause Swarm to send the user a notification for every committed change that matches one of theirReviews:
paths.For example, if the
opt_in_review_path
is set to//depot/swarmReviews
, users can opt-in to Swarm review notifications by adding that path, or a path such as//depot/...
, to theReviews:
field in their user spec. - disable_change_emails
-
Optional item. When set to true, notifications for committed changes, based on the
Reviews:
field and the users and projects you follow, are disabled.
Note
If your Helix Versioning Engine already has a review daemon in operation,
users receive two notifications for Reviews:
paths. You
may want to deprecate the review daemon in favor of Swarm's change
notifications.
Note
Groups have per-group notification settings. See Add a group for details.
Global settings
There are many situations that can result in email
notifications being sent out to users. Whilst it is possible for
a user to configure their own settings, it is also possible for the
system owner to configure the defaults for all users by modifying
the settings in the config.php
.
Each notification consists of an Event
and a
Role
. The Event
is what happened
(for example, a new review was created, a file was submitted) and the
Role
is the role of a user who could receive a
notification. A user can belong to multiple roles, in which case if
any of them are set to send a notification, then the user will receive
a notification.
For example, when a new review is voted on, there are two roles of users who could receive notifications - the author of this review, and reviewers of the review.
Configuration options
By default, all notifications are enabled for all roles. The
system-wide defaults can be changed by adding the following options
into the notifications
block of the
.
These options are in addition to those described above.
SWARM_ROOT
/data/config.php
<?php
// this block should be a peer of 'p4'
'notifications' => array(
'review_new' => array(
'is_author' => 'Enabled',
'is_member' => 'Enabled'
),
'review_files' => array(
'is_author' => 'Enabled',
'is_reviewer' => 'Enabled'
),
'review_vote' => array(
'is_author' => 'Enabled',
'is_reviewer' => 'Enabled'
),
'review_state' => array(
'is_author' => 'Enabled',
'is_reviewer' => 'Enabled'
),
'review_changelist_commit' => array(
'is_reviewer' => 'Enabled',
'is_member' => 'Enabled',
'is_moderator' => 'Enabled',
),
'review_comment_new' => array(
'is_author' => 'Enabled',
'is_reviewer' => 'Enabled'
),
'review_comment_update' => array(
'is_author' => 'Enabled',
'is_reviewer' => 'Enabled'
),
'review_comment_liked' => array(
'is_commenter' => 'Enabled',
),
'review_join_leave' => array (
'is_reviewer' => 'Enabled',
),
)
Each setting can have one of four possible values to either enable or disable notifications of that type. If multiple settings apply to a given event, then a user will receive a notification if any of them are enabled.
- Enabled
-
Notifications for this event and role are enabled, and a user will receive emails by default.
- Disabled
-
Notifications for this event and role are disabled, and a user will not receive emails by default.
- ForcedEnabled
-
Same as for
Enabled
, but this is forced enabled for all users. An individual user is not able to disable this notification type on their settings page. - ForcedDisabled
-
As for
Disabled
, but this is forced disabled for all users. An individual user will not be able to enable this notification type on their settings page.
Unless one of the forced options is used, system wide options can be overridden by individual users, who can configure which notifications they receive.
Notifications are a combination of the event that caused
the notification, and the role of the user who might receive it. So
the review_vote
option is the event
(invoked when a user votes on a review), and it has two roles,
is_author
and is_reviewer
. You
can configure whether the author of the review is notified if the
review is voted up/down, and also whether reviewers of the review
are notified.
Notification Roles
The various roles are as follows.
- is_author
-
This role is the user who was the author of the review.
- is_reviewer
-
This role includes all users who are listed as being a reviewer on the review.
- is_member
-
This role includes all users who are a member of the project in which the event happened.
- is_follower
-
This role includes all users who are followers of the project in which the event happened.
- is_commenter
-
This role is the user who was the author of a comment.
Notification events
An event is the action which causes the notification.
- review_new
-
A new review has been created.
- review_files
-
Files have been added to a review.
- review_vote
-
A user has voted on a review.
- review_state
-
The status of a review has been changed.
- review_changelist_commit
-
Files on a review have been committed.
- review_comment_new
-
A comment has been added to a review.
- review_comment_update
-
A comment on a review has been updated.
- review_comment_liked
-
A user has liked a comment.
- review_join_leave
-
A user has joined or left a review.