YouTrack InCloud 2018.2 Help

YouTrack App for Slack

With the YouTrack app for Slack, you can link your YouTrack InCloud instance to your Slack workspace and get the most out of both applications. Users can divert their YouTrack notifications from email to Slack and view all of their YouTrack updates as direct messages.

The YouTrack app also shows issue previews when the user who posts a link to the issue in Slack authorizes the app to display the content to other users. This lets other users view issue content directly in Slack and determine whether they get all of the information that they need from the preview or need to click the link.

Enable the Integration

For users to take advantage of these features, you must first enable the integration. Before you start, make sure that you meet the following requirements:

  • You need to have permission to add an app to your Slack workspace. A Workspace Owner has the ability to restrict app permissions to Workspace Owners only or Workspace Owners and selected members or groups.

  • Your workspace must allow apps that aren't available in Slack's App Directory. If the Only allow apps from the App Directory option is enabled for your workspace, a Workspace Owner needs to toggle this option off.

To enable the Slack integration:

  1. From the Server Settings section of the Administration menu, select Global Settings.

  2. In the Notifications section of the page, verify that the REST API option is enabled.

    youtrack app rest api
    If this option is disabled, YouTrack cannot send notifications to the YouTrack app.

  3. At the bottom of the page, click the Integrate with Slack link.
    youtrack app integrate with slack
    • You are redirected to a page in Slack that lets you install the YouTrack app.

  4. Select the Slack workspace where you want to install the app from the drop-down list.

    youtrack app select workspace
    You can choose from any workspace that you are currently signed in to or sign in to another workspace.

  5. Click the Install button.
    • The YouTrack app is installed in the selected Slack workspace.

    • The welcome page for the YouTrack app opens.

  6. Open your Slack workspace and select YouTrack from the Apps menu.

    youtrack app finish setup

  7. Click the Let's do this button.
    • The YouTrack app displays a list of permissions that it requires from Slack.

      youtrack app allow actions

  8. Click the Allow button.
    • The YouTrack app requests permissions from Slack.

    • The integration is enabled in the Slack workspace.

Manage Channel Access

To use integration features in a channel, you need to add the app to the conversation. When you enter a slash command or apply a custom action in a channel where the app is not a participant, the slackbot prompts you to perform this action.

youtrack app add to channel

If you want to make the integration widely available, you can grant the app access to all public channels.

To add the app to public channels:

  1. In any message posted by the app, click the app name, then select Settings.

    youtrack app open settings

  2. On the Channel Access page, enable the All public channels option.

    youtrack app join public channels

  3. Click the Allow button to confirm this action.

When the app has access to public channels, the option on the YouTrack Settings page let you perform the following actions:

  • Exclude the app from specific channels.

  • Manually add the app to private channels and conversations.

Authorize the YouTrack App

As the user who enabled the integration, you are already logged in to the YouTrack app. By logging in, the YouTrack app knows exactly which Slack account belongs to you. This lets the app route notifications from YouTrack as direct messages to your Slack account. It also uses your role assignments to determine whether you can post a link to an issue in a project with limited access or with restricted visibility.

All other users need to authorize the app by logging in with their YouTrack account.

To authorize the YouTrack app:

  1. Open your Slack workspace.

  2. Click the Browse apps button in the Apps menu.
    • The Browse Apps window opens.

    youtrack app browse apps
  3. In the In your workspace section of the page, select YouTrack.
    • The YouTrack app is added to the list of apps in your workspace.

  4. From the Apps menu, select YouTrack.

  5. In the message input box, enter the command /youtrack login.
    • The YouTrack app responds with instructions to authorize your YouTrack.

  6. Click the link in the message to request authorization.
    • If you're already logged in to the YouTrack instance that is linked to your workspace, YouTrack authorizes the app.

    • If you're not logged in, the Log in to YouTrack Slack Integration page opens in a new tab. Enter your username/email address and password, then click the Log in button.

When your account is authorized, the welcome page for the YouTrack app opens in a new browser tab. You can close the tab and start working with the app in Slack.

Enable Notifications in Slack

One of the core features of the YouTrack app is the ability to receive YouTrack notifications in Slack. With notifications enabled, all of the messages that are generated and sent by YouTrack are sent to you as direct messages from the app.

To enable notifications, enter the slash command:

/youtrack enable notifications

The app replies with a confirmation message.

youtrack app enable notifications

In this message, you can click the Disable in YouTrack button to disable email and Jabber notifications in your YouTrack profile. This diverts all messages that are sent by YouTrack to your Slack workspace.

Mute YouTrack Notifications

If you ever want a little break, you can mute notifications for half an hour, one day, a week, or even longer. Just enter the slash command:

/youtrack mute [period]

Use the following syntax to specify the period value:

  • Specify minutes with an integer. For example, /youtrack mute 15 mutes notifications for 15 minutes.

  • For longer periods, the full format is 1w2d3h4m.

When muted, any notification that would be sent to your account is ignored. You’ll only start to get notifications after the specified period or by entering the slash command:

/youtrack unmute

When you post a link to a channel, Slack automatically expands most links to display an inline preview. The preview displays basic information about the destination web page. With link previews enabled, the app does the same for issue links.

When you post an issue link to a channel, the preview is attached to the message. The app shows the issue ID and summary as a link and displays the description. For issues with longer descriptions, click the Show more link to display all of the text.

content previews issue links

Be aware that all members of the channel can view the content in the preview, even if they don’t have access to the issue itself. As the user who posts the link, it’s up to you to decide whether you share this information or not. If there are users in the channel who shouldn't see this information, you can click the icon to the left of the preview to remove the attachment from the message.

The ability to display link previews in a message is based on the access profile for your YouTrack account. If you post a link to an issue that you don't have permission to view in YouTrack, the preview is not shown. This behavior blocks unauthorized users from discovering content in private issues.

Create Issue Drafts

The YouTrack app supports a custom action that lets you create an issue draft in YouTrack. The selected message is copied to the description field, so all you need to do is pick a project, enter a summary, set the values for fields, and report the issue.

To create an issue draft:

  1. Move the pointer over the message that you want to copy to an issue.

  2. Click the More actions button in the message toolbar.

  3. Select Create issue draft.
    youtrack app create issue draft
    If this action is not visible in the list, select More message actions, then locate it in the Use an action dialog.
    • The app generates the issue draft in YouTrack and posts a private message to the channel.

    youtrack app issue draft created
  4. Click the link in the private message to open the draft in YouTrack and report the issue.

Slash Commands

For a list of available commands, enter /youtrack. The following commands are available when used with the /youtrack slash command:

Command

Description

enable previews

Enables content previews for issue links.

disable previews

Disables content preview for issue links.

enable notifications

Enables notifications as direct messages from the YouTrack app.

disable notifications

Disables notifications from the YouTrack app.

mute [period]

Mutes notifications from the YouTrack app for the specified period.
  • Specify minutes with an integer. For example, /youtrack mute 15 mutes notifications for 15 minutes.

  • For longer periods, the full format is 1w2d3h4m.

unmute

Unmutes notifications from the YouTrack app.

login

Initiates an authorization request from the app to your YouTrack account. The app replies to this command with an authorization link that you can use to log in.

logout

Logs you out of the YouTrack app. When logged out, all of the features that are supported by the app are unavailable.

Last modified: 9 October 2018