Swarm 2017.2 Guide (August 2017)

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.

<?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',
        ),
    )