Notifications

This section describes the configurables that can be set for notifications.

Note

For more information on how to delay comment notifications, and configure comment threading, see Comments.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Swarm can be configured to provide generic notifications of committed changes in Helix Core Server, taking the role of a review daemon A program that periodically checks the Helix Core Server machine to determine if any changelists have been submitted. If so, the daemon sends an email message to users who have subscribed to any of the files included in those changelists, informing them of changes in files they are interested in..

Notifications configuration is expressed with a notifications block in the SWARM_ROOT/data/config.php file, similar to the following example (defaults shown):

<?php
    // this block should be a peer of 'p4'
    'notifications' => array(
        'honor_p4_reviews'      => false, // defaults to false
        'opt_in_review_path'    => '',    // required if honor_p4_reviews is true; defaults to ''
        'disable_change_emails' => false, // optional; defaults to false
    ),

If honor_p4_reviews is set to true, then opt_in_review_path must be set to a path somewhere in the depot. This path does not need to point to an actual file that exists, but it must be accessible by all users who want to make use of this functionality. For example:

'notifications' => array(
        'honor_p4_reviews'   => true, 
        'opt_in_review_path' => '//depot/swarmReviews', 
),

If these two values are set, then users can make use of the Perforce review functionality by subscribing to the opt_in_review_path in their user spec. Any user subscribed to that file, will receive notifications for all the other paths they are subscribed to.

We recommend that opt_in_review_path point to a file that does not exist. Ideally, it points to a file that no user is likely to want to create. It must however be in a valid depot.

For example, if a user has the following review paths set in their user spec:

$ p4 user -o asmith
User:	asmith    

Email:	asmith@example.com

FullName:	Alice Smith

Reviews:
        //depot/swarmReviews 
        //depot/main/acme/...
        //depot/main/orion/...
        //depot/dev/asmith/...
        //streams/main

The //depot/swarmReviews means that this user is subscribed to the path set in opt_in_review_path, and therefore will receive notifications.

The subscription lines ending in /..., define which paths in the depot the user is interested in. For example, this user will receive a notification for a change made to //depot/main/acme/foo.txt, but not a change made to //depot/dev/acme/foo.txt.

To receive notifications for stream spec changes in a path, leave the /... off of the end of the subscription line. For example, the //streams/main subscription line means the user will receive a notification for a change made to a stream spec in //streams/main.

To see which users are subscribed to receive notifications you can run p4 reviews <path> against the opt_in_review_path value:

$ p4 reviews //depot/swarmReviews
asmith <asmith@example.com> (Alice Smith)   
bbrown <bbrown@example.com> (Bob Brown)
erogers <erogers@example.com> (Eve Rogers)

To see which users are subscribed to files in a particular changelist, you can run p4 reviews -c <changelist>. Swarm will notify the users who subscribe to both the review of this changelist and the review path, opt_in_review_path.

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, required only if honor_p4_reviews is set. This item specifies a special depot path, which typically would not exist in the Helix Core Server machine. 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 their Reviews: 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 the Reviews: 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. Notifications for reviews and comments will still be sent.

Note

If your Helix Core Server machine 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 and groups. Whilst it is possible for a user and group owner to configure their own settings, it is also possible for the system owner to configure the defaults for all users and groups by modifying the settings in the config.php.

Note

If a group owner is not specified for the group: only users with super privileges can configure group notification settings.
If one or more group owners are specified for the group: only group owners and users with super privileges can configure group notification settings.

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 the user or group who could receive a notification. A user or group can belong to multiple roles, in which case if any of them are set to send a notification, then the user or group will receive a notification.

For example, when a review is voted on (review_vote) , there are a number of roles of users, and groups that could be notified:

Users: the user that voted on the review (is_self), the author of the review (is_author), a user who is a moderator of the project branch the review is in (is_moderator), and a user who is a reviewer of the review (is_reviewer).
Groups: members of a moderator group for the project branch the review is in (is_moderator), and members of a reviewer group for the review (is_reviewer).

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 SWARM_ROOT/data/config.php. These options are in addition to those described above.

<?php
    // this block should be a peer of 'p4'
    'notifications' => array(
        'review_new' => array(
            'is_author' => 'Enabled',
            'is_member' => 'Enabled',
        ),
        'review_files' => array(
            'is_self'      => 'Enabled', 
            'is_author'    => 'Enabled',
            'is_reviewer'  => 'Enabled',
            'is_moderator' => 'Enabled',
        ),
        'review_vote' => array(
            'is_self'      => 'Enabled',                 	 
            'is_author'    => 'Enabled',
            'is_reviewer'  => 'Enabled',
            'is_moderator' => 'Enabled', 
       ),
       'review_required_vote' => array(       
            'is_self'      => 'Enabled',
            'is_author'    => 'Enabled', 
            'is_reviewer'  => 'Enabled',
            'is_moderator' => 'Enabled',
       ),
       'review_optional_vote' => array(
            'is_self'      => 'Enabled',
            'is_author'    => 'Enabled', 
            'is_reviewer'  => 'Enabled',
            'is_moderator' => 'Enabled',
       ),        
       'review_state' => array(
            'is_self'      => 'Disabled',            
            'is_author'    => 'Enabled',
            'is_reviewer'  => 'Enabled',
            'is_moderator' => 'Enabled',
        ),
        'review_tests' => array(
             'is_author'    => 'Enabled',
             'is_reviewer'  => 'Enabled', 
             'is_moderator' => 'Enabled',
        ),
        'review_changelist_commit' => array(
            'is_author'    => 'Enabled',
            '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_opened_issue' => array(
            'is_self'      => 'Enabled',
            'is_author'    => 'Enabled',
            'is_reviewer'  => 'Enabled',
            'is_moderator' => 'Enabled',               
        ),
        'review_join_leave' =>   array (
            'is_self'      => 'Enabled',
            'is_author'    => 'Enabled',
            'is_reviewer'  => 'Enabled',
            'is_moderator' => '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 and group owners, who can configure which notifications they receive.

Notification Roles

The various roles are as follows:

is_self: This role is the user who changed the state of the review.
is_author: This role is the user who was the author of the review.
is_reviewer: This role includes all users and groups 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_moderator: This role includes all users and groups who are listed as being a moderator of the project branch 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 that 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_tests: Automated tests have failed for a review. The first time automated tests pass for a review after a test failure for that review.
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 or group has joined or left a review.