Notifications

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

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

A configuration change only takes effect when the configuration cache has been reloaded. You must be an admin or super user to reload the P4 Code Review config cache.

To reload the configuration:

  1. Open the user menu (top-right corner of P4 Code Review).

  2. Select System Information.

  3. Open the Cache Info tab.

  4. Click Reload Configuration.

If changes to the config.php file might have caused the P4 Code Review web interface to become unresponsive, remove the problematic changes from the config.php file, then clear the configuration cache by running this command: rm -f /opt/perforce/swarm/data/cache/module-config-cache.php

P4 Code Review can be configured to provide generic notifications of committed changes in P4 Server, taking the role of a review daemon.

The review daemon ignores protections and notifications are triggered for review paths regardless of the user rights on the paths.

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
        'websocket' => (
            'enabled'    => true,
        ),
    ),

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, P4 Code Review 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 P4 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 P4 Code Review 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 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.

  • 'websocket': Optional item. Use this section to enable browser-based real-time updates for review pages.

    • enabled: Enables the real-time updates feature. Default is false.

    • server_url: Optional override for the WebSocket endpoint used by browsers.

    To learn more, see Real time updates using websocket.

If your P4 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 P4 Code Review's change notifications.

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.

  • 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), multiple roles of users and groups might 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.

Real time updates using websocket

Use this section to enable browser-based real-time updates for review pages.

'notifications' => [
    'websocket' => [
        'enabled'    => true,
        'server_url' => 'wss://your-swarm-host/ws',
    ],
],

  • enabled: Enables the real-time updates feature. Default is false.

  • server_url: Optional override for the WebSocket endpoint used by browsers.

In the default deployment, administrators should normally leave server_url unset. P4 Code Review derives the WebSocket endpoint from the page request and connects to the same origin by using /ws. This avoids extra firewall, VPN, DNS, and certificate configuration.

Set server_url only when you intentionally want browsers to connect to a different host or port, such as a dedicated WebSocket endpoint or a custom reverse-proxy topology.

If the P4 Code Review page is served over HTTPS, browsers must connect to the WebSocket endpoint over wss://.

If a TLS-terminating proxy forwards plain HTTP internally and the application derives ws://, set server_url explicitly or correct the proxy's X-Forwarded-Proto handling.

Origin handling

The WebSocket gateway validates the browser Origin header. In standard deployments, the allow-list is derived automatically from environment.external_url, or from the configured hostname when no external URL is specified.

Users must access P4 Code Review using the same URL configured for the deployment. For example, if users access the site by IP address while the allow-list is configured for a hostname, the WebSocket connection can be established but live updates might not work.

If users access P4 Code Review through a load balancer, CDN, or alternate public hostname, ensure that the externally visible URL matches how users actually reach the site.

After changing the external URL, restart the WebSocket service.

Multi-server note

In current releases, multi-P4 Server deployments work automatically. There is no P4_SERVER_ID setting for administrators to configure for this feature.

Operational note

Enabling notifications.websocket.enabled activates the feature in P4 Code Review but does not start the WebSocket service. If the feature is enabled manually in config.php, ensure that the service is also enabled and started.

After enabling the feature, always verify that the WebSocket service has started successfully. On some installation paths, the service might not be running immediately after initial enablement.

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.