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. |
| 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. |
Install and Configure the Add-on
The YouTrack Integration add-on enables the integration features in your Confluence installation.
To install the add-on:
From the Confluence Administration menu, select Add-ons.
Click the Find new add-ons link at the top of the page.
Search the Marketplace for the YouTrack Integration add-on and install it.
Next, configure the settings for the add-on.
To configure the add-on:
Open the Manage add-ons page, then select the YouTrack Integration add-on.
Click the Configure button.
The YouTrack Integration Settings page opens.
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 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.
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.
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.
|
| 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:
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}
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.
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.
|
| 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.