atlassian-labs / msteams-jira-server

Microsoft Teams plugin for Jira Server

Jira Server

Official plugin for Jira Server that integrates with Microsoft Teams.

Usage

Jira Server for Microsoft Teams brings your Jira Server experience into your collaboration environment, letting you and your team stay focused, communicate on issues and backlog. Interact with Jira Server bot for Microsoft Teams to: create, assign, watch, edit issues, log working time. You may also interact with the bot from your team channel. With the messaging extension, you can quickly search for a specific issue and submit it to a channel or conversation. With the actionable message, you can quickly create a new issue, pre-populated with message text as the issue description, or save the message as a comment on one of your Jira Server issues. Also, you can add your project backlog to your channel as a tab, so that your team could easily track and work on the issues within the tab. Issue urls sent in a message to the group chat or team channel unfurl cards with context about the issue. The unfurl displays key information such as summary, status, priority, updated date, reporter, assignee and those values can be changed from the card directly. There are available 'Assigned to me’, ‘Reported by me’, ‘Watched by me’ and ‘My filters’ tabs by default but you also have a possibility to add a tab with a custom filter and save it.

Important: To use messaging extension, bot, or tabs you’ll need to install Microsoft Teams for Jira Server add-on to your Jira Server. Make sure you have admin permissions within your Jira Server to be able to install and configure the add-on. Once the add-on is installed, the add-on will generate and assign a unique Jira ID to your Jira Server instance. Share the generated Jira ID with the team so that your teammates could connect Microsoft Teams to Jira. Jira Server connector for Microsoft Teams can be set up independently and doesn’t require add-on installation. Connector is using webhooks and can be configured directly from the Teams channel. Please note, that the webhook set-up in Jira requires Jira admin permissions.

Installation

Prerequisites

