Content:
1. Introduction
2. Integration Capabilities
3. Prerequisites
4. Initial Configurations in Businessmap
5. Configuring the Integration
6. Use Cases
1. Introduction
This article describes the integration between Businessmap and Azure Repos.
A potential reader of this article is expected to be familiar with Businessmap (boards, cards, business rules, etc.) and Azure Repos (branches, commits, pull requests, etc.).
However, if you have any questions or encounter some difficulties along the way, do not hesitate to contact the Businessmap Support team at support@businessmap.io
2. Integration Capabilities
The integration is bi-directional. It offers the following capabilities:
From Businessmap to Azure Repos:
- Create a new branch in Azure Repos when card is moved to specific column in Businessmap
- Create a pull request in Azure Repos when card is moved to specific column in Businessmap
From Azure Repos to Businessmap:
- Create a card from an Azure Repos commit message.
- Link an existing card from an Azure Repos commit message.
- Add comments to the card on:
- commits, branch deletions
- pull request comments and state changes (completed or abandoned)
- On abandoned pull request (closed but not merged), the corresponding card in Businessmap will be blocked (if configured), and a rework card will be created as a predecessor of the original card.
- On finished pull request (closed and merged), the corresponding card in Businessmap will be moved to the previously configured column.
3. Prerequisites
To use the integration, you need the following:
In Businessmap:
- Add custom fields, to the boards that will be integrated. The names of the custom fields could be as you like, the integration will ask explicitly which ones to be used.:
- A custom field to store a link to the branch → "Branch link" (custom field type: link) which is mandatory;
- "Reponame" (custom field type: text) and "Pull Request" (custom field type: link) are optional.
- Two available business rules (configuration for them is automatically done only once, when connection is set up)
- Integration user must have Account owner admin privileges.
In Azure Repos:
-
Personal Access Token (PAT) with access to all repositories which grants these permissions:
Code (Read & write); User Profile (Read); Project and Team (Read); Service Connections (Read, query, & manage)
4. Initial Configurations in Businessmap
API Credentials
To use the integration, you will need a Businessmap API Key of a user with the Account Owner admin privilege. We recommend that you set up and use the API key of a dedicated user for the integration.
Mandatory custom field
The integration requires one mandatory Custom Field in Businessmap, where the Azure Repos branch link is stored for each integrated card. It could be a text or link type custom field.
Every card (bug, feature, etc.) created manually in Businessmap, utilizing the Businessmap to Azure Repos integration, must have a custom field set with branch link.
The custom field name could be as you like, but we will be referring to it as “Branch Link” further in this article. In the image below you see Branch link, Reponame and Pull Request link as custom field names.
Optional custom fields
A text custom field where the Azure project and repository name will be stored.
This custom field is not mandatory, but if you add it to your board and select it for the connection, it will provide an overview of which project and changes this card exactly refers to.
We will be referring to this custom field as “Reponame” further in this article.
A link or text custom field where the URL for the created pull request will be stored.
This custom field is not obligatory, but if you add it to your board, it will provide a single-click connection between a card and its related pull request.
We will be referring to this custom field as “Pull request link” further in this article.
Business Rules
Furthermore, two Business Rules will be created automatically during the configuration process. One business rule is necessary for branch creation, and the other is needed for pull request creation. At a later stage, you can fine-tune the business rules that were created automatically.
5. Configuring the Integration
1. Access the integration’s main application page at: https://solutions.businessmap.io/adoRepo2Bmap
Log in to the application using the Businessmap user API key which will be used for the integration
Note: The integration needs just the subdomain as a Businessmap subdomain value.
For example if you open your businessmap account with this URL: “https://company.kanbanize.com”, your subdomain is “company”.
2. Once logged in, you will see all your existing integrations and be able to create new ones.
3. Edit or delete any of the existing configurations or create "New Connection" providing the required information.
Note: Setting project and repository is only available during the creation/setup of a new integration link!
Creating new connection includes filling the form in multiple steps.
Step 1 - You need to specify the following values:
- Connection Name – The connection name that you use to identify this connection to Azure Repos
- PAT - This is the Azure personal access token used to connect and get data from Azure Repos
- Organization - select organization which repository you want to connect to
- Repository - select the actual repository to link to
- Base branch – The main branch that will be used by the Businessmap to Azure Repos integration to determine which branch to use as base and create a new one, when a card is created in Businessmap.
- Board – The board where the cards will be created.
- Branch link to be saved in this custom field – The name of the “Branch Link” custom field where the link to a branch will be populated when a card creation is linked to a branch via commit.
Fields on all other steps are optional.
Step 2 - you have to fill in details for “Manual Branch Tracking”. Fill-in these options if you want to create cards in Businessmap, directly from commit in Azure repository. Add this command to the commit message in order to create the card in Businessmap: //bmap new
You can to specify the following values:
- Branch cards column – The connection name that you use to identify this connection to Azure Repos
- Branch cards lane - This is the Azure personal access token used to connect and get data from Azure Repos
-
Custom field for repository name - this is the Reponame custom field, which if set will show the exact project and reponame which is linked to this card
This is how to use the above setup to create a card in Businessmap when you make direct commit from VS Code. When you make new commit, just add //bmap new to the commit message and this will create the card in Businessmap
Step 3 - setting up the “Pull Requests” options
You can specify the following values:
- Custom field for pull request links – The Pull Request Link custom field. It will be filled with direct link to the pull request in Azure Repos
- Pull requests completed column - This is the column where the card will be moved to when pull request is merged and closed
The form that follows can be used to set the Rework options. They allow you to set where new card for the additional work will be created if the pull request is rejected.
You can specify the following values:
- Reworks column – This is the column where rework card will be created if pull request is abandoned
- Reworks lane - This is the lane where rework card will be created if pull request is abandoned
- Rework card type - This will set special card type to the rework card
- Rework prefix - Rework card title with be changed to include this prefix at the front
Step 4 - setting up the “Block Configuration” options
You can to specify the following values:
- Block Policy – This will set if the parent card will be blocked if the pull request is rejected
- Block reason - If card is to be blocked, this will set the exact block reason
Step 5 - setting up the Business Rules that trigger the branch and pull request creation in Azure Repos
You can to specify the following values:
- Automatically create business rules – This turns on/off the creation of the Business Rules
- Create branch business rule target column - If card is to be blocked, this will set the exact block reason
- Create Pull Request business rule target column - If card is to be blocked, this will set the exact block reason
After setting the options, the connection will be created when clicking on the “Save” button. Later you can change these values in the Businessmap business rules if you like.
Note: The default configurations are:
- Branch name will be set to: {{cardType}}/{{cardId}}-{{cardTitle}}
- Pull request title will be: “REVIEW {{cardTitle}}” and its body “Pull Request opened from Businessmap”
Note: Once the connection is created, a Business Rules Authorization Token is automatically generated. This token is used for communication from Businessmap to Azure Repos. Do not change it as this will cause the Business Rule to stop working:
6. Use Cases
In this section, we will explore the use cases described in Integration Capabilities sections. At this point, it is assumed that the setup of the integration from the previous sections has been completed and your integration is ready to run.
The main use case is that you use Businessmap as your Product development life cycle (PDLC) solution, where you have a board workflow with multiple columns such as "Development", "Review", "QA Testing", "Deployment", "Ready for Merge", etc ...
On the other hand you have the Azure Repos as your source code control system and you link the commits and automate your branching and merge requests with your day to day tracking of work items, such as Bug, Features, Improvements and Product Releases.
Scenario from Businessmap to Azure Repos
Here is what an example workflow can look like in Businessmap:
1. Create a Branch in Azure Repos when card is moved to a column
To create a branch on a Businessmap card moved event, we create a card in Businessmap backlog column. We then move the card to the column configured in the business rule to create a new branch.
If everything is OK, the branch will be created in Azure Repos and you will see the "Branch link" custom field populated with a new value, pointing to the Branch.
Note: If you have created the “Branch Link” custom field as a Link-type custom field, you will be able to go to the new branch with direct click on the custom field in Businessmap.
Now, if someone makes a new commit, we will see the first comment in the Comments tab of the card.
Note: If you click a link in the comments, you will be forwarded to the correspondent branch, commit, or pull request
2. A Businessmap card moved to a specific column will create a Pull Request in Azure Repos.
Following the previous scenario, when development is finished, we can move the card to trigger the “Pull Request Create” business rule.
If everything is OK, you will see the “Pull Request Link” custom field populated with a new value too and the corresponding Pull Request in your Azure Repos. There will also be a new comment about that.
Note: If you have created the "Pull Request Link" custom field as a link-type custom field, you will be able to go to the Azure Repos Pull Reuqest with one click on the custom field in Businessmap.
Scenario from Azure Repos to Businessmap:
3. Create a card from an Azure Repos commit to a branch that is not yet tracked in Businessmap
To inform the integration that you want to create card in Businessmap that will be linked to the branch you committed, you have to add this command to the commit message line //bmap
The following combinations are valid: //bmap or //businessmap
For the sake of simplicity, we will use only //bmap from now on in this article, but feel free to use the other valid command start.
To create a new card in Businessmap, just add the following message to your commit: //bmap new
A new card will be created in the linked board.
4. Link an existing card from a Azure Repos commit.
To link an existing card in Businessmap, you can use the same method as the one for creating a new card, just add the card id to the commit, instead of "new" as shown below:
//bmap your_card_id
Note: replace your_card_id with a real card id in your account. e.g. 7862
If 7862 is a correct ID of a card and you have access to it, the card with ID 7862 will be linked to the branch where the commit is done.
5. Add comments to a card on commits, branch deletions, pull request comments and state changes (completed, abandoned).
To add comments to a card, the card will need to be linked to an Azure Repos branch or pull request. Previously described use cases 1, 2, 3 or 4 (see above) will generate a comment in the card.
6. On rejected pull request (closed but not merged), the related card will be blocked (if configured), and a rework card will be created as a predecessor of the original card.
To block a related card and create a rework card on abandoned pull request, the card will need to be linked to a pull request as described in use case 2 (see above). This functionality will only work if the block card has been configured previously on the integrations main page as described in Step.4 from section 5. Configuring the integration.
If the reviewer of code in Azure Repos has some comments or issue with the new development, the pull request can be abandoned without merging.
In this case, the card is blocked, a comment is added, and the rework is created as it is set in the configuration.
When rework card is completed and moved to the pull request merge column, the rework card will be moved to pull request completed column, the block from the parent card will be removed and pull request will be reopened.
7. On completed pull request (closed and merged), the related card will be moved to the previously configured column.
To move a related card on finished pull request, the card will need to be linked to an Azure Repos pull request as described in use case 2.
If the reviewer of code in Azure Repos approves and completed the pull request with the new development, the pull request will be closed and card will be send to previously selected column.