NOT REVIEWED

Notes about the integration

In order to use the integration you need to have a codeBeamer MX account.

Registration through the MS Teams app is not supported currently.

There are two ways to setup and use the integration:

1. Use the codeBeamer MX Integration MS Teams app which can be downloaded for Teams from the Microsoft AppSource.
   1. This requires to have your codeBeamer MX instance running in Azure cloud with *.intland.cloud domain.
2. Use a custom MS Teams app which enables custom URL configuration.

Please note that for the integration to work, the codeBeamer MX instance needs to be publicly accessible so MS Teams can send requests to the instance.

Integration setup/configuration

For the configuration to work, you will need to provide your Teams tenant ID.

The tenant ID can be found by signing in to Teams, clicking on the more menu at one of your teams, and selecting the "Get link to team" option. This will show an URL which contains the tenant ID.

To configure the integration, System Admin permission is required because you will need to alter the codeBeamer MX instance's application configuration.

For using the codeBeamer MX Integration app from AppSource

This configuration is responsible to recognise incoming requests from Teams and act on them to send results back. It also responsible to validate requests too.

1. Go to the System Admin page and find the Application configuration option.
2. Find the "msTeams" configuration object.
3. The following properties need to be set:
   1. "enabled": true
   2. "appClientId": "85914958-cb27-456e-9327-fe28a0a269a8"
   3. "appClientSecret": "APP_CLIENT_SECRET"
   4. "tenantId": "YOUR_TENANT_ID"
   5. "notificationConfig": object with the following properties:
      1. "botId": "c9151aa8-562d-4f70-a7aa-21a7b74665f0"
      2. "botSecret": "BOT_SECRET"
      3. "linkType": "RETINA"
      4. "notificationsEnabled": true
      5. "serviceUrl": "https://smba.trafficmanager.net/emea/"
   6. "tenantRegistrationConfig": object with the following properties:
      1. "authUser": "AUTH_USER"
      2. "authPassword": "AUTH_PASSWORD"
      3. "checkRegistrationURL": "https://teams.intland.cloud/query"
      4. "registrationURL": "https://teams.intland.cloud/register"
      5. verifyBotTokenURL": "https://teams.intland.cloud/verify"

For the necessary passwords and secrets used in our Application Configuration, please contact our support team.

Make sure that no other "chat-ops" integration is enabled (e.g. Slack) while the MS Teams integration is enabled with the "enabled": true property.

After the codeBeamer MX configuration has been saved, the instance needs to be registered to our traffic routing server to be able to receive requests from Teams. To register the instance, find the "MS Teams configuration" option on the System admin page.

There will be the previously configured tenant ID printed along with a button saying "Register tenant ID with current endpoint".

Click on the button and if the "tenantID" and "registrationURL" configuration properties are correct, a registration successful message will appear.

Please note that one instance can be only associated with one tenant ID so after a successful registration the tenant ID - instance pair cannot be changed. In case a change is required, please contact our support team.

For notification sending to work correctly the tenant's administrator needs to consent to the application's permissions. This makes codeBeamer MX possible to search, validate or even create channels in Teams.

To consent to the application's permissions, find the MS Teams configuration option on the System admin page and click on the "Consent notification sending permissions" button.

This will open a new tab where Microsoft prompts for the consent, click on accept to continue.

After this, your tenant can access the application which allows the above mentioned behavior to work.

Please note that for notification sending, the codeBeamer MX bot needs to be installed/a member in the Teams team where the notifications are expected.

The only thing left to do is download and install the codeBeamer MX Integration app from AppSource in Teams.

For using a custom MS Teams app

This is the recommended way to use the integration if your codeBeamer MX instance runs from a different cloud provider or it is self hosted.

Please note that you will need granted permissions to install a custom application for your team in Teams.

Create the custom application

codeBeamer MX has the following REST endpoints to support the Teams integration:

For executing commands with codeBeamer MX Bot: https://codebeamer-mx-instance.com/cb/rest/chatops/command

For configuring common cardboard tabs: https://codebeamer-mx-instance.com/mx/#/msteams/configure-tab

where the "codebeamer-mx-instance.com" is the publicly available URL of the codeBeamer MX instance.

The first thing to do is to create the custom Teams application and the URLs above needs to be used for its configuration.

