Using Jira applications with Slack

How do I install the Jira Server for Slack app in Jira?

Head to the Atlassian Marketplace to download the Jira Server for Slack app. 

How do I connect the Jira Server for Slack app to my Jira site?

As an administrator, you'll now have a "Slack" navigation item under "Administration → Applications"

From here, select "Set up integration"

Once you access the integration screen, click on "Go to Slack"

You'll then be taken to Slack's App Directory to install the Jira Server Slack app. Click the green "Add to Slack" button for the Slack App and complete Slack's OAuth Process:

Make sure that you are logged as Slack Admin on that workspace, otherwise the button "Add to Slack" will not work, and you will be redirected to Atlassian Marketplace Jira Server for Slack app instead.

Once you complete the OAuth Process in Slack, you'll then see a new configuration page for your integration. Scroll to the bottom to see the two fields you need to complete. First, add your Jira Server web address. Please do not include a trailing / after your web address. Second, you'll want to copy the contents of box #2 back into your Jira setup. 

Paste the credentials into the Jira configuration on the Jira Server side. Click save here, and be sure to click "Submit" in your Slack window (screenshot above).

Once the connection has been setup, you'll receive a success notification from Jira Server in your direct message with Slackbot.

How do I set up a project to post notifications into Slack?

In order to connect to any Slack channels you must first confirm access to your Slack account. On the Slack integration screen in Jira (in both Project and Global Admin), you'll see a link to do this under "Connection status" if you haven't done it yet. Clicking this link will take you to a Slack auth link, which will give the app the ability to view your channels.

Once you've completed this step, you should now see "You're accessing Slack as [Your Name]", and should now be able to select private channels from the drop down. Each user who wants to connect their private channels to the Slack integration will need to do this step.

As a Jira Administrator

In the Applications section of Administration, you'll see "Slack" listed under Integrations. From here, you can connect Jira projects to different slack channels.

Once you've selected a channel, you'll now see the connection to Slack listed below. You will also receive a notification in Slack that Jira notifications have been set up to appear in the channel.

From the configuration menu in Jira, you can filter exactly what notifications you want sent to that room. If you're looking for a more fine tuned filtering style, "Advanced" will enable you to use custom JQL filtering. "Basic" verbosity makes notifications text one-liners, enabling "Extended" verbosity brings in an issue card with details like assignee, status and priority. You can also control restricted comments notifications here.

As a Project Administrator

Project Administrators are able to set up and configure their Slack notifications. In Jira, under Project Settings, you should see a link for the Slack integration. From this page, project administrators can see current Slack channel connections for that project, as well as set up new ones. 

How do I set up personal notifications?

The integration allows you to receive some specific personal notifications in Slack via a direct message from the bot.

1. Go to your Jira user profile page.
2. Click the Tools dropdown, on the top-right corner of the page.
3. Click the item Slack notifications.
   
   
   
4. In the next page, choose the options for when you want to be notified and the Slack workspace of your preference.
   

How do I set up Slack post function notifications?

Post functions are custom actions that are triggered when issues are transitioned to specific workflow statuses.

In order to add a post function to a give status, go to the project settings and click to edit the workflow.

In the new workflow draft, select a transition (gray line with an arrow) such as he one pointing to IN PROGRESS and click Post Functions.

A new tab will open in your browser. Then:

1. Click Add post function link
2. Select Notify Slack option
3. Click Add button
4. You now will see the configuration page where you can setup the notification you need.
5. After editing what you need, click Add.
6. Finally publish the workflow.

The configuration page for the Slack post function is demonstrated in the image below:

The available options are:

• JQL: filter which issues will generate a post function notification.
• Teams: select which workspace will populate the Channels field autocomplete. This does not influence directly the notification, just channel selection.
• Channels: list of channels where the notification will be sent to. You can notify channels in multiple workspaces by switching the Teams field and selecting your preferred channels.
• Message: customize the notification template message. It uses Velocity engine.
• Preview: renders a simplified version of the message that will be generated using dummy data.

The buttons in the message editor will give you a variety of examples on how you can setup your template. All the variables available in the scope of the template are:

$user -> John Smith
$user.name -> jsmith

$issue -> KEY-1
$issue.summary -> An important issue

$project -> My Project
$project.key -> MP
$project.description -> A project description

$status -> Done

$priority -> low

