With the REST client implementation for the workflow API, you can use a workflow to script a push-style integration with Slack. This integration lets you post notifications to a channel in Slack when a new issue is created in a specific project. In addition, we provide a sample workflow that lets you post notifications to Slack when the priority of an existing issue is raised to High. You can modify this workflow to post notifications for any type of issue update.
This integration uses Incoming WebHooks to enable an integration between Slack and YouTrack. The YouTrack workflow sends a normal HTTP request with a JSON payload that contains the issue ID and summary.
Unlike the Slack integration over XMPP, this integration only lets you post notifications to a channel in Slack. This type of integration does not let users update issues with commands by sending direct messages to a Jabber bot.
To set up this integration with Slack, follow these steps:
The basic setup described here lets you post notifications to a specific channel in Slack when an issue is created in a single YouTrack project. For more complex integrations, see Multi-channel and Multi-project Configurations.
Add a Custom Integration to Slack
This type of Slack integration is enabled on a per-project basis in YouTrack and enabled for a specific channel in Slack.
To add a custom integration:
In Slack, access the channel that you want to integrate with YouTrack.
From the Channel Settings menu, select Add an app or integration.
The App Directory page opens.
Click Build in the page header.
Click Make a Custom Integration.
The Build a Custom Integration page opens.
Select the Incoming WebHooks option.
In the Post to Channel section, select the channel that you want to integrate with YouTrack.
Click the Add Incoming WebHooks Integration button.
The Incoming WebHooks page displays the settings for your integration.
Copy the Webhook URL and paste it into a text editor. In the following procedure, you add this URL to your workflow rules in YouTrack.
Optionally, customize the settings for your custom integration:
Setting
Description
Customize Name
Assign the integration a username.
Customize Icon
Upload a custom image to use for messages from this integration.
Click the Save Settings button.
Customize the Slack Integration Workflow
The next step is to edit the Slack Integration workflow so it sends notifications to your channel in Slack.
This workflow contains two rules: Post New Issues to Slack and Post Priority Change to Slack. This procedure shows you how to customize the rule that posts new issues. For a detailed description of the second rule, see Update Notifications.
From the Workflow menu, select Import Workflow from File.
Select the ZIP archive that you downloaded in step 1.
The workflow is imported into the workflow editor.
Open the Post New Issues to Slack rule in the editor.
Locate the doHttpPost method in the code.
Replace the whole URL with the Webhook URL that you copied from your custom integration in the previous procedure.
From the Workflow menu, select Upload Workflows to Server.
The customized workflows are uploaded to your YouTrack server.
Enable the Slack Integration Workflow in YouTrack
The last step is to attach the Slack Integration workflow to your project in YouTrack.
To enable the Slack Integration workflow:
Open the project that you want to integrate with Slack.
Click the Edit project link.
Select the Workflow tab.
From the Attach workflows list, select Slack-Integration-Generic.
The Slack Integration workflow is attached to your project.
The workflow is enabled and ready for use with your project.
When the setup is complete and the workflow is attached to your project, notification is sent to the channel when an issue is created in the project.
In each notification, the YouTrack issue ID is set as a direct link to the issue in YouTrack.
Update Notifications
The workflow we use for this integration only posts the issue ID, summary, and the color code that indicates the issue priority. If you want to include more information, all you have to do is modify the payload to include more details about each issue.
When you post issue updates to Slack, take a selective approach and post only important updates to the channel. If you spam the channel with too many updates, important discussions are constantly interrupted by the bot.
Our sample workflow includes a rule that sends notification to the channel when the priority of an existing issue is raised to High. The YouTrack development team uses different set of conditions to push notifications to Slack when an issue is added to the current sprint. We offer this rule as an example of just one of may conditions that you can consider for sending update notifications to Slack.
Multi-channel and Multi-project Configurations
The basic setup lets you post updates from a single YouTrack project to a specific channel in Slack. However, you can easily configure this setup for more complex integration scenarios.
One Project, Many Channels
The Slack Integration workflow is scripted to support an integration between one YouTrack project and one channel in Slack. You can add custom integrations to different channels in Slack and add the Webhook URL for each channel to your workflow rules.
The following lines of code in the workflow can be customized to send notifications to multiple channels from a single project:
If you want to send notifications from multiple YouTrack projects to a single channel in Slack, the setup is relatively simple.
Follow the steps described here to add the URL for your Slack channel to the workflow rules.
Attach this workflow to all of the projects you want to report to Slack.
Separate Projects, Separate Channels
In a slightly more complicated setup, you have multiple teams who discuss different projects in separate channels. You want to direct notifications from specific projects to the channels where each team discusses their issues.
The easiest way to handle this situation is to create separate workflows for each project and customize the rules accordingly.
To support this use case:
Create a new workflow in the workflow editor. Give the workflow a name that shows its relationship to the project where it will be applied.
Copy the rules from the Slack Integration workflow and past them to the new workflow.
Update the Webhook URL in the workflow rules to reference the Slack channel that you want to notify in this project.
Repeat steps 1 through 3 for every channel that you want to notify in each project.
Upload the workflows to your server.
Attach each workflow to the project for which it has been customized.
An alternative approach is to add conditional statements to your workflow rules. With conditional statements, you can identify the project that each issue belongs to and send notifications to dedicated channels in Slack. You can then attach the same workflow to all of the projects that are referenced in the workflow and update the same set of workflow rules when you want to enable Slack integration in a new project.
To support this use case, replace the single doHttpPost method with a conditional statement. Use the following sample as a guide:
