Comment mentions

This section describes how to customize how Swarm treats user @mentions and group @@mentions in auto-complete drop-downs, comments, changelists, and review descriptions.

Note
  • @mentions for users is only available for Swarm 2017.1 and later.
  • @@mentiions for groups is only available for Swarm 2017.3 and later.
  • If your Helix Core Server is configured to be case sensitive this will also apply to the names specified in your exclude lists.
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.

By default:

  • When a user uses an @mention or @@mention in a comment, Swarm will auto-complete for all Swarm users or groups respectively.
  • When a user edits the reviewers on a review, Swarm will auto-complete for all Swarm users and groups.
  • When a user edits the author of a review, Swarm will auto-complete for all Swarm users.

This behavior can be fine tuned with the mentions configuration block in the SWARM_ROOT/data/config.php file. For example:

<?php
    'mentions' => array(
        'mode' => 'global',
        'user_exclude_list' => array('super', 'swarm-admin'),
        'group_exclude_list' => array('testers', 'writers'),
    ),

  • mode controls the scope of the auto-complete dropdown that is shown when the user starts typing an @mention or an @@mention in a review comment:

    • global displays all users/groups in Swarm, this is the default value
    • projects: only displays project members (users and groups) in the auto-complete list
    • disabled disables the auto-complete drop down so that it is not displayed

  • user_exclude_list users in the exclude list:

    • are not suggested when you @mention them in a comment, edit reviewers, or edit the author in Swarm.
    • are not added to the review if you manually add them as an @mention in a Swarm comment or a review description.
    • are not added to the review if they are @mentioned in a changelist description.
    • cannot be added to the review with the Swarm API.
      • Tip

      When you add a user to the exclude list:

      • the user is not removed from any reviews that they are already on.
      • the user will stop receiving email notifications for those reviews.

  • group_exclude_list groups in the exclude list:

    • are not suggested when you @@mention them in a comment or edit reviewers in Swarm.
    • are not added to the review if you manually add them as an @@mention in a Swarm comment or review description.
    • are not added to the review if they are @@mentioned in a changelist description.
    • cannot be added to the review with the Swarm API.
      • Tip

      When you add a group to the exclude list:

      • the group is not removed from any reviews that it is already on.
      • the group members will stop receiving email notifications for those reviews.
      • if a member of an excluded group is also on the review as a user or as a member of another group, that user will continue to receive emails for the review.

Regular expressions in exclude lists

Regular expressions can be used in user and group exclude lists but they should be used with care to avoid accidentally excluding the wrong users or groups. Swarm exclude lists can use any valid PHP regular expression but not all of them make sense for the exclude lists.

Note

Swarm adds a ^ character before your regular expression and a $ character after it. For example: ^your-reg-ex-pattern$ You must take this into account when constructing your regular expressions.

Tip
  • You can test the results of your regular expressions before using them, see regular expressions 101.
  • Case sensitivity for regular expressions in the exclude lists is determined by the case sensitivity setting of the Helix Core Server.

Regular expression examples

Useful regular expressions are shown below:

Exact match only:

'super' only users or groups named super are excluded.

Beginning with:

'admin.*' users or groups beginning with admin are excluded.

For example: the following would be excluded:

administrator, admin-group, and admin

Ending with:

'.*admin' users or groups ending with admin are excluded.

For example: the following would be excluded:

test-admin, buildadmin, and admin

Ending with digits

'.*[0-9]+' users or groups ending with digits are excluded.

For example: the following would be excluded:

test03, admin-10, tester_123456

Containing:

'.*admin.*' users or groups that contain admin are excluded.

For example: the following would be excluded:

test-admin, buildadmin, administrator, admin-group, and admin