$issueType -> Task

$creator -> John Smith
$creator.name -> jsmith

$assignee -> John Smith
$assignee.name -> jsmith

$reporter -> John Smith
$reporter.name -> jsmith

$action -> Transition

$firstStep -> In Progress
$user.name -> jsmith

$endStep -> Done

// accessing fields
$customFields.fieldName
$customFields.customField_123456
$customFields.get('fieldName')
$customFields.get('customField_123456')
-> My Field: Field Value

// accessing field attributes
$!customFields.fieldName.name 
$!customFields.customField_123456.name
-> My Field
$!customFields.fieldName.value
-> Text field value, or empty if null


// multivalued custom fields
$customFields.fieldName.value.value 
-> Selected field value
$customFields.fieldName.value.toString() 
-> Multivalued field value as string

How do I connect Jira Server to a direct message or multi party direct message?

Unfortunately, it's not possible to set up Jira Server notifications into Slack's direct messages or multi party direct messages.
Alternatively we suggest setting up a private channel and configuring notifications to route there.

How do I connect to a different Slack Workspace?

The Jira Server for Slack app supports the ability to connect to multiple Slack Workspaces, such as in a Slack Enterprise Grid. To do so, on any of the Slack integration pages in Jira, you should see a dropdown of workspaces at the top. To connect to a new workspace, click this and click "Connect to a new team." Please follow the steps from above (How do I connect  the Jira Server app to my Jira site?) to connect your new workspace to this Jira Server instance.

I use multiple Jira Server instances or my instances are behind a firewall. How do I connect them to Slack?

The process for setting up additional Jira Server instances with Slack takes some manual configuration to setup. Please ensure that you follow the below steps perfectly to ensure proper connectivity between your Jira Server instance and Slack. You can repeat this process multiple times for each additional Jira Server instance you have.

To get started, first visit https://api.slack.com/apps?new_classic_app=1. Make sure you create the App with classic scopes as Slack has released a new permission model that's not compatible with this App at this moment.

Slash Commands

Slash commands lets users trigger an interaction with your app directly from the message box in Slack.

1. In your app settings, go to Slash Commands.

2. Click Create New Command.

3. Copy the details of this command over, replacing {{url}} with your Jira Server's URL:
   Command name: /jira_server
   Request URL: https://{{url}}/slack/command
   Usage hint: account, ISSUEKEY-123, help

   Make sure the Command name is not taken by another Slack app in your workspace.

   Once saved, your new slash command should show up in the list.

Now continue to OAuth & Permissions under Features.

OAuth & Permissions

First, we'll click Add New Redirect URL. Set this to http://{{url}}/slack/oauth. Again, replace {{url}} with your Jira Server's URL. Make sure to click Save URLs.

Next, scroll down to the Scopes section. Please add the following scopes:

Double check that you've added all scopes, and click Save.

Bot Users

Click "Bot Users" in the Features navigation bar and click Add a Bot User.

You can set the Display name and default username to whatever you'd like (for instance, "Finance Jira"). Click the Add Bot User button at the bottom.

Event Subscriptions

Click on the Event Subscriptions navigation menu item and toggle Enable Events to the on position.

Add your Request URL https://{{url}}/slack/event and click Change. Please validate that it says "Verified" to ensure your connection between Slack and your Jira Server instance

Now you can subscribe to the following events under "Workspace Events"

Scroll down to Bot Events and add the following events here:

Scroll down to App Unfurl Domains and add your Jira Server domain.

Validate all of the events have been added and click "Save Changes"

Install the App

You can now install your app to your workspace by clicking "Install App" under settings and "Install App to Workspace"

In the Jira config screen, click the "Connect to a new Team" menu item. Then click on "advanced" for connection type. You'll need to copy each of the settings from your Slack app configuration into this screen. Once completed, you'll be able to start using your Jira Server integration.

Can I distribute the Slack App I created to connect my Jira instance to multiple workspaces?

Yes, if you have followed the steps above to created a custom App.

First, your instance needs to have at least one connection with a workspace using the App credentials. This is required so the integration knows the App's client and secret.

Then, find the installation URL in Slack:

