Page History

JIRA is the issue tracking and project management system supplied by Atlassian. The JIRA Issues macro allows you to display a list of issues from a JIRA site on a Confluence page.

This macro allows you to list publicly accessible issues from any JIRA site, as well as issues restricted to your user account on a JIRA site, assuming:

• You are logged in to both the JIRA and Confluence sites, and
• Your usernames on both of these sites match.

You can also create, find and insert JIRA issues directly within text on a Confluence page or blog post. For more information, refer to Inserting JIRA Issues.

Screenshot: Example of JIRA Issues shown on a Confluence page

On this page:

Usage with the Macro Browser

To insert the JIRA issues macro into a page using the Macro Browser,

Usage with the Wiki Markup Editor

To show a list of issues from any JIRA site to which you and your readers have access, the syntax is:

{jiraissues:<URL of the XML view of a search conducted on any accessible JIRA site>}

OR:

{jira:<URL of the XML view of a search conducted on any accessible JIRA site>}

Refer to the instructions below for details on obtaining this URL.

Displaying a List of JIRA Issues from any accessible JIRA site

Step 1 — Obtain the URL of the Issue Filter

1. Log in to your JIRA system.
2. Go to the 'Issues' screen and create a new filter. Do not modify an existing filter.
   This is the 'Find Issues' screen in JIRA 3.13.x and earlier.
3. Set up your search parameters and use 'View' to check the issues returned.
4. Once the filter is finished, go to the Filter's 'View' tab/section in the top-left area of the JIRA interface.
5. Copy the XML link. To do this, follow the appropriate steps below:
   • If you are using JIRA 4.0.x or later:
     • Click the 'Views' menu and use this menu to copy the XML link to your clipboard. For example, right-click the 'XML' menu item and choose the right-click menu option for copying that link.
   • If you are using JIRA 3.13.x or earlier:
     1. Locate the 'Current View' links section (see example below) and find the 'XML' link.
     2. Copy the 'XML' link to your clipboard.

Step 2 — Embed the Issue Filter URL onto your Confluence Page

1. Log in to your Confluence system.
2. Edit the page where you wish to display the list of JIRA issues.
3. Type the following text into a new line at the appropriate location:

   Code Block
   {jira:CONTENT}

4. Replace 'CONTENT' with the JIRA filter URL from your clipboard.
5. Customise the macro output by adding optional parameters. See below.
6. Save the Confluence page.

Parameters

The JIRA Issues macro allows the following parameters:

Issues Displayed a Page at a Time

If you are using JIRA 3.13 or later, the JIRA Issues macro will retrieve and show a 'page' of issues at a time. The buttons underneath the table allow you to move to the next or previous page, or to the start or end of the list. The number of issues retrieved per page is determined by the url parameter — see the description of the macro parameters above.

If your version of JIRA is 3.12 or earlier, the JIRA Issues macro will retrieve all the issues at once and display them as a single 'page'.

Example

Below is an example of some macro markup code, requesting a list of issues from the Atlassian public JIRA site:

The example code contains three parameters (see above parameter table for their meanings):

• anonymous=true
• url=<a long URL derived from the XML view of a JIRA filter>
• columns=type;key;summary

Below are the results of the above macro markup, displayed on this Confluence page:

Displaying Issues which have Restricted Viewing

Maybe your JIRA instance is not visible to anonymous visitors — everyone has to log in before they can see JIRA issues. Or maybe some of the JIRA issues are restricted to viewing by certain users only. This section explains how to handle JIRA issues that have restricted viewing.

Using Confluence-to-JIRA Trusted Communication (Recommended)

For Confluence 2.7.0 and later and JIRA 3.12 and later, your administrator can set up trusted communication between Confluence and JIRA. The entire process is described in the Confluence Administrator's Guide. Provided that your administrator has set up trusted communication, you don't need to add any extra parameters. Confluence and JIRA will work out the security between them, ensuring that the user will see only the issues they are authorised to see. Read the section below if you want more detail.

Specifying Username and Password in the JIRA URL (Not Recommended)

If you have not set up trusted communication between JIRA and Confluence and if your JIRA issues have restricted viewing (i.e. JIRA requires a login before allowing access to the issues), then you need to type a JIRA username and password into the macro markup code and save it onto the Confluence page.

Append the following parameters to the end of the search URL:

&os_username=MYNAME&os_password=MYPASSWORD

where MYNAME is a JIRA username and MYPASSWORD is the corresponding password for that username. This username and password should not include an ampersand (&) symbol.

Troubleshooting

HTTPS

The JIRA Issues macro can access a JIRA instance running under SSL as long as the Confluence server is set to accept the JIRA SSL certificate. Refer to the Confluence Knowledge Base article for more information about problems connecting to SSL services.

And see also:

• Troubleshooting Trusted Communication between JIRA and Confluence

RELATED TOPICS

Inserting JIRA Issues
JIRA Portlet Macro
Working with Macros

In the Administrator's Guide:

• Configuring JIRA with Confluence
• Setting Up Trusted Communication between JIRA and Confluence

Take me back to the Wikis Help Guide.