YouTrack Server
 
2019.2
Get YouTrack Standalone
You are viewing the documentation for an earlier version of YouTrack Server. View this page in the current documentation
  1. Administration
  2. External Integrations
  3. Confluence Integration

Confluence Integration

Last modified: 17 December 2019

This integration adds the following macros to your Confluence installation:

Macro

Description

Issue

Inserts a link to a YouTrack issue into a page in Confluence. The link reflects the issue state.

Report

Lets you insert a list of YouTrack issues that match a query to a page in Confluence.

Create

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

note

Availability

  • The latest version of the YouTrack Integration add-on is supported by Atlassian Confluence Server versions 6.1.0 and later.

  • Older versions of the add-on are available for Atlassian Confluence Server versions 3.5 and later, but do not contain support for the Create macro.

The instructions on this page are relevant to Confluence version 6.1.0.

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

note

For additional information, refer to the documentation for the Atlassian Universal Plugin Manager.

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:

    Setting

    Description

    YouTrack host REST address

    Enter 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 attempts

    Determines 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 base

    Overrides the address that is specified as the YouTrack host REST address for links to issues in YouTrack.

    Ignore YouTrack SSL certificate check

    When 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 info

    When 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 Login 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 login and password.

  4. Click the Save Settings button.

    • The add-on is ready for use.

Insert a Dynamic Link to an Issue

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:

Setting

Description

id

Stores 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-template

Stores 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:

Setting

Description

project

Limits issues in the report to a single project. Enter the project ID.

query

Specifies which issues are shown in the report.

reportFields

Determines which fields and issue attributes are shown as columns in the table.

pageSize

Determines how many issues are listed on a single page in the report.

numPages

Sets 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:

Setting

Description

projectId

Sets the project in which the new issue is created.

summary

Sets the summary for the new issue.

description

Adds 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-template

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