Slack-Jira Add-on

Administration Manual

Slack-Jira Add-on is a perfect tool to make your distributed work environment more productive, effective and rewarding.

Empower a Team to manage the workflow directly from the group chat, receive notifications about work advancements, improve collaboration and control the progress from the finger-tips.

Slack-Jira plugin lets you combine the best from both domains - strict, organized handling of Jira tickets and dynamic, human-centric Slack chats. Environment for software projects has never been so handy, intelligible and fun.

Try the Slack-Jira Add-on in three easy steps:

https://marketplace.atlassian.com/apps/1216557/slack-jira-integration

This is a part of Slack-Jira guides that unveil all features and related use cases for building effective workflows. Full set of documentation includes:

 

Bitband Team recommends get a grasp of these manuals to shorten deployment time and smooth adoption.

Table of Contents

1. Installation

 

Slack-Jira Add-on allows quick and simple installation from Atlassian marketplace just in three single steps. The process can be initiated by visiting the official marketplace page:

https://marketplace.atlassian.com/apps/1216557/slack-jira-integration

 

Express installation description is available in the "Slack-Jira Quick Tour" page.

Here is an additional approach to install the Add-on directly from Jira:

  1. Log into Jira instance with administrative privileges account.

  2. In the Jira Administration menu select Add-ons item.

  3. Search for “Slack Jira Integration” by Bitband

  4. Initiate installation by clicking on “Install” and proceed by accepting a license agreement.

Once the installation routine is over it’s possible to proceed to integration stage.

2. Slack-Jira Integration in Details

 

Short and straight-forward description of this process is available in the Slack-Jira Quick Tour page.

This comprehensive overview of the procedures helps to conduct proper systems pairing in complex environments.

2.1. Prerequisites

 

BitBand strongly recommends to perform the following actions for proper integration

  1. Setup additional Slack account with administrative privileges (“Slack admin” type) and use it for Slack and Jira binding.

  2. Bind Slack and Jira using account with administrative privileges in Jira environment. It doesn’t have to be a separate Jira account, just with administrative rights.

Once these stages are successfully completed the integration can be initiated

2.2. Slack Authorization

 

To create a bridge over Jira and Slack open Jira Settings and perform these easy steps:

  1. Open “System” item and scroll down to “Slack integration” menu.

  2. Open “Slack Integration” menu item.

  3. Click on “Sign with Slack” button.

  4. In pop-up browser’s window select Slack workspace you wish to create a connection with.

  5. Confirm authorization by clicking “Allow” button on the center bottom of the pop-up window.

Once pop-up windows is automatically closed there will be a “Welcome” page for “Slack-Jira Integration” Add-on displayed.

Validate connected Slack workspace (1) and Slack Account id (2) listed on the “Configure” tab on the center of the screen.

It’s possible to change a connection to Slack workspace or Slack account by selecting “Disconnect” option from the Action menu and repeating the steps described in this chapter.

Here is the video tutorial about integration of these two systems which is complementary to step-by-step instructions above.

Double click to switch it to the full screen and watch in all details.

3. Customizing Slack-Jira Notifications

 

The Add-on provides flexible options for customizing notifications.

Settings described in this section are only accessible if Slack was successfully connected to “Slack Integration” Add-on.

 

Current version of Slack-Jira Add-on provides forward synchronization of content between the parties. It means if the channel was deleted directly from Slack the Slack-Jira won’t be getting appropriate information and will try to send notifications to it complying with existing set of rules.

 

Another peculiarity arises from Slack channel type. Slack-Jira Add-on is not able to obtain information about Slack private channels nor to create private channels from the Add-on interface.

However, if the application will contain any rule for archived Slack channel and corresponding trigger fires then a new notification will unarchive the channel.

 

Overall customization process is straightforward and anyone familiar with the basic conceptions of Jira and Slack will be able to setup the whole environment in minutes. The overall process can be observed in this 5 minutes video. (Double click to switch it to the full screen and watch in all details.)

Slack Jira Integration add-on by Bitband

In the chapters below one can find an extensive description about all types of notifications and related options.

3.1. System Channels

 

This part of the application can be found following the next path:

