Microsoft Teams for Jira Data Center documentation
To start using Microsoft Teams for Jira Data Center, you need to install both of the following apps:
- Jira Data Center app in Microsoft Teams (installed from Microsoft Teams Apps menu)
- Microsoft Teams for Jira Data Center in your Jira instance (installed from Atlassian Marketplace)
Note: Jira Data Center connector doesn’t require Jira app (add-on) installation, it should be configured manually by Jira administrator.
App 1: Installing into Microsoft Teams
Before you begin
Here are the prerequisites for installing this app:
- Microsoft Office 365. It should be Office 365 with Business license or Enterprise Office 365. Your IT admin also has to enable Microsoft Teams in Office 365.
- Allow external apps in Microsoft Teams for Office 365 should be set to On. Your IT admin has to enable it in the Admin center by going to Settings > Services & add-ins > Microsoft Teams > Apps > Allow external apps in Microsoft Teams > On. Note that after enabling the external apps in Office365, synchronization may take several hours.
Steps
- In your Microsoft Teams, go to "Apps” menu in bottom-left corner.
- Search for “Jira Data Center”.
- Select the tile and follow the installation dialog.
The installation provides the following capabilities within Microsoft Teams:
- Connector
- Messaging Extension
- Bot
- Team and personal tabs
Connector
Connector provides one-way communications from Jira Data Center to Microsoft Teams via webhooks. You can add connector to your Microsoft Teams channel from the channel menu:
On the connector configuration page, you will see the instructions and the webhook URL. Following the instructions, you need to create a webhook from your Jira Data Center instance. This can be done from Administration > System > Webhooks. Paste the webhook URL from connector configuration into Jira webhook and save. Finish by adding the connector in Microsoft Teams. You should receive a channel notification from connector telling that the connector has been added.
Jira ID
Jira ID is a unique identified that is generated after installing Microsoft Teams for Jira Data Center on your Jira instance. If this app is installed and you have the admin permissions, you'll see the Jira ID at the bottom of the app's configuration page. If you don't have the right permissions, contact your Jira admin to provide you with the Jira ID.
Messaging Extension
You need to have the Microsoft Teams for Jira Data Center app installed in your Jira instance for this capability to work.
All your messaging extensions can be open from the bottom of the compose box. There are some native messaging extensions, such as Emoji, Giphy, and Sticker. Choose the More Options (...) button to see Jira Data Center and other messaging extensions. You can also pin Jira Data Center messaging extension so that you don’t have to select it from options menu every time.
Once you open the messaging extension, click “Sign In” to connect to your Jira instance. You will be asked to provide Jira ID.
When you paste the correct Jira ID, your next step will be to enter your Jira login credentials for authentication. After that, in the messaging extension you should see the search field and the list of recent issues from Jira. You’re all set!
Bot
Bot is another capability of Microsoft Teams. The Jira Data Center bot will be your personal assistant when working with Jira.
To start your interaction with the bot, select Open in front of “Bot” on installation screen, or simply search “Jira Data Center” in your main search area of Microsoft Teams at the top, and open Jira Data Center Bot.
To see which commands are available for you, type “help” in your conversation with the bot.
For most of the commands, the bot will ask you to authorize in Jira. To do that, you need to enter the “connect” command and following the dialog, paste your Jira ID and login credentials.
Team and personal tabs
Jira Data Center tab capability lets you pin your team’s backlog to your channel so that all the team members can see and manage it directly from Microsoft Teams.
There are also pre-defined personal tabs available in your Jira Data Center app, where you can quickly navigate to issues assigned to you, reported by you, or your issues report with your custom filter applied.
In order to see and interact with the tab, you or your teammates will be asked to authorize in Jira. This can be done by selecting the Sign in button on the tab and follow the dialog.
App 2: Installing into Jira
To install the Microsoft Teams for Jira Data Center app in your Jira instance, you need to be a Jira administrator.
- Go to ⚙ > Applications > Application Links.
- Select Create links.
- Select Atlassian Product.
In the "Application URL", enter
https://jira-server.msteams-atlassian.com/, and select Create new link.You might see a warning saying that "No response was received from the URL you entered". Ignore it, and click Continue.
- On the first screen of the Application link:
- Enter Microsoft Teams as the Application Name.
- Select the Create incoming link checkbox.
- Select Continue.
- On the next screen, enter the following consumer details:
- Consumer key: OauthKey
- Consumer name: MicrosoftTeamsIntegration
- Public key: You can copy it from the app's configuration screen. It looks like the following example:
- On next screen of the Link applications dialog, enter the following consumer details:
- Consumer key enter "OauthKey" as a value
- Consumer name enter "MicrosoftTeamsIntegration" as a value
- Public key which you can copy from app (add-on) configuration screen in a box. Use the following example:
- Select Continue. You should now have an application link that looks like this:
Now, once the configuration is set, you should see the following Jira ID at the bottom of the configuration screen:
The Jira ID will be requested from Microsoft Teams users during authentication. Share this ID with your users.
Configuring firewall
Jira Data Center for Microsoft Teams (App 1) uses multiple Microsoft Azure services behind-the-scenes, and they must be reachable from your network. Regardless of the user's location, all of the following IP/hosts should be allowlisted:
Web application backends (https://jira-server.msteams-atlassian.com and https://connectors.msteams-atlassian.com/) are hosted on Azure App Service. You may find IP details for whitelist from official source here. You may also copy Azure App Service IPs from the expanded list below and paste them during firewall configuration:
- Jira Data Center app (add-on) establishes a connection with Azure SignalR Hub (https://msteams-jira-server.service.signalr.net)
- Bot is built on top of Azure Bot Framework Service:
- login.botframework.com (Bot authentication)
- login.microsoftonline.com (Bot authentication)
- *.botframework.com (Bot channels)
- westus.api.cognitive.microsoft.com
- (for Luis.ai NLP integration)
- state.botframework.com
- (Bot state storage)
- cortanabfchanneleastus.azurewebsites.net
- (Cortana channel)
- cortanabfchannelwestus.azurewebsites.net (Cortana channel)
Authorization
Starting with version 1.4., Jira Data Center for Microsoft Teams (App 1) (Jira Data Center application 2019.10.20 released on 2019-10-21) uses pure OAuth 1.0a authentication flow.
It requires the end-user to authenticate in Jira Data Center, allow using her credentials to authenticate as her in future, and provide generated verification code to Microsoft Teams.
Jira Data Center for Microsoft Teams does not process and store Jira user passwords.
Version 1.4x and above:
To successfully authenticate in app it's required for user to have direct network access to Jira Data Center. This may mean connecting VPN or doing this inside work subnet where Jira Data Center is hosted. Please note this is valid only for authentication process and is not needed further for other workflows.
Revamped process now consists of 9 stages:
- Enter Jira id in Microsoft Teams. Click “Connect”.
- On the next screen click on the “Authorize” link. It has the following format: https:///jira/plugins/servlet/oauth/authorize?oauth_token=.
- It will either open Jira login page or redirect you to third-party identity provider like Azure Active Directory. Please put your credentials and log in.
- You will be redirected to Jira authorization page asking to allow Microsoft Teams to access to your data in Jira. Note you do not pass and store password in our app.
- Click “Allow”. You will be redirected to “Access Approved” Jira page.
- Look for verification code and copy it. Note this page can be displayed in a locale selected in your Jira profile and verification code may have other punctuation signs other than apostrophes around it.
- Paste the verification code to a respective field in Microsoft Teams.
- Click “Continue”. If the code is correct, you will be redirected to “Authentication successful” page and popup should close.
- You are all set and can manage your Jira issues in Microsoft Teams.
Additional notes:
- To change the user or stop working with the integration, you can use the Sign out function in the tabs, and the disconnect bot command.
- If you previously grated Microsoft Teams the access to the Jira data, you don't need to re-authorize.
- If you're trying to authenticate with an old Microsoft Teams for Jira Data Center app version, you’ll get a warning after ‘Connect’ step asking to contact your Jira administrator to update the app to the most recent version
FAQ
In this section we have gathered the most common requests to our support team and obstacles that users can face working with the app. You might find the answers to your questions here. You may also reach to our support team via the contact form here in case you still have questions.