Setting up connector

General Info 

MS Teams connector plugin is made to send webhooks from Bitbucket to channel in MS Teams messenger. The notifications are based on the events user has chosen to get notifications about. 

Whether you are planning to get notified on pull request events or if someone forked a repository, you can customize it as you need and get information in MS Teams channel in a cool and informative way. 

Set up

In order to establish Bitbucket and MS Teams communication user must set up a connection on the MS Teams and Bitbucket side. To do so see the instruction below. 

I. Create a channel in MS Teams messenger

(skip if you already have one)

Switch to Teams tab.

>

Press Join or create a team.

>

Press Create Team.

>

Give name to your Team and Press Next.

II. Set up a workflow in MS Teams

You can get a link from MS teams using the “MS Teams Worklows” functionality.

It is recommended to create your Team and channel before configuring the MS Team workflow. 

Create MS Teams workflow

1. Open Microsoft teams application and find the Workflows section in the expandable menu hidden behind the three dots.

2. Select the Workflows section to open the configuration list.

3. Click on the New flow button to create a new workflow or switch to the Create tab.

4. In order to create the correct link select the option “Post to a channel when a webhook request is received“.

5. Give name to your future Workflow and if necessary select the user in the Sign it menu as all notifications will be posted on behalf of the selected user in this section. To change the user, please sign in as the necessary user in the menu behind the 3 dots next to the Microsoft Teams logo.

6. Press Next.

7. Select the Team and Channel where the workflow should post Bitbucket notifications. 

8. Confirm creation by pressing the Create flow button.

9. Once you have completed these steps, you will be provided with the link to be further used in Microsoft Teams connector for Jira. Please copy this link and press Done to finish the process of creating the workflow link and proceed to other settings.

Update workflow (optional)

In order to let your workflow send notifications to a particular MS Teams channel you must link this workflow to your channel. If you want to change the channel or by some reason you haven't specified it yet, proceed with the following steps.

1. In the created workflow open the Edit menu and select the required Team and Channel to post notifications to.

2. There are several more settings for you to configure, but to get the notification functionality set the Team and Channel in the corresponding fields.

3. Once it is done, press Save to complete configuration.

III. Set up a connector in Bitbucket

There are 2 places where user can set up a connector in Bitbucket. 

1. Repository settings
2. Project settings

Both sections have identical basic features, yet connector on repository level will send notifications to MS Teams channel on events in particular repository. While connector on project level will notify on events in all repositories in project.

Configurations created on project level can be viewed on repository page, yet can cannot be edited there. Editing is possible only from add-on configuration in project settings.  

For Project: Bitbucket → Project → Project settings → MS Teams Connector

For Repository: Bitbucket → Project → Repository → Repository settings → MS Teams Connector

This is the menu where you can complete the set up. 

Paste previously copied channel link into the field "Webhook URL" and press Test Connection if you want to double check connection.

If everything is done right you will see a notification on successful setup completion. Now you can customize notification events you want to receive in MS Teams channel. 

IV. Configure notification Filters

MS teams Connector allows narrowing down notification pool to minimize notification spamming with the help of 4 filters:

• Users

Select users in the corresponding fields if you want to get notification to channel only if actions are performed by them.

• User Groups

Notification will be sent to MS Teams channel only if events were triggered by users in the selected group.

• Branch (only on repository level)

Type branch name if you want to get notifications only if they took place within this particular branch. You can add several branches to monitor for events happening within.

This filter works only for events like Push, File changed and all of the Pull Request section events. If some other event takes place within a repository, it will bypass this filter.

• Folder (only on repository level)

Type repository folder or folder path to get notification to MS Teams channel only about events happening within particular folder. Type another folder name or its path in the new field to monitor for events in all selected folders.

This filter works only for events like Push, Merged, File changed. If some other event takes place within a repository, it will bypass this filter.

V. Set up notifications

Given webhook connector provides user with a range of events one can choose to receive in MS Teams channel. 

After the connection is set up you can customize connector to send only those event notifications that you want it to. Select checkboxes next to the events you want to get notifications about.

Press Save.

Now every time the selected event takes place with the current repository, a corresponding message will appear in your MS Teams channel.

Connector Activation/Deactivation

Notifications from Bitbucket can be turned On and Off at once in repository settings menu.

Just fing a toggle element at the top of the connector interface and change it's status by clicking on it. Depending on its state notifications will be active  or inactive.