“Jira Settings”  → “System” → “Slack Integration” → “System channels” → create or pick a channel.

The following managing options are available for the System notifications:

 

  • Create - originates a notification once all required values are indicated.

  • Edit - provides a way to alter some of the existent channel parameters.

  • Remove - removes a binding from Slack-Jira Add-on. Corresponding Slack channel will NOT be removed.

System level triggers will track changes for all Jira projects and issues. Notifications of these changes will be sent to the Slack channels and users in accordance with the rest of configuration options set for a current notification.

In the video tutotial below one can find a short and comprehensive description on system level notifications creation.

Slack-Jira Add-on provides the variety of choices to fine-tune information flows.

3.1.1. System Channel Parameters

 

The following managing options are available for the System notifications:

 

  • Create - originates a notification once all required values are indicated.

  • Edit - provides a way to alter some of the existent channel parameters.

  • Remove - removes a binding from Slack-Jira Add-on. Corresponding Slack channel will NOT be removed.

System level triggers will track changes for all Jira projects and issues. Notifications of these changes will be sent to the Slack channels and users in accordance with the rest of configuration options set for a current notification.

Slack-Jira Add-on provides the variety of choices to fine-tune information flows.

  • Channel name - defines a new channel for notifications forwarding. Channel with entered name will be created in connected Slack workspace. Name length should be less or equal to 20 symbols. It can only contain lowercase letters, numbers, hyphens, and underscores.

Option is not available if “Existing channel” or “Direct channel” option was set.

  • Existing channel - provides a list of channels from connected Slack workspace to pick from.

Option is not available if “Direct channel” option was set.

  • Direct channel - allows to send notifications directly to a Slack user.

Option is not available if “Existing channel” option was set.

“Channel name” or “Existing channel” or “Direct channel” setting should be set for system notification creation to be finished.

These three options are mutually exclusive - for example: “Channel name” option and its value will be ignored if “Existing channel” or “Direct channel” option was selected.

  • Channel topic - specifies a subject for a channel. Current topic for existent channel will be updated to the specified value.

“Direct channel” type doesn’t comply with this logic and topic is not used.

It’s possible to update Channel topic from channel editing option or directly from Slack. In the latter case corresponding field in Slack-Jira Add-on won’t be synchronized backwards.

  • Invite Slack users - there is an option to automatically invite other users for newly created or existing channels.

This does not have an effect on personal (Direct) channels type.

3.1.2. System Channel Filtering Options

 

Notification scope can be limited by applying filtering options available in Jira.

Slack-Jira Add-on allows to switch between the next filtering modes:

  • No filter - triggers won’t include any additional selection. All messages will be sent.

  • Basic filter - allows to indicate what notifications match to Jira options and values will be sent.

  • Advanced JQL filter - allows to specify filtering using Jira built-in query language.

These modes are mutually exclusive. Even if filtering parameters were indicated but mode was switched to another one (i.e. from “Basic filter” to “Advanced JQL filter”) then none of the grayed-out parameters will be applied.

Basic filters include the following Jira fields and their respective values to select from:

  • Priority

  • Resolution

  • Status

  • Type

  • Assignee

  • Reporter

Slack-Jira Add-on inherits custom statuses for these fields and provides a way to use them along with the standard values  for notifications filtering.

Advanced JQL filter provides a powerful interface to manipulating Jira options. Full description of JQL opportunities and related parameters can be found on official Jira web-page:  https://confluence.atlassian.com/jirasoftwarecloud/advanced-searching-764478330.html

Once necessary trigger parameters in all page tabs are set a notification can be activated using the “Create” button. In editing mode current changes can be committed using “Save” button.

3.1.3. System Channel Events Switch

 

Along with issues parameters filtering the Slack-JIra Add-on provides opportunity to limit notifications by indicating about what events the notifications should be sent. There are next event categories and statuses available:

  • Issue (created, deleted, updated, assigned, reopened, moved, done).

  • Worklog (created, changed, deleted).

  • Comment (created, updated, deleted).

  • Project (created, updated, deleted).

  • Project version (release, unreleased, created, updated, merged, deleted).

  • User (created, updated, deleted).

  • Sprint (created, updated, deleted, started, closed).

  • Board (created, updated, deleted, configuration changed).

