Slack integration

Note

You must be an admin or super user to integrate Helix Swarm with Slack.
Slack integration matches project ID to project_channels configurable. By default, project ID is the lower case letters of the project name. Ensure that you configure the project ID in the Swarm config.php file. For example, myproject.

This section details how to install, configure, and use the Helix Swarm Slack integration. The Helix Swarm Slack integration lets teams collaborate with Helix Swarm notifications in Slack. The Slack integration posts a message in the configured Swarm project Slack channels each time a change is committed, a review is created, or a review is updated in the project.

To install the Slack integration:

Navigate to https://www.perforce.com/products/helix-swarm/slack-integration.
Click Add to Slack button.
Select the workspace from the top of the page that you wish to integrate Slack with.
Request install permissions from your Application Manager.
Once the Application Manager approves your request, Helix Swarm Slack integration is installed into your selected workspace.
To enable Swarm to work with Slack, edit the Swarm config.php file to include the displayed Slack configuration.

The Swarm config.php file is saved in the SWARM_ROOT/data/ directory.

Note

After the Helix Swarm Slack integration is installed, you must configure the project in the Swarm config.php file. For more information on how to configure a project for Slack integration, see Setup project configurations.

Slack configuration

Add the following Slack configuration to the Swarm config.php file. The Swarm config.php file is saved in the SWARM_ROOT/data/ directory.

'slack' => array(
	     'token' => 'TOKEN',
	     'project_channels' => array(), //See Setup project configurations to configure a project for Slack integration
	     'summary_file_names' => false,
	     'bypass_restricted_changelist' => false,
	     'summary_file_limit' => 10,
	     'user' => array(
		        'enabled' => true,
		        'name' =>'Helix Swarm',
		        'icon' => 'URL',
		        'force_user_header' => false,
		),
),

token

The Slack app provides a token that is used by Swarm.

project_channels

Specifies the Swarm projects ID and Slack channels they post to in the project_channels array. You can configure multiple channels to receive a notification for a project. For more information on how to use project_channels configurable, see Setup project configurations.

summary_file_names

Attaches the file to the original notification message sent to a Slack channel.

bypass_restricted_changelist

Allows Swarm to post notification messages to a Slack channel when a change is committed or a review is created for a restricted changelist, default value is false. For more information about a restricted changelist, see Restricted Changes.

summary_file_limit

Limits the number of files shown in the original notification message sent to a Slack channel, default value is 10.

user

Specifies details about the Swarm user in a Slack notification.

enabled: Forces the Swarm app to use the custom user name. This overrides the Swarm app details.
name: This is the user name shown in the Slack channel when a notification is posted.
icon: This is the avatar icon shown in the Slack channel when a notification is posted, overrides the avatar set in the Swarm app.
force_user_header: The Slack notification shows the user name and avatar only for the first notification by a user. Slack does not apply the user name and avatar to any more notifications from the same user. By default this is set to false.

When set to true, Slack adds the user name and avatar for every notification.

Setup project configurations

This section details how you can configure a project in Helix Swarm to send Slack notifications to a Slack channel.

Important

After project configuration is complete, you must restart the workers and the configuration cache for the updated configuration to take effect.

For more information on how to restart workers, see Workers section.
For more information on how to restart configuration cache, see Reload Configuration button section.

Note

To keep the private projects secure, ensure that the Slack channel you wish to send notifications to is a private channel. For more information on how to add the Helix Swarm application to a private channel, see Add Helix Swarm application to a private channel.

To send notifications to a channel for a project, you must configure the project_channels block as follows:

<?php
    //This block should be a peer of 'p4' 
    'slack' => array(
         'token' => 'xoxb-3875744143189-3925283455653-pxxZoTKz3JqUeDXGd66XFW4D',  
         'project_channels' => array(
              //Project myproject will go into slack channel myproject-channel
              'myproject' => array( 
                  'myproject-channel',
               ),
              //Project with no setting will go to no-project-channel
              '*no-project-channel*' => array(
                  'no-project-channel',
               ),
              //No project on this review/change 
              '*without_project*' => array(
                   'no-link-project',  
               ),
               //All notification get sent here even if we matched above
               '*all*' => array(
                    'all-notifications', 
               ),
        ),
  ),

project_channels

Specify the Swarm projects ID and the Slack channels they post to in the project_channels array. You can configure multiple channels to receive a notification for a project.

Example

Swarm project: myproject
Slack channel: myproject-channel

All notifications for the project myproject will go to the myproject-channel Slack channel.

no-project-channel (optional)

For a project that has no defined project mapping and with *no-project-channel* configurable defined, the Slack notifications are sent to *no-project-channel*. For example, all notifications for the project myproject goes to myproject-channel and similarly all notifications for any other project goes to *no-project-channel*.

without_project (optional)

When *without_project* configurable is defined, it means that no notification is sent if the notification is not associated with a project.

all (optional)

When *all* configurable is defined, all notifications are sent here even if *no-project-channel* and *without_project* options are configured.

Swarm is now configured to send notifications to a Slack channel for a project.

Add Helix Swarm application to a private channel

To send notifications to a private channel you must add the Helix Swarm application to the private channel as follows:

In Slack, open the private channel you would like to send notifications to.
Select your picture or avatar in the top right to open the channel menu.
Select the Integrations tab.
For the Helix Swarm Bot select Add apps to add the application to your private channel.

Helix Swarm can now send notifications to your private channel.

Slack notification trigger

Helix Swarm will post a message on a Slack channel for every commit. This includes each time a change is committed, a review is created, or a review is updated. Any update to a review in Helix Swarm is displayed as a recently occurred activity stream in the associated Slack channel.

Here is a list of actions that will trigger Helix Swarm to send a notification to the associated project Slack channel.

Event	Description
joined	When a user joins the review
left	When a user leaves the review
made their vote required on	When a user's vote has been made required
made their vote optional on	When a user's vote has been made optional
disabled notifications on	When a user disables the notifications for a review
re-enabled notifications on	When a user re-enables the notifications for a review
edited reviewers on	When the reviewers are edited for a review
voted	When a user votes up or down
cleared their vote on	When a user clears their vote
requested further review of	When a user changes the review state to needsReview
requested revisions to	When a user changes the review state to needsRevision
rejected	When a user changes the review state to rejected
archived	When a user changes the review state to archived
approved	When a user changes the review state to approved
updated description of	When a user updates the description of the review
updated files in	When a user updates the files in a review

Slack integration

Slack configuration

token

project_channels

summary_file_names

bypass_restricted_changelist

summary_file_limit

user

Setup project configurations

project_channels

Example

*no-project-channel* (optional)

*without_project* (optional)

*all* (optional)

Add Helix Swarm application to a private channel

Slack notification trigger

no-project-channel (optional)

without_project (optional)

all (optional)