In this article:
1. Introduction
2. Integration Capabilities
3. Configuration Process
4. Use Cases
4.1. Card is created
4.2. Comment is added
4.3. Create a card (default)
4.4. Create a card (custom)
4.5. Create a card (last)
4.6. Add as comment
4.7. Add a comment to a card using a post (command)
4.8. Add a comment to a card using a thread (mention + command)
1. Introduction
This article describes the integration between Slack (https://slack.com/) and Businessmap (https://businessmap.io). A potential reader is expected to be familiar with Businessmap (boards, cards, business rules, etc.) and Slack (channels, messages, apps, etc.).
However, if you have any questions or encounter some difficulties along the way, do not hesitate to contact our Support team at support@businessmap.io
2. Integration Capabilities
The integration is bi-directional. It offers the following capabilities:
From Businessmap to Slack
1. Card is created — Post a message to a Slack channel when a new card is created in Businessmap.
2. Comment is added — Post a message to a Slack thread when a comment is added to a card in Businessmap.
From Slack to Businessmap
3. Create a card (default) — A quick and easy way to create a card specifying only the board, title, and description of the card. The created cards go to the “Backlog” column.
4. Create a card (custom) — A more customizable way to create a card, allowing you to specify the board, workflow, column, lane, priority, title, and description of the card.
5. Create a card (last) — Create a card based on the last card configured using the “Create a card (custom)” option.
6. Add as comment — Add a message as a comment to a card.
7. Add a comment to a card using a post (command) — Add a comment to a card in Businessmap from a Slack post.
8. Add a comment to a card using a thread (mention + command) — Add a comment to a card in Businessmap from a Slack thread.
Note: By default, the message content is populated in the “Description” field.
3. Configuration Process
Step 1: You need to install the application into your Slack domain from this URL:
https://license.kanbanize.com/tools/slack2knb/
Step 2: Click the “Add to Slack” button and it will redirect you to Slack to grant the needed permissions for the application.
Img. 1
Step 3: On the Slack web page, select the Slack domain that you want to install the application to and click on “Allow” to grant the necessary permissions for the application to work.
Img. 2
Step 4: Once the app has been added to your Slack domain, it will automatically redirect you to the Slack App. If you do not have the Slack app, you can click the link in the message to open the browser version of Slack.
Img. 3
Step 5: You should now be able to see the Businessmap app (formerly Kanbanize) in the Apps section on the left side menu. Select it and navigate to the “Home” tab.
Img. 4
Step 6: Select “Set Businessmap Credentials” and configure the connection settings. You need to populate the subdomain and an API key.
Your subdomain is the first part of your URL, e.g. subdomain.kanbanize.com. To get the API key, go to your account, click on the user dropdown menu from the top right corner, and select API key. Any user with permissions to create cards in Businessmap can use their own API key.
If you would like to configure the connection settings for your entire Slack organization, you can check the “Global Businessmap logins” checkbox.
Img. 5
If the logins have been set successfully, you should see a confirmation message in the "Messages" tab of your Businessmap app.
Img. 6
Note: All users in the Slack organization who want to create cards in Businessmap directly from Slack need to perform steps 1 to 5 above. If global logins are set for the Slack organization, users do not need to set their own logins.
Step 7: (Optional) You can also modify the fields to populate when creating custom cards from the “Settings” section on the “Home” tab. Click on “Fields Options.” This will open a pop-up window, where you can select the additional fields.
Img. 7
Once you are happy with your selection, click “Submit.” If the fields have been set successfully, you should see a confirmation message in the “Messages” tab of your Businessmap app.
Img. 8
Step 8: (optional) Invite the Businessmap Slack App to your channel so you can receive messages from it and send notes back. This needs to be done for all channels integrated with Businessmap. This can be done by opening the channel and typing a message “/invite @Businessmap"
Img. 9
If successful, you should get the following message in the channel.
Img. 10
Step 9: (optional) If you would like to use the integrations' capability from Businessmap to Slack, you will need to specify a custom field to store the Slack thread ID. Click on “Connect Businessmap to Slack” and select a custom field from the dropdown.
Img. 11
Note: This field should be added to the board where cards will be created.
4. Use Cases
In this section, we will explore the use cases described in the Integration Capabilities section. 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.
4.1. Card is created
To post a message to a Slack channel when a new card is created in Businessmap, you will need to set up a business rule in Businessmap. Start with creating a Card is created Business Rule. Set up “Invoke web service” to trigger the message post to a predefined channel.
Img. 12
Note: All parameters are required and must be set in order to connect Businessmap to Slack and post a message about new cards.
Field* | Value | Description |
---|---|---|
Name | Send message to Slack on newly created card | customizable name of the web service call |
URL | https://kipus.kanbanize.com/slack/card | must be set exactly like that |
Method | POST | must be set exactly like that |
Authentication | API KEY | must be set exactly like that |
API KEY header name | token | must be set exactly like that |
API KEY header value | xxxxxx | must be copy/pasted exactly as it is from the Businessmap Slack App |
Send the parameters in the body of the web service call | checked | must be checked |
team | Txxxxx | The team id is the part of the browser URL that starts with "T", i.e. "T03G8KTU813" |
channel | Cxxxxx | The channel id is the part of the browser URL that starts with "C", i.e. "C03GDUD0GHJ" |
user | Uxxxxx | Click on the three dots within your profile and select “Copy Member ID” |
cardId | xxxxxx | Select “Card Id” from the parameter options |
text | New card created (Card Id) Title | The customizable message you want to post to Slack |
Note: To add a link to the Businessmap card in your Slack message, the link must be set up in a format recognized by Slack. This is the correct format:
<https://{YourSubdomain}.kanbanize.com/ctrl_board/{BoardId}/cards/{CardId}|{Link}>
- {YourSubdomain} — Set your subdomain;
- {BoardId} — This is the selected “Board ID” option from the available Businessmap parameters;
- {CardId} — This is the selected “Card Id” option from the available Businessmap parameters;
- {Link} — This is a custom text which will be turned into a link;
4.2. Comment is added
Post a message to a Slack thread when a comment is added to a card in Businessmap.
To post a message to a Slack thread when a comment is added to a card in Businessmap, you will need to set up a business rule in Businessmap. Start with creating Card is updated Business Rule. Set it up to trigger when there is a new comment "Comment (new)". Make sure that the rule is NOT triggered if the added comment starts with "Slack:", which will ensure the rule will not activate when a comment is added from Slack, thus creating a loop. Set up "Invoke web service" to trigger the message post to a predefined Slack channel.
Img. 13
Img. 14
Note: All parameters are required and must be set in order to connect Businessmap to Slack and post a comment to a Slack thread.
Field* | Value | Description |
---|---|---|
Name | Send comment to Slack | customizable name of the web service call |
URL | https://kipus.kanbanize.com/slack/comment | must be set exactly like that |
Method | POST | must be set exactly like that |
Authentication | API KEY | must be set exactly like that |
API KEY header name | token | must be set exactly like that |
API KEY header value | xxxxxx | must be copy/pasted exactly as it is from the Businessmap Slack App |
Send the parameters in the body of the web service call | checked | must be checked |
team | Txxxxx | The team id is the part of the browser URL that starts with "T", i.e. "T03G8KTU813" |
channel | Cxxxxx | The channel id is the part of the browser URL that starts with "C", i.e. "C03GDUD0GHJ" |
thread_ts | Slack Thread ID | Select the custom field parameter option which matches the one set in the Businessmap Slack App |
text | Last Comment | Select “Last Comment” from the parameter options |
4.3. Create a card (default)
To create a card using the default method, select the three dots next to the message you want to use as your card description and select the “Create a card (default)” option.
Img. 15
Img. 16
This will open another pop-up window where you can select the board and title, and also check and modify the description of the card.
Img. 17
The created cards will go to the “Backlog” column in the “Cards Workflow” on the board you chose.
4.4. Create a card (custom)
To create a card using the custom method, select the 3 dots next to the message you want to use as your card description and click on the “Create a card (custom)” option (see Img. 15 and Img. 16).
This will open a series of pop-up windows where you can select the board and workflow and configure the card. The dropdown values are dynamically provided based on the board and workflow you selected.
Img. 18
Img. 19
The last pop-up window will let you configure the “Column,” “Lane,” “Priority,” and “Title” of your card. You can also check and modify the “Description” of your card.
Img. 20
When you are happy with the configuration, click on the “Create” button and you will be able to see your newly created card in the board, workflow, column, and lane you selected.
4.5. Create a card (last)
Creating a card with the “last” method can only be used after the “Create a card (custom)” method has been used at least once. To create a card using the last method, select the 3 dots next to the message you want to use as your card description and pick the “Create a card (last)” option (see Img. 15 and Img. 16).
This will open a pop-up, where you can see the board, workflow, column, and lane of the previously created card using the custom method and specify the “Priority” and the “Title” of the new card you want to create. You can also check and modify the “Description” of your card.
Img. 21
When you have configured the priority, title, and description, click the “Create” button and you will be able to see your newly created card in the same board, workflow, column, and lane as your previously created card.
4.6. Add as comment
To add a message as a comment to a card, select the three dots next to the message you want to use as your card description and select the “Add as comment” option.
Img. 22
Img. 23
This will open a pop-up window where you can select the card you want by ID or title. You can also make modifications to the message.
Img. 24
When you are happy with the configuration, click on the “Create” button and you will be able to see your newly created comment in the card you selected.
4.7. Add a comment to a card using a post (command)
Adding a comment to a card using the command can be done using the command "/bmcomment". Open a channel where the Businessmap Slack Bot has been invited and enter the command, the card ID where you want your comment to be posted, and the comment text.
Img. 25
4.8. Add a comment to a card using a thread (mention + command)
Adding a comment to a card in Businessmap from a Slack thread can be done using a mention of the Businessmap Slack app and the command “/bmcomment”. Open a thread and enter “@Businessmap /bmcomment 1234 Comment Text”.
Img. 26