If events and the rest of necessary trigger parameters in all other tabs are adjusted then a notification can be activated using “Create” button. In editing mode the changes can be stored using “Save” button.

3.1.4. System Channel Notifications Options

 

Slack-Jira Add-on provides additional settings to manipulate information flow for System level notifications.

  • Force all notifications to this channel regardless of project and issue

This option allows to override “Filters” and “Events” scopes and forward all messages to a current channel.

  • Create notifications in Slack thread message

This configuration item toggles message forwarding in a thread flow inside a current channel.

Due to Slack design this item doesn’t have any impact on Direct channels (messages directly to a user).

All changes to this group of settings should be confirmed by clicking on “Save” button.

For a new notification the “Create” button should be used if all other pertinent parameters were adjusted.

3.1.5. System Channel Message Format

 

A descriptiveness of the notifications can be adjusted in this section of the menu.

It allows to select Jira fields and their statuses to be sent in a message. More than 65 JIra fields available for reporting.

Single notification can carry on up to 10 fields. If a higher number will be selected then several notifications for a single event will be generated.

Message format change should be committed by clicking on “Save” or “Create” button depending on activity type.

3.2. Project Channels

 

This part of the application can be found following the next path:

“Jira Settings”  → “System” → “Slack Integration” → “Project channels” → create or pick a channel.

The following managing options are available for the Project notifications:

 

  • Create - originates a notification once all required values are indicated.

  • Edit - provides a way to alter some of the existent channel parameters.

  • Remove - removes a binding from Slack-Jira Add-on. Corresponding Slack channel will NOT be removed.

Project level triggers will track changes only for the selected projects and related issues.

Notifications of these changes will be sent to the Slack channels and users in accordance with the rest of configuration options set for a current notification.

Slack-Jira Add-on provides the variety of choices to fine-tune information flows.

3.2.1. Project Channel Parameters

 

This section allows to specify where Slack-Jira app should sent notifications. It’s possible to deliver messages to a new channel, existing channel, or directly to a Slack user.

  • Project - specifies existing Jira project to track changes on. Default value inherits a name of the first project alphabetically.

  • Channel name - defines a new channel for notifications forwarding. Channel with entered name will be created in connected Slack workspace. Name length should be less or equal to 20 symbols. It can only contain lowercase letters, numbers, hyphens, and underscores.

Option is not available if “Existing channel” or “Direct channel” option was set.

  • Existing channel - provides a list of channels from connected Slack workspace to pick from.

Option is not available if “Direct channel” option was set.

  • Direct channel - allows to send notifications directly to a Slack user.

Option is not available if “Existing channel” option was set.

“Channel name” or “Existing channel” or “Direct channel” setting should be set for project notification creation to be finished.

These three options are mutually exclusive - for example: “Channel name” option and its value will be ignored if “Existing channel” or “Direct channel” option was selected.

  • Channel topic - specifies a subject for a channel. Current topic for existent channel will be updated to the specified value.

“Direct channel” type doesn’t comply with this logic and topic is not used.

It’s possible to update Channel topic from channel editing option or directly from Slack. In the latter case corresponding field in Slack-Jira Add-on won’t be synchronized backwards.

  • Invite Slack users - there is an option to automatically invite other users for newly created or existing channels.

This does not have an effect on personal (Direct) channels type.

3.2.2. Project Channel Filtering Options

 

Notification scope can be limited by applying filtering options available in Jira.

Slack-Jira Add-on allows to switch between the next filtering modes:

  • No filter - triggers won’t include any additional selection. All messages will be sent.

  • Basic filter - allows to indicate what notifications match to Jira options and values will be sent.

  • Advanced JQL filter - allows to specify filtering using Jira built-in query language.

These modes are mutually exclusive. Even if filtering parameters were indicated but mode was switched to another one (i.e. from “Basic filter” to “Advanced JQL filter”) then none of the grayed-out parameters will be applied.

Basic filters include the following Jira fields and their respective values to select from:

  • Priority

  • Resolution

  • Status

  • Type

  • Assignee

  • Reporter

Slack-Jira Add-on inherits custom statuses for these fields and provides a way to use them along with the standard values  for notifications filtering.

