YouTrack Server 2023.3 Help

Confluence Integration

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.

Issue List

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

Install and Configure the Add-on

The YouTrack Integration app enables the integration features in your Confluence installation.

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

To install the app:

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

  2. Click the Find new apps link at the top of the page.

  3. Search the Marketplace for the YouTrack Integration app and install it.

    Find new addons

Next, configure the settings for the app.

To configure the app:

  1. Open the Manage apps page, then select the YouTrack Integration app.

  2. Click the Configure button.

    • The YouTrack Integration Plugin Settings page opens.

    YouTrack Integration plugin settings.

  3. Enter values for the following settings:

    Setting

    Description

    YouTrack site

    Enter the base URL for your YouTrack.

    For YouTrack Cloud instances hosted on myjetbrains.com, your base URL includes the trailing /youtrack.

    For example:

    • https://yourcompany.youtrack.cloud
    • https://yourcompany.myjetbrains.com/youtrack

    REST API endpoint

    Enter a URI that points to the REST endpoint for your YouTrack installation.

    Use only when your Confluence site is unable to connect to the YouTrack backend using the base URL.

    Ignore 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 only when your YouTrack SSL certificate is not recognized by your Confluence instance.

    Enable debug level

    When enabled, the macros that are supported by the app write detailed information to Confluence logs.

    Access token

    Enter a permanent token that grants authorized access to your YouTrack site. The permanent token authorizes the app 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.

  4. Click the Save Settings button.

    • The app 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:

Setting

Description

Issue ID

Stores the ID of the issue in YouTrack.

Style

Determines the presentation of the issue link.

  • When Compact, 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.

Resolved issue presentation

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

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

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

  • When Unchanged, the presentation for resolved issues the same as unresolved issues.

Template

Stores a string of text that is shown for each issue link. The template supports a collection of placeholders for various issue attributes. These placeholders are replaced by the respective value for each issue when shown on the Confluence page.

For example, if you enter the following string into the Template field:

$issue $State fix before $Due_Date

The link for a specific issue would look like this:

Link presentation for a YouTrack issue.

The following placeholders are supported:

  • $issue - displays the issue ID.

  • $summary - displays the issue summary.

  • $description - displays the issue description.

  • $[field_name] - displays the value for the corresponding custom field.

    Enter the name of the custom field as shown in the YouTrack issue, replacing space characters with underscores.

The following example shows a link to an unresolved issue:

Link to a resolved 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 List of Issues

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 ID

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

Query

Specifies which issues are shown in the report.

Issue fields

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

Issues per page

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

Max pages

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}

Macro that shows an embedded list of YouTrack issues.
Last modified: 22 March 2024
External IntegrationsSlack Integration