1. Find your App in Slack API page.
2. Go to the Manage Distribution under Settings.
3. Activate distribution with other workspaces. You will need to meet Slack's requirements for that.
4. Copy the Sharable URL.
5. Navigate to the shareable URL in a browser. It will trigger an installation flow. 
6. Select the target workspace and proceed.
7. At this point, if your App and the integration are correctly setup, you should be redirected to the integration configuration page in Jira, with the new connection already setup for you.

I'm using Data Center. Does this integration work for me?

Yes, this integration is fully compatible with Jira Data Center.

Which Slash commands does the Jira Server integration support? 

There are the slash commands you can use while interacting the integration:

Can the Jira Server bot provide my team a preview of Jira issues (aka unfurling)?

Of course! When someone writes a message with one or more Jira issue keys (in upper or lower case, so both DEV-36 or dev-36 will work) and the Jira Server bot is present in the conversation, the Jira Server bot will unfurl the message and show a preview of the issues. 

It's also possible to unfurl via using a slash command by typing /jira_server TICKET-ID

How can I create a dedicated channel for an issue?

When looking at a ticket, you should now see a new label for Slack in the right side bar. From here, you can see if a dedicated channel has already been assigned, or assign a new one.

In the drop down, you can select a specific Workspace and then channel. You can also create a new channel directly from this screen. In Slack, you'll get a notification that the ticket was linked to the channel.

All status updates will now be posted to this channel. Any time a user mentions this ticket in a public or private channel that has Jira configured in, that mention will now show up on the Jira issue view.

How can I fine-tune the integration?

We can add Jira system properties to tune specific parts of the integration, as described in the table below:

slack.notification.include.images

slack.client.max.channel.bulk.load

slack.client.list.all.conversations

slack.client.pagination.limit

slack.client.retry.on.connection.failure

slack.client.connect.timeout

slack.client.read.timeout

slack.client.write.timeout

slack.client.retry.count

slack.client.rate.limit.retry.count

slack.client.ping.interval

slack.client.force.http1

slack.client.thread.pool.size

slack.client.queue.size

slack.client.cache.expire.seconds

slack.skip.private.mention

How can I troubleshoot the integration?

Debug logging

You can enable DEBUG level logging though Logging and profiling configuration, using the following packages:

• com.atlassian.plugins.slack
• com.atlassian.jira.plugins.slack

Connectivity from Slack

If you're having connectivity issues between your instance and Slack, double-check the following:

• Slack can reach your instance through a HTTPS-secured URL.
• You have properly saved your base URL without a trailing slash in the Slack App configuration.

• Make sure the paths <baseUrl>/slack/* and <baseUrl>/rest/slack/latest/* are whitelisted in your firewall and security filters in place.

• Make sure those paths allows "anonymous" requests, since incoming requests from Slack use a different authentication mechanism.
• If you're unable to expose your instance, you can still use the integration in notification-only mode, by creating a custom app as described in this page.

You can check the integration is available by making a request to the verification event endpoint. In a bash terminal it can be done with the following command:

curl -X POST \
  https://<jira-base-url>/slack/event \
  -H 'Content-Type: application/json' \
  -H "X-Slack-Request-Timestamp: $(date +%s)" \
  -H 'X-Slack-Signature: any-value' \
  -d '{"challenge": "boo","type": "url_verification"}'

Failure to submit instance URL in Slack

The "Oops" error when submitting your instance URL is known to happen sometimes just after the App has been removed from a workspace, because Slack tries to reach out to the instance before completing the uninstallation.

This issue tends to fix itself within 15 minutes or so as Slack finishes the processing.

Advanced configurations

In order to access the advanced configuration dialog:

1. Go to the Slack configuration in Jira Administration > Applications > Slack or Project Settings > Slack integration.
2. Open on the ... menu.
3. Click Advanced Settings.

In the dialog you can configure:

• Issue preview (unfurling): enable or disable unfurling globally or on a per-project basis.
• Issue preview for externally shared channels: enable or disable unfurling if a channel is shared with another organization. Only available at the global level.
• Hide Slack issue panel: hide the issue panel globally or on a per-project basis. Useful if you have projects open to external users, for instance.
• Restricted comments notifications in dedicated channels: enable sending restricted comments notifications to dedicated channels. Only available at the project level. Useful if you want to override comment restrictions for a specific project e.g. support agents' dedicated channel for a support request they are working on.

Is this supported by Atlassian?

Yes, absolutely. This integration is built and maintained by Atlassian. If you need support, visit support.atlassian.com.