If your Confluence instance is connected to Jira, you can search and display Jira issues in a list on Confluence pages. You can then customize the display to add, remove, and reorder fields.
Make changes to your search with keywords, filters, or JQL (Jira Query Language).
If you’re an Atlassian Marketplace user, you may be looking for help on using the legacy Jira issue macro.
You can paste a link to a single Jira issue using Smart Link display options.
Insert Jira issues
Edit a Confluence page or create a new one. You have 3 options to insert Jira issues:
Option 1
Select from the toolbar and select Jira issues:
Option 2
While editing a page, type /jira and select Jira issues:
Option 3
You have the option to search for issues in Jira and paste the search filter URL into a Confluence page.
Search for issues
Start inserting Jira issues by using filters with basic keyword search or with JQL.
Learn how to search for Jira issues using JQL (Jira Query Language).
BASIC is selected by default. With this option, you can use filters and keywords to search for issues.
If you select JQL, enter your query or search keywords. For example, project = 'Starfish'
Select COUNT VIEW if you want to display just the number of issues.
Select Insert issues.
Manage field columns
Once your Jira issues are displayed as a list, you can drag columns to move them around. Choose the columns you want to appear by selecting the column icon .
Edit your issues
If you need to make changes to your search query, select the pencil icon at the bottom of the list.
Resize the width of the list by selecting the expand icon from the side.
Using the Jira legacy macro for Marketplace app users
Using the Jira macro, you can:
Display alist of issues on your page, based on aJira Query Language (JQL)search, filter or URL.
Display a single issue.
Display acountof issues.
Create new issues and display the issues on your page without leaving Confluence.
Use the Jira legacy macro
To add the Jira legacy macro:
When editing, select from the toolbar
Find the macro by name and select it
Configure it as needed
You can also type/ on the page to bring up the same list you'd see by selectingfrom the toolbar. Continue typing the name of the macro to filter the list.
To edit the Jira legacy macro:
Select the macro placeholder.
Selectthe Edit icon to open the configuration panel.
Configure the parameters. Your changes are saved as you go.
Resume editing the page, and the panel closes.
You can also select the centered , medium-width , and full-width icons to adjust the width of some macros. Select the trashcan iconto remove the macro.
Displaying issues via a Jira Query Language (JQL) search
You can use the macro to display alistof issues on your page, based on the results of a search usingJira Query Language (JQL).
JQL is a simple query language that is similar to SQL. A basic JQL query consists of a field, followed by an operator (such as = or >), followed by one or more values or functions.
Examples:
The following query will find all issues in the 'TEST' project:
1234project = "TEST"The following query will find all issues in the 'documentation' component of the 'CONF' project:
1234project = CONF and component = documentation
For more information about JQL syntax, see Advanced searching in the Jira documentation.
To display a list of issues based on a JQL search:
Insert the Jira macro onto your Confluence page, as described above.
Choose a Jira instance next to the Search button.
If prompted, log in to the Jira instance.
Enter the JQL query into the Search box.
Select Search.
If you want to customize the display, select Display options and adjust the columns and number of issues that will appear in your list of issues.
Select Insert.
Displaying issues via a Jira URL
You can paste any of the following Jira application URLs into the Jira Issues macro. Confluence will immediately convert the URL to a JQL search.
Any URL for an issue search or filter.
A URL for a single issue.
The URL of the XML view of a search.
Auto-convert: You can paste URLs directly into the Confluence editor (without calling up the macro browser). Confluence will automatically convert the URL into a Jira Issues macro.
Displaying a single issue, or selected issues
To display a single Jira issue, choose one of the following methods:
Paste the URL of the issue directly onto the Confluence page. (There is no need to use the macro browser.) Confluence will auto-convert the link to a Jira Issues macro.
Or: Add the Jira issues macro to the page as described above, and choose Recently Viewed to see the issues you have visited recently. Select an issue and chooseInsert.
Or: Add the Jira issues macro to the page as described above, and paste the issue URL into the search box in the macro browser.
Or: Add the Jira issues macro to the page, define your search criteria in the macro browser via JQL as described above, then select the check box next to the issue in the search results, within the macro browser.
You can choose to show just the issue key, or the issue key and a summary. Select the macro placeholder and choose Show Summary or Hide Summary.
To display a subset of Jira issues from your search results:
Add the Jira issues macro to the page.
Define your search criteria in the macro browser via JQL, as described above.
Select the check boxes next to the required issues in the search results, within the macro browser.
Displaying a count of issues
You can choose to display the number of issues returned by your search, rather than a list of issues. The Jira Issues macro will display a count of issues, linked to the search in your Jira application.
To display an issue count:
Add the Jira Issues macro to the page.
Define your search criteria in the macro browser via JQL, as described above.
Select Display options, then select Total issue count next to 'Display options' in the macro browser.
Select Insert.
Creating anew issue
While editing a Confluence page, you can create an issue in Jira and display it on your Confluence page, without leaving the Confluence editor.
To create an issue and add it to your page:
Add the Jira Issues macro to the page, as described above.
Select Create New Issue.
Supply the information about your Jira instance, project, and issue, as prompted.
Select Insert.
Confluence will send a request to your Jira application, to create the issue, then display the newly created issue on your page.
Limitations
The Jira legacy macro will notify you if it is unable to create an issue in the selected project. This may be because the project has a required field, field configuration or other customizationthat is not supported by the Jira legacy macro. In this situation you will need to create the issue directly in your Jira application.
Rendering HTML from Jira applications
Formatted fields from Jira can be displayed in Confluence if you set up a Confluence-to-Jira application link. Otherwise, such formatted fields will be escaped within the output of the Jira legacy macro.This is to prevent the possibility of malicious HTML being served by an untrusted Jira instance. The most likely field where you will notice this is in the description field.
Disabling the Jira legacy macro
Apps cannot be disabled in Atlassian Cloud applications. To stop using an app, you must either uninstall, or unsubscribe, which cancels your subscription to the app.