Advanced JQL filter provides a powerful interface to manipulating Jira options. Full description of JQL opportunities and related parameters can be found on official Jira web-page:  https://confluence.atlassian.com/jirasoftwarecloud/advanced-searching-764478330.html

Once necessary trigger parameters in all page tabs are set a notification can be activated using the “Create” button. In editing mode current changes can be committed using “Save” button.

3.2.3. Project Channel Events Switch

 

Along with issues parameters filtering the Slack-JIra Add-on provides opportunity to limit notifications by indicating about what events the notifications should be sent. There are next event categories and statuses available:

  • Issue (created, deleted, updated, assigned, reopened, moved, done).

  • Worklog (created, changed, deleted).

  • Comment (created, updated, deleted).

  • Project (created, updated, deleted).

  • Project version (release, unreleased, created, updated, merged, deleted).

If events and the rest of necessary trigger parameters in all other tabs are adjusted then a notification can be activated using “Create” button. In editing mode the changes can be stored using “Save” button.

3.2.4. Project Channel Notifications Options

 

Slack-Jira Add-on provides additional settings to manipulate information flow for Project level notifications.

  • Do not send notifications to system channels

The option allows to suppress messaging to system-level channels about events in a current project. It won’t have an effect if the setting “Force all notifications to this channel regardless of project and issue” was activated in a system-level channel.

  • Force all notifications to this channel regardless of issue channel setting

This option allows to override “Filters” and “Events” scopes for the project- and issue- level notifications and forward all reports to a current channel.

  • Create notifications in Slack thread message

This configuration item toggles message forwarding in a thread flow inside a current channel.

Due to Slack design this item doesn’t have any impact on Direct channels (messages directly to a user).

All changes to this group of settings should be confirmed by clicking on “Save” button.

For a new notification the “Create” button should be used if all other pertinent parameters were adjusted.

 

3.2.5. Project Channel Message Format

A descriptiveness of the notifications can be adjusted in this section of the menu.

It allows to select Jira fields and their statuses to be sent in a message. More than 65 JIra fields available for reporting.

Single notification can carry on up to 10 fields. If a higher number will be selected then several notifications for a single event will be generated.

Message format change should be committed by clicking on “Save” or “Create” button depending on activity type.

 

3.3. Issue Channels

This part of the application can be found following the next path:

“Jira Settings”  → “System” → “Slack Integration” → “Issue channels” → create or pick a channel.

However, notifications of this type can be created directly from an issue. To access notification generating dialog open a Jira issue, click on “Activity” drop-down menu and pick “Slack” option.

It’s possible to manage (create, edit, remove) one or several channels for issue-level notifications from this menu.

All created notification triggers will be listed in the “Issue channels” tab on the “Slack Integration” page. It’s also possible to reach editing mode for existent channels from this menu.

The following managing options are available for the Issue-level notifications:

 

  • Create - originates a notification once all required values are indicated.

  • Edit - provides a way to alter some of the existent channel parameters.

  • Remove - removes a binding from Slack-Jira Add-on. Corresponding Slack channel will NOT be removed.

  • Turn on/off - allows to manipulate an activity of all existent notifications by altering the option in the “Issue channels” menu - “Allow Slack notifications from individual JIRA issues”

Issue level triggers will track changes only for the selected issue and related fields. Brief descriptive video shows the generic outline of this routine.

Notifications of these changes will be sent to the Slack channels and users in accordance with the rest of configuration options set for a current notification. Slack-Jira Add-on provides the variety of choices to fine-tune information flows.

3.3.1. Issue Channel Parameters

 

Issue-level notification provides next options:

  • Channel name - defines a new channel for notifications forwarding. Channel with entered name will be created in connected Slack workspace. Name length should be less or equal to 20 symbols. It can only contain lowercase letters, numbers, hyphens, and underscores.

Option is not available if “Existing channel” or “Direct channel” option was set.

  • Existing channel - provides a list of channels from connected Slack workspace to pick from.

Option is not available if “Direct channel” option was set.

  • Direct channel - allows to send notifications directly to a Slack user.

Option is not available if “Existing channel” option was set.