1. Sign in to Teams and install the App Studio application
2. Select the Manifest editor tab and click on the "Create new app" button
3. Fill the required inputs at the App Details section
4. Select the Tabs option from the Capabilities section
5. Enter the tab configuration URL using the "For configuring common cardboard tabs" URL from above
6. Select the Bots option from the Capabilities section and click on the Set up button
7. Enter the name "codeBeamer MX Bot" or something similar for the bot's name input and click on the create bot button.
8. Generate a password for the bot and keep note of both the bot's ID (appears under the bot name) and password (shown at generation).
9. Enter the messaging endpoint URL using the "For executing commands with codeBeamer MX Bot" URL from above
10. Select the Test and distribute option from the Finish section. Here you can install the app just like you would install it from AppSource

Next you need to create a new app registration at https://portal.azure.com.

1. Sign in to https://portal.azure.com and find the Azure Active Directory service.
2. From the left menu, select the App registrations option
3. Click on the New registration button, enter a name for the application and click on save
4. Keep note of the Application (client) ID
5. Select the Certificates & secrets option from the left side menu and generate a new secret by clicking on the New client secret button. Keep note of the generated secret.
6. Select the Authentication option from the left side menu, click on the Add platform button and select Web application
7. Enter the following URL: https://codebeamer-mx-instance.com/mx (this should be the codeBeamer MX instance's URL) and save the configuration
8. Add an additional URL to the previous configuration: https://codebeamer-mx-instance.com/cb/rest/exposed/connectMSTeamsAccountToFrontendProduct
9. Select the API permissions option from the left side menu and provide the following permissions to the application:
   1. Microsoft Graph
      1. ChannelSettings.ReadWrite.All (delegated)
      2. Group.Read.All (delegated)
      3. Group.Read.All (application)
      4. Group.ReadWrite.All (delegated)
      5. Group.ReadWrite.All (application)
      6. User.Read (delegated)
      7. User.Read.All (delegated)
      8. User.Read.All (application)
      9. User.ReadBasic.All (delegated)
      10. User.ReadWrite.All (application)
   2. Microsoft Teams Services
      1. User.Read.All (application)
10. Grant admin consent for the selected permissions

These were the necessary configurations outside of codeBeamer MX, now the following configuration is necessary in codeBeamer MX:

This configuration is responsible to recognise incoming requests from Teams and act on them to send results back.

For filling the properties, use the:

• tenant ID (for the property "tenantId")
• Application (client) ID (for the property "appClientId")
• Generated client secret for the application (for the property "appClientSecret")
• Created bot's ID (for the property "botId")
• Created bot's generated secret (for the property "botSecred")

1. Go to the System Admin page and find the Application configuration option.
2. Find the "msTeams" configuration object.
3. The following properties need to be set:
   1. "enabled": true
   2. "appClientId": "APP_CLIENT_ID"
   3. "appClientSecret": "APP_CLIENT_SECRET"
   4. "tenantId": "TENANT_ID"
   5. "notificationConfig": object with the following properties:
      1. "botId": "BOT_ID"
      2. "botSecret": "BOT_SECRET"
      3. "linkType": "RETINA"
      4. "notificationsEnabled": true
      5. "serviceUrl": "https://smba.trafficmanager.net/emea/"

Make sure that no other "chat-ops" integration is enabled (e.g. Slack) while the MS Teams integration is enabled with the "enabled": true property.

Prepare the usage

When everything is ready for use, you need to tell codeBeamer MX who are you in Teams, in other words you need to pair your codeBeamer MX account with the account you use in Teams.

Note: You only have to pair the accounts once and it does not matter whether you do the account connection with the cardboard tabs or codeBeamer MX Bot.

Pairing Your accounts using common cardboard tabs

1. Create a common cardboard tab by installing the Teams application and adding a tab to a team
2. When the tab configuration dialog appears, a codeBeamer MX login screen will show up where you need to log in with Your codeBeamer MX credentials
3. After you logged in, in case Your accounts has not been pared, a page will be shown with a 'connect your accounts' button.
4. Click on the button and accept the application's permission if prompted
5. You will be redirected to Your codeBeamer MX instance where you will need to log in if You are not authenticated yet
6. When the codeBeamer MX instance load finish, a success message will be shown telling that the account connection was successful

