YouTrack Standalone 2018.2 Help

Slack Integration

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.

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.

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:

  1. Add a Custom Integration to Slack
  2. Customize the Slack Notifications Workflow
  3. Enable the Slack Notifications Workflow in YouTrack

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:

  1. In Slack, access the channel that you want to integrate with YouTrack.

  2. From the Channel Settings menu, select Add an app.
    slackIntegrationAddApp

    • The App Directory page opens in your web browser.

  3. Click Build in the page header.
    slackIntegrationBuild

    • The Slack API page opens.

  4. Click the Start Building button.
    slack integration start building

    • The Your Apps page opens.

  5. Click the Create an App button.
    slackIntegrationCustom

    • The Create a Slack App dialog opens.

      create slack app dialog

  6. Complete the fields in the form:

    • In the App Name field, assign a name to the integration.

    • From the Development Slack Workplace drop-down list, select the channel that you want to integrate with YouTrack.

  7. Click the Create App button.

    • The new app opens to the Basic Information page.

  8. In the Add features and functionality section of the page, click Incoming Webhooks.
    slack integration basic info

    • The Incoming Webhooks page opens.

  9. Toggle the Activate Incoming Webhooks option to On.

    slackIntegrationIncomingWebhooks

  10. Scroll to the bottom of the page and click the Add New Webhook to Workspace button.

    add new webhook

  11. From the Post to drop-down list, select the channel that you want to integrate with YouTrack.

    slack integration post to channel

  12. Click the Authorize button.

    • A WebHook URL is added to your workspace.

  13. Click the Copy button to copy the Webhook URL to your clipboard.

    slackIntegrationWebhookURL
    In the following procedure, you add this URL to your workflow rules in YouTrack.

  14. Optionally, customize the settings for your custom integration:

  15. 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.

slackIntegrationSettings

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:

  1. From the Project-related Settings section of the Administration menu, select Workflows.

  2. Locate the Slack Notifications workflow that you want to modify and click its name in the list.

    • The workflow opens in the Workflows page.

  3. Click the send-to-slack link in the left menu.

    • The send-to-slack rule opens in the workflow editor.

  4. 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.

  5. 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:

  1. Open the project that you want to integrate with Slack.

  2. Click the Edit project link.

  3. Select the Workflow tab.

  4. From the Attach workflows drop-down list, select Slack Notifications.

    • The Slack Integration workflow is attached to your project.

  5. 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.

slackIntegrationNewIssue

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:

var sendTo = function(hook) { var connection = new http.Connection(hook, null, 2000); var 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.

  1. Follow the steps described here to add the URL for your Slack channel to the workflow rules.

  2. 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:

  1. 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.

  2. Copy the rule from the Slack Notifications workflow and add them as an on-change rule to the new workflow.

  3. Update the Webhook URL in the workflow rule to reference the Slack channel that you want to notify in this project.

  4. Save your changes in the workflow editor.

  5. Repeat steps 1 through 4 for every channel that you want to notify in each project.

  6. 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:

var 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]) { var connection = new http.Connection(hooks[issue.project.key], null, 2000); var 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!'); }
Last modified: 7 March 2019
HipChat IntegrationLanguage Support