“Channel name” or “Existing channel” or “Direct channel” setting should be set for project notification creation to be finished.

These three options are mutually exclusive - for example: “Channel name” option and its value will be ignored if “Existing channel” or “Direct channel” option was selected.

  • Channel topic - specifies a subject for a channel. Current topic for existent channel will be updated to the specified value.

“Direct channel” type doesn’t comply with this logic and topic is not used.

It’s possible to update Channel topic from channel editing option or directly from Slack. In the latter case corresponding field in Slack-Jira Add-on won’t be synchronized backwards.

  • Invite Slack users - there is an option to automatically invite other users for newly created or existing channels.

This does not have an effect on personal (Direct) channels type.

For editing purposes it’s possible to access issue channel parameters as from “Slack Integration” menu (“Jira Settings”  → “System” → “Slack Integration” → “Issue channels” → edit a channel) as well as from the Jira issue itself (pick Jira issue  → “Activity” → “Slack” → “Channels” → edit a channel).

3.3.2. Issue Channel Events Switch

 

Along with issues parameters filtering the Slack-JIra Add-on provides opportunity to limit notifications by indicating about what events the notifications should be sent. For the issue-level notifications next event categories and statuses are available to alter:

  • Issue (created, deleted, updated, assigned, reopened, moved, done).

  • Worklog (created, changed, deleted).

  • Comment (created, updated, deleted).

 

Additional events triggers are available in the “System channels” or “Project channels” types of notification.

If events and the rest of necessary trigger parameters in all other tabs are adjusted then a notification can be activated using “Create” button. In editing mode the changes can be stored using “Save” button.

3.3.3. Issue Channel Notifications Options

 

Slack-Jira Add-on provides additional settings to manipulate information flow for Issue level notifications.

  • Do not send notifications to system channels

The option allows to suppress messaging to upper level channels (system, project) about events in a current issue. It won’t have an effect if any or both of the settings “Force all notifications to this channel regardless of project and issue” and “Force all notifications to this channel regardless of issue channel settings” was activated in a system-level and/or project-level channels.

  • Create notifications in Slack thread message

This configuration item toggles message forwarding in a thread flow inside a current channel.

Due to Slack design this item doesn’t have any impact on Direct channels (messages directly to a user).

All changes to this group of settings should be confirmed by clicking on “Save” button.

For a new notification the “Create” button should be used if all other pertinent parameters were adjusted.

3.3.4. Issue Channel Message Format

 

A descriptiveness of the notifications can be adjusted in this section of the menu.

It allows to select Jira fields and their statuses to be sent in a message. More than 65 JIra fields available for reporting.

Single notification can carry on up to 10 fields. If a higher number will be selected then several notifications for a single event will be generated.

Message format change should be committed by clicking on “Save” or “Create” button depending on activity type.

4. Advanced Slack-Jira Notification Capabilities

 

In certain environments a Company might be looking for additional functionality to make workflows even more flexible and precise. Here are a couple of additional notification functions which are useful for certain use cases.

4.1. Notification to Private Channels

 

Slack provides an option to conduct non-public discussions with a limited access to the chat from other users. Information from Jira might also be reported in a secure way to the private channels.

There are a number of peculiarities related to data streamlining to these channels which are described here.

Current version of Slack-Jira app doesn’t allow to create private Slack channels directly from the Add-on interface. To attach private Slack channel one should manually create such a chat in Slack and then specify its’ name in the “Channel name” field.

Slack channel value should not exceed 20 characters to be successfully accepted as a name by the Add-on.

It’s not possible to re-use any Slack channel that was previously added over Add-on interface and converted to a private type. Once converted the notifications won’t be able to reach the chat.

Private channels are not visible in the “Existing channel” or “Direct channel” menus.

5. Configuration and Operability Validation

 

Administration options walk-through allows to setup and customize Slack-Jira installation to the particular work environment and Company’s taste.

 

New system’s configuration should be validated from both sides:

  • Data flow and commands from Jira to Slack;

  • Control flow from Slack to Jira;

 

The first item can be tested by manipulating Jira issues and checking the information passes to Slack.

The second item can be validated by using commands from Slack to Jira. They are described in the “Slack-Jira Add-on User Manual”.