Pairing Your accounts using with codeBeamer MX Bot

1. Add codeBeamer MX Bot to Teams by installing the Teams application.
2. Open the chat conversation with the bot
3. Send a "help" message to the bot
4. The bot will reply with a message telling that Your accounts has not been connected yet
5. Click on the button in the message
6. A page will open up where you need Accept the application's permissions
7. You will be redirected to Your codeBeamer MX instance where you will need to log in if You are not authenticated yet
8. When the codeBeamer MX instance load finish, a success message will be shown telling that the account connection was successful
9. You can go back to Teams and start running commands with the help of the bot

Integration Features

There are three main features of the integration app:

1. Common cardboard tabs for teams or chats
2. codeBeamer MX Bot for
   1. executing commands
   2. sending notifications

Common cardboard tabs

The common cardboard tabs is a tab where everyone can see the same cardboard wheter it shows tickets from a tracker of from a release.

At configuration the configurator need to select a workspace first, then a tracker or a release from that workspace depending on the selected cardboard type. The displayed cardboard is the same cardboard that you can access in codeBeamer MX, except there are a few limitations:

• The work item dialog is not available
• The user cannot access any cardboard or page other than the one selected at the tab configuration
• Only the cardboard related filters and views are available

This means that the user can change status, edit items using the sidebar or use swimlanes like in codeBeamer MX

Tickets are updated on the fly if there is any change happens to them.

Each Teams user who use this cardboard, needs to sign in to codeBeamer MX first before accessing the cardboard tab, this means that users who does not have access to that cardboard won't see it in Teams either.

Every change made on the tickets from Teams, reflected in codeBeamer MX as well.

codeBeamer MX Bot

codeBeamer MX Bot can be used as a one-on-one conversation chat bot or You can invite it to group conversations.

Executing commands

To execute commands with codeBeamer MX Bot, you only need to send the command as a plain text message to the bot directly, or prepend a mention of the bot to the command if you are in a group conversation.

codeBeamer MX Bot will send back the result of the command execution as a message. Keep in mind that in a group conversation everyone will see the bot response, even if someone would not have permission to see that specific content in codeBeamer MX.

codeBeamer MX Bot can respond with a message that contains further actions. All of these actions can be executed with a separate command but you can choose to execute the command using the actions from the response message.

Execute the 'help' command to find out what codeBeamer MX Bot can do.

Available commands:

• disconnect - Disconnect Your MS Teams account from Your codeBeamer MX account if you want to associate a different codeBeamer MX account to it.
• [ID] assign user1 user2 - Assign a work item (identified by ID) to the listed users (user names should be listed separated by space)
• [ID] details - Display basic details of a work item (identified by ID) along with some executable actions
• [ID] transition STATUS NAME - Change a work item's (identified by ID) status to the given STATUS NAME
• [ID] add comment COMMENT MESSAGE - Add a comment to a work item (identified by ID) containing the given COMMENT MESSAGE
• [ID] comments - list the comments of a work item (identified by ID)
• search PATTERN - Search for work items that matches with the given PATTERN (used like a global search in codeBeamer MX)
• recent - show a list of recently visited work items
• help - show a help message containing the available commands

Replace the term [ID] with a work item's ID like this:

1091 details
1091 assign johndoe developer
1091 transition in progress

Notification sending

The notification sending can be enabled or disabled from the application configuration with system admin permission.

Use the property "notificationsEnabled": true under "msTeams" then "notificationConfig" to enable notification sending.

Notification sending can be configured for each tracker, at the tracker configuration, notification tab.

For the MS Teams integration, you need to provide a valid team name and a channel name. This will be the channel where the notifications from that tracker will be sent.

If you provide a non-existing channel name, you have the option to create that channel on the fly. The team name should exist it cannot be created on the fly like a channel.

When an event, like work item update, create or delete happens, a notification will be created and sent to the configured channel. The notification will contain information about the event and work item too.

If there is no channel configured for a tracker, you won't receive notifications from that tracker in Teams.

Notifications will be sent on the following events:

• A new work item has been created in the tracker
• A work item has been updated (some field has been changed) in the tracker.
• A comment has been added to a work item.
• An association has been added to a work item.

You can configure the same channel for multiple trackers but it is possible to create a separate channel for each tracker too.