Open topic with navigation

Notifications

Swarm can be configured to provide generic notifications of committed changes in Helix Server, taking the role of a review daemonA review daemon is a program that periodically checks the Helix 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:

<?php
    // this block should be a peer of 'p4'
    'notifications' => array(
        'honor_p4_reviews'      => false,                  // defaults to false
        'opt_in_review_path'    => '//depot/swarmReviews', // 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:	[email protected]

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.

For example, 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 <[email protected]> (Alice Smith)   
bbrown <[email protected]> (Bob Brown)
erogers <[email protected]> (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 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.

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.

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.