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 SWARM_ROOT/data/config.php file, similar to the following example:

<?php
    // this block should be a peer of 'p4'
    'notifications' => array(
        'honor_p4_reviews'      => false,                 // defaults to false
        'opt_in_review_path'    => '//depot/swarmReview', // 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/...

The //depot/swarmReviews means that this user is subscribed to the path set in opt_in_review_path, and therefore will receive notifications. The rest of the subscription lines define which paths in the depot this user is interested in. Therefore 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 see which users are subscribed to receive notifications, you can run p4 reviews <path> against the opt_in_review_path value, e.g.:

$ p4 reviews //depot/swarmReview
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 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 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 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 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_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.