Microsoft Teams Jira Connector provides one-way integration from Jira to Microsoft Teams. It is a much more secure and robust integration.

2-way integration details are described in the Microsoft Teams Jira On-Premises guides.

Marketplace link: https://marketplace.atlassian.com/apps/1216325/microsoft-teams-jira-connector?hosting=server&tab=overview

Frequently Asked Questions

You can check the FAQs on the Microsoft Teams Jira Connector product page.

Alerts configuration

You can find alert configuration on the Alerts Configuration page.

Scheduled reports configuration

You can read about Scheduled reports configuration on this page.

Configuration

There is a global and project-level configuration. The global configuration is available to the global administrators only.

The global configuration is in the System → Mail → Microsoft Teams.

The project-level configuration is accessible in the Project Settings → Microsoft Teams. Only project or global administrators can change the project-level configuration.

Video Demo

Go to the Microsoft Teams channel configuration, Connectors and add an Incoming Webhook Connector.

microsoft teams Jira connector add connector

Find Incoming Webhook and add one. Put the name as Jira and set the Jira logo.

Set the name and the icon of the Connector.

Copy the webhook URL that will be used later on during the configuration process.

Notifications from Jira to Microsoft Teams

Navigate to the configuration page in the Global or Project level, select the projects you want to get notification about and paste the webhook URL (or select a managed URL).

Setup the filters. Do remember that some values are only available when there is only 1 project selected.

You can configure custom fields filters. For instance, below you can see the Epic Link filter.

 

The configuration gets stored when you press the Save button.

You can have multiple notification rules.

When you just installed the plugin, please try to create a very simple configuration to the event "Someone leaves a comment" and with no filters. This will validate that the plugin has the correct license and your Jira can access Microsoft Teams.

Microsoft Teams message fields configuration

When you create a rule you can configure which issue fields are sent to Microsoft Teams.

Microsoft Teams message fields section contains 5 settings:

  • Exclude sending message details - when set the card will not contain any message fields (or we can call them facts).

  • Include links to attachment(s) - when set includes links to the issue attachments (if present).

  • Include links - when set the card could include the issue links (other issues as well as general links that can be added to the card).

  • Hide Empty Fields - when set the card does not get empty fields.

And the last setting is the issue fields selection multi-select field. It allows you to configure which fields the Microsoft Teams card should contain when the message is sent using the rule.

You can reorder fields by drag-and-dropping the names.

Project exclusion

In the Global configuration, you can configure the projects that cannot use this App.

Admin events notifications

Global administrators can configure Microsoft Teams Jira Connector to receive system-level event notifications. It includes events related to users, plugins and re-index all completed events.

Custom event type mapping

In the Global configuration, you can map custom event types to the system ones in order to process them as well.

Important: without this mapping custom event types are not handled, as the App does not know how to handle those. By mapping them to a system event you can help them App to understand them.

Destination Url Management

With Url Management you can configure named Microsoft Teams Incoming Webhook URLs and optionally restrict them to particular Jira projects. Managed URLs provide a few benefits:

  • You can identify URLs by name, which provide much more flexibility to administer

  • Restrictions by the Jira project permit enables your project admins to use them without asking for a new URL. For instance, you can create a URL for Customer Success teams and permit them to use it only by the Customer Success Jira project. The configuration becomes much simpler.

  • Simplified URL creation.

  • Important: The URLs do not work as filters. If you configured which project URL is available but use it globally, the notifications will be sent according to the rule.

The Url Management is available ONLY to global administrators.

You can create a new Managed Destination Url by clicking Create button.

You can click Test to verify the delivery/reachability of the Microsoft Teams channel.

When the URL is created it is visible in the URLs table.

In order to use the newly created Managed Destination Url, you need to create a new rule or edit an existing one. In the Destination section, you can opt in to use the Managed URL.

Afterwards, you or the user of the URL can select a URL from available URLs.

The rule with a Managed Destination Url looks like this.

And the message for a newly created Jira Service Management support request looks like this.

Allow only Managed URLs

Using global configuration settings you can enable the setting “Allow only managed URLs“ that won’t allow entering a URL directly into a rule and only managed URLs should be used. It is a recommended setting because it enables elevated security and control on where the data can be sent.

You can also specify in this section the URL mask that is used to validate all NEW URLs. We recommend it to correspond to your Microsoft tenant name in the following format - https://moveworkforward.webhook.office.com.*, where in this case moveworkforward is the Microsoft Teams tenant.

Audit trail

Advanced Microsoft Teams Jira Connector provides two kinds of audit trails:

  • for the messages sent by the App. It is ephemeral, which means it does show only the last 100 messages and they are kept in the memory only. It is used to debug issues and questions.

  • for the application settings. This trail helps the admins see who has done what changes and it integrates with Jira’s audit trail.

Disallow reports or alerts

System admins can disallow (hide) reports or alerts in the global Settings tab. You can hide all of the types or a subset of types.

Do not send notifications on the bulk update

In the global settings, the admins can enable a setting that will permit to NOT send the notifications during the Bulk Change when the “Not send email notifications“ is used.

Enable 2-way integration between Microsoft Teams and Jira On-Premises

Please follow the set of guides and documents → Microsoft Teams Jira Connector 2-way integration guides .

Additional configuration via environment variables

moveworkforward.pool.size - this variable can be used to control the amount of thread in the thread pool (from version 3.10.08).

Troubleshooting

Update

Please make sure that you have the latest App version, we fix the issue pretty quickly and there is a chance that your problem had been fixed.

Network

Please make sure Jira can reach the Microsoft Teams Incoming Webhook URLs (for instance https://moveworkforward.webhook.office.com).

Please use the “Test” button to check the network connectivity. Please see this info for more details about IP or domain whitelisting.

Debug mode

If you see some problems with the App we recommend checking the browser console for errors as well as enabling debug mode for the App's namespace to see any errors.

App namespace to enable DEBUG log level: com.moveworkforward.

Here is official Atlassian’s documentation on how to enable the debug mode - https://confluence.atlassian.com/jirakb/change-logging-levels-in-jira-server-629178605.html

Download the support zip

You can send us the support zip which contains the log files. You can download it following this official Atlassian documentation.

Get help

You can create a Jira Service Management support request with all information you could gather, please include the screenshot of the configuration (please don't worry about the webhook URLs, we won't store or use them) and the logs or errors you could find in the browser or on the server-side.

Official Roadmap

The Road map link in the Trello.

Updated: