This integration is no longer supported due to breaking changes in the Slack API, see https://api.slack.com/changelog/2020-11-no-more-tokens-in-querystrings-for-newly-created-apps

Integration usage notes

• To use the Slack integration features, you need to have a slack account and you need to be a member of a slack workspace where the integration app has been set up previously.
• Your codeBeamer user need to have the Rest / Remote API - Access permission since the communication between Slack and codeBeamer is going through the codeBeamer's REST API.

Integration Setup

Prerequisites

To set up the integration you will need to be a member in a slack workspace where you have permission to install a slack app. The integration can be set up only for one slack workspace of one codeBeamer instance.

If you already member of such a workspace then you can skip the Create a Slack workspace section and jump directly to the Create a Slack Application section.

Create a Slack workspace

To create a slack workspace, go to slack and enter your e-mail address as shown in the following screenshot:

After clicking on Confirm follow Slack's instructions. After the creation finished, Slack offers to invite your teammates to this workspace but it is optional so you can skip this step. If you set up everything, you will see the brand new workspace that you just created.

Create a Slack Application

To create a Slack application for your workspace go to the following page: Slack apps. You should see a green Create new app button, but you may need to sign in to your workspace in order to see it.

Click on the Create new app button and give the app a name and select the proper workspace as follows:

After naming your app and setting the workspace click on the Create App button. You should see a page similar to this:

First thing to do is set up the endpoint URLs that the app will use to communicate with codeBeamer, so select he Interactivity & Shortcuts option from the left side menu.

Here you need to enter two URLs, the first URL should be YOUR_URL/rest/chatops/interactive-message and the second should be YOUR URL/rest/chatops/slack/external-options-load

where YOUR_URL is your codeBeamer's public URL with the context path. This URL should be reachable by Slack across the Internet.

The following feature will be the Slash Commands so select this menu option from the left side menu.

Click on the Create new Command button and fill in the fields as it is on the next sceenshot. The most important part is the Request URL which should be YOUR_URL/rest/chatops/command

where YOUR_URL is the same as mentioned above.

After the command creation you should see something similar to this:

After saving the command will be visible on the Slash Commans page

The next step is to set up the app permissions so select the OAuth & Permissions option from the left side menu.

Here you need to set two things. The first is to add a Redirect URL:

The URL should be YOUR_URL/connectSlackAccount.spr where YOUR_URL is the same as before.

Make sure you click on the Save URLs button too.

The second setting is the bot user's permissions. It can be set on the same page just scroll down a little:

The necessary permissions are the chat:write, team:read and the users:read permissions.

Click on the Save Changes button after the permission addition.

You are almost finished the configuration, the last step is to install the app to your workspace. Click on the Install App to workspace button at the top of the OAuth & Permissions page.

You should see a similar summary of the app's features and permissions like this:

Click on the Authorize button and you should see your Slack user's oAuth token and what is more important, the bot's oAuth token too.

You will need this bot oAuth token for further configuration so note it.

There are also some information what should be noted at the Basic Information page selected from the left side menu.

At the App Credentials section you will need the Client ID, Client Secret and the Verification token.

The Slack app creation has been finished, the next step is to introduce this Slack app to codeBeamer.

Configure codeBeamer

After you created the Slack App, there are a few things that you need to configure in codeBeamer too. These are the informations you noted from the previous section:

• Bot oAuth token
• Client ID
• Client Secret
• Verification token

Go to the System Admin page in codeBeamer and select the Slack Integration option:

First enter the Bot oAuth token and click on the Validate token button.

If the token is correct you should see something similar:

Fill the remaining mandatory fields and don't forget to check the Slack integration features enabled checkbox and optionally the Notifications enabled checkbox too.

After filling all mandatory fields, click on the save button.

Now you finished the codeBeamer side configurations.

Later if you want to turn off all the slack integration features, or only the notification sending, just uncheck the appropriate checkbox and save the settings.

Connect Your Accounts

Before using the /cb slash command there is one last step to take. When interacting with codeBeamer from Slack, it is necessary for codeBeamer to know which user is doing the specific operations fired from Slack, so to get codeBeamer to know who are you in Slack you need to connect your Slack account with your codeBeamer account. This can be done by simply trying to use a command and the integration will tell you what to do next.

Go to your slack workspace and use the /cb command by typing /cb to the message line.

You should get a similar message like this:

Click on the URL and click on the Authorize button.

You will be redirected to codeBeamer and you will see a message that tells you whether the account connection has been succeeded or not. You may need to sign in with your codeBeamer account if you are currently not signed in.

Now you can go back to Slack and use the command without any problems. Remember that your codeBeamer account need to have the Rest / Remote API - Access permission in order to use the command.

Once you have done this account connection, you will not need to do it again with the same account.

Integration Features

Here you can find all the features that the integration provides to you.

Features available from codeBeamer

These features can be used from the codeBeamer's user interface if the integration is enabled.

Notifications

It is possible to send notifications about certain events directly to your Slack workspace so you can immediately see all the changes.

Notifications are configured by Trackers and Repositories. If you want to get notifications about Bugs you have to set up a Slack channel for the Bugs

also if you want to be notified about a Repository's Pull Requests, then you need to set up a Slack channel for that specific Repository. However these channes can be the same.

The only restriction about these channels that they need to be public Slack channels.

Please keep in mind that because of a change in Slack, the integration Slack app has to be added the Slack channel to be able to send notification messages to that channel.

How to add the application to a channel

Open the channel that you would like to use as a notification channel.

Type "add" to the message sender input and the "Add apps to this channel" option will show up. Select that option.

Search for the integration application and click on the "Add" button next to it.

After this, the application has been added to the channel and it can be used as a notification channel in codeBeamer.

Setting channels for notifications

You need to specify where the notifications about a Repository's changes or a Tracker's items should be sent for each Tracker or Repository that you want to be notified about.

This configuration can be done at a Tracker's configuration page, under the Notifications tab:

You can enter the desired channel's name or ID to the input field.

If the integration is not enabled, you should see a message like this:

If you enter a not existing channel's name, then the integration will offer you to create a channel with that name:

Please note that in Slack, channel names can not be longer than 22 characters and can not contain neither special characters nor spaces.

If you have not connected your codeBeamer account with your Slack account previously and you try to save a notification channel for a tracker then you should get the following error:

The existence of the connection is necessary because the given channel will be looked up in Slack and this operation can not be done without the proper information.

When you finish the channel setting the notifications about this Tracker's items will be sent to the configured channel! Make sure that the notification sending is enabled

at Slack integration settings on the System admin page.

Jumping to a notification thread

Notifications are structured around Work Items so all the notifications related to a specific Work Item will be shown in one Slack Thread. The first notification of a Work item will be sent as a regular

message to the configured notification channel, but further messages about that Work Item will be aligned to a Thread which opens from the first notification message.

For example here you can see a notification about a Work Item creation and an update notification about the same Work Item:

On the right side you can see the Tread which only contains notifications about that specific Work Item.

Notifications sent to a Thread will also be posted to the parent channel too.

These Threads can be accessed from codeBeamer too. Go to a Work Item and select the ChatOps Channels option from the dropdown menu as you can see on the next screenshot:

Note that this option is only available if the integration features are enabled and your codeBeamer user has the Rest / Remote API - Access permission.

You will see a Jump to Work Item's Message Thread if there is any Threaded notifications about this Work Item.

Notification about Work Item creation

A notification will be sent when a new Work Item is created if there is a channel set up for the Work Item's Tracker and notification sending is enabled at the integration configuration.

A Work Item created notification looks like this:

Notification about Work Item updates

A notification will be sent when a Work Item is updated if there is a channel set up for the Work Item's Tracker and notification sending is enabled at the integration configuration.

A Work Item updated notification looks like this:

Notification about Comment addition

A notification will be sent when somebody adds a comment to a Work Item if there is a channel set up for the Work Item's Tracker and notification sending is enabled at the integration configuration.

A comment added notification looks like this:

Notification about Work Item escalation

A notification will be sent when a Work item is escalated if there is a channel set up for the Work Item's Tracker and notification sending is enabled at the integration configuration.

A Work Item escalated notification looks like this:

Notification about Association addition

A notification will be sent when an Association is added to a Work item if there is a channel set up for the Work Item's Tracker and notification sending is enabled at the integration configuration.

An Association added to a Work Item notification looks like this:

Notification about Pull Requests

The same type of notifications works also for Pull Requests in this case instead of setting a notification channel for a Tracker, you need to set a notification channel for the Repository:

Having a conversation about a Work Item (Joining channels to it)

It is possible to join a Slack channel to a Work Item in order to discuss things in it without the limitations of the comments.

You can also invite other project members to this channel in one step. The prerequisite of the invitation is that the invited user needs to have an existing connection between his or her Slack and codeBeamer accounts.

The management of these conversation channels can be seen on the dialog that opens after selecting the ChatOps channels option from a Work Item's dropdown menu:

This menu option can be reachable from several places like:

• Work Item details
• Table view
• Document view
• Planner

The dialog looks like this:

On the dialog you can see the:

• Work Item's notification message thread link if there is any threaded notifications for the Work Item
• The available channes that are currently joined to the Work Item (the padlock icon indicates that the joined channel is private and you can see it because you are a member of that private channel)
• A management part where you can Join either a new channel or an existing one to the Work Item.