1. Clone solution to local repository. To do that you can use clone action.
2. Create or use your existing Microsoft Teams account for testing the application.
3. Create Azure Bot.
   • Select the New button found on the upper left-hand corner of the Azure portal. Type bot in the search box and press enter. Select the Azure Bot card.
   • On the Azure Bot blade click the Create button to start the creation process.
   • Fill all required fields. If should be available only in your Microsoft tenant select Type of App as Single Tenant.
   • Press Create button to create the service. You can monitor the creation progress by checking the Notifications pane. The notifications will be changing from 'Deployment in progress...' to 'Deployment succeeded'.
   • When deployment is finished go to Azure portal main screen, select All resources from the list of services and select the bot.
   • Open Configuration blade. Fill Messaging endpoint field. Use your application base url https://<MICROSOFT_BOT_APPLICATION_BASE_URL>/api/messages.
   • Click Manage Password link, placed near Microsoft App ID field.
   • Click New client secret for generating a new password.
   • Save generated password as BOT_APP_SECRET.
   • Navigate to Overview section and save Application (client) ID as BOT_APP_ID.
   • Navigate to Channels section and select Microsoft Teams channel. Check 'I agree to the Microsoft Channel Publication Terms and the Microsoft Privacy Statements for my deployment to the Microsoft Teams channel.' and Save the configuration.
   • Navigate to Authentication. section.
   • In the Redirect URIs, add a redirect URL of type Web with a value https://<MICROSOFT_BOT_APPLICATION_BASE_URL>/loginResult.html.
   • In the Implicit grant and hybrid flows section, check ID tokens as this sample requires the Implicit grant flow to be enabled to sign-in the user.
   • Also, in the Redirect URIs, add a redirect URL of type Web and value https://token.botframework.com/.auth/web/redirect or https://token.botframework.azure.us/.auth/web/redirect for GCCH configuration.
   • Select Save.
   • Navigate to Expose an API.
   • Check if Application ID URI is populated. Set it to default value, if not.
   • Click Add a scope button. Enter clear Scope name (e.g. App.Read), set "Admins and users" for the field Who can consent?, enter some description and save the scope.
   • Navigate to API permissions.
   • Click Add a permission button. Select just created API from My APIs tab. Select the Scope previously created above and save the changes. Please copy the value of just added permission (it's like api://.../...). It will be necessary later.
   • Navigate to Manifest. Set accessTokenAcceptedVersion as 2. Save changes.
   • Go to Azure portal main screen, select All resources from the list of services and select your created Azure Bot resource.
   • From the Configuration blade on bot resource, click Add OAuth Connection Settings button on the bottom of page.
   • Enter clear name for the new connection string. Save it as AAD_OAUTH_CONNECTION_NAME
   • In Service Provider select box choose Azure Active Directory v2. Client id is the Application (client) ID of AzureAD app registration (BOT_APP_ID). Client secret is the secret of AzureAD app registration (BOT_APP_SECRET). Set value of Tennant ID to common or your specific Microsoft tenant id if the app is not multi tenant. Scopes should be a value of the added permission (like: api://.../...).
   • Save the changes
   • Open just created Connection string from Azure Bot resource. Press Test Connection.
   • If connection was tested successfully add Name of just created connection to the appsettings.Development.json as a value of property OAuthConnectionName.
4. Install locally or configure Mongo Db on Azure. Example for Azure:
   • Login into Azure.
   • Click on All Resources -> Create -> Find Azure Cosmos DB and press Create. Select Azure Cosmos DB for MongoDB card (or select it from the drop down). Press Create.
   • Fill all items. Use or create new resource group. Click Create.
   • Navigate to Azure Cosmos DB created resource.
   • Add new Collection. Save its name as DATABASE_NAME (e.g. jiraintegrationdb).
   • Click on Connection String and copy Primary Connection string. Example: mongodb://testingmsteams:azgsTNX2Jq.../?ssl=true&replicaSet=globaldb
   • Copy and edit it by adding newly created database name after the last '/' in line: mongodb://testingmsteams:azgsTNX2Jq.../__DATABASE_NAME__?ssl=true&replicaSet=globaldb. Example : mongodb://testingmsteams:azgsTNX2Jq.../jiraintegrationdb?ssl=true&replicaSet=globaldb
   • Save it as DATABASE_URL.
5. Create new Azure Storage Account
   • Save Primary Connection string (Access keys > Connection string for the key1) as TABLE_BOT_DATA_STORE_CONNECTION_STRING.
6. Create Azure SignalR Service instance
   • Select the New button found on the upper left-hand corner of the Azure portal. In the New screen, type SignalR Service in the search box and press enter
   • Select SignalR Service from the search results, then select Create.
   • Configure the settings for your new instance.
   • Select Create to start deploying the SignalR Service instance.
   • Go to created resource > Keys. Save connection string as SIGNALR_CONNECTION_STRING
7. Create new Azure Cache for Redis
   • Save Primary Connection string (Access keys > Primary connection string) as CACHE_CONNECTION_STRING.

Configuring

1. Download ngrok.Install it and run ngrok http 5000 --host-header=localhost:5000 in the terminal. Note that ports can be different. Use yours. The ngrok will emulate traffic to your connection. The created link is your <MICROSOFT_BOT_APPLICATION_BASE_URL>. You can use any other tunnel for your preference to set up app locally. For the hosted app use it's base url.
2. Run npm install command in the terminal from a root of ClienApp folder to install project dependencies.
3. Open appsettings.Development.json for MicrosoftTeamsIntegration.Jira and put this json inside it:

  {
    "BaseUrl": "https://<MICROSOFT_BOT_APPLICATION_BASE_URL>",
    "DatabaseUrl": "DATABASE_URL",
    "MicrosoftAppId": "BOT_APP_ID",
    "MicrosoftAppPassword": "BOT_APP_SECRET",
    "OAuthConnectionName": "AAD_OAUTH_CONNECTION_NAME",
    "StorageConnectionString": "TABLE_BOT_DATA_STORE_CONNECTION_STRING",
    "BotDataStoreContainer": "DATA_STORE_CONTAINER_NAME", // name of container that will be automatically created in Azure storage (TABLE_BOT_DATA_STORE_CONNECTION_STRING) on app startup
    "CacheConnectionString": "CACHE_CONNECTION_STRING",
    "MicrosoftLoginBaseUrl": "https://login.microsoftonline.com",
    "Azure": {
       "SignalR": {
          "ConnectionString": "SIGNALR_CONNECTION_STRING"
       }
    },
    "Logging": {
    "LogLevel": {
       "Default": "Debug",
       "System": "Information",
       "Microsoft": "Information"
       }
    }      
  }

1. Fill the json with previously saved values from the Prerequisites section above
2. Build project and start it with any server (for example IIS Express).

GCC/GCCH configuration

In order to use the application with GCC/GCHH please fill next configs in appsettings.Development.json file (those configs should be empty for commercial cloud or local environment)

  {
    "MicrosoftLoginBaseUrl": "https://login.microsoftonline.us"
    "ChannelService": "https://botframework.azure.us",
    "OAuthUrl": "https://tokengcch.botframework.azure.us/",
    "ToChannelFromBotLoginUrl": "https://login.microsoftonline.us/MicrosoftServices.onmicrosoft.us",
    "ToChannelFromBotOAuthScope": https://api.botframework.us",
    "ToBotFromChannelTokenIssuer": "https://api.botframework.us",
    "ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.azure.us/v1/.well-known/openidconfiguration",
    "ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.us/cab8a31a-1906-4287-a0d8-4eef66b95f6e/v2.0/.well-known/openid-configuration",
 }

Deployment

In case you want to deploy the application later you need to do some additional configurationL:

1. Login into Azure.
2. Create new Web App resource:
   • Set runtime to .Net 6 or later
   • Click "Create" button
   • Go to just created resource,copy Default domain and save it as <MICROSOFT_BOT_APPLICATION_BASE_URL>
   • Go to Configuration section and add all configs from Configuring section above. As an option you can create App Configuration resource and set all the configs there and the app service configuration will just keep App Configuration resource connection string.
3. Deploy your application to Web App resource

Install Jira Server app (add-on)

1. Install standalone Jira server is installed on your machine or you have installed Atlassian SDK (https://developer.atlassian.com/server/framework/atlassian-sdk/install-the-atlassian-sdk-on-a-windows-system/).
2. Create Jira Server add-on. See more details here.
3. Got to your local instance of Jira Server -> Settings -> Manage apps.
4. Click Upload app and select *.jar file of your Jira Server addon created previously.
5. Finish installation. Expand new app. All modules should be enabled.
6. Press Configure and follow steps on the page.

Debug integration locally

1. Copy manifests\cloud\development or manifests\server\development folder to new folder in local desktop.
2. Change local manifest.json.
3. Put BOT_APP_ID into all botId occurrences.
4. Replace all occurrences of https://msteamsdev.ngrok.io to https://<MICROSOFT_BOT_APPLICATION_BASE_URL>.
5. Create ZIP file of manifiest and two *.png files.
6. Login to Microsoft Teams.
7. Click on Store -> Upload Custom App and put your ZIP there.

Side note - every time you will restart ngrok your microsoft bot application base url changes. After restart you have to change all <MICROSOFT_BOT_APPLICATION_BASE_URL> urls once again (in Portal Azure, User Secrets or appsettings.json, manifests, install Jira Sever\Cloud Add-on). Register free ngrok account to resolve this issue.

Documentation

Please visit a link to get more details.

Tests

All unit tests for Jira Server project are placed under MicrosoftTeamsIntegration.Jira.Tests. You can use Test Explorer in the Visual Studio IDE to run them and View test results. It displays the results in groups of Failed Tests, Passed Tests, Skipped Tests and Not Run Tests. The details pane at the bottom or side of the Test Explorer displays a summary of the test run. Another way to execute all tests is to run dotnet test command in the terminal from the project root folder.

Contributions

Contributions to Jira Server are welcome! Please see CONTRIBUTING.md for details.

License

Copyright (c) 2019 - 2021 Atlassian and others. Apache 2.0 licensed, see LICENSE file.

msteams-jira-server's Issues

Unable to unwatch issues with most recent versions of the App

When trying to unwatch a ticket, MS Teams gets:

Something went wrong in the Jira Server application

And in the application logs, we can see the following when the request to remove a watcher is received by Jira:

2022-05-26 07:33:02,459+0100 OkHttp https://msteams-jira-server.service.signalr.net/... INFO [c.m.teams.service.SignalRService] Message received: {"requestUrl":"api/2/issue/ISSUE-KEY/watchers?username=some.user.here","requestType":"DELETE","requestBody":"","token":"TRIMMED>...","teamsId":"<TRIMMED>","atlasId":"<TRIMMED>"}
And Jira's response is:
2022-05-26 07:33:02,579+0100 OkHttp https://msteams-jira-server.service.signalr.net/... DEBUG [c.m.teams.service.SignalRService] SignalR invoke hub method Callback() with response: {"code":415,"response":"","message":"Something went wrong in Jira Server application."}

---

This does not happens with the latest version on Marketplace. But it's happening at least with the following:

• 2022.06.95
• 2022.02.88 - Provided to a customer with additional logging for debug purposes.

Authentication breaks when accessing JSM issue without permission

We conducted an experiment to test the behavior of user permissions on Jira Software (JSW) and Jira Service Management (JSM) projects on MS Teams. We found that when the user “vwong-sd-demo” was part of the “jira-software-users” group, we are able to edit the issue SCRUM1-10 in MS Teams.

However, when the same user was not a licensed JSM user, we were not able to edit the issue ITSM1-10 in Teams, which was the expected behavior (due to lack of permission), but we get in an infinite loop of Teams asking for authentication.

The following was confirmed by @vhensorskyi:

• If the user is not a member of jira-servicedesk-users an infinite loop of the login page or the unhandledRejection error appears. Depending on what role is assigned to the user.
• if the user belongs to the group but doesn’t contain any role in the project the unhandledRejection error shows on the task module.
• if the user belongs to the group and either Service Desk Team or Administrator role is applied then user is able to edit issues in MS Teams.