With the http module from the workflow API, you can use workflows to script push-style integrations with Slack. This type of integration lets you post notifications to Slack for specific issue events.
The workflow-based 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.
This integration only lets you post notifications to Slack. This type of integration does not let users update issues with commands by sending direct messages to a bot account.
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 for issue events 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.
Open the Details panel, then select Add apps from the More menu.
The Add apps dialog opens in your Slack workspace.
Click the Manage apps link in the header.
The Slack App Directory page opens in your web browser.
Click Build in the page header.
The Slack API page opens.
Click the Create New App button.
The Create a Slack App dialog opens.
Complete the fields in the form:
In the App Name field, assign a name to the integration.
From the Development Slack Workplace list, select the channel that you want to integrate with YouTrack.
Click the Create App button.
The new app opens to the Basic Information page.
In the Add features and functionality section of the page, click Incoming Webhooks.
The Incoming Webhooks page opens.
Toggle the Activate Incoming Webhooks option to On.
Scroll to the bottom of the page and click the Add New Webhook to Workspace button.
The webhook is generated.
The page opens to a form that lets you choose where the integration posts messages in your workspace.
From the list, select the channel that you want to integrate with YouTrack.
Click the Allow button.
A WebHook URL is added to your workspace.
Click the Copy button to copy the Webhook URL to your clipboard.
In the following procedure, you add this URL to your workflow rules in YouTrack.
Optionally, customize the settings for your custom integration:
Click the Save Settings button.
There are additional settings you can customize on the Basic Information page for your app. These settings affect the appearance of the account that posts notifications to your channel.
The following settings are available in the Display Information section of the page:
Setting
Description
App name
Lets you customize the name that is displayed for notifications that are posted by the integration.
Short description
Lets you explain why this account is posting notifications to the channel.
App icon & Preview
Displays a custom image in notifications from this integration.
Background color
Customizes the background color.
Customize the Slack Notifications Workflow
The next step is to edit the default Slack Notifications workflow so it sends notifications to your channel in Slack.
To customize the Slack Notifications workflow:
From the Administration menu, select Workflows.
Locate the Slack Notifications workflow that you want to modify and click its name in the list.
The workflow opens in the Workflows page.
Click the send-to-slack link in the left menu.
The send-to-slack rule opens in the workflow editor.
Locate the variable declaration for the SLACK_WEBHOOK_URL and replace the value with the Webhook URL that you copied from your custom integration in the previous procedure.
Click the Save button in the workflow editor.
Your changes are applied to the script.
Enable the Slack Notifications Workflow in YouTrack
The last step is to attach the Slack Notifications 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 Notifications.
The Slack Integration workflow is attached to your project.
If the requires setup label is shown next to the workflow, click the Configure project button in the sidebar to resolve any errors.
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, resolved, or reopened in the project. If you want to include other events that are important to your team, you can easily customize this notification scheme.
In each notification, the YouTrack issue ID is set as a direct link to the issue in YouTrack.
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 rule.
To customize the workflow rule to support this case, modify the block of code that establishes a connection and sends the notification. Use the following sample as a guide:
const sendTo = function (hook) {
const connection = new http.Connection(hook, null, 2000);
const response = connection.postSync('', null, JSON.stringify(payload));
if (!response.isSuccess) {
console.warn('Failed to post notification to Slack. Details: ' + response.toString());
}
}
sendTo('https://hooks.slack.com/services/T00000001/B000000001/XXXXXXXXXXXXXXXXXXXXXXXX');
sendTo('https://hooks.slack.com/services/T00000002/B000000002/XXXXXXXXXXXXXXXXXXXXXXXX');
sendTo('https://hooks.slack.com/services/T00000003/B000000003/XXXXXXXXXXXXXXXXXXXXXXXX');
Many Projects, One Channel
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 rule from the Slack Notifications workflow and add them as an on-change rule to the new workflow.
Update the Webhook URL in the workflow rule to reference the Slack channel that you want to notify in this project.
Save your changes in the workflow editor.
Repeat steps 1 through 4 for every channel that you want to notify in each project.
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, add a conditional statement that associates each project with a specific channel. Use the following sample as a guide:
const hooks = {
ctx.Project1.key: 'https://hooks.slack.com/services/T00000001/B000000001/XXXXXXXXXXXXXXXXXXXXXXXX',
ctx.Project2.key:'https://hooks.slack.com/services/T00000002/B000000002/XXXXXXXXXXXXXXXXXXXXXXXX'
};
if (hooks[issue.project.key]) {
const connection = new http.Connection(hooks[issue.project.key], null, 2000);
const response = connection.postSync('', null, JSON.stringify(payload));
if (!response.isSuccess) {
console.warn('Failed to post notification to Slack. Details: ' + response.toString());
}
} else {
console.warn('Project ' + ctx.project.key + ' does not have an associated Slack hook!');
}