Also when this connection between a channel and a Work Item is being deleted, a message about the deletion will be sent to the joined channel before deletion.

Joining a Work Item to an existing channel

If you Join a Work Item to an existing private or public channel, the following operations will happen:

1. A message will be sent to the selected channel that contains the Work Item's details (this will be visible by everyone depending on the current context)
2. A Thread will be opened from this details message where the discussion can take place.
3. Optionally if you selected project members at the Invite Users field, those users will be invited to this channel.
4. You will be immediately redirected to the seleted channel.

Joining a Work Item to a new channel

If you Join a Work Item to a new private or public channel, the following operations will happen:

1. A new private or public slack channel will be created (Note that the channel creating rules are considered like the length of the channel name and allowed characters in it).
2. The channel's Topic will automatically set to a predefined phrase which consists of the Work Item's Tracker Key, ID, it's summary and the URL of the Work Item.
3. The entered Initial message will be sent to the channel as a message.
4. Optionally the given purpose of the channel will be set.
5. Optionally if you selected project members at the Invite Users field, those users will be inviteed to this channel.

Features available from Slack

These features are available using either the /cb slash command or clicking on a button on a message sent by the integration's bot.

Slash Commands

At the command explanations the [ID] means either a Work Item's ID or an URL to the Work Item.

For example the 1412930 and You must login to see this link. Register now, if you have no user account yet. are both valid variables for [ID].

Help command

With the help command you can see all the available commands that can be used.

/cb help or simply just /cb

Only you can see the command's result message.

Details command

With the details command you can see basic informations about a Work Item. /cb [ID] details

This version of the message is only visible to you and there are also actions available from the message.

The colored line's color represents the Work Item's current status. The title is an URL which points to the Work Item in codeBeamer allowing you to quicly jump to it.

If you omit the details word from the end of the command: /cb [ID] then you will get a similar message but this time without actions and also this message is no longer visibly only by you.

Without the details word, the Work Item's details will be visible by everyone depending on the current context (private channel, public channel, direct message, etc)

If you enter a wrong [ID] then the result message looks like this:

Comments command

With the comments command you can list all or the last n comments written for a Work Item. /cb [ID] comments or /cb [ID] comments N where N is the limit of the comments shown.

By default N is 10 if not given.

If there is no comment for a Work Item then the message looks like this:

Recent command

With the recent command you can see your recently visited items in codeBeamer.

The latest item appears at the bottom of the list and the oldest item appears on the top. /cb recent or /cb recent N where N is the limit of the items shown.

By default N is 10 if not given.

Add comment command

With the add comment command you can add a comment to a Work Item from Slack.

There are two different usages of this command.

The first way is to provide the comment mesage along with the command, in this way the comment is immediately added to the Work Item in one step. /cb add comment This comment was added from slack!

The second way is to omit the comment part and just write /cb add comment

In this way a dialog will show up where you can write the comment's text and after the Comment button the comment will be added.

Search command

With the search command you can search for Work Items in codeBeamer in a similar way like with the global search bar next to your profile. /cb search search-expression

For example the /cb search variants will result the following message:

Assign command

With the assign command you can assign a Work Item to other workspace members. /cb [ID] assign @TeamMate1 @Developer2 ...

The existing assigns will be overwritten by the given assigns.

For example the command /cb 1524316 assign @istvan.hanufer will result the following

The assign command can be used in two ways. One way is that you already saw above to provide the user or users with @mention after the assign keyword.

The orher way is to omit the users after the assign keyword and enter just this: /cb [ID] assign.

In this way you will get a list of assign options:

Here you can also select roles and user groups along with project users. There is also a list of assigned users/roles/groups on the top of the list.

If you use the command this way the selected assign target will not overwrite the existing ones like at the @mention way, simply just adds the target to the existing ones.

You can also click on one of the options at the Assigned to group to disassociate.

If there is a user in your Slack workspace who did not connect his or her Slack account with the codeBeamer account, assign that user to a Work Item will result the following:

Transition command

With the transition command you can change the status of a Work Item.

Like at the assign command you can also use this command in two ways:

1. Provide a status that you want the Work Item to put into with a state transition.
2. Omit the status and select a status from the given available statuses.

The first case's command is /cb [ID] transition status name for example: /cb 1524316 transition in progress.

Note that the above example only works if there is a state transition from the Work Item's current status to a status named in progress and this state transition can be done without filling additional fields of the Work Item.

On the following screenshot you can see the /cb 1524304 transition closed command's result:

The second case's command is /cb [ID] transition.

In this way you will get a message like this:

Or if there are too many available transitions, instead of buttons, the will be a list of the available statuses:

Disconnect command

With the disconnect command you can delete the connection between your codeBeamer account and your Slack account. /cb disconnect