YouTrack Standalone 2021.1 Help

Confluence Integration

This integration adds the following macros to your Confluence installation:

MacroDescription
IssueInserts a link to a YouTrack issue into a page in Confluence. The link reflects the issue state.
ReportLets you insert a list of YouTrack issues that match a query to a page in Confluence.
CreateCreates a new issue in YouTrack and embeds a dynamic link into the page in Confluence. The formatting that is applied to the link text lets you track the issue state.

Install and Configure the Add-on

The YouTrack Integration add-on enables the integration features in your Confluence installation.

To install the add-on:

  1. From the Confluence Administration menu, select Add-ons.

  2. Click the Find new add-ons link at the top of the page.

  3. Search the Marketplace for the YouTrack Integration add-on and install it.

    Find new addons

Next, configure the settings for the add-on.

To configure the add-on:

  1. Open the Manage add-ons page, then select the YouTrack Integration add-on.

  2. Click the Configure button.

    • The YouTrack Integration Settings page opens.

    YouTrack Integration settings
  3. Enter values for the following settings:

    SettingDescription
    YouTrack host REST addressEnter the base URL for your YouTrack installation, followed by /rest/. For YouTrack InCloud instances, your base URL includes the trailing /youtrack. For example:
    https://yourcompany.myjetbrains.com/youtrack/rest/
    Number of consecutive connection attemptsDetermines the maximum number of consecutive attempts that Confluence will take to load information from YouTrack. If Confluence reaches this number without establishing a connection, an error is shown.
    Link baseOverrides the address that is specified as the YouTrack host REST address for links to issues in YouTrack.
    Ignore YouTrack SSL certificate checkWhen enabled, Confluence does not check for the SSL certificate for your YouTrack server when it tries to establish a connection. Use when your YouTrack SSL certificate is not recognized by your Confluence instance.
    Log extended debug infoWhen enabled, the macros that are supported by the add-on write detailed information to Confluence logs.
    Use token authorization

    When enabled, authorization with YouTrack is established with a permanent token. The permanent token authorizes the add-on on behalf of the user that generates the token. To learn how to generate a permanent token for your account, see Create a Permanent Token.

    Confluence users are only able to add links, reports, and create issues in projects that are accessible to this user. For best results, use an account that has a high level of access in YouTrack.

    When disabled, the integration settings display input fields for a Username and Password. You can authorize the add-on with the credentials for a user account in YouTrack.

    We strongly recommend that you use token authorization, as it is usually more secure than a combination of username and password.

  4. Click the Save Settings button.

    • The add-on is ready for use.

To insert a dynamic link into a Confluence page, use the Issue macro with the following format: {issue:id=<issueID> }. The visual presentation of the link reflects the status of the issue.

  • Links to unresolved issues are shown in normal text.

  • Links to resolved issues are shown with strikethrough text.

Use the following settings to define the issue link:

SettingDescription
idStores the ID of the issue in YouTrack.
style

Determines the presentation of the issue link.

  • When short, shows only the issue ID.

  • When detailed, shows the issue ID and summary.

With either presentation style, the issue ID shows values for key custom fields and issue attributes in a tooltip.

strikethru-resolved

Determines the presentation for issue links when the issue is resolved.

  • When all, the issue summary (if visible) and issue ID are presented in strikethrough text when the issue is resolved.

  • When issueId, only the issue ID is presented in strikethrough text for resolved issues.

  • When none, the presentation for resolved issues is unchanged.

link-text-templateStores the $issue placeholder for that identifies the link as a reference to an issue. This setting cannot be modified.

The following example shows a link to a resolved issue:

Link to issue

When you move the pointer over this link, a tooltip displays additional information. This includes the issue summary, reporter, priority, state, assignee, votes, and type.

Use these links to aggregate a collection of issues that are related to the content on your Confluence pages.

Insert a Report

To insert a list of issues that match a query in YouTrack, use the Report macro in the following format: {report:project=<projectID>|query=<search query>}

Use the following settings to define the report:

SettingDescription
projectLimits issues in the report to a single project. Enter the project ID.
querySpecifies which issues are shown in the report.
reportFieldsDetermines which fields and issue attributes are shown as columns in the table.
pageSizeDetermines how many issues are listed on a single page in the report.
numPagesSets the number pages that you can click through in the report.

The following example shows a list of unresolved issues from the DOC project: {report:project=DOC|query=#Unresolved}

Report

Create an Issue

To insert a list of issues that match a query in YouTrack, use the Create macro. The visual presentation of the link reflects the status of the issue.

  • Links to unresolved issues are shown in normal text.

  • Links to resolved issues are shown with strikethrough text.

Use the following settings to define the new issue:

SettingDescription
projectIdSets the project in which the new issue is created.
summarySets the summary for the new issue.
descriptionAdds a description to the new issue.
style

Determines the presentation of the issue link.

  • When short, shows only the issue ID.

  • When detailed, shows the issue ID and summary.

With either presentation style, the issue ID shows values for key custom fields and issue attributes in a tooltip.

strikethru-resolved

Determines the presentation for issue links when the issue is resolved.

  • When all, the issue summary (if visible) and issue ID are presented in strikethrough text when the issue is resolved.

  • When issueId, only the issue ID is presented in strikethrough text for resolved issues.

  • When none, the presentation for resolved issues is unchanged.

link-text-templateStores the $issue placeholder for that identifies the link as a reference to an issue. This setting cannot be modified.

Each time you modify the macro after saving the Confluence page, a new issue is created.

Last modified: 08 March 2021